diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f69c7ae2698..5e8a797ce74 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,14 +6,14 @@ on:
   pull_request:
 
 concurrency:
-  group: ci-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   # Detect docs-only changes to skip heavy jobs (test, build, Windows, macOS, Android).
   # Lint and format always run. Fail-safe: if detection fails, run everything.
   docs-scope:
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     outputs:
       docs_only: ${{ steps.check.outputs.docs_only }}
       docs_changed: ${{ steps.check.outputs.docs_changed }}
@@ -33,7 +33,7 @@ jobs:
   changed-scope:
     needs: [docs-scope]
     if: needs.docs-scope.outputs.docs_only != 'true'
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     outputs:
       run_node: ${{ steps.scope.outputs.run_node }}
       run_macos: ${{ steps.scope.outputs.run_macos }}
@@ -204,6 +204,14 @@ jobs:
         if: matrix.task == 'test' && matrix.runtime == 'node'
         run: echo "OPENCLAW_VITEST_REPORT_DIR=$RUNNER_TEMP/vitest-reports" >> "$GITHUB_ENV"
 
+      - name: Configure Node test resources
+        if: matrix.task == 'test' && matrix.runtime == 'node'
+        run: |
+          # `pnpm test` runs `scripts/test-parallel.mjs`, which spawns multiple Node processes.
+          # Default heap limits have been too low on Linux CI (V8 OOM near 4GB).
+          echo "OPENCLAW_TEST_WORKERS=2" >> "$GITHUB_ENV"
+          echo "OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144" >> "$GITHUB_ENV"
+
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
@@ -664,7 +672,8 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: temurin
-          java-version: 21
+          # setup-android's sdkmanager currently crashes on JDK 21 in CI.
+          java-version: 17
 
       - name: Setup Android SDK
         uses: android-actions/setup-android@v3
diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml
index a286026ae32..05e63005dd5 100644
--- a/.github/workflows/docker-release.yml
+++ b/.github/workflows/docker-release.yml
@@ -13,6 +13,10 @@ on:
       - ".agents/**"
       - "skills/**"
 
+concurrency:
+  group: docker-release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
diff --git a/.github/workflows/formal-conformance.yml b/.github/workflows/formal-conformance.yml
index a8ec86bfce7..8ba6d7e56b8 100644
--- a/.github/workflows/formal-conformance.yml
+++ b/.github/workflows/formal-conformance.yml
@@ -108,6 +108,7 @@ jobs:
 
       - name: Comment on PR (informational)
         if: steps.drift.outputs.drift == 'true'
+        continue-on-error: true
         uses: actions/github-script@v7
         with:
           script: |
diff --git a/.github/workflows/install-smoke.yml b/.github/workflows/install-smoke.yml
index e6c0914f018..45154a5fab4 100644
--- a/.github/workflows/install-smoke.yml
+++ b/.github/workflows/install-smoke.yml
@@ -7,8 +7,8 @@ on:
   workflow_dispatch:
 
 concurrency:
-  group: install-smoke-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: install-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   docs-scope:
@@ -33,19 +33,17 @@ jobs:
       - name: Checkout CLI
         uses: actions/checkout@v4
 
-      - name: Setup pnpm (corepack retry)
-        run: |
-          set -euo pipefail
-          corepack enable
-          for attempt in 1 2 3; do
-            if corepack prepare pnpm@10.23.0 --activate; then
-              pnpm -v
-              exit 0
-            fi
-            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
-            sleep $((attempt * 10))
-          done
-          exit 1
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm + cache store
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          pnpm-version: "10.23.0"
+          cache-key-suffix: "node22"
 
       - name: Install pnpm deps (minimal)
         run: pnpm install --ignore-scripts --frozen-lockfile
diff --git a/.github/workflows/sandbox-common-smoke.yml b/.github/workflows/sandbox-common-smoke.yml
index 27c18aea572..c92a05c3aeb 100644
--- a/.github/workflows/sandbox-common-smoke.yml
+++ b/.github/workflows/sandbox-common-smoke.yml
@@ -14,8 +14,8 @@ on:
       - scripts/sandbox-common-setup.sh
 
 concurrency:
-  group: sandbox-common-smoke-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: sandbox-common-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   sandbox-common-smoke:
diff --git a/.github/workflows/workflow-sanity.yml b/.github/workflows/workflow-sanity.yml
index 14fe6ae429f..438a71162da 100644
--- a/.github/workflows/workflow-sanity.yml
+++ b/.github/workflows/workflow-sanity.yml
@@ -6,8 +6,8 @@ on:
     branches: [main]
 
 concurrency:
-  group: workflow-sanity-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
+  group: workflow-sanity-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   no-tabs:
diff --git a/.gitignore b/.gitignore
index e8c8baf330e..ea7f13ee132 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,6 +27,8 @@ apps/android/.cxx/
 *.bun-build
 apps/macos/.build/
 apps/shared/MoltbotKit/.build/
+apps/shared/OpenClawKit/.build/
+apps/shared/OpenClawKit/Package.resolved
 **/ModuleCache/
 bin/
 bin/clawdbot-mac
diff --git a/AGENTS.md b/AGENTS.md
index 8a48c040243..3aaed9009a8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -119,6 +119,19 @@
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.
 - Release flow: always read `docs/reference/RELEASING.md` and `docs/platforms/mac/release.md` before any release work; do not ask routine questions once those docs answer them.
 
+## GHSA (Repo Advisory) Patch/Publish
+
+- Fetch: `gh api /repos/openclaw/openclaw/security-advisories/<GHSA>`
+- Latest npm: `npm view openclaw version --userconfig "$(mktemp)"`
+- Private fork PRs must be closed:
+  `fork=$(gh api /repos/openclaw/openclaw/security-advisories/<GHSA> | jq -r .private_fork.full_name)`
+  `gh pr list -R "$fork" --state open` (must be empty)
+- Description newline footgun: write Markdown via heredoc to `/tmp/ghsa.desc.md` (no `"\\n"` strings)
+- Build patch JSON via jq: `jq -n --rawfile desc /tmp/ghsa.desc.md '{summary,severity,description:$desc,vulnerabilities:[...]}' > /tmp/ghsa.patch.json`
+- Patch + publish: `gh api -X PATCH /repos/openclaw/openclaw/security-advisories/<GHSA> --input /tmp/ghsa.patch.json` (publish = include `"state":"published"`; no `/publish` endpoint)
+- If publish fails (HTTP 422): missing `severity`/`description`/`vulnerabilities[]`, or private fork has open PRs
+- Verify: re-fetch; ensure `state=published`, `published_at` set; `jq -r .description | rg '\\\\n'` returns nothing
+
 ## Troubleshooting
 
 - Rebrand/migration issues or legacy config/service warnings: run `openclaw doctor` (see `docs/gateway/doctor.md`).
@@ -182,3 +195,39 @@
 - Publish: `npm publish --access public --otp="<otp>"` (run from the package dir).
 - Verify without local npmrc side effects: `npm view <pkg> version --userconfig "$(mktemp)"`.
 - Kill the tmux session after publish.
+
+## Plugin Release Fast Path (no core `openclaw` publish)
+
+- Release only already-on-npm plugins. Source list is in `docs/reference/RELEASING.md` under "Current npm plugin list".
+- Run all CLI `op` calls and `npm publish` inside tmux to avoid hangs/interruption:
+  - `tmux new -d -s release-plugins-$(date +%Y%m%d-%H%M%S)`
+  - `eval "$(op signin --account my.1password.com)"`
+- 1Password helpers:
+  - password used by `npm login`:
+    `op item get Npmjs --format=json | jq -r '.fields[] | select(.id=="password").value'`
+  - OTP:
+    `op read 'op://Private/Npmjs/one-time password?attribute=otp'`
+- Fast publish loop (local helper script in `/tmp` is fine; keep repo clean):
+  - compare local plugin `version` to `npm view <name> version`
+  - only run `npm publish --access public --otp="<otp>"` when versions differ
+  - skip if package is missing on npm or version already matches.
+- Keep `openclaw` untouched: never run publish from repo root unless explicitly requested.
+- Post-check for each release:
+  - per-plugin: `npm view @openclaw/<name> version --userconfig "$(mktemp)"` should be `2026.2.16`
+  - core guard: `npm view openclaw version --userconfig "$(mktemp)"` should stay at previous version unless explicitly requested.
+
+## Changelog Release Notes
+
+- When cutting a mac release with beta GitHub prerelease:
+  - Tag `vYYYY.M.D-beta.N` from the release commit (example: `v2026.2.15-beta.1`).
+  - Create prerelease with title `openclaw YYYY.M.D-beta.N`.
+  - Use release notes from `CHANGELOG.md` version section (`Changes` + `Fixes`, no title duplicate).
+  - Attach at least `OpenClaw-YYYY.M.D.zip` and `OpenClaw-YYYY.M.D.dSYM.zip`; include `.dmg` if available.
+
+- Keep top version entries in `CHANGELOG.md` sorted by impact:
+  - `### Changes` first.
+  - `### Fixes` deduped and ranked with user-facing fixes first.
+- Before tagging/publishing, run:
+  - `node --import tsx scripts/release-check.ts`
+  - `pnpm release:check`
+  - `pnpm test:install:smoke` or `OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke` for non-root smoke path.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ec5a51b207..8ec200ba620 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,33 +2,67 @@
 
 Docs: https://docs.openclaw.ai
 
-## 2026.2.15 (Unreleased)
+## 2026.2.16 (Unreleased)
 
 ### Changes
 
+- Discord: unlock rich interactive agent prompts with Components v2 (buttons, selects, modals, and attachment-backed file blocks) so for native interaction through Discord. Thanks @thewilloftheshadow.
+- Discord: components v2 UI + embeds passthrough + exec approval UX refinements (CV2 containers, button layout, Discord-forwarding skip). Thanks @thewilloftheshadow.
+- Plugins: expose `llm_input` and `llm_output` hook payloads so extensions can observe prompt/input context and model output usage details. (#16724) Thanks @SecondThread.
 - Subagents: nested sub-agents (sub-sub-agents) with configurable depth. Set `agents.defaults.subagents.maxSpawnDepth: 2` to allow sub-agents to spawn their own children. Includes `maxChildrenPerAgent` limit (default 5), depth-aware tool policy, and proper announce chain routing. (#14447) Thanks @tyler6204.
+- Slack/Discord/Telegram: add per-channel ack reaction overrides (account/channel-level) to support platform-specific emoji formats. (#17092) Thanks @zerone0x.
+- Cron/Gateway: add finished-run webhook delivery toggle (`notify`) and dedicated webhook auth token support (`cron.webhookToken`) for outbound cron webhook posts. (#14535) Thanks @advaitpaliwal.
+- Cron/Gateway: separate per-job webhook delivery (`delivery.mode = "webhook"`) from announce delivery, enforce valid HTTP(S) webhook URLs, and keep a temporary legacy `notify + cron.webhook` fallback for stored jobs. (#17901) Thanks @advaitpaliwal.
+- Channels: deduplicate probe/token resolution base types across core + extensions while preserving per-channel error typing. (#16986) Thanks @iyoda and @thewilloftheshadow.
 
 ### Fixes
 
-- Subagents/Models: preserve `agents.defaults.model.fallbacks` when subagent sessions carry a model override, so subagent runs fail over to configured fallback models instead of retrying only the overridden primary model.
+- Security: replace deprecated SHA-1 sandbox configuration hashing with SHA-256 for deterministic sandbox cache identity and recreation checks. Thanks @kexinoh.
+- Security/Logging: redact Telegram bot tokens from error messages and uncaught stack traces to prevent accidental secret leakage into logs. Thanks @aether-ai-agent.
+- Sandbox/Security: block dangerous sandbox Docker config (bind mounts, host networking, unconfined seccomp/apparmor) to prevent container escape via config injection. Thanks @aether-ai-agent.
+- Sandbox: preserve array order in config hashing so order-sensitive Docker/browser settings trigger container recreation correctly. Thanks @kexinoh.
+- Gateway/Security: redact sensitive session/path details from `status` responses for non-admin clients; full details remain available to `operator.admin`. (#8590) Thanks @fr33d3m0n.
+- Gateway/Control UI: preserve requested operator scopes for Control UI bypass modes (`allowInsecureAuth` / `dangerouslyDisableDeviceAuth`) when device identity is unavailable, preventing false `missing scope` failures on authenticated LAN/HTTP operator sessions. (#17682) Thanks @leafbird.
+- LINE/Security: fail closed on webhook startup when channel token or channel secret is missing, and treat LINE accounts as configured only when both are present. (#17587) Thanks @davidahmann.
+- Skills/Security: restrict `download` installer `targetDir` to the per-skill tools directory to prevent arbitrary file writes. Thanks @Adam55A-code.
+- Skills/Linux: harden go installer fallback on apt-based systems by handling root/no-sudo environments safely, doing best-effort apt index refresh, and returning actionable errors instead of failing with spawn errors. (#17687) Thanks @mcrolly.
+- Web Fetch/Security: cap downloaded response body size before HTML parsing to prevent memory exhaustion from oversized or deeply nested pages. Thanks @xuemian168.
 - Config/Gateway: make sensitive-key whitelist suffix matching case-insensitive while preserving `passwordFile` path exemptions, preventing accidental redaction of non-secret config values like `maxTokens` and IRC password-file paths. (#16042) Thanks @akramcodez.
-- Group chats: always inject group chat context (name, participants, reply guidance) into the system prompt on every turn, not just the first. Prevents the model from losing awareness of which group it's in and incorrectly using the message tool to send to the same group. (#14447) Thanks @tyler6204.
-- TUI: make searchable-select filtering and highlight rendering ANSI-aware so queries ignore hidden escape codes and no longer corrupt ANSI styling sequences during match highlighting. (#4519) Thanks @bee4come.
-- TUI/Windows: coalesce rapid single-line submit bursts in Git Bash into one multiline message as a fallback when bracketed paste is unavailable, preventing pasted multiline text from being split into multiple sends. (#4986) Thanks @adamkane.
-- TUI: suppress false `(no output)` placeholders for non-local empty final events during concurrent runs, preventing external-channel replies from showing empty assistant bubbles while a local run is still streaming. (#5782) Thanks @LagWizard and @vignesh07.
-- Auto-reply/WhatsApp/TUI/Web: when a final assistant message is `NO_REPLY` and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show `NO_REPLY` placeholders. (#7010) Thanks @Morrowind-Xie.
+- Dev tooling: harden git `pre-commit` hook against option injection from malicious filenames (for example `--force`), preventing accidental staging of ignored files. Thanks @mrthankyou.
+- Gateway/Agent: reject malformed `agent:`-prefixed session keys (for example, `agent:main`) in `agent` and `agent.identity.get` instead of silently resolving them to the default agent, preventing accidental cross-session routing. (#15707) Thanks @rodrigouroz.
 - Gateway/Chat: harden `chat.send` inbound message handling by rejecting null bytes, stripping unsafe control characters, and normalizing Unicode to NFC before dispatch. (#8593) Thanks @fr33d3m0n.
 - Gateway/Send: return an actionable error when `send` targets internal-only `webchat`, guiding callers to use `chat.send` or a deliverable channel. (#15703) Thanks @rodrigouroz.
-- Gateway/Agent: reject malformed `agent:`-prefixed session keys (for example, `agent:main`) in `agent` and `agent.identity.get` instead of silently resolving them to the default agent, preventing accidental cross-session routing. (#15707) Thanks @rodrigouroz.
-- Gateway/Security: redact sensitive session/path details from `status` responses for non-admin clients; full details remain available to `operator.admin`. (#8590) Thanks @fr33d3m0n.
-- Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.
+- Control UI: prevent stored XSS via assistant name/avatar by removing inline script injection, serving bootstrap config as JSON, and enforcing `script-src 'self'`. Thanks @Adam55A-code.
+- Agents/Security: sanitize workspace paths before embedding into LLM prompts (strip Unicode control/format chars) to prevent instruction injection via malicious directory names. Thanks @aether-ai-agent.
+- Agents/Sandbox: clarify system prompt path guidance so sandbox `bash/exec` uses container paths (for example `/workspace`) while file tools keep host-bridge mapping, avoiding first-attempt path misses from host-only absolute paths in sandbox command execution. (#17693) Thanks @app/juniordevbot.
+- Agents/Context: apply configured model `contextWindow` overrides after provider discovery so `lookupContextTokens()` honors operator config values (including discovery-failure paths). (#17404) Thanks @michaelbship and @vignesh07.
+- Agents/Context: derive `lookupContextTokens()` from auth-available model metadata and keep the smallest discovered context window for duplicate model ids, preventing cross-provider cache collisions from overestimating session context limits. (#17586) Thanks @githabideri and @vignesh07.
 - Agents/OpenAI: force `store=true` for direct OpenAI Responses/Codex runs to preserve multi-turn server-side conversation state, while leaving proxy/non-OpenAI endpoints unchanged. (#16803) Thanks @mark9232 and @vignesh07.
-- CLI/Build: make legacy daemon CLI compatibility shim generation tolerant of minimal tsdown daemon export sets, while preserving restart/register compatibility aliases and surfacing explicit errors for unavailable legacy daemon commands. Thanks @vignesh07.
+- Memory/FTS: make `buildFtsQuery` Unicode-aware so non-ASCII queries (including CJK) produce keyword tokens instead of falling back to vector-only search. (#17672) Thanks @KinGP5471.
+- Auto-reply/Compaction: resolve `memory/YYYY-MM-DD.md` placeholders with timezone-aware runtime dates and append a `Current time:` line to memory-flush turns, preventing wrong-year memory filenames without making the system prompt time-variant. (#17603, #17633) Thanks @nicholaspapadam-wq and @vignesh07.
+- Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.
+- Group chats: always inject group chat context (name, participants, reply guidance) into the system prompt on every turn, not just the first. Prevents the model from losing awareness of which group it's in and incorrectly using the message tool to send to the same group. (#14447) Thanks @tyler6204.
+- Browser/Agents: when browser control service is unavailable, return explicit non-retry guidance (instead of "try again") so models do not loop on repeated browser tool calls until timeout. (#17673) Thanks @austenstone.
+- Subagents: use child-run-based deterministic announce idempotency keys across direct and queued delivery paths (with legacy queued-item fallback) to prevent duplicate announce retries without collapsing distinct same-millisecond announces. (#17150) Thanks @widingmarcus-cyber.
+- Subagents/Models: preserve `agents.defaults.model.fallbacks` when subagent sessions carry a model override, so subagent runs fail over to configured fallback models instead of retrying only the overridden primary model.
+- Telegram: omit `message_thread_id` for DM sends/draft previews and keep forum-topic handling (`id=1` general omitted, non-general kept), preventing DM failures with `400 Bad Request: message thread not found`. (#10942) Thanks @garnetlyx.
 - Telegram: replace inbound `<media:audio>` placeholder with successful preflight voice transcript in message body context, preventing placeholder-only prompt bodies for mention-gated voice messages. (#16789) Thanks @Limitless2023.
 - Telegram: retry inbound media `getFile` calls (3 attempts with backoff) and gracefully fall back to placeholder-only processing when retries fail, preventing dropped voice/media messages on transient Telegram network errors. (#16154) Thanks @yinghaosang.
 - Telegram: finalize streaming preview replies in place instead of sending a second final message, preventing duplicate Telegram assistant outputs at stream completion. (#17218) Thanks @obviyus.
+- Telegram: disable block streaming when `channels.telegram.streamMode` is `off`, preventing newline/content-block replies from splitting into multiple messages. (#17679) Thanks @saivarunk.
+- Telegram: route non-abort slash commands on the normal chat/topic sequential lane while keeping true abort requests (`/stop`, `stop`) on the control lane, preventing command/reply race conditions from control-lane bypass. (#17899) Thanks @obviyus.
+- Discord: preserve channel session continuity when runtime payloads omit `message.channelId` by falling back to event/raw `channel_id` values for routing/session keys, so same-channel messages keep history across turns/restarts. Also align diagnostics so active Discord runs no longer appear as `sessionKey=unknown`. (#17622) Thanks @shakkernerd.
+- Discord: dedupe native skill commands by skill name in multi-agent setups to prevent duplicated slash commands with `_2` suffixes. (#17365) Thanks @seewhyme.
+- Discord: ensure role allowlist matching uses raw role IDs for message routing authorization. Thanks @xinhuagu.
+- Web UI/Agents: hide `BOOTSTRAP.md` in the Agents Files list after onboarding is completed, avoiding confusing missing-file warnings for completed workspaces. (#17491) Thanks @gumadeiras.
+- Memory/QMD: scope managed collection names per agent and precreate glob-backed collection directories before registration, preventing cross-agent collection clobbering and startup ENOENT failures in fresh workspaces. (#17194) Thanks @jonathanadams96.
+- Auto-reply/WhatsApp/TUI/Web: when a final assistant message is `NO_REPLY` and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show `NO_REPLY` placeholders. (#7010) Thanks @Morrowind-Xie.
 - Cron: infer `payload.kind="agentTurn"` for model-only `cron.update` payload patches, so partial agent-turn updates do not fail validation when `kind` is omitted. (#15664) Thanks @rodrigouroz.
-- Subagents: use child-run-based deterministic announce idempotency keys across direct and queued delivery paths (with legacy queued-item fallback) to prevent duplicate announce retries without collapsing distinct same-millisecond announces. (#17150) Thanks @widingmarcus-cyber.
+- TUI: make searchable-select filtering and highlight rendering ANSI-aware so queries ignore hidden escape codes and no longer corrupt ANSI styling sequences during match highlighting. (#4519) Thanks @bee4come.
+- TUI/Windows: coalesce rapid single-line submit bursts in Git Bash into one multiline message as a fallback when bracketed paste is unavailable, preventing pasted multiline text from being split into multiple sends. (#4986) Thanks @adamkane.
+- TUI: suppress false `(no output)` placeholders for non-local empty final events during concurrent runs, preventing external-channel replies from showing empty assistant bubbles while a local run is still streaming. (#5782) Thanks @LagWizard and @vignesh07.
+- TUI: preserve copy-sensitive long tokens (URLs/paths/file-like identifiers) during wrapping and overflow sanitization so wrapped output no longer inserts spaces that corrupt copy/paste values. (#17515, #17466, #17505) Thanks @abe238, @trevorpan, and @JasonCry.
+- CLI/Build: make legacy daemon CLI compatibility shim generation tolerant of minimal tsdown daemon export sets, while preserving restart/register compatibility aliases and surfacing explicit errors for unavailable legacy daemon commands. Thanks @vignesh07.
 
 ## 2026.2.14
 
@@ -43,6 +77,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Security/Sessions/Telegram: restrict session tool targeting by default to the current session tree (`tools.sessions.visibility`, default `tree`) with sandbox clamping, and pass configured per-account Telegram webhook secrets in webhook mode when no explicit override is provided. Thanks @aether-ai-agent.
 - CLI/Plugins: ensure `openclaw message send` exits after successful delivery across plugin-backed channels so one-shot sends do not hang. (#16491) Thanks @yinghaosang.
 - CLI/Plugins: run registered plugin `gateway_stop` hooks before `openclaw message` exits (success and failure paths), so plugin-backed channels can clean up one-shot CLI resources. (#16580) Thanks @gumadeiras.
 - WhatsApp: honor per-account `dmPolicy` overrides (account-level settings now take precedence over channel defaults for inbound DMs). (#10082) Thanks @mcaxtr.
@@ -82,9 +117,11 @@ Docs: https://docs.openclaw.ai
 - Gateway/Subagents: preserve queued announce items and summary state on delivery errors, retry failed announce drains, and avoid dropping unsent announcements on timeout/failure. (#16729) Thanks @Clawdette-Workspace.
 - Gateway/Config: make `config.patch` merge object arrays by `id` (for example `agents.list`) instead of replacing the whole array, so partial agent updates do not silently delete unrelated agents. (#6766) Thanks @lightclient.
 - Webchat/Prompts: stop injecting direct-chat `conversation_label` into inbound untrusted metadata context blocks, preventing internal label noise from leaking into visible chat replies. (#16556) Thanks @nberardi.
+- Auto-reply/Prompts: include trusted inbound `message_id`, `chat_id`, `reply_to_id`, and optional `message_id_full` metadata fields so action tools (for example reactions) can target the triggering message without relying on user text. (#17662) Thanks @MaikiMolto.
 - Gateway/Sessions: abort active embedded runs and clear queued session work before `sessions.reset`, returning unavailable if the run does not stop in time. (#16576) Thanks @Grynn.
 - Sessions/Agents: harden transcript path resolution for mismatched agent context by preserving explicit store roots and adding safe absolute-path fallback to the correct agent sessions directory. (#16288) Thanks @robbyczgw-cla.
 - Agents: add a safety timeout around embedded `session.compact()` to ensure stalled compaction runs settle and release blocked session lanes. (#16331) Thanks @BinHPdev.
+- Agents/Tools: make required-parameter validation errors list missing fields and instruct: "Supply correct parameters before retrying," reducing repeated invalid tool-call loops (for example `read({})`). (#14729)
 - Agents: keep unresolved mutating tool failures visible until the same action retry succeeds, scope mutation-error surfacing to mutating calls (including `session_status` model changes), and dedupe duplicate failure warnings in outbound replies. (#16131) Thanks @Swader.
 - Agents/Process/Bootstrap: preserve unbounded `process log` offset-only pagination (default tail applies only when both `offset` and `limit` are omitted) and enforce strict `bootstrapTotalMaxChars` budgeting across injected bootstrap content (including markers), skipping additional injection when remaining budget is too small. (#16539) Thanks @CharlieGreenman.
 - Agents/Workspace: persist bootstrap onboarding state so partially initialized workspaces recover missing `BOOTSTRAP.md` once, while completed onboarding keeps BOOTSTRAP deleted even if runtime files are later recreated. Thanks @gumadeiras.
@@ -96,6 +133,7 @@ Docs: https://docs.openclaw.ai
 - Tools/Write/Edit: normalize structured text-block arguments for `content`/`oldText`/`newText` before filesystem edits, preventing JSON-like file corruption and false “exact text not found” misses from block-form params. (#16778) Thanks @danielpipernz.
 - Ollama/Agents: avoid forcing `<final>` tag enforcement for Ollama models, which could suppress all output as `(no output)`. (#16191) Thanks @Glucksberg.
 - Plugins: suppress false duplicate plugin id warnings when the same extension is discovered via multiple paths (config/workspace/global vs bundled), while still warning on genuine duplicates. (#16222) Thanks @shadril238.
+- Agents/Process: supervise PTY/child process lifecycles with explicit ownership, cancellation, timeouts, and deterministic cleanup, preventing Codex/Pi PTY sessions from dying or stalling on resume. (#14257) Thanks @onutc.
 - Skills: watch `SKILL.md` only when refreshing skills snapshot to avoid file-descriptor exhaustion in large data trees. (#11325) Thanks @household-bard.
 - Memory/QMD: make `memory status` read-only by skipping QMD boot update/embed side effects for status-only manager checks.
 - Memory/QMD: keep original QMD failures when builtin fallback initialization fails (for example missing embedding API keys), instead of replacing them with fallback init errors.
@@ -109,6 +147,7 @@ Docs: https://docs.openclaw.ai
 - Memory/QMD: make QMD result JSON parsing resilient to noisy command output by extracting the first JSON array from noisy `stdout`.
 - Memory/QMD: treat prefixed `no results found` marker output as an empty result set in qmd JSON parsing. (#11302) Thanks @blazerui.
 - Memory/QMD: avoid multi-collection `query` ranking corruption by running one `qmd query -c <collection>` per managed collection and merging by best score (also used for `search`/`vsearch` fallback-to-query). (#16740) Thanks @volarian-vai.
+- Memory/QMD: rebind managed collections when existing collection metadata drifts (including sessions name-only listings), preventing non-default agents from reusing another agent's `sessions` collection path. (#17194) Thanks @jonathanadams96.
 - Memory/QMD: make `openclaw memory index` verify and print the active QMD index file path/size, and fail when QMD leaves a missing or zero-byte index artifact after an update. (#16775) Thanks @Shunamxiao.
 - Memory/QMD: detect null-byte `ENOTDIR` update failures, rebuild managed collections once, and retry update to self-heal corrupted collection metadata. (#12919) Thanks @jorgejhms.
 - Memory/QMD/Security: add `rawKeyPrefix` support for QMD scope rules and preserve legacy `keyPrefix: "agent:..."` matching, preventing scoped deny bypass when operators match agent-prefixed session keys.
@@ -126,6 +165,7 @@ Docs: https://docs.openclaw.ai
 - Media/Security: allow local media reads from OpenClaw state `workspace/` and `sandboxes/` roots by default so generated workspace media can be delivered without unsafe global path bypasses. (#15541) Thanks @lanceji.
 - Media/Security: harden local media allowlist bypasses by requiring an explicit `readFile` override when callers mark paths as validated, and reject filesystem-root `localRoots` entries. (#16739)
 - Media/Security: allow outbound local media reads from the active agent workspace (including `workspace-<agentId>`) via agent-scoped local roots, avoiding broad global allowlisting of all per-agent workspaces. (#17136) Thanks @MisterGuy420.
+- Outbound/Media: thread explicit `agentId` through core `sendMessage` direct-delivery path so agent-scoped local media roots apply even when mirror metadata is absent. (#17268) Thanks @gumadeiras.
 - Discord/Security: harden voice message media loading (SSRF + allowed-local-root checks) so tool-supplied paths/URLs cannot be used to probe internal URLs or read arbitrary local files.
 - Security/BlueBubbles: require explicit `mediaLocalRoots` allowlists for local outbound media path reads to prevent local file disclosure. (#16322) Thanks @mbelinky.
 - Security/BlueBubbles: reject ambiguous shared-path webhook routing when multiple webhook targets match the same guid/password.
@@ -141,6 +181,7 @@ Docs: https://docs.openclaw.ai
 - Security/Media: stream and bound URL-backed input media fetches to prevent memory exhaustion from oversized responses. Thanks @vincentkoc.
 - Security/Skills: harden archive extraction for download-installed skills to prevent path traversal outside the target directory. Thanks @markmusson.
 - Security/Slack: compute command authorization for DM slash commands even when `dmPolicy=open`, preventing unauthorized users from running privileged commands via DM. Thanks @christos-eth.
+- Security/Pairing: scope pairing allowlist writes/reads to channel accounts (for example `telegram:yy`), and propagate account-aware pairing approvals so multi-account channels do not share a single per-channel pairing allowFrom store. (#17631) Thanks @crazytan.
 - Security/iMessage: keep DM pairing-store identities out of group allowlist authorization (prevents cross-context command authorization). Thanks @vincentkoc.
 - Security/Google Chat: deprecate `users/<email>` allowlists (treat `users/...` as immutable user id only); keep raw email allowlists for usability. Thanks @vincentkoc.
 - Security/Google Chat: reject ambiguous shared-path webhook routing when multiple webhook targets verify successfully (prevents cross-account policy-context misrouting). Thanks @vincentkoc.
@@ -196,6 +237,7 @@ Docs: https://docs.openclaw.ai
 - Docs/Hooks: update hooks documentation URLs to the new `/automation/hooks` location. (#16165) Thanks @nicholascyh.
 - Security/Audit: warn when `gateway.tools.allow` re-enables default-denied tools over HTTP `POST /tools/invoke`, since this can increase RCE blast radius if the gateway is reachable.
 - Security/Plugins/Hooks: harden npm-based installs by restricting specs to registry packages only, passing `--ignore-scripts` to `npm pack`, and cleaning up temp install directories.
+- Security/Sessions: preserve inter-session input provenance for routed prompts so delegated/internal sessions are not treated as direct external user instructions. Thanks @anbecker.
 - Feishu: stop persistent Typing reaction on NO_REPLY/suppressed runs by wiring reply-dispatcher cleanup to remove typing indicators. (#15464) Thanks @arosstale.
 - Agents: strip leading empty lines from `sanitizeUserFacingText` output and normalize whitespace-only outputs to empty text. (#16158) Thanks @mcinteerj.
 - BlueBubbles: gracefully degrade when Private API is disabled by filtering private-only actions, skipping private-only reactions/reply effects, and avoiding private reply markers so non-private flows remain usable. (#16002) Thanks @L-U-C-K-Y.
@@ -326,6 +368,7 @@ Docs: https://docs.openclaw.ai
 - Configure/Gateway: reject literal `"undefined"`/`"null"` token input and validate gateway password prompt values to avoid invalid password-mode configs. (#13767) Thanks @omair445.
 - Gateway: handle async `EPIPE` on stdout/stderr during shutdown. (#13414) Thanks @keshav55.
 - Gateway/Control UI: resolve missing dashboard assets when `openclaw` is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.
+- Gateway/Control UI: keep partial assistant output visible when runs are aborted, and persist aborted partials to session transcripts for follow-up context.
 - Cron: use requested `agentId` for isolated job auth resolution. (#13983) Thanks @0xRaini.
 - Cron: prevent cron jobs from skipping execution when `nextRunAtMs` advances. (#14068) Thanks @WalterSumbon.
 - Cron: pass `agentId` to `runHeartbeatOnce` for main-session jobs. (#14140) Thanks @ishikawa-pro.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a5e9164a94d..355fb5c6890 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,24 +13,33 @@ Welcome to the lobster tank! 🦞
 - **Peter Steinberger** - Benevolent Dictator
   - GitHub: [@steipete](https://github.com/steipete) · X: [@steipete](https://x.com/steipete)
 
-- **Shadow** - Discord + Slack subsystem
+- **Shadow** - Discord subsystem, Discord admin
   - GitHub: [@thewilloftheshadow](https://github.com/thewilloftheshadow) · X: [@4shad0wed](https://x.com/4shad0wed)
 
-- **Vignesh** - Memory (QMD), formal modeling, TUI, and Lobster
+- **Vignesh** - Memory (QMD), formal modeling, TUI, IRC, and Lobster
   - GitHub: [@vignesh07](https://github.com/vignesh07) · X: [@\_vgnsh](https://x.com/_vgnsh)
 
 - **Jos** - Telegram, API, Nix mode
   - GitHub: [@joshp123](https://github.com/joshp123) · X: [@jjpcodes](https://x.com/jjpcodes)
 
+- **Ayaan Zaidi** - Telegram subsystem, iOS app
+  - GitHub: [@obviyus](https://github.com/obviyus) · X: [@0bviyus](https://x.com/0bviyus)
+
+- **Tyler Yust** - Agents/subagents, cron, BlueBubbles, macOS app
+  - GitHub: [@tyler6204](https://github.com/tyler6204) · X: [@tyleryust](https://x.com/tyleryust)
+
+- **Mariano Belinky** - iOS app, Security
+  - GitHub: [@mbelinky](https://github.com/mbelinky) · X: [@belimad](https://x.com/belimad)
+
+- **Seb Slight** - Docs, Agent Reliability, Runtime Hardening
+  - GitHub: [@sebslight](https://github.com/sebslight) · X: [@sebslig](https://x.com/sebslig)
+
 - **Christoph Nakazawa** - JS Infra
   - GitHub: [@cpojer](https://github.com/cpojer) · X: [@cnakazawa](https://x.com/cnakazawa)
 
 - **Gustavo Madeira Santana** - Multi-agents, CLI, web UI
   - GitHub: [@gumadeiras](https://github.com/gumadeiras) · X: [@gumadeiras](https://x.com/gumadeiras)
 
-- **Maximilian Nussbaumer** - DevOps, CI, Code Sanity
-  - GitHub: [@quotentiroler](https://github.com/quotentiroler) · X: [@quotentiroler](https://x.com/quotentiroler)
-
 ## How to Contribute
 
 1. **Bugs & small fixes** → Open a PR!
diff --git a/appcast.xml b/appcast.xml
index 02d053bd5cd..2b3ed8fcc9a 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -140,6 +140,74 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.14/OpenClaw-2026.2.14.zip" length="22914034" type="application/octet-stream" sparkle:edSignature="lR3nuq46/akMIN8RFDpMkTE0VOVoDVG53Xts589LryMGEtUvJxRQDtHBXfx7ZvToTq6CFKG+L5Kq/4rUspMoAQ=="/>
         </item>
+        <item>
+            <title>2026.2.15</title>
+            <pubDate>Mon, 16 Feb 2026 05:04:34 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
+            <sparkle:version>11213</sparkle:version>
+            <sparkle:shortVersionString>2026.2.15</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>OpenClaw 2026.2.15</h2>
+<h3>Changes</h3>
+<ul>
+<li>Discord: unlock rich interactive agent prompts with Components v2 (buttons, selects, modals, and attachment-backed file blocks) so for native interaction through Discord. Thanks @thewilloftheshadow.</li>
+<li>Discord: components v2 UI + embeds passthrough + exec approval UX refinements (CV2 containers, button layout, Discord-forwarding skip). Thanks @thewilloftheshadow.</li>
+<li>Plugins: expose <code>llm_input</code> and <code>llm_output</code> hook payloads so extensions can observe prompt/input context and model output usage details. (#16724) Thanks @SecondThread.</li>
+<li>Subagents: nested sub-agents (sub-sub-agents) with configurable depth. Set <code>agents.defaults.subagents.maxSpawnDepth: 2</code> to allow sub-agents to spawn their own children. Includes <code>maxChildrenPerAgent</code> limit (default 5), depth-aware tool policy, and proper announce chain routing. (#14447) Thanks @tyler6204.</li>
+<li>Slack/Discord/Telegram: add per-channel ack reaction overrides (account/channel-level) to support platform-specific emoji formats. (#17092) Thanks @zerone0x.</li>
+<li>Cron/Gateway: add finished-run webhook delivery toggle (<code>notify</code>) and dedicated webhook auth token support (<code>cron.webhookToken</code>) for outbound cron webhook posts. (#14535) Thanks @advaitpaliwal.</li>
+<li>Channels: deduplicate probe/token resolution base types across core + extensions while preserving per-channel error typing. (#16986) Thanks @iyoda and @thewilloftheshadow.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Security: replace deprecated SHA-1 sandbox configuration hashing with SHA-256 for deterministic sandbox cache identity and recreation checks. Thanks @kexinoh.</li>
+<li>Security/Logging: redact Telegram bot tokens from error messages and uncaught stack traces to prevent accidental secret leakage into logs. Thanks @aether-ai-agent.</li>
+<li>Sandbox/Security: block dangerous sandbox Docker config (bind mounts, host networking, unconfined seccomp/apparmor) to prevent container escape via config injection. Thanks @aether-ai-agent.</li>
+<li>Sandbox: preserve array order in config hashing so order-sensitive Docker/browser settings trigger container recreation correctly. Thanks @kexinoh.</li>
+<li>Gateway/Security: redact sensitive session/path details from <code>status</code> responses for non-admin clients; full details remain available to <code>operator.admin</code>. (#8590) Thanks @fr33d3m0n.</li>
+<li>Gateway/Control UI: preserve requested operator scopes for Control UI bypass modes (<code>allowInsecureAuth</code> / <code>dangerouslyDisableDeviceAuth</code>) when device identity is unavailable, preventing false <code>missing scope</code> failures on authenticated LAN/HTTP operator sessions. (#17682) Thanks @leafbird.</li>
+<li>LINE/Security: fail closed on webhook startup when channel token or channel secret is missing, and treat LINE accounts as configured only when both are present. (#17587) Thanks @davidahmann.</li>
+<li>Skills/Security: restrict <code>download</code> installer <code>targetDir</code> to the per-skill tools directory to prevent arbitrary file writes. Thanks @Adam55A-code.</li>
+<li>Skills/Linux: harden go installer fallback on apt-based systems by handling root/no-sudo environments safely, doing best-effort apt index refresh, and returning actionable errors instead of failing with spawn errors. (#17687) Thanks @mcrolly.</li>
+<li>Web Fetch/Security: cap downloaded response body size before HTML parsing to prevent memory exhaustion from oversized or deeply nested pages. Thanks @xuemian168.</li>
+<li>Config/Gateway: make sensitive-key whitelist suffix matching case-insensitive while preserving <code>passwordFile</code> path exemptions, preventing accidental redaction of non-secret config values like <code>maxTokens</code> and IRC password-file paths. (#16042) Thanks @akramcodez.</li>
+<li>Dev tooling: harden git <code>pre-commit</code> hook against option injection from malicious filenames (for example <code>--force</code>), preventing accidental staging of ignored files. Thanks @mrthankyou.</li>
+<li>Gateway/Agent: reject malformed <code>agent:</code>-prefixed session keys (for example, <code>agent:main</code>) in <code>agent</code> and <code>agent.identity.get</code> instead of silently resolving them to the default agent, preventing accidental cross-session routing. (#15707) Thanks @rodrigouroz.</li>
+<li>Gateway/Chat: harden <code>chat.send</code> inbound message handling by rejecting null bytes, stripping unsafe control characters, and normalizing Unicode to NFC before dispatch. (#8593) Thanks @fr33d3m0n.</li>
+<li>Gateway/Send: return an actionable error when <code>send</code> targets internal-only <code>webchat</code>, guiding callers to use <code>chat.send</code> or a deliverable channel. (#15703) Thanks @rodrigouroz.</li>
+<li>Control UI: prevent stored XSS via assistant name/avatar by removing inline script injection, serving bootstrap config as JSON, and enforcing <code>script-src 'self'</code>. Thanks @Adam55A-code.</li>
+<li>Agents/Security: sanitize workspace paths before embedding into LLM prompts (strip Unicode control/format chars) to prevent instruction injection via malicious directory names. Thanks @aether-ai-agent.</li>
+<li>Agents/Sandbox: clarify system prompt path guidance so sandbox <code>bash/exec</code> uses container paths (for example <code>/workspace</code>) while file tools keep host-bridge mapping, avoiding first-attempt path misses from host-only absolute paths in sandbox command execution. (#17693) Thanks @app/juniordevbot.</li>
+<li>Agents/Context: apply configured model <code>contextWindow</code> overrides after provider discovery so <code>lookupContextTokens()</code> honors operator config values (including discovery-failure paths). (#17404) Thanks @michaelbship and @vignesh07.</li>
+<li>Agents/Context: derive <code>lookupContextTokens()</code> from auth-available model metadata and keep the smallest discovered context window for duplicate model ids, preventing cross-provider cache collisions from overestimating session context limits. (#17586) Thanks @githabideri and @vignesh07.</li>
+<li>Agents/OpenAI: force <code>store=true</code> for direct OpenAI Responses/Codex runs to preserve multi-turn server-side conversation state, while leaving proxy/non-OpenAI endpoints unchanged. (#16803) Thanks @mark9232 and @vignesh07.</li>
+<li>Memory/FTS: make <code>buildFtsQuery</code> Unicode-aware so non-ASCII queries (including CJK) produce keyword tokens instead of falling back to vector-only search. (#17672) Thanks @KinGP5471.</li>
+<li>Auto-reply/Compaction: resolve <code>memory/YYYY-MM-DD.md</code> placeholders with timezone-aware runtime dates and append a <code>Current time:</code> line to memory-flush turns, preventing wrong-year memory filenames without making the system prompt time-variant. (#17603, #17633) Thanks @nicholaspapadam-wq and @vignesh07.</li>
+<li>Agents: return an explicit timeout error reply when an embedded run times out before producing any payloads, preventing silent dropped turns during slow cache-refresh transitions. (#16659) Thanks @liaosvcaf and @vignesh07.</li>
+<li>Group chats: always inject group chat context (name, participants, reply guidance) into the system prompt on every turn, not just the first. Prevents the model from losing awareness of which group it's in and incorrectly using the message tool to send to the same group. (#14447) Thanks @tyler6204.</li>
+<li>Browser/Agents: when browser control service is unavailable, return explicit non-retry guidance (instead of "try again") so models do not loop on repeated browser tool calls until timeout. (#17673) Thanks @austenstone.</li>
+<li>Subagents: use child-run-based deterministic announce idempotency keys across direct and queued delivery paths (with legacy queued-item fallback) to prevent duplicate announce retries without collapsing distinct same-millisecond announces. (#17150) Thanks @widingmarcus-cyber.</li>
+<li>Subagents/Models: preserve <code>agents.defaults.model.fallbacks</code> when subagent sessions carry a model override, so subagent runs fail over to configured fallback models instead of retrying only the overridden primary model.</li>
+<li>Telegram: omit <code>message_thread_id</code> for DM sends/draft previews and keep forum-topic handling (<code>id=1</code> general omitted, non-general kept), preventing DM failures with <code>400 Bad Request: message thread not found</code>. (#10942) Thanks @garnetlyx.</li>
+<li>Telegram: replace inbound <code><media:audio></code> placeholder with successful preflight voice transcript in message body context, preventing placeholder-only prompt bodies for mention-gated voice messages. (#16789) Thanks @Limitless2023.</li>
+<li>Telegram: retry inbound media <code>getFile</code> calls (3 attempts with backoff) and gracefully fall back to placeholder-only processing when retries fail, preventing dropped voice/media messages on transient Telegram network errors. (#16154) Thanks @yinghaosang.</li>
+<li>Telegram: finalize streaming preview replies in place instead of sending a second final message, preventing duplicate Telegram assistant outputs at stream completion. (#17218) Thanks @obviyus.</li>
+<li>Discord: preserve channel session continuity when runtime payloads omit <code>message.channelId</code> by falling back to event/raw <code>channel_id</code> values for routing/session keys, so same-channel messages keep history across turns/restarts. Also align diagnostics so active Discord runs no longer appear as <code>sessionKey=unknown</code>. (#17622) Thanks @shakkernerd.</li>
+<li>Discord: dedupe native skill commands by skill name in multi-agent setups to prevent duplicated slash commands with <code>_2</code> suffixes. (#17365) Thanks @seewhyme.</li>
+<li>Discord: ensure role allowlist matching uses raw role IDs for message routing authorization. Thanks @xinhuagu.</li>
+<li>Web UI/Agents: hide <code>BOOTSTRAP.md</code> in the Agents Files list after onboarding is completed, avoiding confusing missing-file warnings for completed workspaces. (#17491) Thanks @gumadeiras.</li>
+<li>Auto-reply/WhatsApp/TUI/Web: when a final assistant message is <code>NO_REPLY</code> and a messaging tool send succeeded, mirror the delivered messaging-tool text into session-visible assistant output so TUI/Web no longer show <code>NO_REPLY</code> placeholders. (#7010) Thanks @Morrowind-Xie.</li>
+<li>Cron: infer <code>payload.kind="agentTurn"</code> for model-only <code>cron.update</code> payload patches, so partial agent-turn updates do not fail validation when <code>kind</code> is omitted. (#15664) Thanks @rodrigouroz.</li>
+<li>TUI: make searchable-select filtering and highlight rendering ANSI-aware so queries ignore hidden escape codes and no longer corrupt ANSI styling sequences during match highlighting. (#4519) Thanks @bee4come.</li>
+<li>TUI/Windows: coalesce rapid single-line submit bursts in Git Bash into one multiline message as a fallback when bracketed paste is unavailable, preventing pasted multiline text from being split into multiple sends. (#4986) Thanks @adamkane.</li>
+<li>TUI: suppress false <code>(no output)</code> placeholders for non-local empty final events during concurrent runs, preventing external-channel replies from showing empty assistant bubbles while a local run is still streaming. (#5782) Thanks @LagWizard and @vignesh07.</li>
+<li>TUI: preserve copy-sensitive long tokens (URLs/paths/file-like identifiers) during wrapping and overflow sanitization so wrapped output no longer inserts spaces that corrupt copy/paste values. (#17515, #17466, #17505) Thanks @abe238, @trevorpan, and @JasonCry.</li>
+<li>CLI/Build: make legacy daemon CLI compatibility shim generation tolerant of minimal tsdown daemon export sets, while preserving restart/register compatibility aliases and surfacing explicit errors for unavailable legacy daemon commands. Thanks @vignesh07.</li>
+</ul>
+<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.15/OpenClaw-2026.2.15.zip" length="22896513" type="application/octet-stream" sparkle:edSignature="MLGsd2NeHXFRH1Or0bFQnAjqfuuJDuhl1mvKFIqTQcRvwbeyvOyyLXrqSbmaOgJR3wBQBKLs6jYQ9dQ/3R8RCg=="/>
+        </item>
         <item>
             <title>2026.2.13</title>
             <pubDate>Sat, 14 Feb 2026 04:30:23 +0100</pubDate>
@@ -241,101 +309,5 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.13/OpenClaw-2026.2.13.zip" length="22902077" type="application/octet-stream" sparkle:edSignature="RpkwlPtB2yN7UOYZWfthV5grhDUcbhcHMeicdRA864Vo/P0Hnq5aHKmSvcbWkjHut96TC57bX+AeUrL7txpLCg=="/>
         </item>
-        <item>
-            <title>2026.2.12</title>
-            <pubDate>Fri, 13 Feb 2026 03:17:54 +0100</pubDate>
-            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>9500</sparkle:version>
-            <sparkle:shortVersionString>2026.2.12</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>OpenClaw 2026.2.12</h2>
-<h3>Changes</h3>
-<ul>
-<li>CLI: add <code>openclaw logs --local-time</code> to display log timestamps in local timezone. (#13818) Thanks @xialonglee.</li>
-<li>Telegram: render blockquotes as native <code><blockquote></code> tags instead of stripping them. (#14608)</li>
-<li>Config: avoid redacting <code>maxTokens</code>-like fields during config snapshot redaction, preventing round-trip validation failures in <code>/config</code>. (#14006) Thanks @constansino.</li>
-</ul>
-<h3>Breaking</h3>
-<ul>
-<li>Hooks: <code>POST /hooks/agent</code> now rejects payload <code>sessionKey</code> overrides by default. To keep fixed hook context, set <code>hooks.defaultSessionKey</code> (recommended with <code>hooks.allowedSessionKeyPrefixes: ["hook:"]</code>). If you need legacy behavior, explicitly set <code>hooks.allowRequestSessionKey: true</code>. Thanks @alpernae for reporting.</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Gateway/OpenResponses: harden URL-based <code>input_file</code>/<code>input_image</code> handling with explicit SSRF deny policy, hostname allowlists (<code>files.urlAllowlist</code> / <code>images.urlAllowlist</code>), per-request URL input caps (<code>maxUrlParts</code>), blocked-fetch audit logging, and regression coverage/docs updates.</li>
-<li>Security: fix unauthenticated Nostr profile API remote config tampering. (#13719) Thanks @coygeek.</li>
-<li>Security: remove bundled soul-evil hook. (#14757) Thanks @Imccccc.</li>
-<li>Security/Audit: add hook session-routing hardening checks (<code>hooks.defaultSessionKey</code>, <code>hooks.allowRequestSessionKey</code>, and prefix allowlists), and warn when HTTP API endpoints allow explicit session-key routing.</li>
-<li>Security/Sandbox: confine mirrored skill sync destinations to the sandbox <code>skills/</code> root and stop using frontmatter-controlled skill names as filesystem destination paths. Thanks @1seal.</li>
-<li>Security/Web tools: treat browser/web content as untrusted by default (wrapped outputs for browser snapshot/tabs/console and structured external-content metadata for web tools), and strip <code>toolResult.details</code> from model-facing transcript/compaction inputs to reduce prompt-injection replay risk.</li>
-<li>Security/Hooks: harden webhook and device token verification with shared constant-time secret comparison, and add per-client auth-failure throttling for hook endpoints (<code>429</code> + <code>Retry-After</code>). Thanks @akhmittra.</li>
-<li>Security/Browser: require auth for loopback browser control HTTP routes, auto-generate <code>gateway.auth.token</code> when browser control starts without auth, and add a security-audit check for unauthenticated browser control. Thanks @tcusolle.</li>
-<li>Sessions/Gateway: harden transcript path resolution and reject unsafe session IDs/file paths so session operations stay within agent sessions directories. Thanks @akhmittra.</li>
-<li>Gateway: raise WS payload/buffer limits so 5,000,000-byte image attachments work reliably. (#14486) Thanks @0xRaini.</li>
-<li>Logging/CLI: use local timezone timestamps for console prefixing, and include <code>±HH:MM</code> offsets when using <code>openclaw logs --local-time</code> to avoid ambiguity. (#14771) Thanks @0xRaini.</li>
-<li>Gateway: drain active turns before restart to prevent message loss. (#13931) Thanks @0xRaini.</li>
-<li>Gateway: auto-generate auth token during install to prevent launchd restart loops. (#13813) Thanks @cathrynlavery.</li>
-<li>Gateway: prevent <code>undefined</code>/missing token in auth config. (#13809) Thanks @asklee-klawd.</li>
-<li>Gateway: handle async <code>EPIPE</code> on stdout/stderr during shutdown. (#13414) Thanks @keshav55.</li>
-<li>Gateway/Control UI: resolve missing dashboard assets when <code>openclaw</code> is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.</li>
-<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
-<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
-<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
-<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
-<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
-<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
-<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
-<li>Heartbeat: prevent scheduler stalls on unexpected run errors and avoid immediate rerun loops after <code>requests-in-flight</code> skips. (#14901) Thanks @joeykrug.</li>
-<li>Cron: honor stored session model overrides for isolated-agent runs while preserving <code>hooks.gmail.model</code> precedence for Gmail hook sessions. (#14983) Thanks @shtse8.</li>
-<li>Logging/Browser: fall back to <code>os.tmpdir()/openclaw</code> for default log, browser trace, and browser download temp paths when <code>/tmp/openclaw</code> is unavailable.</li>
-<li>WhatsApp: convert Markdown bold/strikethrough to WhatsApp formatting. (#14285) Thanks @Raikan10.</li>
-<li>WhatsApp: allow media-only sends and normalize leading blank payloads. (#14408) Thanks @karimnaguib.</li>
-<li>WhatsApp: default MIME type for voice messages when Baileys omits it. (#14444) Thanks @mcaxtr.</li>
-<li>Telegram: handle no-text message in model picker editMessageText. (#14397) Thanks @0xRaini.</li>
-<li>Telegram: surface REACTION_INVALID as non-fatal warning. (#14340) Thanks @0xRaini.</li>
-<li>BlueBubbles: fix webhook auth bypass via loopback proxy trust. (#13787) Thanks @coygeek.</li>
-<li>Slack: change default replyToMode from "off" to "all". (#14364) Thanks @nm-de.</li>
-<li>Slack: detect control commands when channel messages start with bot mention prefixes (for example, <code>@Bot /new</code>). (#14142) Thanks @beefiker.</li>
-<li>Signal: enforce E.164 validation for the Signal bot account prompt so mistyped numbers are caught early. (#15063) Thanks @Duartemartins.</li>
-<li>Discord: process DM reactions instead of silently dropping them. (#10418) Thanks @mcaxtr.</li>
-<li>Discord: respect replyToMode in threads. (#11062) Thanks @cordx56.</li>
-<li>Heartbeat: filter noise-only system events so scheduled reminder notifications do not fire when cron runs carry only heartbeat markers. (#13317) Thanks @pvtclawn.</li>
-<li>Signal: render mention placeholders as <code>@uuid</code>/<code>@phone</code> so mention gating and Clawdbot targeting work. (#2013) Thanks @alexgleason.</li>
-<li>Discord: omit empty content fields for media-only messages while preserving caption whitespace. (#9507) Thanks @leszekszpunar.</li>
-<li>Onboarding/Providers: add Z.AI endpoint-specific auth choices (<code>zai-coding-global</code>, <code>zai-coding-cn</code>, <code>zai-global</code>, <code>zai-cn</code>) and expand default Z.AI model wiring. (#13456) Thanks @tomsun28.</li>
-<li>Onboarding/Providers: update MiniMax API default/recommended models from M2.1 to M2.5, add M2.5/M2.5-Lightning model entries, and include <code>minimax-m2.5</code> in modern model filtering. (#14865) Thanks @adao-max.</li>
-<li>Ollama: use configured <code>models.providers.ollama.baseUrl</code> for model discovery and normalize <code>/v1</code> endpoints to the native Ollama API root. (#14131) Thanks @shtse8.</li>
-<li>Voice Call: pass Twilio stream auth token via <code><Parameter></code> instead of query string. (#14029) Thanks @mcwigglesmcgee.</li>
-<li>Feishu: pass <code>Buffer</code> directly to the Feishu SDK upload APIs instead of <code>Readable.from(...)</code> to avoid form-data upload failures. (#10345) Thanks @youngerstyle.</li>
-<li>Feishu: trigger mention-gated group handling only when the bot itself is mentioned (not just any mention). (#11088) Thanks @openperf.</li>
-<li>Feishu: probe status uses the resolved account context for multi-account credential checks. (#11233) Thanks @onevcat.</li>
-<li>Feishu DocX: preserve top-level converted block order using <code>firstLevelBlockIds</code> when writing/appending documents. (#13994) Thanks @Cynosure159.</li>
-<li>Feishu plugin packaging: remove <code>workspace:*</code> <code>openclaw</code> dependency from <code>extensions/feishu</code> and sync lockfile for install compatibility. (#14423) Thanks @jackcooper2015.</li>
-<li>CLI/Wizard: exit with code 1 when <code>configure</code>, <code>agents add</code>, or interactive <code>onboard</code> wizards are canceled, so <code>set -e</code> automation stops correctly. (#14156) Thanks @0xRaini.</li>
-<li>Media: strip <code>MEDIA:</code> lines with local paths instead of leaking as visible text. (#14399) Thanks @0xRaini.</li>
-<li>Config/Cron: exclude <code>maxTokens</code> from config redaction and honor <code>deleteAfterRun</code> on skipped cron jobs. (#13342) Thanks @niceysam.</li>
-<li>Config: ignore <code>meta</code> field changes in config file watcher. (#13460) Thanks @brandonwise.</li>
-<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
-<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
-<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
-<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
-<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
-<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
-<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
-<li>Daemon: suppress <code>EPIPE</code> error when restarting LaunchAgent. (#14343) Thanks @0xRaini.</li>
-<li>Antigravity: add opus 4.6 forward-compat model and bypass thinking signature sanitization. (#14218) Thanks @jg-noncelogic.</li>
-<li>Agents: prevent file descriptor leaks in child process cleanup. (#13565) Thanks @KyleChen26.</li>
-<li>Agents: prevent double compaction caused by cache TTL bypassing guard. (#13514) Thanks @taw0002.</li>
-<li>Agents: use last API call's cache tokens for context display instead of accumulated sum. (#13805) Thanks @akari-musubi.</li>
-<li>Agents: keep followup-runner session <code>totalTokens</code> aligned with post-compaction context by using last-call usage and shared token-accounting logic. (#14979) Thanks @shtse8.</li>
-<li>Hooks/Plugins: wire 9 previously unwired plugin lifecycle hooks into core runtime paths (session, compaction, gateway, and outbound message hooks). (#14882) Thanks @shtse8.</li>
-<li>Hooks/Tools: dispatch <code>before_tool_call</code> and <code>after_tool_call</code> hooks from both tool execution paths with rebased conflict fixes. (#15012) Thanks @Patrick-Barletta, @Takhoffman.</li>
-<li>Discord: allow channel-edit to archive/lock threads and set auto-archive duration. (#5542) Thanks @stumct.</li>
-<li>Discord tests: use a partial @buape/carbon mock in slash command coverage. (#13262) Thanks @arosstale.</li>
-<li>Tests: update thread ID handling in Slack message collection tests. (#14108) Thanks @swizzmagik.</li>
-</ul>
-<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.12/OpenClaw-2026.2.12.zip" length="22877692" type="application/octet-stream" sparkle:edSignature="TGylTM4/7Lab+qp1nuPeOAmEVV1WkafXUPub8ws0z/0mYfbVygRuiev+u3zdPjQWhLnGYTgRgKVyW+kB2+Q2BQ=="/>
-        </item>
     </channel>
 </rss>
\ No newline at end of file
diff --git a/apps/android/app/build.gradle.kts b/apps/android/app/build.gradle.kts
index b7689b252b3..148b2e58a75 100644
--- a/apps/android/app/build.gradle.kts
+++ b/apps/android/app/build.gradle.kts
@@ -21,8 +21,8 @@ android {
     applicationId = "ai.openclaw.android"
     minSdk = 31
     targetSdk = 36
-    versionCode = 202602150
-    versionName = "2026.2.15"
+    versionCode = 202602160
+    versionName = "2026.2.16"
     ndk {
       // Support all major ABIs — native libs are tiny (~47 KB per ABI)
       abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
diff --git a/apps/ios/Sources/Calendar/CalendarService.swift b/apps/ios/Sources/Calendar/CalendarService.swift
index 9ac83dd3928..94b2d9ea3f5 100644
--- a/apps/ios/Sources/Calendar/CalendarService.swift
+++ b/apps/ios/Sources/Calendar/CalendarService.swift
@@ -6,7 +6,7 @@ final class CalendarService: CalendarServicing {
     func events(params: OpenClawCalendarEventsParams) async throws -> OpenClawCalendarEventsPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .event)
-        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsRead(status: status)
         guard authorized else {
             throw NSError(domain: "Calendar", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
@@ -39,7 +39,7 @@ final class CalendarService: CalendarServicing {
     func add(params: OpenClawCalendarAddParams) async throws -> OpenClawCalendarAddPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .event)
-        let authorized = await Self.ensureWriteAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsWrite(status: status)
         guard authorized else {
             throw NSError(domain: "Calendar", code: 2, userInfo: [
                 NSLocalizedDescriptionKey: "CALENDAR_PERMISSION_REQUIRED: grant Calendar permission",
@@ -95,38 +95,6 @@ final class CalendarService: CalendarServicing {
         return OpenClawCalendarAddPayload(event: payload)
     }
 
-    private static func ensureAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        case .fullAccess:
-            return true
-        case .writeOnly:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
-    private static func ensureWriteAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized, .fullAccess, .writeOnly:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
     private static func resolveCalendar(
         store: EKEventStore,
         calendarId: String?,
diff --git a/apps/ios/Sources/Camera/CameraController.swift b/apps/ios/Sources/Camera/CameraController.swift
index e76dbeeabb9..1e9c10bc44c 100644
--- a/apps/ios/Sources/Camera/CameraController.swift
+++ b/apps/ios/Sources/Camera/CameraController.swift
@@ -93,14 +93,10 @@ actor CameraController {
         }
         withExtendedLifetime(delegate) {}
 
-        let maxPayloadBytes = 5 * 1024 * 1024
-        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under 5MB (API limit).
-        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
-        let res = try JPEGTranscoder.transcodeToJPEG(
-            imageData: rawData,
+        let res = try PhotoCapture.transcodeJPEGForGateway(
+            rawData: rawData,
             maxWidthPx: maxWidth,
-            quality: quality,
-            maxBytes: maxEncodedBytes)
+            quality: quality)
 
         return (
             format: format.rawValue,
@@ -335,8 +331,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishProcessingPhoto photo: AVCapturePhoto,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard !self.didResume else { return }
         self.didResume = true
 
@@ -364,8 +360,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard let error else { return }
         guard !self.didResume else { return }
         self.didResume = true
diff --git a/apps/ios/Sources/EventKit/EventKitAuthorization.swift b/apps/ios/Sources/EventKit/EventKitAuthorization.swift
new file mode 100644
index 00000000000..c27e9a3efde
--- /dev/null
+++ b/apps/ios/Sources/EventKit/EventKitAuthorization.swift
@@ -0,0 +1,34 @@
+import EventKit
+
+enum EventKitAuthorization {
+    static func allowsRead(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess:
+            return true
+        case .writeOnly:
+            return false
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+
+    static func allowsWrite(status: EKAuthorizationStatus) -> Bool {
+        switch status {
+        case .authorized, .fullAccess, .writeOnly:
+            return true
+        case .notDetermined:
+            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
+            return false
+        case .restricted, .denied:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+}
+
diff --git a/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift b/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift
index 223cfda5c90..ce1ba4bf2cb 100644
--- a/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift
+++ b/apps/ios/Sources/Gateway/GatewayDiscoveryModel.swift
@@ -136,43 +136,9 @@ final class GatewayDiscoveryModel {
     }
 
     private func updateStatusText() {
-        let states = Array(self.statesByDomain.values)
-        if states.isEmpty {
-            self.statusText = self.browsers.isEmpty ? "Idle" : "Setup"
-            return
-        }
-
-        if let failed = states.first(where: { state in
-            if case .failed = state { return true }
-            return false
-        }) {
-            if case let .failed(err) = failed {
-                self.statusText = "Failed: \(err)"
-                return
-            }
-        }
-
-        if let waiting = states.first(where: { state in
-            if case .waiting = state { return true }
-            return false
-        }) {
-            if case let .waiting(err) = waiting {
-                self.statusText = "Waiting: \(err)"
-                return
-            }
-        }
-
-        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
-            self.statusText = "Searching…"
-            return
-        }
-
-        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
-            self.statusText = "Setup"
-            return
-        }
-
-        self.statusText = "Searching…"
+        self.statusText = GatewayDiscoveryStatusText.make(
+            states: Array(self.statesByDomain.values),
+            hasBrowsers: !self.browsers.isEmpty)
     }
 
     private static func prettyState(_ state: NWBrowser.State) -> String {
diff --git a/apps/ios/Sources/Gateway/GatewaySetupCode.swift b/apps/ios/Sources/Gateway/GatewaySetupCode.swift
new file mode 100644
index 00000000000..8ccbab42da7
--- /dev/null
+++ b/apps/ios/Sources/Gateway/GatewaySetupCode.swift
@@ -0,0 +1,42 @@
+import Foundation
+
+struct GatewaySetupPayload: Codable {
+    var url: String?
+    var host: String?
+    var port: Int?
+    var tls: Bool?
+    var token: String?
+    var password: String?
+}
+
+enum GatewaySetupCode {
+    static func decode(raw: String) -> GatewaySetupPayload? {
+        if let payload = decodeFromJSON(raw) {
+            return payload
+        }
+        if let decoded = decodeBase64Payload(raw),
+           let payload = decodeFromJSON(decoded)
+        {
+            return payload
+        }
+        return nil
+    }
+
+    private static func decodeFromJSON(_ json: String) -> GatewaySetupPayload? {
+        guard let data = json.data(using: .utf8) else { return nil }
+        return try? JSONDecoder().decode(GatewaySetupPayload.self, from: data)
+    }
+
+    private static func decodeBase64Payload(_ raw: String) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        let normalized = trimmed
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let padding = normalized.count % 4
+        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
+        guard let data = Data(base64Encoded: padded) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+}
+
diff --git a/apps/ios/Sources/Gateway/TCPProbe.swift b/apps/ios/Sources/Gateway/TCPProbe.swift
new file mode 100644
index 00000000000..e22da96298f
--- /dev/null
+++ b/apps/ios/Sources/Gateway/TCPProbe.swift
@@ -0,0 +1,43 @@
+import Foundation
+import Network
+import os
+
+enum TCPProbe {
+    static func probe(host: String, port: Int, timeoutSeconds: Double, queueLabel: String) async -> Bool {
+        guard port >= 1, port <= 65535 else { return false }
+        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(port)) else { return false }
+
+        let endpointHost = NWEndpoint.Host(host)
+        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
+
+        return await withCheckedContinuation { cont in
+            let queue = DispatchQueue(label: queueLabel)
+            let finished = OSAllocatedUnfairLock(initialState: false)
+            let finish: @Sendable (Bool) -> Void = { ok in
+                let shouldResume = finished.withLock { flag -> Bool in
+                    if flag { return false }
+                    flag = true
+                    return true
+                }
+                guard shouldResume else { return }
+                connection.cancel()
+                cont.resume(returning: ok)
+            }
+
+            connection.stateUpdateHandler = { state in
+                switch state {
+                case .ready:
+                    finish(true)
+                case .failed, .cancelled:
+                    finish(false)
+                default:
+                    break
+                }
+            }
+
+            connection.start(queue: queue)
+            queue.asyncAfter(deadline: .now() + timeoutSeconds) { finish(false) }
+        }
+    }
+}
+
diff --git a/apps/ios/Sources/Info.plist b/apps/ios/Sources/Info.plist
index 3a4de04847a..6fe56394eed 100644
--- a/apps/ios/Sources/Info.plist
+++ b/apps/ios/Sources/Info.plist
@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 			<string>APPL</string>
 			<key>CFBundleShortVersionString</key>
-			<string>2026.2.15</string>
+			<string>2026.2.16</string>
 			<key>CFBundleVersion</key>
-			<string>20260215</string>
+			<string>20260216</string>
 			<key>NSAppTransportSecurity</key>
 			<dict>
 			<key>NSAllowsArbitraryLoadsInWebContent</key>
diff --git a/apps/ios/Sources/Model/NodeAppModel+Canvas.swift b/apps/ios/Sources/Model/NodeAppModel+Canvas.swift
index 372f8361d30..e8dce2cd30c 100644
--- a/apps/ios/Sources/Model/NodeAppModel+Canvas.swift
+++ b/apps/ios/Sources/Model/NodeAppModel+Canvas.swift
@@ -61,37 +61,10 @@ extension NodeAppModel {
     private static func probeTCP(url: URL, timeoutSeconds: Double) async -> Bool {
         guard let host = url.host, !host.isEmpty else { return false }
         let portInt = url.port ?? ((url.scheme ?? "").lowercased() == "wss" ? 443 : 80)
-        guard portInt >= 1, portInt <= 65535 else { return false }
-        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(portInt)) else { return false }
-
-        let endpointHost = NWEndpoint.Host(host)
-        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
-        return await withCheckedContinuation { cont in
-            let queue = DispatchQueue(label: "a2ui.preflight")
-            let finished = OSAllocatedUnfairLock(initialState: false)
-            let finish: @Sendable (Bool) -> Void = { ok in
-                let shouldResume = finished.withLock { flag -> Bool in
-                    if flag { return false }
-                    flag = true
-                    return true
-                }
-                guard shouldResume else { return }
-                connection.cancel()
-                cont.resume(returning: ok)
-            }
-
-            connection.stateUpdateHandler = { state in
-                switch state {
-                case .ready:
-                    finish(true)
-                case .failed, .cancelled:
-                    finish(false)
-                default:
-                    break
-                }
-            }
-            connection.start(queue: queue)
-            queue.asyncAfter(deadline: .now() + timeoutSeconds) { finish(false) }
-        }
+        return await TCPProbe.probe(
+            host: host,
+            port: portInt,
+            timeoutSeconds: timeoutSeconds,
+            queueLabel: "a2ui.preflight")
     }
 }
diff --git a/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift b/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
index 09c9e2429a6..bf6c0ba2d18 100644
--- a/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
+++ b/apps/ios/Sources/Onboarding/GatewayOnboardingView.swift
@@ -257,15 +257,6 @@ private struct ManualEntryStep: View {
         self.manualPassword = ""
     }
 
-    private struct SetupPayload: Codable {
-        var url: String?
-        var host: String?
-        var port: Int?
-        var tls: Bool?
-        var token: String?
-        var password: String?
-    }
-
     private func applySetupCode() {
         let raw = self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !raw.isEmpty else {
@@ -273,7 +264,7 @@ private struct ManualEntryStep: View {
             return
         }
 
-        guard let payload = self.decodeSetupPayload(raw: raw) else {
+        guard let payload = GatewaySetupCode.decode(raw: raw) else {
             self.setupStatusText = "Setup code not recognized."
             return
         }
@@ -323,34 +314,7 @@ private struct ManualEntryStep: View {
         }
     }
 
-    private func decodeSetupPayload(raw: String) -> SetupPayload? {
-        if let payload = decodeSetupPayloadFromJSON(raw) {
-            return payload
-        }
-        if let decoded = decodeBase64Payload(raw),
-           let payload = decodeSetupPayloadFromJSON(decoded)
-        {
-            return payload
-        }
-        return nil
-    }
-
-    private func decodeSetupPayloadFromJSON(_ json: String) -> SetupPayload? {
-        guard let data = json.data(using: .utf8) else { return nil }
-        return try? JSONDecoder().decode(SetupPayload.self, from: data)
-    }
-
-    private func decodeBase64Payload(_ raw: String) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        let normalized = trimmed
-            .replacingOccurrences(of: "-", with: "+")
-            .replacingOccurrences(of: "_", with: "/")
-        let padding = normalized.count % 4
-        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
-        guard let data = Data(base64Encoded: padded) else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
+    // (GatewaySetupCode) decode raw setup codes.
 }
 
 private struct ConnectionStatusBox: View {
diff --git a/apps/ios/Sources/Reminders/RemindersService.swift b/apps/ios/Sources/Reminders/RemindersService.swift
index 36eea522178..249f439fb17 100644
--- a/apps/ios/Sources/Reminders/RemindersService.swift
+++ b/apps/ios/Sources/Reminders/RemindersService.swift
@@ -6,7 +6,7 @@ final class RemindersService: RemindersServicing {
     func list(params: OpenClawRemindersListParams) async throws -> OpenClawRemindersListPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .reminder)
-        let authorized = await Self.ensureAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsRead(status: status)
         guard authorized else {
             throw NSError(domain: "Reminders", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
@@ -50,7 +50,7 @@ final class RemindersService: RemindersServicing {
     func add(params: OpenClawRemindersAddParams) async throws -> OpenClawRemindersAddPayload {
         let store = EKEventStore()
         let status = EKEventStore.authorizationStatus(for: .reminder)
-        let authorized = await Self.ensureWriteAuthorization(store: store, status: status)
+        let authorized = EventKitAuthorization.allowsWrite(status: status)
         guard authorized else {
             throw NSError(domain: "Reminders", code: 2, userInfo: [
                 NSLocalizedDescriptionKey: "REMINDERS_PERMISSION_REQUIRED: grant Reminders permission",
@@ -100,38 +100,6 @@ final class RemindersService: RemindersServicing {
         return OpenClawRemindersAddPayload(reminder: payload)
     }
 
-    private static func ensureAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        case .fullAccess:
-            return true
-        case .writeOnly:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
-    private static func ensureWriteAuthorization(store: EKEventStore, status: EKAuthorizationStatus) async -> Bool {
-        switch status {
-        case .authorized, .fullAccess, .writeOnly:
-            return true
-        case .notDetermined:
-            // Don’t prompt during node.invoke; prompts block the invoke and lead to timeouts.
-            return false
-        case .restricted, .denied:
-            return false
-        @unknown default:
-            return false
-        }
-    }
-
     private static func resolveList(
         store: EKEventStore,
         listId: String?,
diff --git a/apps/ios/Sources/RootCanvas.swift b/apps/ios/Sources/RootCanvas.swift
index 514e1b4cc47..c8f13eef407 100644
--- a/apps/ios/Sources/RootCanvas.swift
+++ b/apps/ios/Sources/RootCanvas.swift
@@ -256,64 +256,11 @@ private struct CanvasContent: View {
     }
 
     private var statusActivity: StatusPill.Activity? {
-        // Status pill owns transient activity state so it doesn't overlap the connection indicator.
-        if self.appModel.isBackgrounded {
-            return StatusPill.Activity(
-                title: "Foreground required",
-                systemImage: "exclamationmark.triangle.fill",
-                tint: .orange)
-        }
-
-        let gatewayStatus = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
-        let gatewayLower = gatewayStatus.lowercased()
-        if gatewayLower.contains("repair") {
-            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
-        }
-        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
-            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
-        }
-        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
-
-        if self.appModel.screenRecordActive {
-            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
-        }
-
-        if let cameraHUDText, !cameraHUDText.isEmpty, let cameraHUDKind {
-            let systemImage: String
-            let tint: Color?
-            switch cameraHUDKind {
-            case .photo:
-                systemImage = "camera.fill"
-                tint = nil
-            case .recording:
-                systemImage = "video.fill"
-                tint = .red
-            case .success:
-                systemImage = "checkmark.circle.fill"
-                tint = .green
-            case .error:
-                systemImage = "exclamationmark.triangle.fill"
-                tint = .red
-            }
-            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
-        }
-
-        if self.voiceWakeEnabled {
-            let voiceStatus = self.appModel.voiceWake.statusText
-            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
-                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
-            }
-            if voiceStatus == "Paused" {
-                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
-                if self.appModel.talkMode.isEnabled {
-                    return nil
-                }
-                let suffix = self.appModel.isBackgrounded ? " (background)" : ""
-                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
-            }
-        }
-
-        return nil
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.cameraHUDText,
+            cameraHUDKind: self.cameraHUDKind)
     }
 }
 
diff --git a/apps/ios/Sources/RootTabs.swift b/apps/ios/Sources/RootTabs.swift
index 278e56d6150..35786fa89a6 100644
--- a/apps/ios/Sources/RootTabs.swift
+++ b/apps/ios/Sources/RootTabs.swift
@@ -104,66 +104,10 @@ struct RootTabs: View {
     }
 
     private var statusActivity: StatusPill.Activity? {
-        // Keep the top pill consistent across tabs (camera + voice wake + pairing states).
-        if self.appModel.isBackgrounded {
-            return StatusPill.Activity(
-                title: "Foreground required",
-                systemImage: "exclamationmark.triangle.fill",
-                tint: .orange)
-        }
-
-        let gatewayStatus = self.appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
-        let gatewayLower = gatewayStatus.lowercased()
-        if gatewayLower.contains("repair") {
-            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
-        }
-        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
-            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
-        }
-        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
-
-        if self.appModel.screenRecordActive {
-            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
-        }
-
-        if let cameraHUDText = self.appModel.cameraHUDText,
-           let cameraHUDKind = self.appModel.cameraHUDKind,
-           !cameraHUDText.isEmpty
-        {
-            let systemImage: String
-            let tint: Color?
-            switch cameraHUDKind {
-            case .photo:
-                systemImage = "camera.fill"
-                tint = nil
-            case .recording:
-                systemImage = "video.fill"
-                tint = .red
-            case .success:
-                systemImage = "checkmark.circle.fill"
-                tint = .green
-            case .error:
-                systemImage = "exclamationmark.triangle.fill"
-                tint = .red
-            }
-            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
-        }
-
-        if self.voiceWakeEnabled {
-            let voiceStatus = self.appModel.voiceWake.statusText
-            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
-                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
-            }
-            if voiceStatus == "Paused" {
-                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
-                if self.appModel.talkMode.isEnabled {
-                    return nil
-                }
-                let suffix = self.appModel.isBackgrounded ? " (background)" : ""
-                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
-            }
-        }
-
-        return nil
+        StatusActivityBuilder.build(
+            appModel: self.appModel,
+            voiceWakeEnabled: self.voiceWakeEnabled,
+            cameraHUDText: self.appModel.cameraHUDText,
+            cameraHUDKind: self.appModel.cameraHUDKind)
     }
 }
diff --git a/apps/ios/Sources/Settings/SettingsTab.swift b/apps/ios/Sources/Settings/SettingsTab.swift
index 662a22cb049..8eb725df4a1 100644
--- a/apps/ios/Sources/Settings/SettingsTab.swift
+++ b/apps/ios/Sources/Settings/SettingsTab.swift
@@ -304,7 +304,7 @@ struct SettingsTab: View {
                 }
             }
             .onAppear {
-                self.localIPAddress = Self.primaryIPv4Address()
+                self.localIPAddress = NetworkInterfaces.primaryIPv4Address()
                 self.lastLocationModeRaw = self.locationEnabledModeRaw
                 self.syncManualPortText()
                 let trimmedInstanceId = self.instanceId.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -590,15 +590,6 @@ struct SettingsTab: View {
         }
     }
 
-    private struct SetupPayload: Codable {
-        var url: String?
-        var host: String?
-        var port: Int?
-        var tls: Bool?
-        var token: String?
-        var password: String?
-    }
-
     private func applySetupCodeAndConnect() async {
         self.setupStatusText = nil
         guard self.applySetupCode() else { return }
@@ -626,7 +617,7 @@ struct SettingsTab: View {
             return false
         }
 
-        guard let payload = self.decodeSetupPayload(raw: raw) else {
+        guard let payload = GatewaySetupCode.decode(raw: raw) else {
             self.setupStatusText = "Setup code not recognized."
             return false
         }
@@ -727,67 +718,14 @@ struct SettingsTab: View {
     }
 
     private static func probeTCP(host: String, port: Int, timeoutSeconds: Double) async -> Bool {
-        guard let nwPort = NWEndpoint.Port(rawValue: UInt16(port)) else { return false }
-        let endpointHost = NWEndpoint.Host(host)
-        let connection = NWConnection(host: endpointHost, port: nwPort, using: .tcp)
-        return await withCheckedContinuation { cont in
-            let queue = DispatchQueue(label: "gateway.preflight")
-            let finished = OSAllocatedUnfairLock(initialState: false)
-            let finish: @Sendable (Bool) -> Void = { ok in
-                let shouldResume = finished.withLock { flag -> Bool in
-                    if flag { return false }
-                    flag = true
-                    return true
-                }
-                guard shouldResume else { return }
-                connection.cancel()
-                cont.resume(returning: ok)
-            }
-            connection.stateUpdateHandler = { state in
-                switch state {
-                case .ready:
-                    finish(true)
-                case .failed, .cancelled:
-                    finish(false)
-                default:
-                    break
-                }
-            }
-            connection.start(queue: queue)
-            queue.asyncAfter(deadline: .now() + timeoutSeconds) {
-                finish(false)
-            }
-        }
+        await TCPProbe.probe(
+            host: host,
+            port: port,
+            timeoutSeconds: timeoutSeconds,
+            queueLabel: "gateway.preflight")
     }
 
-    private func decodeSetupPayload(raw: String) -> SetupPayload? {
-        if let payload = decodeSetupPayloadFromJSON(raw) {
-            return payload
-        }
-        if let decoded = decodeBase64Payload(raw),
-           let payload = decodeSetupPayloadFromJSON(decoded)
-        {
-            return payload
-        }
-        return nil
-    }
-
-    private func decodeSetupPayloadFromJSON(_ json: String) -> SetupPayload? {
-        guard let data = json.data(using: .utf8) else { return nil }
-        return try? JSONDecoder().decode(SetupPayload.self, from: data)
-    }
-
-    private func decodeBase64Payload(_ raw: String) -> String? {
-        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        let normalized = trimmed
-            .replacingOccurrences(of: "-", with: "+")
-            .replacingOccurrences(of: "_", with: "/")
-        let padding = normalized.count % 4
-        let padded = padding == 0 ? normalized : normalized + String(repeating: "=", count: 4 - padding)
-        guard let data = Data(base64Encoded: padded) else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
+    // (GatewaySetupCode) decode raw setup codes.
 
     private func connectManual() async {
         let host = self.manualGatewayHost.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -852,44 +790,6 @@ struct SettingsTab: View {
         return nil
     }
 
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
-
     private static func hasTailnetIPv4() -> Bool {
         var addrList: UnsafeMutablePointer<ifaddrs>?
         guard getifaddrs(&addrList) == 0, let first = addrList else { return false }
diff --git a/apps/ios/Sources/Status/StatusActivityBuilder.swift b/apps/ios/Sources/Status/StatusActivityBuilder.swift
new file mode 100644
index 00000000000..a335e2f4643
--- /dev/null
+++ b/apps/ios/Sources/Status/StatusActivityBuilder.swift
@@ -0,0 +1,70 @@
+import SwiftUI
+
+enum StatusActivityBuilder {
+    static func build(
+        appModel: NodeAppModel,
+        voiceWakeEnabled: Bool,
+        cameraHUDText: String?,
+        cameraHUDKind: NodeAppModel.CameraHUDKind?
+    ) -> StatusPill.Activity? {
+        // Keep the top pill consistent across tabs (camera + voice wake + pairing states).
+        if appModel.isBackgrounded {
+            return StatusPill.Activity(
+                title: "Foreground required",
+                systemImage: "exclamationmark.triangle.fill",
+                tint: .orange)
+        }
+
+        let gatewayStatus = appModel.gatewayStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let gatewayLower = gatewayStatus.lowercased()
+        if gatewayLower.contains("repair") {
+            return StatusPill.Activity(title: "Repairing…", systemImage: "wrench.and.screwdriver", tint: .orange)
+        }
+        if gatewayLower.contains("approval") || gatewayLower.contains("pairing") {
+            return StatusPill.Activity(title: "Approval pending", systemImage: "person.crop.circle.badge.clock")
+        }
+        // Avoid duplicating the primary gateway status ("Connecting…") in the activity slot.
+
+        if appModel.screenRecordActive {
+            return StatusPill.Activity(title: "Recording screen…", systemImage: "record.circle.fill", tint: .red)
+        }
+
+        if let cameraHUDText, !cameraHUDText.isEmpty, let cameraHUDKind {
+            let systemImage: String
+            let tint: Color?
+            switch cameraHUDKind {
+            case .photo:
+                systemImage = "camera.fill"
+                tint = nil
+            case .recording:
+                systemImage = "video.fill"
+                tint = .red
+            case .success:
+                systemImage = "checkmark.circle.fill"
+                tint = .green
+            case .error:
+                systemImage = "exclamationmark.triangle.fill"
+                tint = .red
+            }
+            return StatusPill.Activity(title: cameraHUDText, systemImage: systemImage, tint: tint)
+        }
+
+        if voiceWakeEnabled {
+            let voiceStatus = appModel.voiceWake.statusText
+            if voiceStatus.localizedCaseInsensitiveContains("microphone permission") {
+                return StatusPill.Activity(title: "Mic permission", systemImage: "mic.slash", tint: .orange)
+            }
+            if voiceStatus == "Paused" {
+                // Talk mode intentionally pauses voice wake to release the mic. Don't spam the HUD for that case.
+                if appModel.talkMode.isEnabled {
+                    return nil
+                }
+                let suffix = appModel.isBackgrounded ? " (background)" : ""
+                return StatusPill.Activity(title: "Voice Wake paused\(suffix)", systemImage: "pause.circle.fill")
+            }
+        }
+
+        return nil
+    }
+}
+
diff --git a/apps/ios/Tests/Info.plist b/apps/ios/Tests/Info.plist
index 257686822d5..e738e064fcd 100644
--- a/apps/ios/Tests/Info.plist
+++ b/apps/ios/Tests/Info.plist
@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 			<string>BNDL</string>
 			<key>CFBundleShortVersionString</key>
-			<string>2026.2.15</string>
+			<string>2026.2.16</string>
 			<key>CFBundleVersion</key>
-			<string>20260215</string>
+			<string>20260216</string>
 		</dict>
 	</plist>
diff --git a/apps/ios/project.yml b/apps/ios/project.yml
index 60cbce1608f..4231172b777 100644
--- a/apps/ios/project.yml
+++ b/apps/ios/project.yml
@@ -81,8 +81,8 @@ targets:
       properties:
         CFBundleDisplayName: OpenClaw
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.2.15"
-        CFBundleVersion: "20260215"
+        CFBundleShortVersionString: "2026.2.16"
+        CFBundleVersion: "20260216"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.2.15"
-        CFBundleVersion: "20260215"
+        CFBundleShortVersionString: "2026.2.16"
+        CFBundleVersion: "20260216"
diff --git a/apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift b/apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift
index d3226839f80..3cb8f54e396 100644
--- a/apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift
+++ b/apps/macos/Sources/OpenClaw/AnyCodable+Helpers.swift
@@ -1,6 +1,5 @@
 import Foundation
 import OpenClawKit
-import OpenClawProtocol
 
 // Prefer the OpenClawKit wrapper to keep gateway request payloads consistent.
 typealias AnyCodable = OpenClawKit.AnyCodable
@@ -42,40 +41,3 @@ extension AnyCodable {
         }
     }
 }
-
-extension OpenClawProtocol.AnyCodable {
-    var stringValue: String? {
-        self.value as? String
-    }
-
-    var boolValue: Bool? {
-        self.value as? Bool
-    }
-
-    var intValue: Int? {
-        self.value as? Int
-    }
-
-    var doubleValue: Double? {
-        self.value as? Double
-    }
-
-    var dictionaryValue: [String: OpenClawProtocol.AnyCodable]? {
-        self.value as? [String: OpenClawProtocol.AnyCodable]
-    }
-
-    var arrayValue: [OpenClawProtocol.AnyCodable]? {
-        self.value as? [OpenClawProtocol.AnyCodable]
-    }
-
-    var foundationValue: Any {
-        switch self.value {
-        case let dict as [String: OpenClawProtocol.AnyCodable]:
-            dict.mapValues { $0.foundationValue }
-        case let array as [OpenClawProtocol.AnyCodable]:
-            array.map(\.foundationValue)
-        default:
-            self.value
-        }
-    }
-}
diff --git a/apps/macos/Sources/OpenClaw/CameraCaptureService.swift b/apps/macos/Sources/OpenClaw/CameraCaptureService.swift
index cfc8c2cde51..24717ec5536 100644
--- a/apps/macos/Sources/OpenClaw/CameraCaptureService.swift
+++ b/apps/macos/Sources/OpenClaw/CameraCaptureService.swift
@@ -106,14 +106,16 @@ actor CameraCaptureService {
         }
         withExtendedLifetime(delegate) {}
 
-        let maxPayloadBytes = 5 * 1024 * 1024
-        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under 5MB (API limit).
-        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
-        let res = try JPEGTranscoder.transcodeToJPEG(
-            imageData: rawData,
-            maxWidthPx: maxWidth,
-            quality: quality,
-            maxBytes: maxEncodedBytes)
+        let res: (data: Data, widthPx: Int, heightPx: Int)
+        do {
+            res = try PhotoCapture.transcodeJPEGForGateway(
+                rawData: rawData,
+                maxWidthPx: maxWidth,
+                quality: quality)
+        } catch {
+            throw CameraError.captureFailed(error.localizedDescription)
+        }
+
         return (data: res.data, size: CGSize(width: res.widthPx, height: res.heightPx))
     }
 
@@ -355,8 +357,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishProcessingPhoto photo: AVCapturePhoto,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard !self.didResume, let cont else { return }
         self.didResume = true
         self.cont = nil
@@ -378,8 +380,8 @@ private final class PhotoCaptureDelegate: NSObject, AVCapturePhotoCaptureDelegat
     func photoOutput(
         _ output: AVCapturePhotoOutput,
         didFinishCaptureFor resolvedSettings: AVCaptureResolvedPhotoSettings,
-        error: Error?)
-    {
+        error: Error?
+    ) {
         guard let error else { return }
         guard !self.didResume, let cont else { return }
         self.didResume = true
diff --git a/apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift b/apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift
index 3cf800fd108..3ed0d67ffbc 100644
--- a/apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift
+++ b/apps/macos/Sources/OpenClaw/CanvasFileWatcher.swift
@@ -1,17 +1,13 @@
-import CoreServices
 import Foundation
 
 final class CanvasFileWatcher: @unchecked Sendable {
-    private let url: URL
-    private let queue: DispatchQueue
-    private var stream: FSEventStreamRef?
-    private var pending = false
-    private let onChange: () -> Void
+    private let watcher: CoalescingFSEventsWatcher
 
     init(url: URL, onChange: @escaping () -> Void) {
-        self.url = url
-        self.queue = DispatchQueue(label: "ai.openclaw.canvaswatcher")
-        self.onChange = onChange
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [url.path],
+            queueLabel: "ai.openclaw.canvaswatcher",
+            onChange: onChange)
     }
 
     deinit {
@@ -19,76 +15,10 @@ final class CanvasFileWatcher: @unchecked Sendable {
     }
 
     func start() {
-        guard self.stream == nil else { return }
-
-        let retainedSelf = Unmanaged.passRetained(self)
-        var context = FSEventStreamContext(
-            version: 0,
-            info: retainedSelf.toOpaque(),
-            retain: nil,
-            release: { pointer in
-                guard let pointer else { return }
-                Unmanaged<CanvasFileWatcher>.fromOpaque(pointer).release()
-            },
-            copyDescription: nil)
-
-        let paths = [self.url.path] as CFArray
-        let flags = FSEventStreamCreateFlags(
-            kFSEventStreamCreateFlagFileEvents |
-                kFSEventStreamCreateFlagUseCFTypes |
-                kFSEventStreamCreateFlagNoDefer)
-
-        guard let stream = FSEventStreamCreate(
-            kCFAllocatorDefault,
-            Self.callback,
-            &context,
-            paths,
-            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-            0.05,
-            flags)
-        else {
-            retainedSelf.release()
-            return
-        }
-
-        self.stream = stream
-        FSEventStreamSetDispatchQueue(stream, self.queue)
-        if FSEventStreamStart(stream) == false {
-            self.stream = nil
-            FSEventStreamSetDispatchQueue(stream, nil)
-            FSEventStreamInvalidate(stream)
-            FSEventStreamRelease(stream)
-        }
+        self.watcher.start()
     }
 
     func stop() {
-        guard let stream = self.stream else { return }
-        self.stream = nil
-        FSEventStreamStop(stream)
-        FSEventStreamSetDispatchQueue(stream, nil)
-        FSEventStreamInvalidate(stream)
-        FSEventStreamRelease(stream)
-    }
-}
-
-extension CanvasFileWatcher {
-    private static let callback: FSEventStreamCallback = { _, info, numEvents, _, eventFlags, _ in
-        guard let info else { return }
-        let watcher = Unmanaged<CanvasFileWatcher>.fromOpaque(info).takeUnretainedValue()
-        watcher.handleEvents(numEvents: numEvents, eventFlags: eventFlags)
-    }
-
-    private func handleEvents(numEvents: Int, eventFlags: UnsafePointer<FSEventStreamEventFlags>?) {
-        guard numEvents > 0 else { return }
-        guard eventFlags != nil else { return }
-
-        // Coalesce rapid changes (common during builds/atomic saves).
-        if self.pending { return }
-        self.pending = true
-        self.queue.asyncAfter(deadline: .now() + 0.12) { [weak self] in
-            guard let self else { return }
-            self.pending = false
-            self.onChange()
-        }
+        self.watcher.stop()
     }
 }
diff --git a/apps/macos/Sources/OpenClaw/CoalescingFSEventsWatcher.swift b/apps/macos/Sources/OpenClaw/CoalescingFSEventsWatcher.swift
new file mode 100644
index 00000000000..7999123dbe2
--- /dev/null
+++ b/apps/macos/Sources/OpenClaw/CoalescingFSEventsWatcher.swift
@@ -0,0 +1,111 @@
+import CoreServices
+import Foundation
+
+final class CoalescingFSEventsWatcher: @unchecked Sendable {
+    private let queue: DispatchQueue
+    private var stream: FSEventStreamRef?
+    private var pending = false
+
+    private let paths: [String]
+    private let shouldNotify: (Int, UnsafeMutableRawPointer?) -> Bool
+    private let onChange: () -> Void
+    private let coalesceDelay: TimeInterval
+
+    init(
+        paths: [String],
+        queueLabel: String,
+        coalesceDelay: TimeInterval = 0.12,
+        shouldNotify: @escaping (Int, UnsafeMutableRawPointer?) -> Bool = { _, _ in true },
+        onChange: @escaping () -> Void
+    ) {
+        self.paths = paths
+        self.queue = DispatchQueue(label: queueLabel)
+        self.coalesceDelay = coalesceDelay
+        self.shouldNotify = shouldNotify
+        self.onChange = onChange
+    }
+
+    deinit {
+        self.stop()
+    }
+
+    func start() {
+        guard self.stream == nil else { return }
+
+        let retainedSelf = Unmanaged.passRetained(self)
+        var context = FSEventStreamContext(
+            version: 0,
+            info: retainedSelf.toOpaque(),
+            retain: nil,
+            release: { pointer in
+                guard let pointer else { return }
+                Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(pointer).release()
+            },
+            copyDescription: nil)
+
+        let paths = self.paths as CFArray
+        let flags = FSEventStreamCreateFlags(
+            kFSEventStreamCreateFlagFileEvents |
+                kFSEventStreamCreateFlagUseCFTypes |
+                kFSEventStreamCreateFlagNoDefer)
+
+        guard let stream = FSEventStreamCreate(
+            kCFAllocatorDefault,
+            Self.callback,
+            &context,
+            paths,
+            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.05,
+            flags)
+        else {
+            retainedSelf.release()
+            return
+        }
+
+        self.stream = stream
+        FSEventStreamSetDispatchQueue(stream, self.queue)
+        if FSEventStreamStart(stream) == false {
+            self.stream = nil
+            FSEventStreamSetDispatchQueue(stream, nil)
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+        }
+    }
+
+    func stop() {
+        guard let stream = self.stream else { return }
+        self.stream = nil
+        FSEventStreamStop(stream)
+        FSEventStreamSetDispatchQueue(stream, nil)
+        FSEventStreamInvalidate(stream)
+        FSEventStreamRelease(stream)
+    }
+}
+
+extension CoalescingFSEventsWatcher {
+    private static let callback: FSEventStreamCallback = { _, info, numEvents, eventPaths, eventFlags, _ in
+        guard let info else { return }
+        let watcher = Unmanaged<CoalescingFSEventsWatcher>.fromOpaque(info).takeUnretainedValue()
+        watcher.handleEvents(numEvents: numEvents, eventPaths: eventPaths, eventFlags: eventFlags)
+    }
+
+    private func handleEvents(
+        numEvents: Int,
+        eventPaths: UnsafeMutableRawPointer?,
+        eventFlags: UnsafePointer<FSEventStreamEventFlags>?
+    ) {
+        guard numEvents > 0 else { return }
+        guard eventFlags != nil else { return }
+        guard self.shouldNotify(numEvents, eventPaths) else { return }
+
+        // Coalesce rapid changes (common during builds/atomic saves).
+        if self.pending { return }
+        self.pending = true
+        self.queue.asyncAfter(deadline: .now() + self.coalesceDelay) { [weak self] in
+            guard let self else { return }
+            self.pending = false
+            self.onChange()
+        }
+    }
+}
+
diff --git a/apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift b/apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift
index 23689f1fb9d..4434443497e 100644
--- a/apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift
+++ b/apps/macos/Sources/OpenClaw/ConfigFileWatcher.swift
@@ -1,23 +1,34 @@
-import CoreServices
 import Foundation
 
 final class ConfigFileWatcher: @unchecked Sendable {
     private let url: URL
-    private let queue: DispatchQueue
-    private var stream: FSEventStreamRef?
-    private var pending = false
-    private let onChange: () -> Void
     private let watchedDir: URL
     private let targetPath: String
     private let targetName: String
+    private let watcher: CoalescingFSEventsWatcher
 
     init(url: URL, onChange: @escaping () -> Void) {
         self.url = url
-        self.queue = DispatchQueue(label: "ai.openclaw.configwatcher")
-        self.onChange = onChange
         self.watchedDir = url.deletingLastPathComponent()
         self.targetPath = url.path
         self.targetName = url.lastPathComponent
+        let watchedDirPath = self.watchedDir.path
+        let targetPath = self.targetPath
+        let targetName = self.targetName
+        self.watcher = CoalescingFSEventsWatcher(
+            paths: [watchedDirPath],
+            queueLabel: "ai.openclaw.configwatcher",
+            shouldNotify: { _, eventPaths in
+                guard let eventPaths else { return true }
+                let paths = unsafeBitCast(eventPaths, to: NSArray.self)
+                for case let path as String in paths {
+                    if path == targetPath { return true }
+                    if path.hasSuffix("/\(targetName)") { return true }
+                    if path == watchedDirPath { return true }
+                }
+                return false
+            },
+            onChange: onChange)
     }
 
     deinit {
@@ -25,94 +36,10 @@ final class ConfigFileWatcher: @unchecked Sendable {
     }
 
     func start() {
-        guard self.stream == nil else { return }
-
-        let retainedSelf = Unmanaged.passRetained(self)
-        var context = FSEventStreamContext(
-            version: 0,
-            info: retainedSelf.toOpaque(),
-            retain: nil,
-            release: { pointer in
-                guard let pointer else { return }
-                Unmanaged<ConfigFileWatcher>.fromOpaque(pointer).release()
-            },
-            copyDescription: nil)
-
-        let paths = [self.watchedDir.path] as CFArray
-        let flags = FSEventStreamCreateFlags(
-            kFSEventStreamCreateFlagFileEvents |
-                kFSEventStreamCreateFlagUseCFTypes |
-                kFSEventStreamCreateFlagNoDefer)
-
-        guard let stream = FSEventStreamCreate(
-            kCFAllocatorDefault,
-            Self.callback,
-            &context,
-            paths,
-            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-            0.05,
-            flags)
-        else {
-            retainedSelf.release()
-            return
-        }
-
-        self.stream = stream
-        FSEventStreamSetDispatchQueue(stream, self.queue)
-        if FSEventStreamStart(stream) == false {
-            self.stream = nil
-            FSEventStreamSetDispatchQueue(stream, nil)
-            FSEventStreamInvalidate(stream)
-            FSEventStreamRelease(stream)
-        }
+        self.watcher.start()
     }
 
     func stop() {
-        guard let stream = self.stream else { return }
-        self.stream = nil
-        FSEventStreamStop(stream)
-        FSEventStreamSetDispatchQueue(stream, nil)
-        FSEventStreamInvalidate(stream)
-        FSEventStreamRelease(stream)
-    }
-}
-
-extension ConfigFileWatcher {
-    private static let callback: FSEventStreamCallback = { _, info, numEvents, eventPaths, eventFlags, _ in
-        guard let info else { return }
-        let watcher = Unmanaged<ConfigFileWatcher>.fromOpaque(info).takeUnretainedValue()
-        watcher.handleEvents(
-            numEvents: numEvents,
-            eventPaths: eventPaths,
-            eventFlags: eventFlags)
-    }
-
-    private func handleEvents(
-        numEvents: Int,
-        eventPaths: UnsafeMutableRawPointer?,
-        eventFlags: UnsafePointer<FSEventStreamEventFlags>?)
-    {
-        guard numEvents > 0 else { return }
-        guard eventFlags != nil else { return }
-        guard self.matchesTarget(eventPaths: eventPaths) else { return }
-
-        if self.pending { return }
-        self.pending = true
-        self.queue.asyncAfter(deadline: .now() + 0.12) { [weak self] in
-            guard let self else { return }
-            self.pending = false
-            self.onChange()
-        }
-    }
-
-    private func matchesTarget(eventPaths: UnsafeMutableRawPointer?) -> Bool {
-        guard let eventPaths else { return true }
-        let paths = unsafeBitCast(eventPaths, to: NSArray.self)
-        for case let path as String in paths {
-            if path == self.targetPath { return true }
-            if path.hasSuffix("/\(self.targetName)") { return true }
-            if path == self.watchedDir.path { return true }
-        }
-        return false
+        self.watcher.stop()
     }
 }
diff --git a/apps/macos/Sources/OpenClaw/CronModels.swift b/apps/macos/Sources/OpenClaw/CronModels.swift
index 43f0fa037d0..cbfbc061d6a 100644
--- a/apps/macos/Sources/OpenClaw/CronModels.swift
+++ b/apps/macos/Sources/OpenClaw/CronModels.swift
@@ -21,6 +21,7 @@ enum CronWakeMode: String, CaseIterable, Identifiable, Codable {
 enum CronDeliveryMode: String, CaseIterable, Identifiable, Codable {
     case none
     case announce
+    case webhook
 
     var id: String {
         self.rawValue
diff --git a/apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift b/apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift
index 195ab66daf9..f85e8d1a5df 100644
--- a/apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift
+++ b/apps/macos/Sources/OpenClaw/DevicePairingApprovalPrompter.swift
@@ -22,16 +22,6 @@ final class DevicePairingApprovalPrompter {
     private var alertHostWindow: NSWindow?
     private var resolvedByRequestId: Set<String> = []
 
-    private final class AlertHostWindow: NSWindow {
-        override var canBecomeKey: Bool {
-            true
-        }
-
-        override var canBecomeMain: Bool {
-            true
-        }
-    }
-
     private struct PairingList: Codable {
         let pending: [PendingRequest]
         let paired: [PairedDevice]?
@@ -238,35 +228,11 @@ final class DevicePairingApprovalPrompter {
     }
 
     private func endActiveAlert() {
-        guard let alert = self.activeAlert else { return }
-        if let parent = alert.window.sheetParent {
-            parent.endSheet(alert.window, returnCode: .abort)
-        }
-        self.activeAlert = nil
-        self.activeRequestId = nil
+        PairingAlertSupport.endActiveAlert(activeAlert: &self.activeAlert, activeRequestId: &self.activeRequestId)
     }
 
     private func requireAlertHostWindow() -> NSWindow {
-        if let alertHostWindow {
-            return alertHostWindow
-        }
-
-        let window = AlertHostWindow(
-            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
-            styleMask: [.borderless],
-            backing: .buffered,
-            defer: false)
-        window.title = ""
-        window.isReleasedWhenClosed = false
-        window.level = .floating
-        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        window.isOpaque = false
-        window.hasShadow = false
-        window.backgroundColor = .clear
-        window.ignoresMouseEvents = true
-
-        self.alertHostWindow = window
-        return window
+        PairingAlertSupport.requireAlertHostWindow(alertHostWindow: &self.alertHostWindow)
     }
 
     private func handle(push: GatewayPush) {
diff --git a/apps/macos/Sources/OpenClaw/InstancesStore.swift b/apps/macos/Sources/OpenClaw/InstancesStore.swift
index 929f12c1699..566340337db 100644
--- a/apps/macos/Sources/OpenClaw/InstancesStore.swift
+++ b/apps/macos/Sources/OpenClaw/InstancesStore.swift
@@ -158,7 +158,7 @@ final class InstancesStore {
 
     private func localFallbackInstance(reason: String) -> InstanceInfo {
         let host = Host.current().localizedName ?? "this-mac"
-        let ip = Self.primaryIPv4Address()
+        let ip = SystemPresenceInfo.primaryIPv4Address()
         let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
         let osVersion = ProcessInfo.processInfo.operatingSystemVersion
         let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
@@ -172,58 +172,13 @@ final class InstancesStore {
             platform: platform,
             deviceFamily: "Mac",
             modelIdentifier: InstanceIdentity.modelIdentifier,
-            lastInputSeconds: Self.lastInputSeconds(),
+            lastInputSeconds: SystemPresenceInfo.lastInputSeconds(),
             mode: "local",
             reason: reason,
             text: text,
             ts: ts)
     }
 
-    private static func lastInputSeconds() -> Int? {
-        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
-        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
-        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
-        return Int(seconds.rounded())
-    }
-
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
-
     // MARK: - Helpers
 
     /// Keep the last raw payload for logging.
diff --git a/apps/macos/Sources/OpenClaw/NodePairingApprovalPrompter.swift b/apps/macos/Sources/OpenClaw/NodePairingApprovalPrompter.swift
index 964b340e6b5..ee994b38f65 100644
--- a/apps/macos/Sources/OpenClaw/NodePairingApprovalPrompter.swift
+++ b/apps/macos/Sources/OpenClaw/NodePairingApprovalPrompter.swift
@@ -38,16 +38,6 @@ final class NodePairingApprovalPrompter {
     private var remoteResolutionsByRequestId: [String: PairingResolution] = [:]
     private var autoApproveAttempts: Set<String> = []
 
-    private final class AlertHostWindow: NSWindow {
-        override var canBecomeKey: Bool {
-            true
-        }
-
-        override var canBecomeMain: Bool {
-            true
-        }
-    }
-
     private struct PairingList: Codable {
         let pending: [PendingRequest]
         let paired: [PairedNode]?
@@ -242,35 +232,11 @@ final class NodePairingApprovalPrompter {
     }
 
     private func endActiveAlert() {
-        guard let alert = self.activeAlert else { return }
-        if let parent = alert.window.sheetParent {
-            parent.endSheet(alert.window, returnCode: .abort)
-        }
-        self.activeAlert = nil
-        self.activeRequestId = nil
+        PairingAlertSupport.endActiveAlert(activeAlert: &self.activeAlert, activeRequestId: &self.activeRequestId)
     }
 
     private func requireAlertHostWindow() -> NSWindow {
-        if let alertHostWindow {
-            return alertHostWindow
-        }
-
-        let window = AlertHostWindow(
-            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
-            styleMask: [.borderless],
-            backing: .buffered,
-            defer: false)
-        window.title = ""
-        window.isReleasedWhenClosed = false
-        window.level = .floating
-        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-        window.isOpaque = false
-        window.hasShadow = false
-        window.backgroundColor = .clear
-        window.ignoresMouseEvents = true
-
-        self.alertHostWindow = window
-        return window
+        PairingAlertSupport.requireAlertHostWindow(alertHostWindow: &self.alertHostWindow)
     }
 
     private func handle(push: GatewayPush) {
diff --git a/apps/macos/Sources/OpenClaw/PairingAlertSupport.swift b/apps/macos/Sources/OpenClaw/PairingAlertSupport.swift
new file mode 100644
index 00000000000..e8e4428bf3f
--- /dev/null
+++ b/apps/macos/Sources/OpenClaw/PairingAlertSupport.swift
@@ -0,0 +1,46 @@
+import AppKit
+
+final class PairingAlertHostWindow: NSWindow {
+    override var canBecomeKey: Bool {
+        true
+    }
+
+    override var canBecomeMain: Bool {
+        true
+    }
+}
+
+@MainActor
+enum PairingAlertSupport {
+    static func endActiveAlert(activeAlert: inout NSAlert?, activeRequestId: inout String?) {
+        guard let alert = activeAlert else { return }
+        if let parent = alert.window.sheetParent {
+            parent.endSheet(alert.window, returnCode: .abort)
+        }
+        activeAlert = nil
+        activeRequestId = nil
+    }
+
+    static func requireAlertHostWindow(alertHostWindow: inout NSWindow?) -> NSWindow {
+        if let alertHostWindow {
+            return alertHostWindow
+        }
+
+        let window = PairingAlertHostWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 520, height: 1),
+            styleMask: [.borderless],
+            backing: .buffered,
+            defer: false)
+        window.title = ""
+        window.isReleasedWhenClosed = false
+        window.level = .floating
+        window.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+        window.isOpaque = false
+        window.hasShadow = false
+        window.backgroundColor = .clear
+        window.ignoresMouseEvents = true
+
+        alertHostWindow = window
+        return window
+    }
+}
diff --git a/apps/macos/Sources/OpenClaw/PresenceReporter.swift b/apps/macos/Sources/OpenClaw/PresenceReporter.swift
index 16d70b8a92c..2e7a1d4c472 100644
--- a/apps/macos/Sources/OpenClaw/PresenceReporter.swift
+++ b/apps/macos/Sources/OpenClaw/PresenceReporter.swift
@@ -1,5 +1,4 @@
 import Cocoa
-import Darwin
 import Foundation
 import OSLog
 
@@ -33,10 +32,10 @@ final class PresenceReporter {
     private func push(reason: String) async {
         let mode = await MainActor.run { AppStateStore.shared.connectionMode.rawValue }
         let host = InstanceIdentity.displayName
-        let ip = Self.primaryIPv4Address() ?? "ip-unknown"
+        let ip = SystemPresenceInfo.primaryIPv4Address() ?? "ip-unknown"
         let version = Self.appVersionString()
         let platform = Self.platformString()
-        let lastInput = Self.lastInputSeconds()
+        let lastInput = SystemPresenceInfo.lastInputSeconds()
         let text = Self.composePresenceSummary(mode: mode, reason: reason)
         var params: [String: AnyHashable] = [
             "instanceId": AnyHashable(self.instanceId),
@@ -64,9 +63,9 @@ final class PresenceReporter {
 
     private static func composePresenceSummary(mode: String, reason: String) -> String {
         let host = InstanceIdentity.displayName
-        let ip = Self.primaryIPv4Address() ?? "ip-unknown"
+        let ip = SystemPresenceInfo.primaryIPv4Address() ?? "ip-unknown"
         let version = Self.appVersionString()
-        let lastInput = Self.lastInputSeconds()
+        let lastInput = SystemPresenceInfo.lastInputSeconds()
         let lastLabel = lastInput.map { "last input \($0)s ago" } ?? "last input unknown"
         return "Node: \(host) (\(ip)) · app \(version) · \(lastLabel) · mode \(mode) · reason \(reason)"
     }
@@ -87,50 +86,7 @@ final class PresenceReporter {
         return "macos \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
     }
 
-    private static func lastInputSeconds() -> Int? {
-        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
-        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
-        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
-        return Int(seconds.rounded())
-    }
-
-    private static func primaryIPv4Address() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        var fallback: String?
-        var en0: String?
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let name = String(cString: ptr.pointee.ifa_name)
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-
-            if name == "en0" { en0 = ip; break }
-            if fallback == nil { fallback = ip }
-        }
-
-        return en0 ?? fallback
-    }
+    // (SystemPresenceInfo) last input + primary IPv4.
 }
 
 #if DEBUG
@@ -148,11 +104,11 @@ extension PresenceReporter {
     }
 
     static func _testLastInputSeconds() -> Int? {
-        self.lastInputSeconds()
+        SystemPresenceInfo.lastInputSeconds()
     }
 
     static func _testPrimaryIPv4Address() -> String? {
-        self.primaryIPv4Address()
+        SystemPresenceInfo.primaryIPv4Address()
     }
 }
 #endif
diff --git a/apps/macos/Sources/OpenClaw/Resources/Info.plist b/apps/macos/Sources/OpenClaw/Resources/Info.plist
index c57ed6ac808..37c85b6f3dd 100644
--- a/apps/macos/Sources/OpenClaw/Resources/Info.plist
+++ b/apps/macos/Sources/OpenClaw/Resources/Info.plist
@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.2.15</string>
+    <string>2026.2.16</string>
     <key>CFBundleVersion</key>
-    <string>202602150</string>
+    <string>202602160</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>
diff --git a/apps/macos/Sources/OpenClaw/SystemPresenceInfo.swift b/apps/macos/Sources/OpenClaw/SystemPresenceInfo.swift
new file mode 100644
index 00000000000..843ed371fb5
--- /dev/null
+++ b/apps/macos/Sources/OpenClaw/SystemPresenceInfo.swift
@@ -0,0 +1,16 @@
+import CoreGraphics
+import Foundation
+import OpenClawKit
+
+enum SystemPresenceInfo {
+    static func lastInputSeconds() -> Int? {
+        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
+        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
+        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
+        return Int(seconds.rounded())
+    }
+
+    static func primaryIPv4Address() -> String? {
+        NetworkInterfaces.primaryIPv4Address()
+    }
+}
diff --git a/apps/macos/Sources/OpenClaw/TailscaleService.swift b/apps/macos/Sources/OpenClaw/TailscaleService.swift
index b7f716a4270..2cefa69d59d 100644
--- a/apps/macos/Sources/OpenClaw/TailscaleService.swift
+++ b/apps/macos/Sources/OpenClaw/TailscaleService.swift
@@ -1,10 +1,8 @@
 import AppKit
 import Foundation
 import Observation
+import OpenClawDiscovery
 import os
-#if canImport(Darwin)
-import Darwin
-#endif
 
 /// Manages Tailscale integration and status checking.
 @Observable
@@ -140,7 +138,7 @@ final class TailscaleService {
             self.logger.info("Tailscale API not responding; app likely not running")
         }
 
-        if self.tailscaleIP == nil, let fallback = Self.detectTailnetIPv4() {
+        if self.tailscaleIP == nil, let fallback = TailscaleNetwork.detectTailnetIPv4() {
             self.tailscaleIP = fallback
             if !self.isRunning {
                 self.isRunning = true
@@ -178,49 +176,7 @@ final class TailscaleService {
         }
     }
 
-    private nonisolated static func isTailnetIPv4(_ address: String) -> Bool {
-        let parts = address.split(separator: ".")
-        guard parts.count == 4 else { return false }
-        let octets = parts.compactMap { Int($0) }
-        guard octets.count == 4 else { return false }
-        let a = octets[0]
-        let b = octets[1]
-        return a == 100 && b >= 64 && b <= 127
-    }
-
-    private nonisolated static func detectTailnetIPv4() -> String? {
-        var addrList: UnsafeMutablePointer<ifaddrs>?
-        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-        defer { freeifaddrs(addrList) }
-
-        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-            let flags = Int32(ptr.pointee.ifa_flags)
-            let isUp = (flags & IFF_UP) != 0
-            let isLoopback = (flags & IFF_LOOPBACK) != 0
-            let family = ptr.pointee.ifa_addr.pointee.sa_family
-            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-            var addr = ptr.pointee.ifa_addr.pointee
-            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-            let result = getnameinfo(
-                &addr,
-                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-                &buffer,
-                socklen_t(buffer.count),
-                nil,
-                0,
-                NI_NUMERICHOST)
-            guard result == 0 else { continue }
-            let len = buffer.prefix { $0 != 0 }
-            let bytes = len.map { UInt8(bitPattern: $0) }
-            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-            if Self.isTailnetIPv4(ip) { return ip }
-        }
-
-        return nil
-    }
-
     nonisolated static func fallbackTailnetIPv4() -> String? {
-        self.detectTailnetIPv4()
+        TailscaleNetwork.detectTailnetIPv4()
     }
 }
diff --git a/apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift b/apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift
index 3c59ea792f1..abd18efaa9a 100644
--- a/apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift
+++ b/apps/macos/Sources/OpenClawDiscovery/GatewayDiscoveryModel.swift
@@ -329,43 +329,9 @@ public final class GatewayDiscoveryModel {
     }
 
     private func updateStatusText() {
-        let states = Array(self.statesByDomain.values)
-        if states.isEmpty {
-            self.statusText = self.browsers.isEmpty ? "Idle" : "Setup"
-            return
-        }
-
-        if let failed = states.first(where: { state in
-            if case .failed = state { return true }
-            return false
-        }) {
-            if case let .failed(err) = failed {
-                self.statusText = "Failed: \(err)"
-                return
-            }
-        }
-
-        if let waiting = states.first(where: { state in
-            if case .waiting = state { return true }
-            return false
-        }) {
-            if case let .waiting(err) = waiting {
-                self.statusText = "Waiting: \(err)"
-                return
-            }
-        }
-
-        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
-            self.statusText = "Searching…"
-            return
-        }
-
-        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
-            self.statusText = "Setup"
-            return
-        }
-
-        self.statusText = "Searching…"
+        self.statusText = GatewayDiscoveryStatusText.make(
+            states: Array(self.statesByDomain.values),
+            hasBrowsers: !self.browsers.isEmpty)
     }
 
     private static func txtDictionary(from result: NWBrowser.Result) -> [String: String] {
diff --git a/apps/macos/Sources/OpenClawDiscovery/TailscaleNetwork.swift b/apps/macos/Sources/OpenClawDiscovery/TailscaleNetwork.swift
new file mode 100644
index 00000000000..60b11306d05
--- /dev/null
+++ b/apps/macos/Sources/OpenClawDiscovery/TailscaleNetwork.swift
@@ -0,0 +1,47 @@
+import Darwin
+import Foundation
+
+public enum TailscaleNetwork {
+    public static func isTailnetIPv4(_ address: String) -> Bool {
+        let parts = address.split(separator: ".")
+        guard parts.count == 4 else { return false }
+        let octets = parts.compactMap { Int($0) }
+        guard octets.count == 4 else { return false }
+        let a = octets[0]
+        let b = octets[1]
+        return a == 100 && b >= 64 && b <= 127
+    }
+
+    public static func detectTailnetIPv4() -> String? {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
+        defer { freeifaddrs(addrList) }
+
+        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
+            let flags = Int32(ptr.pointee.ifa_flags)
+            let isUp = (flags & IFF_UP) != 0
+            let isLoopback = (flags & IFF_LOOPBACK) != 0
+            let family = ptr.pointee.ifa_addr.pointee.sa_family
+            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
+
+            var addr = ptr.pointee.ifa_addr.pointee
+            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+            let result = getnameinfo(
+                &addr,
+                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
+                &buffer,
+                socklen_t(buffer.count),
+                nil,
+                0,
+                NI_NUMERICHOST)
+            guard result == 0 else { continue }
+            let len = buffer.prefix { $0 != 0 }
+            let bytes = len.map { UInt8(bitPattern: $0) }
+            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
+            if self.isTailnetIPv4(ip) { return ip }
+        }
+
+        return nil
+    }
+}
+
diff --git a/apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift b/apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift
index 2933e9242f1..0989164a01e 100644
--- a/apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift
+++ b/apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift
@@ -1,9 +1,7 @@
 import Foundation
+import OpenClawDiscovery
 import OpenClawKit
 import OpenClawProtocol
-#if canImport(Darwin)
-import Darwin
-#endif
 
 struct ConnectOptions {
     var url: String?
@@ -301,7 +299,7 @@ private func resolvedPassword(opts: ConnectOptions, mode: String, config: Gatewa
 
 private func resolveLocalHost(bind: String?) -> String {
     let normalized = (bind ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-    let tailnetIP = detectTailnetIPv4()
+    let tailnetIP = TailscaleNetwork.detectTailnetIPv4()
     switch normalized {
     case "tailnet":
         return tailnetIP ?? "127.0.0.1"
@@ -309,45 +307,3 @@ private func resolveLocalHost(bind: String?) -> String {
         return "127.0.0.1"
     }
 }
-
-private func detectTailnetIPv4() -> String? {
-    var addrList: UnsafeMutablePointer<ifaddrs>?
-    guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
-    defer { freeifaddrs(addrList) }
-
-    for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
-        let flags = Int32(ptr.pointee.ifa_flags)
-        let isUp = (flags & IFF_UP) != 0
-        let isLoopback = (flags & IFF_LOOPBACK) != 0
-        let family = ptr.pointee.ifa_addr.pointee.sa_family
-        if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
-
-        var addr = ptr.pointee.ifa_addr.pointee
-        var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
-        let result = getnameinfo(
-            &addr,
-            socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
-            &buffer,
-            socklen_t(buffer.count),
-            nil,
-            0,
-            NI_NUMERICHOST)
-        guard result == 0 else { continue }
-        let len = buffer.prefix { $0 != 0 }
-        let bytes = len.map { UInt8(bitPattern: $0) }
-        guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
-        if isTailnetIPv4(ip) { return ip }
-    }
-
-    return nil
-}
-
-private func isTailnetIPv4(_ address: String) -> Bool {
-    let parts = address.split(separator: ".")
-    guard parts.count == 4 else { return false }
-    let octets = parts.compactMap { Int($0) }
-    guard octets.count == 4 else { return false }
-    let a = octets[0]
-    let b = octets[1]
-    return a == 100 && b >= 64 && b <= 127
-}
diff --git a/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift b/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
index 29a4059b334..8486e4c4551 100644
--- a/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
+++ b/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
@@ -2094,7 +2094,7 @@ public struct CronJob: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
     public let state: [String: AnyCodable]
 
     public init(
@@ -2110,7 +2110,7 @@ public struct CronJob: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?,
+        delivery: AnyCodable?,
         state: [String: AnyCodable]
     ) {
         self.id = id
@@ -2172,7 +2172,7 @@ public struct CronAddParams: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
 
     public init(
         name: String,
@@ -2184,7 +2184,7 @@ public struct CronAddParams: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?
+        delivery: AnyCodable?
     ) {
         self.name = name
         self.agentid = agentid
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
index 272fd81c11d..5328a5b692f 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
@@ -103,18 +103,22 @@ public final class OpenClawChatViewModel {
         let now = Date().timeIntervalSince1970 * 1000
         let cutoff = now - (24 * 60 * 60 * 1000)
         let sorted = self.sessions.sorted { ($0.updatedAt ?? 0) > ($1.updatedAt ?? 0) }
-        var seen = Set<String>()
-        var recent: [OpenClawChatSessionEntry] = []
-        for entry in sorted {
-            guard !seen.contains(entry.key) else { continue }
-            seen.insert(entry.key)
-            guard (entry.updatedAt ?? 0) >= cutoff else { continue }
-            recent.append(entry)
-        }
 
         var result: [OpenClawChatSessionEntry] = []
         var included = Set<String>()
-        for entry in recent where !included.contains(entry.key) {
+
+        // Always show the main session first, even if it hasn't been updated recently.
+        if let main = sorted.first(where: { $0.key == "main" }) {
+            result.append(main)
+            included.insert(main.key)
+        } else {
+            result.append(self.placeholderSession(key: "main"))
+            included.insert("main")
+        }
+
+        for entry in sorted {
+            guard !included.contains(entry.key) else { continue }
+            guard (entry.updatedAt ?? 0) >= cutoff else { continue }
             result.append(entry)
             included.insert(entry.key)
         }
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift
index ef522447f43..02b53e3c392 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift
@@ -1,93 +1,4 @@
-import Foundation
+import OpenClawProtocol
 
-/// Lightweight `Codable` wrapper that round-trips heterogeneous JSON payloads.
-///
-/// Marked `@unchecked Sendable` because it can hold reference types.
-public struct AnyCodable: Codable, @unchecked Sendable, Hashable {
-    public let value: Any
+public typealias AnyCodable = OpenClawProtocol.AnyCodable
 
-    public init(_ value: Any) { self.value = value }
-
-    public init(from decoder: Decoder) throws {
-        let container = try decoder.singleValueContainer()
-        if let intVal = try? container.decode(Int.self) { self.value = intVal; return }
-        if let doubleVal = try? container.decode(Double.self) { self.value = doubleVal; return }
-        if let boolVal = try? container.decode(Bool.self) { self.value = boolVal; return }
-        if let stringVal = try? container.decode(String.self) { self.value = stringVal; return }
-        if container.decodeNil() { self.value = NSNull(); return }
-        if let dict = try? container.decode([String: AnyCodable].self) { self.value = dict; return }
-        if let array = try? container.decode([AnyCodable].self) { self.value = array; return }
-        throw DecodingError.dataCorruptedError(in: container, debugDescription: "Unsupported type")
-    }
-
-    public func encode(to encoder: Encoder) throws {
-        var container = encoder.singleValueContainer()
-        switch self.value {
-        case let intVal as Int: try container.encode(intVal)
-        case let doubleVal as Double: try container.encode(doubleVal)
-        case let boolVal as Bool: try container.encode(boolVal)
-        case let stringVal as String: try container.encode(stringVal)
-        case is NSNull: try container.encodeNil()
-        case let dict as [String: AnyCodable]: try container.encode(dict)
-        case let array as [AnyCodable]: try container.encode(array)
-        case let dict as [String: Any]:
-            try container.encode(dict.mapValues { AnyCodable($0) })
-        case let array as [Any]:
-            try container.encode(array.map { AnyCodable($0) })
-        case let dict as NSDictionary:
-            var converted: [String: AnyCodable] = [:]
-            for (k, v) in dict {
-                guard let key = k as? String else { continue }
-                converted[key] = AnyCodable(v)
-            }
-            try container.encode(converted)
-        case let array as NSArray:
-            try container.encode(array.map { AnyCodable($0) })
-        default:
-            let context = EncodingError.Context(codingPath: encoder.codingPath, debugDescription: "Unsupported type")
-            throw EncodingError.invalidValue(self.value, context)
-        }
-    }
-
-    public static func == (lhs: AnyCodable, rhs: AnyCodable) -> Bool {
-        switch (lhs.value, rhs.value) {
-        case let (l as Int, r as Int): l == r
-        case let (l as Double, r as Double): l == r
-        case let (l as Bool, r as Bool): l == r
-        case let (l as String, r as String): l == r
-        case (_ as NSNull, _ as NSNull): true
-        case let (l as [String: AnyCodable], r as [String: AnyCodable]): l == r
-        case let (l as [AnyCodable], r as [AnyCodable]): l == r
-        default:
-            false
-        }
-    }
-
-    public func hash(into hasher: inout Hasher) {
-        switch self.value {
-        case let v as Int:
-            hasher.combine(0); hasher.combine(v)
-        case let v as Double:
-            hasher.combine(1); hasher.combine(v)
-        case let v as Bool:
-            hasher.combine(2); hasher.combine(v)
-        case let v as String:
-            hasher.combine(3); hasher.combine(v)
-        case _ as NSNull:
-            hasher.combine(4)
-        case let v as [String: AnyCodable]:
-            hasher.combine(5)
-            for (k, val) in v.sorted(by: { $0.key < $1.key }) {
-                hasher.combine(k)
-                hasher.combine(val)
-            }
-        case let v as [AnyCodable]:
-            hasher.combine(6)
-            for item in v {
-                hasher.combine(item)
-            }
-        default:
-            hasher.combine(999)
-        }
-    }
-}
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift
new file mode 100644
index 00000000000..e15baf17fdb
--- /dev/null
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift
@@ -0,0 +1,39 @@
+import Foundation
+import Network
+
+public enum GatewayDiscoveryStatusText {
+    public static func make(states: [NWBrowser.State], hasBrowsers: Bool) -> String {
+        if states.isEmpty {
+            return hasBrowsers ? "Setup" : "Idle"
+        }
+
+        if let failed = states.first(where: { state in
+            if case .failed = state { return true }
+            return false
+        }) {
+            if case let .failed(err) = failed {
+                return "Failed: \(err)"
+            }
+        }
+
+        if let waiting = states.first(where: { state in
+            if case .waiting = state { return true }
+            return false
+        }) {
+            if case let .waiting(err) = waiting {
+                return "Waiting: \(err)"
+            }
+        }
+
+        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
+            return "Searching…"
+        }
+
+        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
+            return "Setup"
+        }
+
+        return "Searching…"
+    }
+}
+
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift
index 8672ab09f68..139aa7d2942 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift
@@ -2,14 +2,6 @@ import OpenClawProtocol
 import Foundation
 
 public enum GatewayPayloadDecoding {
-    public static func decode<T: Decodable>(
-        _ payload: OpenClawProtocol.AnyCodable,
-        as _: T.Type = T.self) throws -> T
-    {
-        let data = try JSONEncoder().encode(payload)
-        return try JSONDecoder().decode(T.self, from: data)
-    }
-
     public static func decode<T: Decodable>(
         _ payload: AnyCodable,
         as _: T.Type = T.self) throws -> T
@@ -18,14 +10,6 @@ public enum GatewayPayloadDecoding {
         return try JSONDecoder().decode(T.self, from: data)
     }
 
-    public static func decodeIfPresent<T: Decodable>(
-        _ payload: OpenClawProtocol.AnyCodable?,
-        as _: T.Type = T.self) throws -> T?
-    {
-        guard let payload else { return nil }
-        return try self.decode(payload, as: T.self)
-    }
-
     public static func decodeIfPresent<T: Decodable>(
         _ payload: AnyCodable?,
         as _: T.Type = T.self) throws -> T?
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaces.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaces.swift
new file mode 100644
index 00000000000..3679ef54234
--- /dev/null
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaces.swift
@@ -0,0 +1,43 @@
+import Darwin
+import Foundation
+
+public enum NetworkInterfaces {
+    public static func primaryIPv4Address() -> String? {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }
+        defer { freeifaddrs(addrList) }
+
+        var fallback: String?
+        var en0: String?
+
+        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
+            let flags = Int32(ptr.pointee.ifa_flags)
+            let isUp = (flags & IFF_UP) != 0
+            let isLoopback = (flags & IFF_LOOPBACK) != 0
+            let name = String(cString: ptr.pointee.ifa_name)
+            let family = ptr.pointee.ifa_addr.pointee.sa_family
+            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
+
+            var addr = ptr.pointee.ifa_addr.pointee
+            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+            let result = getnameinfo(
+                &addr,
+                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
+                &buffer,
+                socklen_t(buffer.count),
+                nil,
+                0,
+                NI_NUMERICHOST)
+            guard result == 0 else { continue }
+            let len = buffer.prefix { $0 != 0 }
+            let bytes = len.map { UInt8(bitPattern: $0) }
+            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
+
+            if name == "en0" { en0 = ip; break }
+            if fallback == nil { fallback = ip }
+        }
+
+        return en0 ?? fallback
+    }
+}
+
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift
index b19792ad7b8..5af33d1d35c 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift
@@ -52,18 +52,26 @@ public enum OpenClawKitResources {
         for candidate in candidates {
             guard let baseURL = candidate else { continue }
 
-            // Direct path
-            let directURL = baseURL.appendingPathComponent("\(bundleName).bundle")
-            if let bundle = Bundle(url: directURL) {
-                return bundle
+            // SwiftPM often places the resource bundle next to (or near) the test runner bundle,
+            // not inside it. Walk up a few levels and check common container paths.
+            var roots: [URL] = []
+            roots.append(baseURL)
+            roots.append(baseURL.appendingPathComponent("Resources"))
+            roots.append(baseURL.appendingPathComponent("Contents/Resources"))
+
+            var current = baseURL
+            for _ in 0 ..< 5 {
+                current = current.deletingLastPathComponent()
+                roots.append(current)
+                roots.append(current.appendingPathComponent("Resources"))
+                roots.append(current.appendingPathComponent("Contents/Resources"))
             }
 
-            // Inside Resources/
-            let resourcesURL = baseURL
-                .appendingPathComponent("Resources")
-                .appendingPathComponent("\(bundleName).bundle")
-            if let bundle = Bundle(url: resourcesURL) {
-                return bundle
+            for root in roots {
+                let bundleURL = root.appendingPathComponent("\(bundleName).bundle")
+                if let bundle = Bundle(url: bundleURL) {
+                    return bundle
+                }
             }
         }
 
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/PhotoCapture.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/PhotoCapture.swift
new file mode 100644
index 00000000000..b5f00d34751
--- /dev/null
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/PhotoCapture.swift
@@ -0,0 +1,19 @@
+import Foundation
+
+public enum PhotoCapture {
+    public static func transcodeJPEGForGateway(
+        rawData: Data,
+        maxWidthPx: Int,
+        quality: Double,
+        maxPayloadBytes: Int = 5 * 1024 * 1024
+    ) throws -> (data: Data, widthPx: Int, heightPx: Int) {
+        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under maxPayloadBytes (API limit).
+        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
+        return try JPEGTranscoder.transcodeToJPEG(
+            imageData: rawData,
+            maxWidthPx: maxWidthPx,
+            quality: quality,
+            maxBytes: maxEncodedBytes)
+    }
+}
+
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/AnyCodable.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/AnyCodable.swift
index ad0c3387296..252e6131e4c 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/AnyCodable.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/AnyCodable.swift
@@ -1,8 +1,9 @@
 import Foundation
 
 /// Lightweight `Codable` wrapper that round-trips heterogeneous JSON payloads.
+///
 /// Marked `@unchecked Sendable` because it can hold reference types.
-public struct AnyCodable: Codable, @unchecked Sendable {
+public struct AnyCodable: Codable, @unchecked Sendable, Hashable {
     public let value: Any
 
     public init(_ value: Any) { self.value = value }
@@ -16,9 +17,7 @@ public struct AnyCodable: Codable, @unchecked Sendable {
         if container.decodeNil() { self.value = NSNull(); return }
         if let dict = try? container.decode([String: AnyCodable].self) { self.value = dict; return }
         if let array = try? container.decode([AnyCodable].self) { self.value = array; return }
-        throw DecodingError.dataCorruptedError(
-            in: container,
-            debugDescription: "Unsupported type")
+        throw DecodingError.dataCorruptedError(in: container, debugDescription: "Unsupported type")
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -51,4 +50,46 @@ public struct AnyCodable: Codable, @unchecked Sendable {
             throw EncodingError.invalidValue(self.value, context)
         }
     }
+
+    public static func == (lhs: AnyCodable, rhs: AnyCodable) -> Bool {
+        switch (lhs.value, rhs.value) {
+        case let (l as Int, r as Int): l == r
+        case let (l as Double, r as Double): l == r
+        case let (l as Bool, r as Bool): l == r
+        case let (l as String, r as String): l == r
+        case (_ as NSNull, _ as NSNull): true
+        case let (l as [String: AnyCodable], r as [String: AnyCodable]): l == r
+        case let (l as [AnyCodable], r as [AnyCodable]): l == r
+        default:
+            false
+        }
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        switch self.value {
+        case let v as Int:
+            hasher.combine(0); hasher.combine(v)
+        case let v as Double:
+            hasher.combine(1); hasher.combine(v)
+        case let v as Bool:
+            hasher.combine(2); hasher.combine(v)
+        case let v as String:
+            hasher.combine(3); hasher.combine(v)
+        case _ as NSNull:
+            hasher.combine(4)
+        case let v as [String: AnyCodable]:
+            hasher.combine(5)
+            for (k, val) in v.sorted(by: { $0.key < $1.key }) {
+                hasher.combine(k)
+                hasher.combine(val)
+            }
+        case let v as [AnyCodable]:
+            hasher.combine(6)
+            for item in v {
+                hasher.combine(item)
+            }
+        default:
+            hasher.combine(999)
+        }
+    }
 }
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
index 29a4059b334..8486e4c4551 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -2094,7 +2094,7 @@ public struct CronJob: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
     public let state: [String: AnyCodable]
 
     public init(
@@ -2110,7 +2110,7 @@ public struct CronJob: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?,
+        delivery: AnyCodable?,
         state: [String: AnyCodable]
     ) {
         self.id = id
@@ -2172,7 +2172,7 @@ public struct CronAddParams: Codable, Sendable {
     public let sessiontarget: AnyCodable
     public let wakemode: AnyCodable
     public let payload: AnyCodable
-    public let delivery: [String: AnyCodable]?
+    public let delivery: AnyCodable?
 
     public init(
         name: String,
@@ -2184,7 +2184,7 @@ public struct CronAddParams: Codable, Sendable {
         sessiontarget: AnyCodable,
         wakemode: AnyCodable,
         payload: AnyCodable,
-        delivery: [String: AnyCodable]?
+        delivery: AnyCodable?
     ) {
         self.name = name
         self.agentid = agentid
diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
index b1e5ef9a10c..4ba650aaf78 100644
--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -27,6 +27,8 @@ Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
   - **Main session**: enqueue a system event, then run on the next heartbeat.
   - **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default or none).
 - Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
+- Webhook posting is per job via `delivery.mode = "webhook"` + `delivery.to = "<url>"`.
+- Legacy fallback remains for stored jobs with `notify: true` when `cron.webhook` is set, migrate those jobs to webhook delivery mode.
 
 ## Quick start (actionable)
 
@@ -99,7 +101,7 @@ A cron job is a stored record with:
 
 - a **schedule** (when it should run),
 - a **payload** (what it should do),
-- optional **delivery mode** (announce or none).
+- optional **delivery mode** (`announce`, `webhook`, or `none`).
 - optional **agent binding** (`agentId`): run the job under a specific agent; if
   missing or unknown, the gateway falls back to the default agent.
 
@@ -140,8 +142,9 @@ Key behaviors:
 - Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
 - Each run starts a **fresh session id** (no prior conversation carry-over).
 - Default behavior: if `delivery` is omitted, isolated jobs announce a summary (`delivery.mode = "announce"`).
-- `delivery.mode` (isolated-only) chooses what happens:
+- `delivery.mode` chooses what happens:
   - `announce`: deliver a summary to the target channel and post a brief summary to the main session.
+  - `webhook`: POST the finished event payload to `delivery.to`.
   - `none`: internal only (no delivery, no main-session summary).
 - `wakeMode` controls when the main-session summary posts:
   - `now`: immediate heartbeat.
@@ -163,11 +166,11 @@ Common `agentTurn` fields:
 - `model` / `thinking`: optional overrides (see below).
 - `timeoutSeconds`: optional timeout override.
 
-Delivery config (isolated jobs only):
+Delivery config:
 
-- `delivery.mode`: `none` | `announce`.
+- `delivery.mode`: `none` | `announce` | `webhook`.
 - `delivery.channel`: `last` or a specific channel.
-- `delivery.to`: channel-specific target (phone/chat/channel id).
+- `delivery.to`: channel-specific target (announce) or webhook URL (webhook mode).
 - `delivery.bestEffort`: avoid failing the job if announce delivery fails.
 
 Announce delivery suppresses messaging tool sends for the run; use `delivery.channel`/`delivery.to`
@@ -192,6 +195,18 @@ Behavior details:
 - The main-session summary respects `wakeMode`: `now` triggers an immediate heartbeat and
   `next-heartbeat` waits for the next scheduled heartbeat.
 
+#### Webhook delivery flow
+
+When `delivery.mode = "webhook"`, cron posts the finished event payload to `delivery.to`.
+
+Behavior details:
+
+- The endpoint must be a valid HTTP(S) URL.
+- No channel delivery is attempted in webhook mode.
+- No main-session summary is posted in webhook mode.
+- If `cron.webhookToken` is set, auth header is `Authorization: Bearer <cron.webhookToken>`.
+- Deprecated fallback: stored legacy jobs with `notify: true` still post to `cron.webhook` (if configured), with a warning so you can migrate to `delivery.mode = "webhook"`.
+
 ### Model and thinking overrides
 
 Isolated jobs (`agentTurn`) can override the model and thinking level:
@@ -213,11 +228,12 @@ Resolution priority:
 
 Isolated jobs can deliver output to a channel via the top-level `delivery` config:
 
-- `delivery.mode`: `announce` (deliver a summary) or `none`.
+- `delivery.mode`: `announce` (channel delivery), `webhook` (HTTP POST), or `none`.
 - `delivery.channel`: `whatsapp` / `telegram` / `discord` / `slack` / `mattermost` (plugin) / `signal` / `imessage` / `last`.
 - `delivery.to`: channel-specific recipient target.
 
-Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
+`announce` delivery is only valid for isolated jobs (`sessionTarget: "isolated"`).
+`webhook` delivery is valid for both main and isolated jobs.
 
 If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
 “last route” (the last place the agent replied).
@@ -333,10 +349,21 @@ Notes:
     enabled: true, // default true
     store: "~/.openclaw/cron/jobs.json",
     maxConcurrentRuns: 1, // default 1
+    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
+    webhookToken: "replace-with-dedicated-webhook-token", // optional bearer token for webhook mode
   },
 }
 ```
 
+Webhook behavior:
+
+- Preferred: set `delivery.mode: "webhook"` with `delivery.to: "https://..."` per job.
+- Webhook URLs must be valid `http://` or `https://` URLs.
+- Payload is the cron finished event JSON.
+- If `cron.webhookToken` is set, auth header is `Authorization: Bearer <cron.webhookToken>`.
+- If `cron.webhookToken` is not set, no `Authorization` header is sent.
+- Deprecated fallback: stored legacy jobs with `notify: true` still use `cron.webhook` when present.
+
 Disable cron entirely:
 
 - `cron.enabled: false` (config)
diff --git a/docs/channels/discord.md b/docs/channels/discord.md
index 37023da6407..e2328514540 100644
--- a/docs/channels/discord.md
+++ b/docs/channels/discord.md
@@ -87,6 +87,77 @@ Token resolution is account-aware. Config token values win over env fallback. `D
 - Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).
 - Native slash commands run in isolated command sessions (`agent:<agentId>:discord:slash:<userId>`), while still carrying `CommandTargetSessionKey` to the routed conversation session.
 
+## Interactive components
+
+OpenClaw supports Discord components v2 containers for agent messages. Use the message tool with a `components` payload. Interaction results are routed back to the agent as normal inbound messages and follow the existing Discord `replyToMode` settings.
+
+Supported blocks:
+
+- `text`, `section`, `separator`, `actions`, `media-gallery`, `file`
+- Action rows allow up to 5 buttons or a single select menu
+- Select types: `string`, `user`, `role`, `mentionable`, `channel`
+
+File attachments:
+
+- `file` blocks must point to an attachment reference (`attachment://<filename>`)
+- Provide the attachment via `media`/`path`/`filePath` (single file); use `media-gallery` for multiple files
+- Use `filename` to override the upload name when it should match the attachment reference
+
+Modal forms:
+
+- Add `components.modal` with up to 5 fields
+- Field types: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select`
+- OpenClaw adds a trigger button automatically
+
+Example:
+
+```json5
+{
+  channel: "discord",
+  action: "send",
+  to: "channel:123456789012345678",
+  message: "Optional fallback text",
+  components: {
+    text: "Choose a path",
+    blocks: [
+      {
+        type: "actions",
+        buttons: [
+          { label: "Approve", style: "success" },
+          { label: "Decline", style: "danger" },
+        ],
+      },
+      {
+        type: "actions",
+        select: {
+          type: "string",
+          placeholder: "Pick an option",
+          options: [
+            { label: "Option A", value: "a" },
+            { label: "Option B", value: "b" },
+          ],
+        },
+      },
+    ],
+    modal: {
+      title: "Details",
+      triggerLabel: "Open form",
+      fields: [
+        { type: "text", label: "Requester" },
+        {
+          type: "select",
+          label: "Priority",
+          options: [
+            { label: "Low", value: "low" },
+            { label: "High", value: "high" },
+          ],
+        },
+      ],
+    },
+  },
+}
+```
+
 ## Access control and routing
 
 <Tabs>
@@ -313,6 +384,23 @@ See [Slash commands](/tools/slash-commands) for command catalog and behavior.
 
   </Accordion>
 
+  <Accordion title="Ack reactions">
+    `ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+    Resolution order:
+
+    - `channels.discord.accounts.<accountId>.ackReaction`
+    - `channels.discord.ackReaction`
+    - `messages.ackReaction`
+    - agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+    Notes:
+
+    - Discord accepts unicode emoji or custom emoji names.
+    - Use `""` to disable the reaction for a channel or account.
+
+  </Accordion>
+
   <Accordion title="Config writes">
     Channel-initiated config writes are enabled by default.
 
@@ -482,6 +570,30 @@ Default gate behavior:
 | moderation                                                                                                                                                               | disabled |
 | presence                                                                                                                                                                 | disabled |
 
+## Components v2 UI
+
+OpenClaw uses Discord components v2 for exec approvals and cross-context markers. Discord message actions can also accept `components` for custom UI (advanced; requires Carbon component instances), while legacy `embeds` remain available but are not recommended.
+
+- `channels.discord.ui.components.accentColor` sets the accent color used by Discord component containers (hex).
+- Set per account with `channels.discord.accounts.<id>.ui.components.accentColor`.
+- `embeds` are ignored when components v2 are present.
+
+Example:
+
+```json5
+{
+  channels: {
+    discord: {
+      ui: {
+        components: {
+          accentColor: "#5865F2",
+        },
+      },
+    },
+  },
+}
+```
+
 ## Voice messages
 
 Discord voice messages show a waveform preview and require OGG/Opus audio plus metadata. OpenClaw generates the waveform automatically, but it needs `ffmpeg` and `ffprobe` available on the gateway host to inspect and convert audio files.
@@ -574,6 +686,7 @@ High-signal Discord fields:
 - media/retry: `mediaMaxMb`, `retry`
 - actions: `actions.*`
 - presence: `activity`, `status`, `activityType`, `activityUrl`
+- UI: `ui.components.accentColor`
 - features: `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix`
 
 ## Safety and operations
diff --git a/docs/channels/groups.md b/docs/channels/groups.md
index 1b3fb0394a3..6bd278846c5 100644
--- a/docs/channels/groups.md
+++ b/docs/channels/groups.md
@@ -105,7 +105,7 @@ Want “groups can only see folder X” instead of “no host access”? Keep `w
         docker: {
           binds: [
             // hostPath:containerPath:mode
-            "~/FriendsShared:/data:ro",
+            "/home/user/FriendsShared:/data:ro",
           ],
         },
       },
diff --git a/docs/channels/slack.md b/docs/channels/slack.md
index 243e2f6d044..c4e95c21cf3 100644
--- a/docs/channels/slack.md
+++ b/docs/channels/slack.md
@@ -287,6 +287,22 @@ Available action groups in current Slack tooling:
 - `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
 - Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
 
+## Ack reactions
+
+`ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+Resolution order:
+
+- `channels.slack.accounts.<accountId>.ackReaction`
+- `channels.slack.ackReaction`
+- `messages.ackReaction`
+- agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+Notes:
+
+- Slack expects shortcodes (for example `"eyes"`).
+- Use `""` to disable the reaction for a channel or account.
+
 ## Manifest and scope checklist
 
 <AccordionGroup>
diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md
index a919d20b0c1..28a9c227f9d 100644
--- a/docs/channels/telegram.md
+++ b/docs/channels/telegram.md
@@ -571,6 +571,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
   </Accordion>
 
+  <Accordion title="Ack reactions">
+    `ackReaction` sends an acknowledgement emoji while OpenClaw is processing an inbound message.
+
+    Resolution order:
+
+    - `channels.telegram.accounts.<accountId>.ackReaction`
+    - `channels.telegram.ackReaction`
+    - `messages.ackReaction`
+    - agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
+
+    Notes:
+
+    - Telegram expects unicode emoji (for example "👀").
+    - Use `""` to disable the reaction for a channel or account.
+
+  </Accordion>
+
   <Accordion title="Config writes from Telegram events and commands">
     Channel config writes are enabled by default (`configWrites !== false`).
 
diff --git a/docs/concepts/session-tool.md b/docs/concepts/session-tool.md
index 945f3883f66..1dc5fb8cca5 100644
--- a/docs/concepts/session-tool.md
+++ b/docs/concepts/session-tool.md
@@ -176,12 +176,24 @@ Behavior:
 
 ## Sandbox Session Visibility
 
-Sandboxed sessions can use session tools, but by default they only see sessions they spawned via `sessions_spawn`.
+Session tools can be scoped to reduce cross-session access.
+
+Default behavior:
+
+- `tools.sessions.visibility` defaults to `tree` (current session + spawned subagent sessions).
+- For sandboxed sessions, `agents.defaults.sandbox.sessionToolsVisibility` can hard-clamp visibility.
 
 Config:
 
 ```json5
 {
+  tools: {
+    sessions: {
+      // "self" | "tree" | "agent" | "all"
+      // default: "tree"
+      visibility: "tree",
+    },
+  },
   agents: {
     defaults: {
       sandbox: {
@@ -192,3 +204,11 @@ Config:
   },
 }
 ```
+
+Notes:
+
+- `self`: only the current session key.
+- `tree`: current session + sessions spawned by the current session.
+- `agent`: any session belonging to the current agent id.
+- `all`: any session (cross-agent access still requires `tools.agentToAgent`).
+- When a session is sandboxed and `sessionToolsVisibility="spawned"`, OpenClaw clamps visibility to `tree` even if you set `tools.sessions.visibility="all"`.
diff --git a/docs/experiments/plans/pty-process-supervision.md b/docs/experiments/plans/pty-process-supervision.md
new file mode 100644
index 00000000000..352850c82f6
--- /dev/null
+++ b/docs/experiments/plans/pty-process-supervision.md
@@ -0,0 +1,192 @@
+---
+summary: "Production plan for reliable interactive process supervision (PTY + non-PTY) with explicit ownership, unified lifecycle, and deterministic cleanup"
+owner: "openclaw"
+status: "in-progress"
+last_updated: "2026-02-15"
+title: "PTY and Process Supervision Plan"
+---
+
+# PTY and Process Supervision Plan
+
+## 1. Problem and goal
+
+We need one reliable lifecycle for long-running command execution across:
+
+- `exec` foreground runs
+- `exec` background runs
+- `process` follow up actions (`poll`, `log`, `send-keys`, `paste`, `submit`, `kill`, `remove`)
+- CLI agent runner subprocesses
+
+The goal is not just to support PTY. The goal is predictable ownership, cancellation, timeout, and cleanup with no unsafe process matching heuristics.
+
+## 2. Scope and boundaries
+
+- Keep implementation internal in `src/process/supervisor`.
+- Do not create a new package for this.
+- Keep current behavior compatibility where practical.
+- Do not broaden scope to terminal replay or tmux style session persistence.
+
+## 3. Implemented in this branch
+
+### Supervisor baseline already present
+
+- Supervisor module is in place under `src/process/supervisor/*`.
+- Exec runtime and CLI runner are already routed through supervisor spawn and wait.
+- Registry finalization is idempotent.
+
+### This pass completed
+
+1. Explicit PTY command contract
+
+- `SpawnInput` is now a discriminated union in `src/process/supervisor/types.ts`.
+- PTY runs require `ptyCommand` instead of reusing generic `argv`.
+- Supervisor no longer rebuilds PTY command strings from argv joins in `src/process/supervisor/supervisor.ts`.
+- Exec runtime now passes `ptyCommand` directly in `src/agents/bash-tools.exec-runtime.ts`.
+
+2. Process layer type decoupling
+
+- Supervisor types no longer import `SessionStdin` from agents.
+- Process local stdin contract lives in `src/process/supervisor/types.ts` (`ManagedRunStdin`).
+- Adapters now depend only on process level types:
+  - `src/process/supervisor/adapters/child.ts`
+  - `src/process/supervisor/adapters/pty.ts`
+
+3. Process tool lifecycle ownership improvement
+
+- `src/agents/bash-tools.process.ts` now requests cancellation through supervisor first.
+- `process kill/remove` now use process-tree fallback termination when supervisor lookup misses.
+- `remove` keeps deterministic remove behavior by dropping running session entries immediately after termination is requested.
+
+4. Single source watchdog defaults
+
+- Added shared defaults in `src/agents/cli-watchdog-defaults.ts`.
+- `src/agents/cli-backends.ts` consumes the shared defaults.
+- `src/agents/cli-runner/reliability.ts` consumes the same shared defaults.
+
+5. Dead helper cleanup
+
+- Removed unused `killSession` helper path from `src/agents/bash-tools.shared.ts`.
+
+6. Direct supervisor path tests added
+
+- Added `src/agents/bash-tools.process.supervisor.test.ts` to cover kill and remove routing through supervisor cancellation.
+
+7. Reliability gap fixes completed
+
+- `src/agents/bash-tools.process.ts` now falls back to real OS-level process termination when supervisor lookup misses.
+- `src/process/supervisor/adapters/child.ts` now uses process-tree termination semantics for default cancel/timeout kill paths.
+- Added shared process-tree utility in `src/process/kill-tree.ts`.
+
+8. PTY contract edge-case coverage added
+
+- Added `src/process/supervisor/supervisor.pty-command.test.ts` for verbatim PTY command forwarding and empty-command rejection.
+- Added `src/process/supervisor/adapters/child.test.ts` for process-tree kill behavior in child adapter cancellation.
+
+## 4. Remaining gaps and decisions
+
+### Reliability status
+
+The two required reliability gaps for this pass are now closed:
+
+- `process kill/remove` now has a real OS termination fallback when supervisor lookup misses.
+- child cancel/timeout now uses process-tree kill semantics for default kill path.
+- Regression tests were added for both behaviors.
+
+### Durability and startup reconciliation
+
+Restart behavior is now explicitly defined as in-memory lifecycle only.
+
+- `reconcileOrphans()` remains a no-op in `src/process/supervisor/supervisor.ts` by design.
+- Active runs are not recovered after process restart.
+- This boundary is intentional for this implementation pass to avoid partial persistence risks.
+
+### Maintainability follow-ups
+
+1. `runExecProcess` in `src/agents/bash-tools.exec-runtime.ts` still handles multiple responsibilities and can be split into focused helpers in a follow-up.
+
+## 5. Implementation plan
+
+The implementation pass for required reliability and contract items is complete.
+
+Completed:
+
+- `process kill/remove` fallback real termination
+- process-tree cancellation for child adapter default kill path
+- regression tests for fallback kill and child adapter kill path
+- PTY command edge-case tests under explicit `ptyCommand`
+- explicit in-memory restart boundary with `reconcileOrphans()` no-op by design
+
+Optional follow-up:
+
+- split `runExecProcess` into focused helpers with no behavior drift
+
+## 6. File map
+
+### Process supervisor
+
+- `src/process/supervisor/types.ts` updated with discriminated spawn input and process local stdin contract.
+- `src/process/supervisor/supervisor.ts` updated to use explicit `ptyCommand`.
+- `src/process/supervisor/adapters/child.ts` and `src/process/supervisor/adapters/pty.ts` decoupled from agent types.
+- `src/process/supervisor/registry.ts` idempotent finalize unchanged and retained.
+
+### Exec and process integration
+
+- `src/agents/bash-tools.exec-runtime.ts` updated to pass PTY command explicitly and keep fallback path.
+- `src/agents/bash-tools.process.ts` updated to cancel via supervisor with real process-tree fallback termination.
+- `src/agents/bash-tools.shared.ts` removed direct kill helper path.
+
+### CLI reliability
+
+- `src/agents/cli-watchdog-defaults.ts` added as shared baseline.
+- `src/agents/cli-backends.ts` and `src/agents/cli-runner/reliability.ts` now consume same defaults.
+
+## 7. Validation run in this pass
+
+Unit tests:
+
+- `pnpm vitest src/process/supervisor/registry.test.ts`
+- `pnpm vitest src/process/supervisor/supervisor.test.ts`
+- `pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts`
+- `pnpm vitest src/process/supervisor/adapters/child.test.ts`
+- `pnpm vitest src/agents/cli-backends.test.ts`
+- `pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts`
+- `pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts`
+- `pnpm vitest src/agents/bash-tools.process.supervisor.test.ts`
+- `pnpm vitest src/process/exec.test.ts`
+
+E2E targets:
+
+- `pnpm test:e2e src/agents/cli-runner.e2e.test.ts`
+- `pnpm test:e2e src/agents/bash-tools.exec.pty-fallback.e2e.test.ts src/agents/bash-tools.exec.background-abort.e2e.test.ts src/agents/bash-tools.process.send-keys.e2e.test.ts`
+
+Typecheck note:
+
+- `pnpm tsgo` currently fails in this repo due to a pre-existing UI typing dependency issue (`@vitest/browser-playwright` resolution), unrelated to this process supervision work.
+
+## 8. Operational guarantees preserved
+
+- Exec env hardening behavior is unchanged.
+- Approval and allowlist flow is unchanged.
+- Output sanitization and output caps are unchanged.
+- PTY adapter still guarantees wait settlement on forced kill and listener disposal.
+
+## 9. Definition of done
+
+1. Supervisor is lifecycle owner for managed runs.
+2. PTY spawn uses explicit command contract with no argv reconstruction.
+3. Process layer has no type dependency on agent layer for supervisor stdin contracts.
+4. Watchdog defaults are single source.
+5. Targeted unit and e2e tests remain green.
+6. Restart durability boundary is explicitly documented or fully implemented.
+
+## 10. Summary
+
+The branch now has a coherent and safer supervision shape:
+
+- explicit PTY contract
+- cleaner process layering
+- supervisor driven cancellation path for process operations
+- real fallback termination when supervisor lookup misses
+- process-tree cancellation for child-run default kill paths
+- unified watchdog defaults
+- explicit in-memory restart boundary (no orphan reconciliation across restart in this pass)
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 66124db9b84..a74d3257a75 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -211,6 +211,11 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
       textChunkLimit: 2000,
       chunkMode: "length", // length | newline
       maxLinesPerMessage: 17,
+      ui: {
+        components: {
+          accentColor: "#5865F2",
+        },
+      },
       retry: {
         attempts: 3,
         minDelayMs: 500,
@@ -227,6 +232,7 @@ WhatsApp runs through the gateway's web channel (Baileys Web). It starts automat
 - Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged name (no `#`). Prefer guild IDs.
 - Bot-authored messages are ignored by default. `allowBots: true` enables them (own messages still filtered).
 - `maxLinesPerMessage` (default 17) splits tall messages even when under 2000 chars.
+- `channels.discord.ui.components.accentColor` sets the accent color for Discord components v2 containers.
 
 **Reaction notification modes:** `off` (none), `own` (bot's messages, default), `all` (all messages), `allowlist` (from `guilds.<id>.users` on all messages).
 
@@ -1232,6 +1238,8 @@ Variables are case-insensitive. `{think}` is an alias for `{thinkingLevel}`.
 ### Ack reaction
 
 - Defaults to active agent's `identity.emoji`, otherwise `"👀"`. Set `""` to disable.
+- Per-channel overrides: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
+- Resolution order: account → channel → `messages.ackReaction` → identity fallback.
 - Scope: `group-mentions` (default), `group-all`, `direct`, `all`.
 - `removeAckAfterReply`: removes ack after reply (Slack/Discord/Telegram/Google Chat only).
 
@@ -1500,6 +1508,31 @@ Provider auth follows standard order: auth profiles → env vars → `models.pro
 }
 ```
 
+### `tools.sessions`
+
+Controls which sessions can be targeted by the session tools (`sessions_list`, `sessions_history`, `sessions_send`).
+
+Default: `tree` (current session + sessions spawned by it, such as subagents).
+
+```json5
+{
+  tools: {
+    sessions: {
+      // "self" | "tree" | "agent" | "all"
+      visibility: "tree",
+    },
+  },
+}
+```
+
+Notes:
+
+- `self`: only the current session key.
+- `tree`: current session + sessions spawned by the current session (subagents).
+- `agent`: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
+- `all`: any session. Cross-agent targeting still requires `tools.agentToAgent`.
+- Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility is forced to `tree` even if `tools.sessions.visibility="all"`.
+
 ### `tools.subagents`
 
 ```json5
@@ -2287,12 +2320,16 @@ Current builds no longer include the TCP bridge. Nodes connect over the Gateway
   cron: {
     enabled: true,
     maxConcurrentRuns: 2,
+    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
+    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
     sessionRetention: "24h", // duration string or false
   },
 }
 ```
 
 - `sessionRetention`: how long to keep completed cron sessions before pruning. Default: `24h`.
+- `webhookToken`: bearer token used for cron webhook POST delivery (`delivery.mode = "webhook"`), if omitted no auth header is sent.
+- `webhook`: deprecated legacy fallback webhook URL (http/https) used only for stored jobs that still have `notify: true`.
 
 See [Cron Jobs](/automation/cron-jobs).
 
diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md
index fe653e82d2a..fe27d2c51ad 100644
--- a/docs/gateway/sandboxing.md
+++ b/docs/gateway/sandboxing.md
@@ -76,7 +76,7 @@ Global and per-agent binds are **merged** (not replaced). Under `scope: "shared"
 - When set (including `[]`), it replaces `agents.defaults.sandbox.docker.binds` for the browser container.
 - When omitted, the browser container falls back to `agents.defaults.sandbox.docker.binds` (backwards compatible).
 
-Example (read-only source + docker socket):
+Example (read-only source + an extra data directory):
 
 ```json5
 {
@@ -84,7 +84,7 @@ Example (read-only source + docker socket):
     defaults: {
       sandbox: {
         docker: {
-          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
+          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
         },
       },
     },
@@ -105,7 +105,8 @@ Example (read-only source + docker socket):
 Security notes:
 
 - Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).
-- Sensitive mounts (e.g., `docker.sock`, secrets, SSH keys) should be `:ro` unless absolutely required.
+- OpenClaw blocks dangerous bind sources (for example: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev`, and parent mounts that would expose them).
+- Sensitive mounts (secrets, SSH keys, service credentials) should be `:ro` unless absolutely required.
 - Combine with `workspaceAccess: "ro"` if you only need read access to the workspace; bind modes stay independent.
 - See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.
 
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index b0ea264c4ab..9f7639a6f07 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -710,7 +710,11 @@ Common use cases:
           scope: "agent",
           workspaceAccess: "none",
         },
+        // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools
+        // to the current session + spawned subagent sessions, but you can clamp further if needed.
+        // See `tools.sessions.visibility` in the configuration reference.
         tools: {
+          sessions: { visibility: "tree" }, // self | tree | agent | all
           allow: [
             "sessions_list",
             "sessions_history",
diff --git a/docs/platforms/mac/release.md b/docs/platforms/mac/release.md
index bb493e750c1..e004c9b5864 100644
--- a/docs/platforms/mac/release.md
+++ b/docs/platforms/mac/release.md
@@ -34,17 +34,17 @@ Notes:
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.15 \
+APP_VERSION=2026.2.16 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-app.sh
 
 # Zip for distribution (includes resource forks for Sparkle delta support)
-ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.15.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.16.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.15.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.16.dmg
 
 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -52,14 +52,14 @@ scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.15.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.15 \
+APP_VERSION=2026.2.16 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
 
 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.15.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.16.dSYM.zip
 ```
 
 ## Appcast entry
@@ -67,7 +67,7 @@ ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenCl
 Use the release note generator so Sparkle renders formatted HTML notes:
 
 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.15.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.16.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
 ```
 
 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
@@ -75,7 +75,7 @@ Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when
 
 ## Publish & verify
 
-- Upload `OpenClaw-2026.2.15.zip` (and `OpenClaw-2026.2.15.dSYM.zip`) to the GitHub release for tag `v2026.2.15`.
+- Upload `OpenClaw-2026.2.16.zip` (and `OpenClaw-2026.2.16.dSYM.zip`) to the GitHub release for tag `v2026.2.16`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`.
 - Sanity checks:
   - `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` returns 200.
diff --git a/docs/tools/index.md b/docs/tools/index.md
index f1496a5982a..71c210bfbbf 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -442,12 +442,14 @@ Notes:
 
 - `main` is the canonical direct-chat key; global/unknown are hidden.
 - `messageLimit > 0` fetches last N messages per session (tool messages filtered).
+- Session targeting is controlled by `tools.sessions.visibility` (default `tree`: current session + spawned subagent sessions). If you run a shared agent for multiple users, consider setting `tools.sessions.visibility: "self"` to prevent cross-session browsing.
 - `sessions_send` waits for final completion when `timeoutSeconds > 0`.
 - Delivery/announce happens after completion and is best-effort; `status: "ok"` confirms the agent run finished, not that the announce was delivered.
 - `sessions_spawn` starts a sub-agent run and posts an announce reply back to the requester chat.
 - `sessions_spawn` is non-blocking and returns `status: "accepted"` immediately.
 - `sessions_send` runs a reply‑back ping‑pong (reply `REPLY_SKIP` to stop; max turns via `session.agentToAgent.maxPingPongTurns`, 0–5).
 - After the ping‑pong, the target agent runs an **announce step**; reply `ANNOUNCE_SKIP` to suppress the announcement.
+- Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility: "spawned"`, OpenClaw clamps `tools.sessions.visibility` to `tree`.
 
 ### `agents_list`
 
diff --git a/docs/tools/multi-agent-sandbox-tools.md b/docs/tools/multi-agent-sandbox-tools.md
index e7de9caf8d3..dc49d94a29a 100644
--- a/docs/tools/multi-agent-sandbox-tools.md
+++ b/docs/tools/multi-agent-sandbox-tools.md
@@ -324,6 +324,7 @@ Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defau
 ```json
 {
   "tools": {
+    "sessions": { "visibility": "tree" },
     "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
     "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
   }
diff --git a/docs/tools/web.md b/docs/tools/web.md
index 859e6144c51..b0e295cd22a 100644
--- a/docs/tools/web.md
+++ b/docs/tools/web.md
@@ -224,6 +224,7 @@ Fetch a URL and extract readable content.
         enabled: true,
         maxChars: 50000,
         maxCharsCap: 50000,
+        maxResponseBytes: 2000000,
         timeoutSeconds: 30,
         cacheTtlMinutes: 15,
         maxRedirects: 3,
@@ -256,6 +257,7 @@ Notes:
 - `web_fetch` sends a Chrome-like User-Agent and `Accept-Language` by default; override `userAgent` if needed.
 - `web_fetch` blocks private/internal hostnames and re-checks redirects (limit with `maxRedirects`).
 - `maxChars` is clamped to `tools.web.fetch.maxCharsCap`.
+- `web_fetch` caps the downloaded response body size to `tools.web.fetch.maxResponseBytes` before parsing; oversized responses are truncated and include a warning.
 - `web_fetch` is best-effort extraction; some sites will need the browser tool.
 - See [Firecrawl](/tools/firecrawl) for key setup and service details.
 - Responses are cached (default 15 minutes) to reduce repeated fetches.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 233a67c48b0..2547cc0b469 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -83,6 +83,10 @@ Cron jobs panel notes:
 
 - For isolated jobs, delivery defaults to announce summary. You can switch to none if you want internal-only runs.
 - Channel/target fields appear when announce is selected.
+- Webhook mode uses `delivery.mode = "webhook"` with `delivery.to` set to a valid HTTP(S) webhook URL.
+- For main-session jobs, webhook and none delivery modes are available.
+- Set `cron.webhookToken` to send a dedicated bearer token, if omitted the webhook is sent without an auth header.
+- Deprecated fallback: stored legacy jobs with `notify: true` can still use `cron.webhook` until migrated.
 
 ## Chat behavior
 
@@ -93,6 +97,10 @@ Cron jobs panel notes:
   - Click **Stop** (calls `chat.abort`)
   - Type `/stop` (or `stop|esc|abort|wait|exit|interrupt`) to abort out-of-band
   - `chat.abort` supports `{ sessionKey }` (no `runId`) to abort all active runs for that session
+- Abort partial retention:
+  - When a run is aborted, partial assistant text can still be shown in the UI
+  - Gateway persists aborted partial assistant text into transcript history when buffered output exists
+  - Persisted entries include abort metadata so transcript consumers can tell abort partials from normal completion output
 
 ## Tailnet access (recommended)
 
diff --git a/docs/web/webchat.md b/docs/web/webchat.md
index a765f67598a..657e00ef8b2 100644
--- a/docs/web/webchat.md
+++ b/docs/web/webchat.md
@@ -25,6 +25,8 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
 
 - The UI connects to the Gateway WebSocket and uses `chat.history`, `chat.send`, and `chat.inject`.
 - `chat.inject` appends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).
+- Aborted runs can keep partial assistant output visible in the UI.
+- Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.
 - History is always fetched from the gateway (no local file watching).
 - If the gateway is unreachable, WebChat is read-only.
 
diff --git a/extensions/bluebubbles/package.json b/extensions/bluebubbles/package.json
index 328f2d8289b..b040a6fb29c 100644
--- a/extensions/bluebubbles/package.json
+++ b/extensions/bluebubbles/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "devDependencies": {
diff --git a/extensions/bluebubbles/src/attachments.ts b/extensions/bluebubbles/src/attachments.ts
index 917079b3ae5..e6d66712e79 100644
--- a/extensions/bluebubbles/src/attachments.ts
+++ b/extensions/bluebubbles/src/attachments.ts
@@ -2,6 +2,7 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import crypto from "node:crypto";
 import path from "node:path";
 import { resolveBlueBubblesAccount } from "./accounts.js";
+import { postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";
 import { resolveChatGuidForTarget } from "./send.js";
@@ -219,26 +220,12 @@ export async function sendBlueBubblesAttachment(params: {
   // Close the multipart body
   parts.push(encoder.encode(`--${boundary}--\r\n`));
 
-  // Combine all parts into a single buffer
-  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
-  const body = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    body.set(part, offset);
-    offset += part.length;
-  }
-
-  const res = await blueBubblesFetchWithTimeout(
+  const res = await postMultipartFormData({
     url,
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": `multipart/form-data; boundary=${boundary}`,
-      },
-      body,
-    },
-    opts.timeoutMs ?? 60_000, // longer timeout for file uploads
-  );
+    boundary,
+    parts,
+    timeoutMs: opts.timeoutMs ?? 60_000, // longer timeout for file uploads
+  });
 
   if (!res.ok) {
     const errorText = await res.text();
diff --git a/extensions/bluebubbles/src/chat.ts b/extensions/bluebubbles/src/chat.ts
index bfb37a4ddf8..7e25c2cec88 100644
--- a/extensions/bluebubbles/src/chat.ts
+++ b/extensions/bluebubbles/src/chat.ts
@@ -2,6 +2,7 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import crypto from "node:crypto";
 import path from "node:path";
 import { resolveBlueBubblesAccount } from "./accounts.js";
+import { postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
 
@@ -376,26 +377,12 @@ export async function setGroupIconBlueBubbles(
   // Close multipart body
   parts.push(encoder.encode(`--${boundary}--\r\n`));
 
-  // Combine into single buffer
-  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
-  const body = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    body.set(part, offset);
-    offset += part.length;
-  }
-
-  const res = await blueBubblesFetchWithTimeout(
+  const res = await postMultipartFormData({
     url,
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": `multipart/form-data; boundary=${boundary}`,
-      },
-      body,
-    },
-    opts.timeoutMs ?? 60_000, // longer timeout for file uploads
-  );
+    boundary,
+    parts,
+    timeoutMs: opts.timeoutMs ?? 60_000, // longer timeout for file uploads
+  });
 
   if (!res.ok) {
     const errorText = await res.text().catch(() => "");
diff --git a/extensions/bluebubbles/src/multipart.ts b/extensions/bluebubbles/src/multipart.ts
new file mode 100644
index 00000000000..851cca016b7
--- /dev/null
+++ b/extensions/bluebubbles/src/multipart.ts
@@ -0,0 +1,32 @@
+import { blueBubblesFetchWithTimeout } from "./types.js";
+
+export function concatUint8Arrays(parts: Uint8Array[]): Uint8Array {
+  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
+  const body = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    body.set(part, offset);
+    offset += part.length;
+  }
+  return body;
+}
+
+export async function postMultipartFormData(params: {
+  url: string;
+  boundary: string;
+  parts: Uint8Array[];
+  timeoutMs: number;
+}): Promise<Response> {
+  const body = Buffer.from(concatUint8Arrays(params.parts));
+  return await blueBubblesFetchWithTimeout(
+    params.url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": `multipart/form-data; boundary=${params.boundary}`,
+      },
+      body,
+    },
+    params.timeoutMs,
+  );
+}
diff --git a/extensions/bluebubbles/src/probe.ts b/extensions/bluebubbles/src/probe.ts
index 7b49ae698ed..e60c47dc643 100644
--- a/extensions/bluebubbles/src/probe.ts
+++ b/extensions/bluebubbles/src/probe.ts
@@ -1,9 +1,8 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
 
-export type BlueBubblesProbe = {
-  ok: boolean;
+export type BlueBubblesProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
 };
 
 export type BlueBubblesServerInfo = {
diff --git a/extensions/copilot-proxy/package.json b/extensions/copilot-proxy/package.json
index 9ffa4b85a9c..756b6a26849 100644
--- a/extensions/copilot-proxy/package.json
+++ b/extensions/copilot-proxy/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/copilot-proxy",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Copilot Proxy provider plugin",
   "type": "module",
diff --git a/extensions/diagnostics-otel/package.json b/extensions/diagnostics-otel/package.json
index 74ccbc24872..c0098b1a14b 100644
--- a/extensions/diagnostics-otel/package.json
+++ b/extensions/diagnostics-otel/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/diagnostics-otel",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw diagnostics OpenTelemetry exporter",
   "type": "module",
   "dependencies": {
diff --git a/extensions/discord/package.json b/extensions/discord/package.json
index 4876a771bb9..b68e1223337 100644
--- a/extensions/discord/package.json
+++ b/extensions/discord/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/discord",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Discord channel plugin",
   "type": "module",
   "devDependencies": {
diff --git a/extensions/discord/src/channel.ts b/extensions/discord/src/channel.ts
index 4119a95e815..f8fc9576e6a 100644
--- a/extensions/discord/src/channel.ts
+++ b/extensions/discord/src/channel.ts
@@ -158,6 +158,12 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
   threading: {
     resolveReplyToMode: ({ cfg }) => cfg.channels?.discord?.replyToMode ?? "off",
   },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- Discord components: set `components` when sending messages to include buttons, selects, or v2 containers.",
+      "- Forms: add `components.modal` (title, fields). OpenClaw adds a trigger button and routes submissions as new messages.",
+    ],
+  },
   messaging: {
     normalizeTarget: normalizeDiscordMessagingTarget,
     targetResolver: {
diff --git a/extensions/feishu/package.json b/extensions/feishu/package.json
index 2cf278d2444..c5ae74770da 100644
--- a/extensions/feishu/package.json
+++ b/extensions/feishu/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/feishu",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng)",
   "type": "module",
   "dependencies": {
diff --git a/extensions/feishu/src/bot.ts b/extensions/feishu/src/bot.ts
index 7a1ffd6191e..a0646a86e0c 100644
--- a/extensions/feishu/src/bot.ts
+++ b/extensions/feishu/src/bot.ts
@@ -1,5 +1,6 @@
 import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk";
 import {
+  buildAgentMediaPayload,
   buildPendingHistoryContextFromMap,
   recordPendingHistoryEntryIfEnabled,
   clearHistoryEntriesIfEnabled,
@@ -433,27 +434,6 @@ async function resolveFeishuMediaList(params: {
  * Build media payload for inbound context.
  * Similar to Discord's buildDiscordMediaPayload().
  */
-function buildFeishuMediaPayload(mediaList: FeishuMediaInfo[]): {
-  MediaPath?: string;
-  MediaType?: string;
-  MediaUrl?: string;
-  MediaPaths?: string[];
-  MediaUrls?: string[];
-  MediaTypes?: string[];
-} {
-  const first = mediaList[0];
-  const mediaPaths = mediaList.map((media) => media.path);
-  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
-  return {
-    MediaPath: first?.path,
-    MediaType: first?.contentType,
-    MediaUrl: first?.path,
-    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
-    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
-    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
-  };
-}
-
 export function parseFeishuMessageEvent(
   event: FeishuMessageEvent,
   botOpenId?: string,
@@ -766,7 +746,7 @@ export async function handleFeishuMessage(params: {
       log,
       accountId: account.accountId,
     });
-    const mediaPayload = buildFeishuMediaPayload(mediaList);
+    const mediaPayload = buildAgentMediaPayload(mediaList);
 
     // Fetch quoted/replied message content if parentId exists
     let quotedContent: string | undefined;
diff --git a/extensions/feishu/src/channel.ts b/extensions/feishu/src/channel.ts
index bdc3aa04ba9..fb7881f2307 100644
--- a/extensions/feishu/src/channel.ts
+++ b/extensions/feishu/src/channel.ts
@@ -1,5 +1,10 @@
 import type { ChannelMeta, ChannelPlugin, ClawdbotConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk";
+import {
+  buildBaseChannelStatusSummary,
+  createDefaultChannelRuntimeState,
+  DEFAULT_ACCOUNT_ID,
+  PAIRING_APPROVED_MESSAGE,
+} from "openclaw/plugin-sdk";
 import type { ResolvedFeishuAccount, FeishuConfig } from "./types.js";
 import {
   resolveFeishuAccount,
@@ -303,20 +308,9 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
   },
   outbound: feishuOutbound,
   status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-      port: null,
-    },
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, { port: null }),
     buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
+      ...buildBaseChannelStatusSummary(snapshot),
       port: snapshot.port ?? null,
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
diff --git a/extensions/feishu/src/types.ts b/extensions/feishu/src/types.ts
index dbfde807806..dad248aa9f4 100644
--- a/extensions/feishu/src/types.ts
+++ b/extensions/feishu/src/types.ts
@@ -1,3 +1,4 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import type {
   FeishuConfigSchema,
   FeishuGroupSchema,
@@ -52,9 +53,7 @@ export type FeishuSendResult = {
   chatId: string;
 };
 
-export type FeishuProbeResult = {
-  ok: boolean;
-  error?: string;
+export type FeishuProbeResult = BaseProbeResult<string> & {
   appId?: string;
   botName?: string;
   botOpenId?: string;
diff --git a/extensions/google-antigravity-auth/index.ts b/extensions/google-antigravity-auth/index.ts
index 15f1bf1ee2b..055cb15e00b 100644
--- a/extensions/google-antigravity-auth/index.ts
+++ b/extensions/google-antigravity-auth/index.ts
@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import {
+  buildOauthProviderAuthResult,
   emptyPluginConfigSchema,
   isWSL2Sync,
   type OpenClawPluginApi,
@@ -396,37 +397,19 @@ const antigravityPlugin = {
                 progress: spin,
               });
 
-              const profileId = `google-antigravity:${result.email ?? "default"}`;
-              return {
-                profiles: [
-                  {
-                    profileId,
-                    credential: {
-                      type: "oauth",
-                      provider: "google-antigravity",
-                      access: result.access,
-                      refresh: result.refresh,
-                      expires: result.expires,
-                      email: result.email,
-                      projectId: result.projectId,
-                    },
-                  },
-                ],
-                configPatch: {
-                  agents: {
-                    defaults: {
-                      models: {
-                        [DEFAULT_MODEL]: {},
-                      },
-                    },
-                  },
-                },
+              return buildOauthProviderAuthResult({
+                providerId: "google-antigravity",
                 defaultModel: DEFAULT_MODEL,
+                access: result.access,
+                refresh: result.refresh,
+                expires: result.expires,
+                email: result.email,
+                credentialExtra: { projectId: result.projectId },
                 notes: [
                   "Antigravity uses Google Cloud project quotas.",
                   "Enable Gemini for Google Cloud on your project if requests fail.",
                 ],
-              };
+              });
             } catch (err) {
               spin.stop("Antigravity OAuth failed");
               throw err;
diff --git a/extensions/google-antigravity-auth/package.json b/extensions/google-antigravity-auth/package.json
index b2afcd50159..7d5bc539f05 100644
--- a/extensions/google-antigravity-auth/package.json
+++ b/extensions/google-antigravity-auth/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/google-antigravity-auth",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Google Antigravity OAuth provider plugin",
   "type": "module",
diff --git a/extensions/google-gemini-cli-auth/index.ts b/extensions/google-gemini-cli-auth/index.ts
index ba7913e2d86..89b7c4d1cfb 100644
--- a/extensions/google-gemini-cli-auth/index.ts
+++ b/extensions/google-gemini-cli-auth/index.ts
@@ -1,4 +1,5 @@
 import {
+  buildOauthProviderAuthResult,
   emptyPluginConfigSchema,
   type OpenClawPluginApi,
   type ProviderAuthContext,
@@ -46,34 +47,16 @@ const geminiCliPlugin = {
               });
 
               spin.stop("Gemini CLI OAuth complete");
-              const profileId = `google-gemini-cli:${result.email ?? "default"}`;
-              return {
-                profiles: [
-                  {
-                    profileId,
-                    credential: {
-                      type: "oauth",
-                      provider: PROVIDER_ID,
-                      access: result.access,
-                      refresh: result.refresh,
-                      expires: result.expires,
-                      email: result.email,
-                      projectId: result.projectId,
-                    },
-                  },
-                ],
-                configPatch: {
-                  agents: {
-                    defaults: {
-                      models: {
-                        [DEFAULT_MODEL]: {},
-                      },
-                    },
-                  },
-                },
+              return buildOauthProviderAuthResult({
+                providerId: PROVIDER_ID,
                 defaultModel: DEFAULT_MODEL,
+                access: result.access,
+                refresh: result.refresh,
+                expires: result.expires,
+                email: result.email,
+                credentialExtra: { projectId: result.projectId },
                 notes: ["If requests fail, set GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID."],
-              };
+              });
             } catch (err) {
               spin.stop("Gemini CLI OAuth failed");
               await ctx.prompter.note(
diff --git a/extensions/google-gemini-cli-auth/package.json b/extensions/google-gemini-cli-auth/package.json
index 5ac915b720e..51f94113444 100644
--- a/extensions/google-gemini-cli-auth/package.json
+++ b/extensions/google-gemini-cli-auth/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/google-gemini-cli-auth",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Gemini CLI OAuth provider plugin",
   "type": "module",
diff --git a/extensions/googlechat/package.json b/extensions/googlechat/package.json
index 40c93804576..2d8648c3b00 100644
--- a/extensions/googlechat/package.json
+++ b/extensions/googlechat/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/googlechat",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Google Chat channel plugin",
   "type": "module",
diff --git a/extensions/googlechat/src/monitor.ts b/extensions/googlechat/src/monitor.ts
index 34f62930ae7..d4c9aef4365 100644
--- a/extensions/googlechat/src/monitor.ts
+++ b/extensions/googlechat/src/monitor.ts
@@ -2,7 +2,9 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import {
   createReplyPrefixOptions,
+  normalizeWebhookPath,
   readJsonBodyWithLimit,
+  resolveWebhookPath,
   requestBodyErrorToText,
   resolveMentionGatingWithBypass,
 } from "openclaw/plugin-sdk";
@@ -86,34 +88,6 @@ function warnDeprecatedUsersEmailEntries(
   );
 }
 
-function normalizeWebhookPath(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return "/";
-  }
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  if (withSlash.length > 1 && withSlash.endsWith("/")) {
-    return withSlash.slice(0, -1);
-  }
-  return withSlash;
-}
-
-function resolveWebhookPath(webhookPath?: string, webhookUrl?: string): string | null {
-  const trimmedPath = webhookPath?.trim();
-  if (trimmedPath) {
-    return normalizeWebhookPath(trimmedPath);
-  }
-  if (webhookUrl?.trim()) {
-    try {
-      const parsed = new URL(webhookUrl);
-      return normalizeWebhookPath(parsed.pathname || "/");
-    } catch {
-      return null;
-    }
-  }
-  return "/googlechat";
-}
-
 export function registerGoogleChatWebhookTarget(target: WebhookTarget): () => void {
   const key = normalizeWebhookPath(target.path);
   const normalizedTarget = { ...target, path: key };
@@ -933,7 +907,11 @@ async function uploadAttachmentForReply(params: {
 
 export function monitorGoogleChatProvider(options: GoogleChatMonitorOptions): () => void {
   const core = getGoogleChatRuntime();
-  const webhookPath = resolveWebhookPath(options.webhookPath, options.webhookUrl);
+  const webhookPath = resolveWebhookPath({
+    webhookPath: options.webhookPath,
+    webhookUrl: options.webhookUrl,
+    defaultPath: "/googlechat",
+  });
   if (!webhookPath) {
     options.runtime.error?.(`[${options.account.accountId}] invalid webhook path`);
     return () => {};
@@ -968,8 +946,11 @@ export function resolveGoogleChatWebhookPath(params: {
   account: ResolvedGoogleChatAccount;
 }): string {
   return (
-    resolveWebhookPath(params.account.config.webhookPath, params.account.config.webhookUrl) ??
-    "/googlechat"
+    resolveWebhookPath({
+      webhookPath: params.account.config.webhookPath,
+      webhookUrl: params.account.config.webhookUrl,
+      defaultPath: "/googlechat",
+    }) ?? "/googlechat"
   );
 }
 
diff --git a/extensions/imessage/package.json b/extensions/imessage/package.json
index dc9e0d6fdc9..b801b57ba32 100644
--- a/extensions/imessage/package.json
+++ b/extensions/imessage/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/imessage",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw iMessage channel plugin",
   "type": "module",
diff --git a/extensions/irc/package.json b/extensions/irc/package.json
index 3e8977f1bd4..88b9d19ee3b 100644
--- a/extensions/irc/package.json
+++ b/extensions/irc/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/irc",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw IRC channel plugin",
   "type": "module",
   "devDependencies": {
diff --git a/extensions/irc/src/types.ts b/extensions/irc/src/types.ts
index 5446649aad2..ac6a5c9cb7b 100644
--- a/extensions/irc/src/types.ts
+++ b/extensions/irc/src/types.ts
@@ -1,3 +1,4 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import type {
   BlockStreamingCoalesceConfig,
   DmConfig,
@@ -83,12 +84,10 @@ export type IrcInboundMessage = {
   isGroup: boolean;
 };
 
-export type IrcProbe = {
-  ok: boolean;
+export type IrcProbe = BaseProbeResult<string> & {
   host: string;
   port: number;
   tls: boolean;
   nick: string;
   latencyMs?: number;
-  error?: string;
 };
diff --git a/extensions/line/package.json b/extensions/line/package.json
index 9e8550e5184..c03d34cf19b 100644
--- a/extensions/line/package.json
+++ b/extensions/line/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/line",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw LINE channel plugin",
   "type": "module",
diff --git a/extensions/line/src/channel.startup.test.ts b/extensions/line/src/channel.startup.test.ts
new file mode 100644
index 00000000000..fa04e6ca6d7
--- /dev/null
+++ b/extensions/line/src/channel.startup.test.ts
@@ -0,0 +1,101 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { linePlugin } from "./channel.js";
+import { setLineRuntime } from "./runtime.js";
+
+function createRuntime() {
+  const probeLineBot = vi.fn(async () => ({ ok: false }));
+  const monitorLineProvider = vi.fn(async () => ({
+    account: { accountId: "default" },
+    handleWebhook: async () => {},
+    stop: () => {},
+  }));
+
+  const runtime = {
+    channel: {
+      line: {
+        probeLineBot,
+        monitorLineProvider,
+      },
+    },
+    logging: {
+      shouldLogVerbose: () => false,
+    },
+  } as unknown as PluginRuntime;
+
+  return { runtime, probeLineBot, monitorLineProvider };
+}
+
+function createStartAccountCtx(params: { token: string; secret: string; runtime: unknown }) {
+  return {
+    account: {
+      accountId: "default",
+      channelAccessToken: params.token,
+      channelSecret: params.secret,
+      config: {},
+    },
+    cfg: {} as OpenClawConfig,
+    runtime: params.runtime,
+    abortSignal: undefined,
+    log: { info: vi.fn(), debug: vi.fn() },
+  };
+}
+
+describe("linePlugin gateway.startAccount", () => {
+  it("fails startup when channel secret is missing", async () => {
+    const { runtime, monitorLineProvider } = createRuntime();
+    setLineRuntime(runtime);
+
+    await expect(
+      linePlugin.gateway.startAccount(
+        createStartAccountCtx({
+          token: "token",
+          secret: "   ",
+          runtime: {},
+        }) as never,
+      ),
+    ).rejects.toThrow(
+      'LINE webhook mode requires a non-empty channel secret for account "default".',
+    );
+    expect(monitorLineProvider).not.toHaveBeenCalled();
+  });
+
+  it("fails startup when channel access token is missing", async () => {
+    const { runtime, monitorLineProvider } = createRuntime();
+    setLineRuntime(runtime);
+
+    await expect(
+      linePlugin.gateway.startAccount(
+        createStartAccountCtx({
+          token: "   ",
+          secret: "secret",
+          runtime: {},
+        }) as never,
+      ),
+    ).rejects.toThrow(
+      'LINE webhook mode requires a non-empty channel access token for account "default".',
+    );
+    expect(monitorLineProvider).not.toHaveBeenCalled();
+  });
+
+  it("starts provider when token and secret are present", async () => {
+    const { runtime, monitorLineProvider } = createRuntime();
+    setLineRuntime(runtime);
+
+    await linePlugin.gateway.startAccount(
+      createStartAccountCtx({
+        token: "token",
+        secret: "secret",
+        runtime: {},
+      }) as never,
+    );
+
+    expect(monitorLineProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channelAccessToken: "token",
+        channelSecret: "secret",
+        accountId: "default",
+      }),
+    );
+  });
+});
diff --git a/extensions/line/src/channel.ts b/extensions/line/src/channel.ts
index 96c0a51d795..cc30264e1e1 100644
--- a/extensions/line/src/channel.ts
+++ b/extensions/line/src/channel.ts
@@ -119,12 +119,13 @@ export const linePlugin: ChannelPlugin<ResolvedLineAccount> = {
         },
       };
     },
-    isConfigured: (account) => Boolean(account.channelAccessToken?.trim()),
+    isConfigured: (account) =>
+      Boolean(account.channelAccessToken?.trim() && account.channelSecret?.trim()),
     describeAccount: (account) => ({
       accountId: account.accountId,
       name: account.name,
       enabled: account.enabled,
-      configured: Boolean(account.channelAccessToken?.trim()),
+      configured: Boolean(account.channelAccessToken?.trim() && account.channelSecret?.trim()),
       tokenSource: account.tokenSource ?? undefined,
     }),
     resolveAllowFrom: ({ cfg, accountId }) =>
@@ -603,7 +604,9 @@ export const linePlugin: ChannelPlugin<ResolvedLineAccount> = {
     probeAccount: async ({ account, timeoutMs }) =>
       getLineRuntime().channel.line.probeLineBot(account.channelAccessToken, timeoutMs),
     buildAccountSnapshot: ({ account, runtime, probe }) => {
-      const configured = Boolean(account.channelAccessToken?.trim());
+      const configured = Boolean(
+        account.channelAccessToken?.trim() && account.channelSecret?.trim(),
+      );
       return {
         accountId: account.accountId,
         name: account.name,
@@ -626,6 +629,16 @@ export const linePlugin: ChannelPlugin<ResolvedLineAccount> = {
       const account = ctx.account;
       const token = account.channelAccessToken.trim();
       const secret = account.channelSecret.trim();
+      if (!token) {
+        throw new Error(
+          `LINE webhook mode requires a non-empty channel access token for account "${account.accountId}".`,
+        );
+      }
+      if (!secret) {
+        throw new Error(
+          `LINE webhook mode requires a non-empty channel secret for account "${account.accountId}".`,
+        );
+      }
 
       let lineBotLabel = "";
       try {
diff --git a/extensions/llm-task/package.json b/extensions/llm-task/package.json
index 13c6b256a97..e527185a0e0 100644
--- a/extensions/llm-task/package.json
+++ b/extensions/llm-task/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/llm-task",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw JSON-only LLM task plugin",
   "type": "module",
diff --git a/extensions/lobster/package.json b/extensions/lobster/package.json
index 6bc9674ad1c..3ceb3736da1 100644
--- a/extensions/lobster/package.json
+++ b/extensions/lobster/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/lobster",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
   "type": "module",
   "devDependencies": {
diff --git a/extensions/matrix/CHANGELOG.md b/extensions/matrix/CHANGELOG.md
index 76e12ddc8e2..71dbe303b57 100644
--- a/extensions/matrix/CHANGELOG.md
+++ b/extensions/matrix/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/matrix/package.json b/extensions/matrix/package.json
index 98eedf802cf..4a9c328ec61 100644
--- a/extensions/matrix/package.json
+++ b/extensions/matrix/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {
diff --git a/extensions/matrix/src/group-mentions.ts b/extensions/matrix/src/group-mentions.ts
index dd8c2bb7e71..8f36f6d9542 100644
--- a/extensions/matrix/src/group-mentions.ts
+++ b/extensions/matrix/src/group-mentions.ts
@@ -3,29 +3,33 @@ import type { CoreConfig } from "./types.js";
 import { resolveMatrixAccountConfig } from "./matrix/accounts.js";
 import { resolveMatrixRoomConfig } from "./matrix/monitor/rooms.js";
 
-export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
+function stripLeadingPrefixCaseInsensitive(value: string, prefix: string): string {
+  return value.toLowerCase().startsWith(prefix.toLowerCase())
+    ? value.slice(prefix.length).trim()
+    : value;
+}
+
+function resolveMatrixRoomConfigForGroup(params: ChannelGroupContext) {
   const rawGroupId = params.groupId?.trim() ?? "";
   let roomId = rawGroupId;
-  const lower = roomId.toLowerCase();
-  if (lower.startsWith("matrix:")) {
-    roomId = roomId.slice("matrix:".length).trim();
-  }
-  if (roomId.toLowerCase().startsWith("channel:")) {
-    roomId = roomId.slice("channel:".length).trim();
-  }
-  if (roomId.toLowerCase().startsWith("room:")) {
-    roomId = roomId.slice("room:".length).trim();
-  }
+  roomId = stripLeadingPrefixCaseInsensitive(roomId, "matrix:");
+  roomId = stripLeadingPrefixCaseInsensitive(roomId, "channel:");
+  roomId = stripLeadingPrefixCaseInsensitive(roomId, "room:");
+
   const groupChannel = params.groupChannel?.trim() ?? "";
   const aliases = groupChannel ? [groupChannel] : [];
   const cfg = params.cfg as CoreConfig;
   const matrixConfig = resolveMatrixAccountConfig({ cfg, accountId: params.accountId });
-  const resolved = resolveMatrixRoomConfig({
+  return resolveMatrixRoomConfig({
     rooms: matrixConfig.groups ?? matrixConfig.rooms,
     roomId,
     aliases,
     name: groupChannel || undefined,
   }).config;
+}
+
+export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
+  const resolved = resolveMatrixRoomConfigForGroup(params);
   if (resolved) {
     if (resolved.autoReply === true) {
       return false;
@@ -43,27 +47,6 @@ export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): b
 export function resolveMatrixGroupToolPolicy(
   params: ChannelGroupContext,
 ): GroupToolPolicyConfig | undefined {
-  const rawGroupId = params.groupId?.trim() ?? "";
-  let roomId = rawGroupId;
-  const lower = roomId.toLowerCase();
-  if (lower.startsWith("matrix:")) {
-    roomId = roomId.slice("matrix:".length).trim();
-  }
-  if (roomId.toLowerCase().startsWith("channel:")) {
-    roomId = roomId.slice("channel:".length).trim();
-  }
-  if (roomId.toLowerCase().startsWith("room:")) {
-    roomId = roomId.slice("room:".length).trim();
-  }
-  const groupChannel = params.groupChannel?.trim() ?? "";
-  const aliases = groupChannel ? [groupChannel] : [];
-  const cfg = params.cfg as CoreConfig;
-  const matrixConfig = resolveMatrixAccountConfig({ cfg, accountId: params.accountId });
-  const resolved = resolveMatrixRoomConfig({
-    rooms: matrixConfig.groups ?? matrixConfig.rooms,
-    roomId,
-    aliases,
-    name: groupChannel || undefined,
-  }).config;
+  const resolved = resolveMatrixRoomConfigForGroup(params);
   return resolved?.tools;
 }
diff --git a/extensions/matrix/src/matrix/probe.ts b/extensions/matrix/src/matrix/probe.ts
index 7bd54bdc400..5681b242c24 100644
--- a/extensions/matrix/src/matrix/probe.ts
+++ b/extensions/matrix/src/matrix/probe.ts
@@ -1,9 +1,8 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import { createMatrixClient, isBunRuntime } from "./client.js";
 
-export type MatrixProbe = {
-  ok: boolean;
+export type MatrixProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs: number;
   userId?: string | null;
 };
diff --git a/extensions/mattermost/package.json b/extensions/mattermost/package.json
index e053f4d43a9..ff4df9f7414 100644
--- a/extensions/mattermost/package.json
+++ b/extensions/mattermost/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/mattermost",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Mattermost channel plugin",
   "type": "module",
diff --git a/extensions/mattermost/src/mattermost/monitor.ts b/extensions/mattermost/src/mattermost/monitor.ts
index ddc6dce702b..db31051356a 100644
--- a/extensions/mattermost/src/mattermost/monitor.ts
+++ b/extensions/mattermost/src/mattermost/monitor.ts
@@ -6,6 +6,7 @@ import type {
   RuntimeEnv,
 } from "openclaw/plugin-sdk";
 import {
+  buildAgentMediaPayload,
   createReplyPrefixOptions,
   createTypingCallbacks,
   logInboundDrop,
@@ -179,27 +180,6 @@ function buildMattermostAttachmentPlaceholder(mediaList: MattermostMediaInfo[]):
   return `${tag} (${mediaList.length} ${suffix})`;
 }
 
-function buildMattermostMediaPayload(mediaList: MattermostMediaInfo[]): {
-  MediaPath?: string;
-  MediaType?: string;
-  MediaUrl?: string;
-  MediaPaths?: string[];
-  MediaUrls?: string[];
-  MediaTypes?: string[];
-} {
-  const first = mediaList[0];
-  const mediaPaths = mediaList.map((media) => media.path);
-  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
-  return {
-    MediaPath: first?.path,
-    MediaType: first?.contentType,
-    MediaUrl: first?.path,
-    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
-    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
-    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
-  };
-}
-
 function buildMattermostWsUrl(baseUrl: string): string {
   const normalized = normalizeMattermostBaseUrl(baseUrl);
   if (!normalized) {
@@ -650,7 +630,7 @@ export async function monitorMattermostProvider(opts: MonitorMattermostOpts = {}
     }
 
     const to = kind === "direct" ? `user:${senderId}` : `channel:${channelId}`;
-    const mediaPayload = buildMattermostMediaPayload(mediaList);
+    const mediaPayload = buildAgentMediaPayload(mediaList);
     const inboundHistory =
       historyKey && historyLimit > 0
         ? (channelHistories.get(historyKey) ?? []).map((entry) => ({
diff --git a/extensions/mattermost/src/mattermost/probe.ts b/extensions/mattermost/src/mattermost/probe.ts
index a02ca4935fd..cb468ec14db 100644
--- a/extensions/mattermost/src/mattermost/probe.ts
+++ b/extensions/mattermost/src/mattermost/probe.ts
@@ -1,9 +1,8 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import { normalizeMattermostBaseUrl, type MattermostUser } from "./client.js";
 
-export type MattermostProbe = {
-  ok: boolean;
+export type MattermostProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs?: number | null;
   bot?: MattermostUser;
 };
diff --git a/extensions/memory-core/package.json b/extensions/memory-core/package.json
index 9adaf8da479..99994f54487 100644
--- a/extensions/memory-core/package.json
+++ b/extensions/memory-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/memory-core",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw core memory search plugin",
   "type": "module",
diff --git a/extensions/memory-lancedb/package.json b/extensions/memory-lancedb/package.json
index a15dcf1caac..58c97bf228e 100644
--- a/extensions/memory-lancedb/package.json
+++ b/extensions/memory-lancedb/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/memory-lancedb",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw LanceDB-backed long-term memory plugin with auto-recall/capture",
   "type": "module",
diff --git a/extensions/minimax-portal-auth/package.json b/extensions/minimax-portal-auth/package.json
index 0fd990f383f..704b9f6b188 100644
--- a/extensions/minimax-portal-auth/package.json
+++ b/extensions/minimax-portal-auth/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/minimax-portal-auth",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw MiniMax Portal OAuth provider plugin",
   "type": "module",
diff --git a/extensions/msteams/CHANGELOG.md b/extensions/msteams/CHANGELOG.md
index ce0da7bd476..fc2b72ed9af 100644
--- a/extensions/msteams/CHANGELOG.md
+++ b/extensions/msteams/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/msteams/package.json b/extensions/msteams/package.json
index 42809fdcd63..10f033b9c9b 100644
--- a/extensions/msteams/package.json
+++ b/extensions/msteams/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/msteams",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Microsoft Teams channel plugin",
   "type": "module",
   "dependencies": {
diff --git a/extensions/msteams/src/channel.ts b/extensions/msteams/src/channel.ts
index d6fd75abf6c..2958e4c22d0 100644
--- a/extensions/msteams/src/channel.ts
+++ b/extensions/msteams/src/channel.ts
@@ -1,6 +1,8 @@
 import type { ChannelMessageActionName, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
 import {
+  buildBaseChannelStatusSummary,
   buildChannelConfigSchema,
+  createDefaultChannelRuntimeState,
   DEFAULT_ACCOUNT_ID,
   MSTeamsConfigSchema,
   PAIRING_APPROVED_MESSAGE,
@@ -415,20 +417,9 @@ export const msteamsPlugin: ChannelPlugin<ResolvedMSTeamsAccount> = {
   },
   outbound: msteamsOutbound,
   status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-      port: null,
-    },
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID, { port: null }),
     buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
+      ...buildBaseChannelStatusSummary(snapshot),
       port: snapshot.port ?? null,
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
diff --git a/extensions/msteams/src/onboarding.ts b/extensions/msteams/src/onboarding.ts
index d950bd2db08..191a2631a91 100644
--- a/extensions/msteams/src/onboarding.ts
+++ b/extensions/msteams/src/onboarding.ts
@@ -63,6 +63,32 @@ function looksLikeGuid(value: string): boolean {
   return /^[0-9a-fA-F-]{16,}$/.test(value);
 }
 
+async function promptMSTeamsCredentials(prompter: WizardPrompter): Promise<{
+  appId: string;
+  appPassword: string;
+  tenantId: string;
+}> {
+  const appId = String(
+    await prompter.text({
+      message: "Enter MS Teams App ID",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  const appPassword = String(
+    await prompter.text({
+      message: "Enter MS Teams App Password",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  const tenantId = String(
+    await prompter.text({
+      message: "Enter MS Teams Tenant ID",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  return { appId, appPassword, tenantId };
+}
+
 async function promptMSTeamsAllowFrom(params: {
   cfg: OpenClawConfig;
   prompter: WizardPrompter;
@@ -251,24 +277,7 @@ export const msteamsOnboardingAdapter: ChannelOnboardingAdapter = {
           },
         };
       } else {
-        appId = String(
-          await prompter.text({
-            message: "Enter MS Teams App ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appPassword = String(
-          await prompter.text({
-            message: "Enter MS Teams App Password",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        tenantId = String(
-          await prompter.text({
-            message: "Enter MS Teams Tenant ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        ({ appId, appPassword, tenantId } = await promptMSTeamsCredentials(prompter));
       }
     } else if (hasConfigCreds) {
       const keep = await prompter.confirm({
@@ -276,44 +285,10 @@ export const msteamsOnboardingAdapter: ChannelOnboardingAdapter = {
         initialValue: true,
       });
       if (!keep) {
-        appId = String(
-          await prompter.text({
-            message: "Enter MS Teams App ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appPassword = String(
-          await prompter.text({
-            message: "Enter MS Teams App Password",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        tenantId = String(
-          await prompter.text({
-            message: "Enter MS Teams Tenant ID",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        ({ appId, appPassword, tenantId } = await promptMSTeamsCredentials(prompter));
       }
     } else {
-      appId = String(
-        await prompter.text({
-          message: "Enter MS Teams App ID",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
-      appPassword = String(
-        await prompter.text({
-          message: "Enter MS Teams App Password",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
-      tenantId = String(
-        await prompter.text({
-          message: "Enter MS Teams Tenant ID",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
+      ({ appId, appPassword, tenantId } = await promptMSTeamsCredentials(prompter));
     }
 
     if (appId && appPassword && tenantId) {
diff --git a/extensions/msteams/src/probe.ts b/extensions/msteams/src/probe.ts
index 6bbcc0b3c3c..b6732c658c4 100644
--- a/extensions/msteams/src/probe.ts
+++ b/extensions/msteams/src/probe.ts
@@ -1,11 +1,9 @@
-import type { MSTeamsConfig } from "openclaw/plugin-sdk";
+import type { BaseProbeResult, MSTeamsConfig } from "openclaw/plugin-sdk";
 import { formatUnknownError } from "./errors.js";
 import { loadMSTeamsSdkWithAuth } from "./sdk.js";
 import { resolveMSTeamsCredentials } from "./token.js";
 
-export type ProbeMSTeamsResult = {
-  ok: boolean;
-  error?: string;
+export type ProbeMSTeamsResult = BaseProbeResult<string> & {
   appId?: string;
   graph?: {
     ok: boolean;
diff --git a/extensions/nextcloud-talk/package.json b/extensions/nextcloud-talk/package.json
index c9e3d2c5861..8861244c04c 100644
--- a/extensions/nextcloud-talk/package.json
+++ b/extensions/nextcloud-talk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/nextcloud-talk",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Nextcloud Talk channel plugin",
   "type": "module",
   "devDependencies": {
diff --git a/extensions/nostr/CHANGELOG.md b/extensions/nostr/CHANGELOG.md
index c61303c1bf2..d5cd6f985f3 100644
--- a/extensions/nostr/CHANGELOG.md
+++ b/extensions/nostr/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/nostr/package.json b/extensions/nostr/package.json
index 91de4c6a646..469b57eca5c 100644
--- a/extensions/nostr/package.json
+++ b/extensions/nostr/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/nostr",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Nostr channel plugin for NIP-04 encrypted DMs",
   "type": "module",
   "dependencies": {
diff --git a/extensions/nostr/src/channel.ts b/extensions/nostr/src/channel.ts
index 8fa8d58b61f..8fe7ce4ac92 100644
--- a/extensions/nostr/src/channel.ts
+++ b/extensions/nostr/src/channel.ts
@@ -1,5 +1,7 @@
 import {
   buildChannelConfigSchema,
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
   DEFAULT_ACCOUNT_ID,
   formatPairingApproveHint,
   type ChannelPlugin,
@@ -157,28 +159,8 @@ export const nostrPlugin: ChannelPlugin<ResolvedNostrAccount> = {
   },
 
   status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-    },
-    collectStatusIssues: (accounts) =>
-      accounts.flatMap((account) => {
-        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
-        if (!lastError) {
-          return [];
-        }
-        return [
-          {
-            channel: "nostr",
-            accountId: account.accountId,
-            kind: "runtime" as const,
-            message: `Channel error: ${lastError}`,
-          },
-        ];
-      }),
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+    collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("nostr", accounts),
     buildChannelSummary: ({ snapshot }) => ({
       configured: snapshot.configured ?? false,
       publicKey: snapshot.publicKey ?? null,
diff --git a/extensions/open-prose/package.json b/extensions/open-prose/package.json
index 389076660c6..d7750c954eb 100644
--- a/extensions/open-prose/package.json
+++ b/extensions/open-prose/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/open-prose",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenProse VM skill pack plugin (slash command + telemetry).",
   "type": "module",
diff --git a/extensions/signal/package.json b/extensions/signal/package.json
index 2f35b466502..74321565137 100644
--- a/extensions/signal/package.json
+++ b/extensions/signal/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/signal",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Signal channel plugin",
   "type": "module",
diff --git a/extensions/signal/src/channel.ts b/extensions/signal/src/channel.ts
index 1b270e89469..18c3bcc2393 100644
--- a/extensions/signal/src/channel.ts
+++ b/extensions/signal/src/channel.ts
@@ -1,6 +1,9 @@
 import {
   applyAccountNameToChannelSection,
+  buildBaseChannelStatusSummary,
   buildChannelConfigSchema,
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
   formatPairingApproveHint,
@@ -249,35 +252,11 @@ export const signalPlugin: ChannelPlugin<ResolvedSignalAccount> = {
     },
   },
   status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-    },
-    collectStatusIssues: (accounts) =>
-      accounts.flatMap((account) => {
-        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
-        if (!lastError) {
-          return [];
-        }
-        return [
-          {
-            channel: "signal",
-            accountId: account.accountId,
-            kind: "runtime",
-            message: `Channel error: ${lastError}`,
-          },
-        ];
-      }),
+    defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+    collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("signal", accounts),
     buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
+      ...buildBaseChannelStatusSummary(snapshot),
       baseUrl: snapshot.baseUrl ?? null,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
diff --git a/extensions/slack/package.json b/extensions/slack/package.json
index f17c978fd04..f0d9bff43b8 100644
--- a/extensions/slack/package.json
+++ b/extensions/slack/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/slack",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Slack channel plugin",
   "type": "module",
diff --git a/extensions/telegram/package.json b/extensions/telegram/package.json
index cc0ed00dcbe..74d289bf702 100644
--- a/extensions/telegram/package.json
+++ b/extensions/telegram/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/telegram",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Telegram channel plugin",
   "type": "module",
diff --git a/extensions/tlon/package.json b/extensions/tlon/package.json
index dcddb873d44..4cc32c2e03a 100644
--- a/extensions/tlon/package.json
+++ b/extensions/tlon/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/tlon",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Tlon/Urbit channel plugin",
   "type": "module",
diff --git a/extensions/tlon/src/urbit/channel-client.ts b/extensions/tlon/src/urbit/channel-client.ts
index 1b38f7d7c80..fb8af656a6f 100644
--- a/extensions/tlon/src/urbit/channel-client.ts
+++ b/extensions/tlon/src/urbit/channel-client.ts
@@ -1,5 +1,5 @@
 import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
-import { ensureUrbitChannelOpen } from "./channel-ops.js";
+import { ensureUrbitChannelOpen, pokeUrbitChannel, scryUrbitPath } from "./channel-ops.js";
 import { getUrbitContext, normalizeUrbitCookie } from "./context.js";
 import { urbitFetch } from "./fetch.js";
 
@@ -70,69 +70,35 @@ export class UrbitChannelClient {
 
   async poke(params: { app: string; mark: string; json: unknown }): Promise<number> {
     await this.open();
-    const pokeId = Date.now();
-    const pokeData = {
-      id: pokeId,
-      action: "poke",
-      ship: this.ship,
-      app: params.app,
-      mark: params.mark,
-      json: params.json,
-    };
-
-    const { response, release } = await urbitFetch({
-      baseUrl: this.baseUrl,
-      path: this.channelPath,
-      init: {
-        method: "PUT",
-        headers: {
-          "Content-Type": "application/json",
-          Cookie: this.cookie,
-        },
-        body: JSON.stringify([pokeData]),
-      },
-      ssrfPolicy: this.ssrfPolicy,
-      lookupFn: this.lookupFn,
-      fetchImpl: this.fetchImpl,
-      timeoutMs: 30_000,
-      auditContext: "tlon-urbit-poke",
-    });
-
-    try {
-      if (!response.ok && response.status !== 204) {
-        const errorText = await response.text().catch(() => "");
-        throw new Error(`Poke failed: ${response.status}${errorText ? ` - ${errorText}` : ""}`);
-      }
-      return pokeId;
-    } finally {
-      await release();
+    const channelId = this.channelId;
+    if (!channelId) {
+      throw new Error("Channel not opened");
     }
+    return await pokeUrbitChannel(
+      {
+        baseUrl: this.baseUrl,
+        cookie: this.cookie,
+        ship: this.ship,
+        channelId,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      { ...params, auditContext: "tlon-urbit-poke" },
+    );
   }
 
   async scry(path: string): Promise<unknown> {
-    const scryPath = `/~/scry${path}`;
-    const { response, release } = await urbitFetch({
-      baseUrl: this.baseUrl,
-      path: scryPath,
-      init: {
-        method: "GET",
-        headers: { Cookie: this.cookie },
+    return await scryUrbitPath(
+      {
+        baseUrl: this.baseUrl,
+        cookie: this.cookie,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
       },
-      ssrfPolicy: this.ssrfPolicy,
-      lookupFn: this.lookupFn,
-      fetchImpl: this.fetchImpl,
-      timeoutMs: 30_000,
-      auditContext: "tlon-urbit-scry",
-    });
-
-    try {
-      if (!response.ok) {
-        throw new Error(`Scry failed: ${response.status} for path ${path}`);
-      }
-      return await response.json();
-    } finally {
-      await release();
-    }
+      { path, auditContext: "tlon-urbit-scry" },
+    );
   }
 
   async getOurName(): Promise<string> {
diff --git a/extensions/tlon/src/urbit/channel-ops.ts b/extensions/tlon/src/urbit/channel-ops.ts
index f62d870fc45..077e8d01816 100644
--- a/extensions/tlon/src/urbit/channel-ops.ts
+++ b/extensions/tlon/src/urbit/channel-ops.ts
@@ -12,6 +12,78 @@ export type UrbitChannelDeps = {
   fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 };
 
+export async function pokeUrbitChannel(
+  deps: UrbitChannelDeps,
+  params: { app: string; mark: string; json: unknown; auditContext: string },
+): Promise<number> {
+  const pokeId = Date.now();
+  const pokeData = {
+    id: pokeId,
+    action: "poke",
+    ship: deps.ship,
+    app: params.app,
+    mark: params.mark,
+    json: params.json,
+  };
+
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: `/~/channel/${deps.channelId}`,
+    init: {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: deps.cookie,
+      },
+      body: JSON.stringify([pokeData]),
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok && response.status !== 204) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`Poke failed: ${response.status}${errorText ? ` - ${errorText}` : ""}`);
+    }
+    return pokeId;
+  } finally {
+    await release();
+  }
+}
+
+export async function scryUrbitPath(
+  deps: Pick<UrbitChannelDeps, "baseUrl" | "cookie" | "ssrfPolicy" | "lookupFn" | "fetchImpl">,
+  params: { path: string; auditContext: string },
+): Promise<unknown> {
+  const scryPath = `/~/scry${params.path}`;
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: scryPath,
+    init: {
+      method: "GET",
+      headers: { Cookie: deps.cookie },
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok) {
+      throw new Error(`Scry failed: ${response.status} for path ${params.path}`);
+    }
+    return await response.json();
+  } finally {
+    await release();
+  }
+}
+
 export async function createUrbitChannel(
   deps: UrbitChannelDeps,
   params: { body: unknown; auditContext: string },
diff --git a/extensions/tlon/src/urbit/sse-client.ts b/extensions/tlon/src/urbit/sse-client.ts
index f4a1b8fdf8c..a379d1680b6 100644
--- a/extensions/tlon/src/urbit/sse-client.ts
+++ b/extensions/tlon/src/urbit/sse-client.ts
@@ -1,6 +1,6 @@
 import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
 import { Readable } from "node:stream";
-import { ensureUrbitChannelOpen } from "./channel-ops.js";
+import { ensureUrbitChannelOpen, pokeUrbitChannel, scryUrbitPath } from "./channel-ops.js";
 import { getUrbitContext, normalizeUrbitCookie } from "./context.js";
 import { urbitFetch } from "./fetch.js";
 
@@ -290,71 +290,31 @@ export class UrbitSSEClient {
   }
 
   async poke(params: { app: string; mark: string; json: unknown }) {
-    const pokeId = Date.now();
-    const pokeData = {
-      id: pokeId,
-      action: "poke",
-      ship: this.ship,
-      app: params.app,
-      mark: params.mark,
-      json: params.json,
-    };
-
-    const { response, release } = await urbitFetch({
-      baseUrl: this.url,
-      path: `/~/channel/${this.channelId}`,
-      init: {
-        method: "PUT",
-        headers: {
-          "Content-Type": "application/json",
-          Cookie: this.cookie,
-        },
-        body: JSON.stringify([pokeData]),
+    return await pokeUrbitChannel(
+      {
+        baseUrl: this.url,
+        cookie: this.cookie,
+        ship: this.ship,
+        channelId: this.channelId,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
       },
-      ssrfPolicy: this.ssrfPolicy,
-      lookupFn: this.lookupFn,
-      fetchImpl: this.fetchImpl,
-      timeoutMs: 30_000,
-      auditContext: "tlon-urbit-poke",
-    });
-
-    try {
-      if (!response.ok && response.status !== 204) {
-        const errorText = await response.text().catch(() => "");
-        throw new Error(`Poke failed: ${response.status}${errorText ? ` - ${errorText}` : ""}`);
-      }
-    } finally {
-      await release();
-    }
-
-    return pokeId;
+      { ...params, auditContext: "tlon-urbit-poke" },
+    );
   }
 
   async scry(path: string) {
-    const { response, release } = await urbitFetch({
-      baseUrl: this.url,
-      path: `/~/scry${path}`,
-      init: {
-        method: "GET",
-        headers: {
-          Cookie: this.cookie,
-        },
+    return await scryUrbitPath(
+      {
+        baseUrl: this.url,
+        cookie: this.cookie,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
       },
-      ssrfPolicy: this.ssrfPolicy,
-      lookupFn: this.lookupFn,
-      fetchImpl: this.fetchImpl,
-      timeoutMs: 30_000,
-      auditContext: "tlon-urbit-scry",
-    });
-
-    try {
-      if (!response.ok) {
-        throw new Error(`Scry failed: ${response.status} for path ${path}`);
-      }
-      return await response.json();
-    } finally {
-      await release();
-    }
+      { path, auditContext: "tlon-urbit-scry" },
+    );
   }
 
   async attemptReconnect() {
diff --git a/extensions/twitch/CHANGELOG.md b/extensions/twitch/CHANGELOG.md
index b8bdcce37bc..a30f2c78439 100644
--- a/extensions/twitch/CHANGELOG.md
+++ b/extensions/twitch/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/twitch/package.json b/extensions/twitch/package.json
index c5b8c470901..490bef10daa 100644
--- a/extensions/twitch/package.json
+++ b/extensions/twitch/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/twitch",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw Twitch channel plugin",
   "type": "module",
diff --git a/extensions/twitch/src/probe.ts b/extensions/twitch/src/probe.ts
index 56ea99146d5..41321103a45 100644
--- a/extensions/twitch/src/probe.ts
+++ b/extensions/twitch/src/probe.ts
@@ -1,3 +1,4 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import { StaticAuthProvider } from "@twurple/auth";
 import { ChatClient } from "@twurple/chat";
 import type { TwitchAccountConfig } from "./types.js";
@@ -6,9 +7,7 @@ import { normalizeToken } from "./utils/twitch.js";
 /**
  * Result of probing a Twitch account
  */
-export type ProbeTwitchResult = {
-  ok: boolean;
-  error?: string;
+export type ProbeTwitchResult = BaseProbeResult<string> & {
   username?: string;
   elapsedMs: number;
   connected?: boolean;
diff --git a/extensions/voice-call/CHANGELOG.md b/extensions/voice-call/CHANGELOG.md
index cb7ab8c8da4..3d3e7738fb1 100644
--- a/extensions/voice-call/CHANGELOG.md
+++ b/extensions/voice-call/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/voice-call/package.json b/extensions/voice-call/package.json
index c184b58ccf3..161f99e4c4c 100644
--- a/extensions/voice-call/package.json
+++ b/extensions/voice-call/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/voice-call",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw voice-call plugin",
   "type": "module",
   "dependencies": {
diff --git a/extensions/whatsapp/package.json b/extensions/whatsapp/package.json
index fcd10985c00..fca5d24aa4a 100644
--- a/extensions/whatsapp/package.json
+++ b/extensions/whatsapp/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/whatsapp",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "private": true,
   "description": "OpenClaw WhatsApp channel plugin",
   "type": "module",
diff --git a/extensions/zalo/CHANGELOG.md b/extensions/zalo/CHANGELOG.md
index f0f3648235d..3d1a3ee5e9a 100644
--- a/extensions/zalo/CHANGELOG.md
+++ b/extensions/zalo/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/zalo/package.json b/extensions/zalo/package.json
index 60c4aca0e66..b836a0ee1cf 100644
--- a/extensions/zalo/package.json
+++ b/extensions/zalo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalo",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Zalo channel plugin",
   "type": "module",
   "dependencies": {
diff --git a/extensions/zalo/src/monitor.ts b/extensions/zalo/src/monitor.ts
index 2c41d8262ca..1ee2efb5315 100644
--- a/extensions/zalo/src/monitor.ts
+++ b/extensions/zalo/src/monitor.ts
@@ -2,7 +2,9 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig, MarkdownTableMode } from "openclaw/plugin-sdk";
 import {
   createReplyPrefixOptions,
+  normalizeWebhookPath,
   readJsonBodyWithLimit,
+  resolveWebhookPath,
   requestBodyErrorToText,
 } from "openclaw/plugin-sdk";
 import type { ResolvedZaloAccount } from "./accounts.js";
@@ -80,34 +82,6 @@ type WebhookTarget = {
 
 const webhookTargets = new Map<string, WebhookTarget[]>();
 
-function normalizeWebhookPath(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return "/";
-  }
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  if (withSlash.length > 1 && withSlash.endsWith("/")) {
-    return withSlash.slice(0, -1);
-  }
-  return withSlash;
-}
-
-function resolveWebhookPath(webhookPath?: string, webhookUrl?: string): string | null {
-  const trimmedPath = webhookPath?.trim();
-  if (trimmedPath) {
-    return normalizeWebhookPath(trimmedPath);
-  }
-  if (webhookUrl?.trim()) {
-    try {
-      const parsed = new URL(webhookUrl);
-      return normalizeWebhookPath(parsed.pathname || "/");
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
 export function registerZaloWebhookTarget(target: WebhookTarget): () => void {
   const key = normalizeWebhookPath(target.path);
   const normalizedTarget = { ...target, path: key };
@@ -700,7 +674,7 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
       throw new Error("Zalo webhook secret must be 8-256 characters");
     }
 
-    const path = resolveWebhookPath(webhookPath, webhookUrl);
+    const path = resolveWebhookPath({ webhookPath, webhookUrl, defaultPath: null });
     if (!path) {
       throw new Error("Zalo webhookPath could not be derived");
     }
diff --git a/extensions/zalo/src/probe.ts b/extensions/zalo/src/probe.ts
index ebdb37a34f3..c2d95fa1d28 100644
--- a/extensions/zalo/src/probe.ts
+++ b/extensions/zalo/src/probe.ts
@@ -1,9 +1,8 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import { getMe, ZaloApiError, type ZaloBotInfo, type ZaloFetch } from "./api.js";
 
-export type ZaloProbeResult = {
-  ok: boolean;
+export type ZaloProbeResult = BaseProbeResult<string> & {
   bot?: ZaloBotInfo;
-  error?: string;
   elapsedMs: number;
 };
 
diff --git a/extensions/zalo/src/token.ts b/extensions/zalo/src/token.ts
index 480f66c8fad..b335f57a3c2 100644
--- a/extensions/zalo/src/token.ts
+++ b/extensions/zalo/src/token.ts
@@ -1,9 +1,8 @@
 import { readFileSync } from "node:fs";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import { type BaseTokenResolution, DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
 import type { ZaloConfig } from "./types.js";
 
-export type ZaloTokenResolution = {
-  token: string;
+export type ZaloTokenResolution = BaseTokenResolution & {
   source: "env" | "config" | "configFile" | "none";
 };
 
diff --git a/extensions/zalouser/CHANGELOG.md b/extensions/zalouser/CHANGELOG.md
index 33f2f4f11ba..cdf1581b628 100644
--- a/extensions/zalouser/CHANGELOG.md
+++ b/extensions/zalouser/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.16
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.15
 
 ### Changes
diff --git a/extensions/zalouser/package.json b/extensions/zalouser/package.json
index a2aa258e596..60481ce2ef0 100644
--- a/extensions/zalouser/package.json
+++ b/extensions/zalouser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalouser",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "OpenClaw Zalo Personal Account plugin via zca-cli",
   "type": "module",
   "dependencies": {
diff --git a/extensions/zalouser/src/probe.ts b/extensions/zalouser/src/probe.ts
index bfeb92ec586..6bdc962052f 100644
--- a/extensions/zalouser/src/probe.ts
+++ b/extensions/zalouser/src/probe.ts
@@ -1,11 +1,10 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
 import type { ZcaUserInfo } from "./types.js";
 import { runZca, parseJsonOutput } from "./zca.js";
 
-export interface ZalouserProbeResult {
-  ok: boolean;
+export type ZalouserProbeResult = BaseProbeResult<string> & {
   user?: ZcaUserInfo;
-  error?: string;
-}
+};
 
 export async function probeZalouser(
   profile: string,
diff --git a/git-hooks/pre-commit b/git-hooks/pre-commit
index b58a53100d4..919e8507bbe 100755
--- a/git-hooks/pre-commit
+++ b/git-hooks/pre-commit
@@ -1,9 +1,38 @@
-#!/bin/sh
-FILES=$(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g')
-[ -z "$FILES" ] && exit 0
+#!/usr/bin/env bash
 
-echo "$FILES" | xargs pnpm lint --fix
-echo "$FILES" | xargs pnpm format --no-error-on-unmatched-pattern
-echo "$FILES" | xargs git add
+set -euo pipefail
 
-exit 0
+ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+RUN_NODE_TOOL="$ROOT_DIR/scripts/pre-commit/run-node-tool.sh"
+FILTER_FILES="$ROOT_DIR/scripts/pre-commit/filter-staged-files.mjs"
+
+if [[ ! -x "$RUN_NODE_TOOL" ]]; then
+  echo "Missing helper: $RUN_NODE_TOOL" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FILTER_FILES" ]]; then
+  echo "Missing helper: $FILTER_FILES" >&2
+  exit 1
+fi
+
+# Security: avoid option-injection from malicious file names (e.g. "--all", "--force").
+# Robustness: NUL-delimited file list handles spaces/newlines safely.
+mapfile -d '' -t files < <(git diff --cached --name-only --diff-filter=ACMR -z)
+
+if [ "${#files[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+mapfile -d '' -t lint_files < <(node "$FILTER_FILES" lint -- "${files[@]}")
+mapfile -d '' -t format_files < <(node "$FILTER_FILES" format -- "${files[@]}")
+
+if [ "${#lint_files[@]}" -gt 0 ]; then
+  "$RUN_NODE_TOOL" oxlint --type-aware --fix -- "${lint_files[@]}"
+fi
+
+if [ "${#format_files[@]}" -gt 0 ]; then
+  "$RUN_NODE_TOOL" oxfmt --write -- "${format_files[@]}"
+fi
+
+git add -- "${files[@]}"
diff --git a/package.json b/package.json
index c85cc08b2ba..bef3ae67b3f 100644
--- a/package.json
+++ b/package.json
@@ -1,13 +1,25 @@
 {
   "name": "openclaw",
-  "version": "2026.2.15",
+  "version": "2026.2.16",
   "description": "Multi-channel AI gateway with extensible messaging integrations",
   "keywords": [],
+  "homepage": "https://github.com/openclaw/openclaw#readme",
+  "bugs": {
+    "url": "https://github.com/openclaw/openclaw/issues"
+  },
   "license": "MIT",
   "author": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openclaw/openclaw.git"
+  },
   "bin": {
     "openclaw": "openclaw.mjs"
   },
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
   "files": [
     "CHANGELOG.md",
     "LICENSE",
@@ -160,7 +172,7 @@
     "sharp": "^0.34.5",
     "signal-utils": "^0.21.1",
     "sqlite-vec": "0.1.7-alpha.2",
-    "tar": "7.5.7",
+    "tar": "7.5.9",
     "tslog": "^4.10.2",
     "undici": "^7.22.0",
     "ws": "^8.19.0",
@@ -177,13 +189,13 @@
     "@types/proper-lockfile": "^4.1.4",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.18.1",
-    "@typescript/native-preview": "7.0.0-dev.20260214.1",
+    "@typescript/native-preview": "7.0.0-dev.20260215.1",
     "@vitest/coverage-v8": "^4.0.18",
     "lit": "^3.3.2",
     "ollama": "^0.6.3",
     "oxfmt": "0.32.0",
     "oxlint": "^1.47.0",
-    "oxlint-tsgolint": "^0.12.2",
+    "oxlint-tsgolint": "^0.13.0",
     "rolldown": "1.0.0-rc.4",
     "tsdown": "^0.20.3",
     "tsx": "^4.21.0",
@@ -205,7 +217,7 @@
       "form-data": "2.5.4",
       "qs": "6.14.2",
       "@sinclair/typebox": "0.34.48",
-      "tar": "7.5.7",
+      "tar": "7.5.9",
       "tough-cookie": "4.1.3"
     },
     "onlyBuiltDependencies": [
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2d8eb48939c..4b5b37f7e4d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,7 +9,7 @@ overrides:
   form-data: 2.5.4
   qs: 6.14.2
   '@sinclair/typebox': 0.34.48
-  tar: 7.5.7
+  tar: 7.5.9
   tough-cookie: 4.1.3
 
 importers:
@@ -161,8 +161,8 @@ importers:
         specifier: 0.1.7-alpha.2
         version: 0.1.7-alpha.2
       tar:
-        specifier: 7.5.7
-        version: 7.5.7
+        specifier: 7.5.9
+        version: 7.5.9
       tslog:
         specifier: ^4.10.2
         version: 4.10.2
@@ -207,8 +207,8 @@ importers:
         specifier: ^8.18.1
         version: 8.18.1
       '@typescript/native-preview':
-        specifier: 7.0.0-dev.20260214.1
-        version: 7.0.0-dev.20260214.1
+        specifier: 7.0.0-dev.20260215.1
+        version: 7.0.0-dev.20260215.1
       '@vitest/coverage-v8':
         specifier: ^4.0.18
         version: 4.0.18(@vitest/browser@4.0.18(vite@7.3.1(@types/node@25.2.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.2))(vitest@4.0.18))(vitest@4.0.18)
@@ -223,16 +223,16 @@ importers:
         version: 0.32.0
       oxlint:
         specifier: ^1.47.0
-        version: 1.47.0(oxlint-tsgolint@0.12.2)
+        version: 1.47.0(oxlint-tsgolint@0.13.0)
       oxlint-tsgolint:
-        specifier: ^0.12.2
-        version: 0.12.2
+        specifier: ^0.13.0
+        version: 0.13.0
       rolldown:
         specifier: 1.0.0-rc.4
         version: 1.0.0-rc.4
       tsdown:
         specifier: ^0.20.3
-        version: 0.20.3(@typescript/native-preview@7.0.0-dev.20260214.1)(typescript@5.9.3)
+        version: 0.20.3(@typescript/native-preview@7.0.0-dev.20260215.1)(typescript@5.9.3)
       tsx:
         specifier: ^4.21.0
         version: 4.21.0
@@ -783,8 +783,8 @@ packages:
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-string-parser@8.0.0-rc.1':
-    resolution: {integrity: sha512-vi/pfmbrOtQmqgfboaBhaCU50G7mcySVu69VU8z+lYoPPB6WzI9VgV7WQfL908M4oeSH5fDkmoupIqoE0SdApw==}
+  '@babel/helper-string-parser@8.0.0-rc.2':
+    resolution: {integrity: sha512-noLx87RwlBEMrTzncWd/FvTxoJ9+ycHNg0n8yyYydIoDsLZuxknKgWRJUqcrVkNrJ74uGyhWQzQaS3q8xfGAhQ==}
     engines: {node: ^20.19.0 || >=22.12.0}
 
   '@babel/helper-validator-identifier@7.28.5':
@@ -2059,33 +2059,33 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@oxlint-tsgolint/darwin-arm64@0.12.2':
-    resolution: {integrity: sha512-XIfavTqkJPGYi/98z7ZCkZvXq2AccMAAB0iwvKDRTQqiweMXVUyeUdx46phCHHH1PgmIVJtVfysThkHq2xCyrw==}
+  '@oxlint-tsgolint/darwin-arm64@0.13.0':
+    resolution: {integrity: sha512-OWQ3U+oDjjupmX0WU9oYyKF2iUOKDMLW/+zan0cd0vYIGId80xTRHHA8oXnREmK8dsMMP3nV3VXME3NH/hS0lw==}
     cpu: [arm64]
     os: [darwin]
 
-  '@oxlint-tsgolint/darwin-x64@0.12.2':
-    resolution: {integrity: sha512-tytsvP6zmNShRNDo4GgQartOXmd4GPd+TylCUMdO/iWl9PZVOgRyswWbYVTNgn85Cib/aY2q3Uu+jOw+QlbxvQ==}
+  '@oxlint-tsgolint/darwin-x64@0.13.0':
+    resolution: {integrity: sha512-wZvgj+eVqNkCUjSq2ExlMdbGDpZfaw6J+YctQV1pkGFdn7Y9cySWdfwu5v/AW2JPsJbFMXJ8GAr+WoZbRapz2A==}
     cpu: [x64]
     os: [darwin]
 
-  '@oxlint-tsgolint/linux-arm64@0.12.2':
-    resolution: {integrity: sha512-3W38yJuF7taEquhEuD6mYQyCeWNAlc1pNPjFkspkhLKZVgbrhDA4V6fCxLDDRvrTHde0bXPmFvuPlUq5pSePgA==}
+  '@oxlint-tsgolint/linux-arm64@0.13.0':
+    resolution: {integrity: sha512-nwtf5BgHbAWSVwyIF00l6QpfyFcpDMp6D+3cpe6NTgBYMSSSC0Ip1gswUwzVccOPoQK48t+J6vHyURQ96M1KDg==}
     cpu: [arm64]
     os: [linux]
 
-  '@oxlint-tsgolint/linux-x64@0.12.2':
-    resolution: {integrity: sha512-EjcEspeeV0NmaopEp4wcN5ntQP9VCJJDrTvzOjMP4W6ajz18M+pni9vkKvmcPIpRa/UmWobeFgKoVd/KGueeuQ==}
+  '@oxlint-tsgolint/linux-x64@0.13.0':
+    resolution: {integrity: sha512-Rkzgj38eVoGSBuGDaCrALS4FM19+m1Qlv0hjB4MWvXUej014XkB5ze+svYE3HX+AAm1ey9QYj/CQzfz203FPIg==}
     cpu: [x64]
     os: [linux]
 
-  '@oxlint-tsgolint/win32-arm64@0.12.2':
-    resolution: {integrity: sha512-a9L7iA5K/Ht/i8d9+7RTp6hbPa4cyXP0MdySVXAO6vczpL/4ildfY9Hr2m2wqL12uK6xe/uVABpVTrqay/wV+g==}
+  '@oxlint-tsgolint/win32-arm64@0.13.0':
+    resolution: {integrity: sha512-Y+0hFqLT5M7UIvGvTR3QFK27l17FqXk6UwwpBFOcyBGJ5bLd1RaAPWjqTmcgPvdolA6FCMeW1pxZuNtKDlYd7A==}
     cpu: [arm64]
     os: [win32]
 
-  '@oxlint-tsgolint/win32-x64@0.12.2':
-    resolution: {integrity: sha512-Cvt40UbTf5ib12DjGN+mMGOnjWa4Bc6Y7KEaXXp9qzckvs3HpNk2wSwMV3gnuR8Ipx4hkzkzrgzD0BAUsySAfA==}
+  '@oxlint-tsgolint/win32-x64@0.13.0':
+    resolution: {integrity: sha512-mXjTttzyyfl8d/XvxggmZFBq0pbQmRvHbjQEv70YECNaLEHG8j8WYUwLa641uudAnV1VoBI34pc7bmgJM7qhOA==}
     cpu: [x64]
     os: [win32]
 
@@ -2995,43 +2995,43 @@ packages:
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
-  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-Jb2WcLGpTOC6x58e8QPYC/14xmDbnbFIuKqUvYoI77hVtojVyxZi8L5Y4CgYqXYx8vRWmIFk35c1OGdtPip6Sg==}
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-icVO/hEMXjWlKhmpjIpqDyCzPvtHqfrPB+2rkd6M3rz84Bmw+o8Xgd7JvRxryZhR+D0y55me/bKh9xgvsgzuhA==}
     cpu: [arm64]
     os: [darwin]
 
-  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-O9l2gVuQFZsb8NIQtu0HN5Tn/Hw2fwylPOPS/0Y4oW+FUMhkqtvetUkb3zZ0qj7capilZ4YnmyGYg3TDqkP4Nw==}
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-Wz73wf1o9+4KwCLg8wnnIZZDAvv2KRZlDyP4X8GfBNzajfIAwYvI0ANWuIDznUUGeDAcqhBJXNe0Bkf4H9y4mg==}
     cpu: [x64]
     os: [darwin]
 
-  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-Hl4e3yxJqzIGgFI8aH/rLGW+a7kSLHJCpAd5JOLG7hHKnamZF4SjlunnoHLV4IcMri+G6UE3W/84i0QvQP5wLA==}
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-AYyXRxVwLZzfkEYN8FGdV4vqXwbTmv93nAZ6gMLvpDG4ItOybAE1R2obFjlFc+Or/rfQmVvfdkTym3c4bRJ3XQ==}
     cpu: [arm64]
     os: [linux]
 
-  '@typescript/native-preview-linux-arm@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-TaFrVnx3iXtl/oH1hzwvFyqWj9tzkjW8Ufl2m0Vx2/7GXnzZadm2KA6tFpGbzzWbZJznmXxKHL4O3AZRQYyZqQ==}
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-6WVXFVSp3LBBiBgBMtAHQgTDN72mDhgjrmXH7GoABTxR9asK8oPfmy5cwTp1sPD46pYhqjnSHMrARyg2FaNSeA==}
     cpu: [arm]
     os: [linux]
 
-  '@typescript/native-preview-linux-x64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-a/JypIXTc/tdodhYdQm24WH6aTfnJJjDbwxce4BS2g6IzYSc2GFcZBvlq1CJYS2FAVLpiSxj0OFAZmgjpCDAKg==}
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-Ui6qbTO+nE7fwh5OGTGfL4ndaT+SpiUiv0F1m3+nMaiAKysY5GbgXUfzWzkSrOODsT8F/4jZ4wCzEzJordt8sQ==}
     cpu: [x64]
     os: [linux]
 
-  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-MJGPEDvdXj8olcWH0P+cWYcaN4r/0J4aSbcaISlen3MZ/2hrrgNl46PV4eGJKKCDniY2pH2fJzrMyJWZOcdb0w==}
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-dBFyAH9h3bMUaIp/84c3gKwyQ6jQmtzVoIBamSrYNw0xinJ56A/Ln5igdNOYrH8+/Aofmeh7pAWaa8U456XMjw==}
     cpu: [arm64]
     os: [win32]
 
-  '@typescript/native-preview-win32-x64@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-BtF48TRUyiCKznlOcQ7r7EXhonGSanm9X2eu7d8Yq1vaWO5SDgB0e+ISQXSoIfs3a1S3d5S5QV/vTE4+vocPxA==}
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-bEMSwX71OGGvfsfHEa/aX7ZUWbPSI2oKEmeWcDQVY8vH1VK1ZwcFzMhKfgVJPt5pKH2bK3EO3xYnAyKkDO/Ung==}
     cpu: [x64]
     os: [win32]
 
-  '@typescript/native-preview@7.0.0-dev.20260214.1':
-    resolution: {integrity: sha512-BDM0ZLf2v6ilR0tDi8OMEr4X08lFCToPk3/p1SSE4GhagzmlU/5b+9slR0kKtaKMrds01FhvaKx6U9+NmAWgbQ==}
+  '@typescript/native-preview@7.0.0-dev.20260215.1':
+    resolution: {integrity: sha512-grs0BbJyPR7VLNerBVteEToPku1InMKVKVKBUTJi19LfK+LU3+pkU6/fsTfZhH3xmIzIxD/sNRQHLt4x/Yb9yg==}
     hasBin: true
 
   '@typespec/ts-http-runtime@0.3.3':
@@ -4728,8 +4728,8 @@ packages:
     engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
 
-  oxlint-tsgolint@0.12.2:
-    resolution: {integrity: sha512-IFiOhYZfSgiHbBznTZOhFpEHpsZFSP0j7fVRake03HEkgH0YljnTFDNoRkGWsTrnrHr7nRIomSsF4TnCI/O+kQ==}
+  oxlint-tsgolint@0.13.0:
+    resolution: {integrity: sha512-VUOWP5T9R9RwuPLKvNgvhsjdPFVhr2k8no8ea84+KhDtYPmk9L/3StNP3WClyPOKJOT8bFlO3eyhTKxXK9+Oog==}
     hasBin: true
 
   oxlint@1.47.0:
@@ -5364,8 +5364,8 @@ packages:
     resolution: {integrity: sha512-iK5/YhZxq5GO5z8wb0bY1317uDF3Zjpha0QFFLA8/trAoiLbQD0HUbMesEaxyzUgDxi2QlcbM8IvqOlEjgoXBA==}
     engines: {node: '>=12.17'}
 
-  tar@7.5.7:
-    resolution: {integrity: sha512-fov56fJiRuThVFXD6o6/Q354S7pnWMJIVlDBYijsTNx6jKSE4pvrDTs6lUnmGvNyfJwFQQwWy3owKz1ucIhveQ==}
+  tar@7.5.9:
+    resolution: {integrity: sha512-BTLcK0xsDh2+PUe9F6c2TlRp4zOOBMTkoQHQIWSIzI0R7KG46uEwq4OPk2W7bZcprBMsuaeFsqwYr7pjh6CuHg==}
     engines: {node: '>=18'}
 
   thenify-all@1.6.0:
@@ -6285,7 +6285,7 @@ snapshots:
 
   '@babel/helper-string-parser@7.27.1': {}
 
-  '@babel/helper-string-parser@8.0.0-rc.1': {}
+  '@babel/helper-string-parser@8.0.0-rc.2': {}
 
   '@babel/helper-validator-identifier@7.28.5': {}
 
@@ -6308,7 +6308,7 @@ snapshots:
 
   '@babel/types@8.0.0-rc.1':
     dependencies:
-      '@babel/helper-string-parser': 8.0.0-rc.1
+      '@babel/helper-string-parser': 8.0.0-rc.2
       '@babel/helper-validator-identifier': 8.0.0-rc.1
 
   '@bcoe/v8-coverage@1.0.2': {}
@@ -7546,22 +7546,22 @@ snapshots:
   '@oxfmt/binding-win32-x64-msvc@0.32.0':
     optional: true
 
-  '@oxlint-tsgolint/darwin-arm64@0.12.2':
+  '@oxlint-tsgolint/darwin-arm64@0.13.0':
     optional: true
 
-  '@oxlint-tsgolint/darwin-x64@0.12.2':
+  '@oxlint-tsgolint/darwin-x64@0.13.0':
     optional: true
 
-  '@oxlint-tsgolint/linux-arm64@0.12.2':
+  '@oxlint-tsgolint/linux-arm64@0.13.0':
     optional: true
 
-  '@oxlint-tsgolint/linux-x64@0.12.2':
+  '@oxlint-tsgolint/linux-x64@0.13.0':
     optional: true
 
-  '@oxlint-tsgolint/win32-arm64@0.12.2':
+  '@oxlint-tsgolint/win32-arm64@0.13.0':
     optional: true
 
-  '@oxlint-tsgolint/win32-x64@0.12.2':
+  '@oxlint-tsgolint/win32-x64@0.13.0':
     optional: true
 
   '@oxlint/binding-android-arm-eabi@1.47.0':
@@ -8473,36 +8473,36 @@ snapshots:
     dependencies:
       '@types/node': 25.2.3
 
-  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-linux-arm@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-linux-x64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview-win32-x64@7.0.0-dev.20260214.1':
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260215.1':
     optional: true
 
-  '@typescript/native-preview@7.0.0-dev.20260214.1':
+  '@typescript/native-preview@7.0.0-dev.20260215.1':
     optionalDependencies:
-      '@typescript/native-preview-darwin-arm64': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-darwin-x64': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-linux-arm': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-linux-arm64': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-linux-x64': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-win32-arm64': 7.0.0-dev.20260214.1
-      '@typescript/native-preview-win32-x64': 7.0.0-dev.20260214.1
+      '@typescript/native-preview-darwin-arm64': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-darwin-x64': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-linux-arm': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-linux-arm64': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-linux-x64': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-win32-arm64': 7.0.0-dev.20260215.1
+      '@typescript/native-preview-win32-x64': 7.0.0-dev.20260215.1
 
   '@typespec/ts-http-runtime@0.3.3':
     dependencies:
@@ -8990,7 +8990,7 @@ snapshots:
       npmlog: 6.0.2
       rc: 1.2.8
       semver: 7.7.4
-      tar: 7.5.7
+      tar: 7.5.9
       url-join: 4.0.1
       which: 2.0.2
       yargs: 17.7.2
@@ -10385,16 +10385,16 @@ snapshots:
       '@oxfmt/binding-win32-ia32-msvc': 0.32.0
       '@oxfmt/binding-win32-x64-msvc': 0.32.0
 
-  oxlint-tsgolint@0.12.2:
+  oxlint-tsgolint@0.13.0:
     optionalDependencies:
-      '@oxlint-tsgolint/darwin-arm64': 0.12.2
-      '@oxlint-tsgolint/darwin-x64': 0.12.2
-      '@oxlint-tsgolint/linux-arm64': 0.12.2
-      '@oxlint-tsgolint/linux-x64': 0.12.2
-      '@oxlint-tsgolint/win32-arm64': 0.12.2
-      '@oxlint-tsgolint/win32-x64': 0.12.2
+      '@oxlint-tsgolint/darwin-arm64': 0.13.0
+      '@oxlint-tsgolint/darwin-x64': 0.13.0
+      '@oxlint-tsgolint/linux-arm64': 0.13.0
+      '@oxlint-tsgolint/linux-x64': 0.13.0
+      '@oxlint-tsgolint/win32-arm64': 0.13.0
+      '@oxlint-tsgolint/win32-x64': 0.13.0
 
-  oxlint@1.47.0(oxlint-tsgolint@0.12.2):
+  oxlint@1.47.0(oxlint-tsgolint@0.13.0):
     optionalDependencies:
       '@oxlint/binding-android-arm-eabi': 1.47.0
       '@oxlint/binding-android-arm64': 1.47.0
@@ -10415,7 +10415,7 @@ snapshots:
       '@oxlint/binding-win32-arm64-msvc': 1.47.0
       '@oxlint/binding-win32-ia32-msvc': 1.47.0
       '@oxlint/binding-win32-x64-msvc': 1.47.0
-      oxlint-tsgolint: 0.12.2
+      oxlint-tsgolint: 0.13.0
 
   p-finally@1.0.0: {}
 
@@ -10791,7 +10791,7 @@ snapshots:
     dependencies:
       glob: 10.5.0
 
-  rolldown-plugin-dts@0.22.1(@typescript/native-preview@7.0.0-dev.20260214.1)(rolldown@1.0.0-rc.3)(typescript@5.9.3):
+  rolldown-plugin-dts@0.22.1(@typescript/native-preview@7.0.0-dev.20260215.1)(rolldown@1.0.0-rc.3)(typescript@5.9.3):
     dependencies:
       '@babel/generator': 8.0.0-rc.1
       '@babel/helper-validator-identifier': 8.0.0-rc.1
@@ -10804,7 +10804,7 @@ snapshots:
       obug: 2.1.1
       rolldown: 1.0.0-rc.3
     optionalDependencies:
-      '@typescript/native-preview': 7.0.0-dev.20260214.1
+      '@typescript/native-preview': 7.0.0-dev.20260215.1
       typescript: 5.9.3
     transitivePeerDependencies:
       - oxc-resolver
@@ -11211,7 +11211,7 @@ snapshots:
       array-back: 6.2.2
       wordwrapjs: 5.1.1
 
-  tar@7.5.7:
+  tar@7.5.9:
     dependencies:
       '@isaacs/fs-minipass': 4.0.1
       chownr: 3.0.0
@@ -11269,7 +11269,7 @@ snapshots:
 
   ts-algebra@2.0.0: {}
 
-  tsdown@0.20.3(@typescript/native-preview@7.0.0-dev.20260214.1)(typescript@5.9.3):
+  tsdown@0.20.3(@typescript/native-preview@7.0.0-dev.20260215.1)(typescript@5.9.3):
     dependencies:
       ansis: 4.2.0
       cac: 6.7.14
@@ -11280,7 +11280,7 @@ snapshots:
       obug: 2.1.1
       picomatch: 4.0.3
       rolldown: 1.0.0-rc.3
-      rolldown-plugin-dts: 0.22.1(@typescript/native-preview@7.0.0-dev.20260214.1)(rolldown@1.0.0-rc.3)(typescript@5.9.3)
+      rolldown-plugin-dts: 0.22.1(@typescript/native-preview@7.0.0-dev.20260215.1)(rolldown@1.0.0-rc.3)(typescript@5.9.3)
       semver: 7.7.4
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
diff --git a/scripts/e2e/Dockerfile b/scripts/e2e/Dockerfile
index 9e293c1abdf..fcad225beda 100644
--- a/scripts/e2e/Dockerfile
+++ b/scripts/e2e/Dockerfile
@@ -15,6 +15,8 @@ COPY skills ./skills
 COPY patches ./patches
 COPY ui ./ui
 COPY extensions/memory-core ./extensions/memory-core
+COPY vendor/a2ui/renderers/lit ./vendor/a2ui/renderers/lit
+COPY apps/shared/OpenClawKit/Tools/CanvasA2UI ./apps/shared/OpenClawKit/Tools/CanvasA2UI
 
 RUN pnpm install --frozen-lockfile
 RUN pnpm build
diff --git a/scripts/pre-commit/filter-staged-files.mjs b/scripts/pre-commit/filter-staged-files.mjs
new file mode 100644
index 00000000000..7e3dcfd7abc
--- /dev/null
+++ b/scripts/pre-commit/filter-staged-files.mjs
@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+/**
+ * Prints selected files as NUL-delimited tokens to stdout.
+ *
+ * Usage:
+ *   node scripts/pre-commit/filter-staged-files.mjs lint -- <files...>
+ *   node scripts/pre-commit/filter-staged-files.mjs format -- <files...>
+ *
+ * Keep this dependency-free: the pre-commit hook runs in many environments.
+ */
+
+const mode = process.argv[2];
+const rawArgs = process.argv.slice(3);
+const files = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
+
+if (mode !== "lint" && mode !== "format") {
+  process.stderr.write("usage: filter-staged-files.mjs <lint|format> -- <files...>\n");
+  process.exit(2);
+}
+
+const lintExts = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+const formatExts = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".md", ".mdx"]);
+
+const shouldSelect = (filePath) => {
+  const ext = path.extname(filePath).toLowerCase();
+  if (mode === "lint") {
+    return lintExts.has(ext);
+  }
+  return formatExts.has(ext);
+};
+
+for (const file of files) {
+  if (shouldSelect(file)) {
+    process.stdout.write(file);
+    process.stdout.write("\0");
+  }
+}
diff --git a/scripts/test-parallel.mjs b/scripts/test-parallel.mjs
index 04b60c35565..6ea080444c3 100644
--- a/scripts/test-parallel.mjs
+++ b/scripts/test-parallel.mjs
@@ -27,10 +27,18 @@ const unitIsolatedFilesRaw = [
   "src/browser/server.agent-contract-form-layout-act-commands.test.ts",
   "src/browser/server.skips-default-maxchars-explicitly-set-zero.test.ts",
   "src/browser/server.auth-token-gates-http.test.ts",
-  "src/browser/server-context.remote-tab-ops.test.ts",
-  "src/browser/server-context.ensure-tab-available.prefers-last-target.test.ts",
+  // Keep this high-variance heavy file off the unit-fast critical path.
+  "src/auto-reply/reply.block-streaming.test.ts",
+  // Archive extraction/fixture-heavy suite; keep off unit-fast critical path.
+  "src/hooks/install.test.ts",
+  // Setup-heavy bot bootstrap suite.
+  "src/telegram/bot.create-telegram-bot.test.ts",
+  // Medium-heavy bot behavior suite; move off unit-fast critical path.
+  "src/telegram/bot.test.ts",
+  // Slack slash registration tests are setup-heavy and can bottleneck unit-fast.
+  "src/slack/monitor/slash.test.ts",
   // Uses process-level unhandledRejection listeners; keep it off vmForks to avoid cross-file leakage.
-  "src/imessage/monitor.skips-group-messages-without-mention-by-default.test.ts",
+  "src/imessage/monitor.shutdown.unhandled-rejection.test.ts",
 ];
 const unitIsolatedFiles = unitIsolatedFilesRaw.filter((file) => fs.existsSync(file));
 
@@ -165,7 +173,7 @@ const defaultWorkerBudget =
             unit: Math.max(2, Math.min(8, Math.floor(localWorkers / 2))),
             unitIsolated: 1,
             extensions: Math.max(1, Math.min(4, Math.floor(localWorkers / 4))),
-            gateway: 1,
+            gateway: 2,
           };
 
 // Keep worker counts predictable for local runs; trim macOS CI workers to avoid worker crashes/OOM.
diff --git a/skills/discord/SKILL.md b/skills/discord/SKILL.md
index 18411486488..dfedea1d88b 100644
--- a/skills/discord/SKILL.md
+++ b/skills/discord/SKILL.md
@@ -16,6 +16,12 @@ Use the `message` tool. No provider-specific `discord` tool exposed to the agent
 - Prefer explicit ids: `guildId`, `channelId`, `messageId`, `userId`.
 - Multi-account: optional `accountId`.
 
+## Guidelines
+
+- Avoid Markdown tables in outbound Discord messages.
+- Mention users as `<@USER_ID>`.
+- Prefer Discord components v2 (`components`) for rich UI; use legacy `embeds` only when you must.
+
 ## Targets
 
 - Send-like actions: `to: "channel:<id>"` or `to: "user:<id>"`.
@@ -47,6 +53,37 @@ Send with media:
 }
 ```
 
+- Optional `silent: true` to suppress Discord notifications.
+
+Send with components v2 (recommended for rich UI):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "components": "[Carbon v2 components]"
+}
+```
+
+- `components` expects Carbon component instances (Container, TextDisplay, etc.) from JS/TS integrations.
+- Do not combine `components` with `embeds` (Discord rejects v2 + embeds).
+
+Legacy embeds (not recommended):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "embeds": [{ "title": "Legacy", "description": "Embeds are legacy." }]
+}
+```
+
+- `embeds` are ignored when components v2 are present.
+
 React:
 
 ```json
@@ -157,4 +194,4 @@ Presence (often gated):
 
 - Short, conversational, low ceremony.
 - No markdown tables.
-- Prefer multiple small replies over one wall of text.
+- Mention users as `<@USER_ID>`.
diff --git a/skills/sherpa-onnx-tts/SKILL.md b/skills/sherpa-onnx-tts/SKILL.md
index ee5daeae97b..1628660637b 100644
--- a/skills/sherpa-onnx-tts/SKILL.md
+++ b/skills/sherpa-onnx-tts/SKILL.md
@@ -18,7 +18,7 @@ metadata:
               "archive": "tar.bz2",
               "extract": true,
               "stripComponents": 1,
-              "targetDir": "~/.openclaw/tools/sherpa-onnx-tts/runtime",
+              "targetDir": "runtime",
               "label": "Download sherpa-onnx runtime (macOS)",
             },
             {
@@ -29,7 +29,7 @@ metadata:
               "archive": "tar.bz2",
               "extract": true,
               "stripComponents": 1,
-              "targetDir": "~/.openclaw/tools/sherpa-onnx-tts/runtime",
+              "targetDir": "runtime",
               "label": "Download sherpa-onnx runtime (Linux x64)",
             },
             {
@@ -40,7 +40,7 @@ metadata:
               "archive": "tar.bz2",
               "extract": true,
               "stripComponents": 1,
-              "targetDir": "~/.openclaw/tools/sherpa-onnx-tts/runtime",
+              "targetDir": "runtime",
               "label": "Download sherpa-onnx runtime (Windows x64)",
             },
             {
@@ -49,7 +49,7 @@ metadata:
               "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-high.tar.bz2",
               "archive": "tar.bz2",
               "extract": true,
-              "targetDir": "~/.openclaw/tools/sherpa-onnx-tts/models",
+              "targetDir": "models",
               "label": "Download Piper en_US lessac (high)",
             },
           ],
diff --git a/src/acp/client.test.ts b/src/acp/client.test.ts
index 7b266b606fc..78292b4e3ed 100644
--- a/src/acp/client.test.ts
+++ b/src/acp/client.test.ts
@@ -1,6 +1,7 @@
 import type { RequestPermissionRequest } from "@agentclientprotocol/sdk";
 import { describe, expect, it, vi } from "vitest";
 import { resolvePermissionRequest } from "./client.js";
+import { extractAttachmentsFromPrompt, extractTextFromPrompt } from "./event-mapper.js";
 
 function makePermissionRequest(
   overrides: Partial<RequestPermissionRequest> = {},
@@ -139,3 +140,32 @@ describe("resolvePermissionRequest", () => {
     expect(res).toEqual({ outcome: { outcome: "cancelled" } });
   });
 });
+
+describe("acp event mapper", () => {
+  it("extracts text and resource blocks into prompt text", () => {
+    const text = extractTextFromPrompt([
+      { type: "text", text: "Hello" },
+      { type: "resource", resource: { text: "File contents" } },
+      { type: "resource_link", uri: "https://example.com", title: "Spec" },
+      { type: "image", data: "abc", mimeType: "image/png" },
+    ]);
+
+    expect(text).toBe("Hello\nFile contents\n[Resource link (Spec)] https://example.com");
+  });
+
+  it("extracts image blocks into gateway attachments", () => {
+    const attachments = extractAttachmentsFromPrompt([
+      { type: "image", data: "abc", mimeType: "image/png" },
+      { type: "image", data: "", mimeType: "image/png" },
+      { type: "text", text: "ignored" },
+    ]);
+
+    expect(attachments).toEqual([
+      {
+        type: "image",
+        mimeType: "image/png",
+        content: "abc",
+      },
+    ]);
+  });
+});
diff --git a/src/acp/event-mapper.test.ts b/src/acp/event-mapper.test.ts
deleted file mode 100644
index 0b7682ef358..00000000000
--- a/src/acp/event-mapper.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { extractAttachmentsFromPrompt, extractTextFromPrompt } from "./event-mapper.js";
-
-describe("acp event mapper", () => {
-  it("extracts text and resource blocks into prompt text", () => {
-    const text = extractTextFromPrompt([
-      { type: "text", text: "Hello" },
-      { type: "resource", resource: { text: "File contents" } },
-      { type: "resource_link", uri: "https://example.com", title: "Spec" },
-      { type: "image", data: "abc", mimeType: "image/png" },
-    ]);
-
-    expect(text).toBe("Hello\nFile contents\n[Resource link (Spec)] https://example.com");
-  });
-
-  it("extracts image blocks into gateway attachments", () => {
-    const attachments = extractAttachmentsFromPrompt([
-      { type: "image", data: "abc", mimeType: "image/png" },
-      { type: "image", data: "", mimeType: "image/png" },
-      { type: "text", text: "ignored" },
-    ]);
-
-    expect(attachments).toEqual([
-      {
-        type: "image",
-        mimeType: "image/png",
-        content: "abc",
-      },
-    ]);
-  });
-});
diff --git a/src/acp/session-mapper.test.ts b/src/acp/session-mapper.test.ts
index 859b1da7380..ac06dcf4b89 100644
--- a/src/acp/session-mapper.test.ts
+++ b/src/acp/session-mapper.test.ts
@@ -1,6 +1,7 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { GatewayClient } from "../gateway/client.js";
 import { parseSessionMeta, resolveSessionKey } from "./session-mapper.js";
+import { createInMemorySessionStore } from "./session.js";
 
 function createGateway(resolveLabelKey = "agent:main:label"): {
   gateway: GatewayClient;
@@ -54,3 +55,26 @@ describe("acp session mapper", () => {
     expect(request).not.toHaveBeenCalled();
   });
 });
+
+describe("acp session manager", () => {
+  const store = createInMemorySessionStore();
+
+  afterEach(() => {
+    store.clearAllSessionsForTest();
+  });
+
+  it("tracks active runs and clears on cancel", () => {
+    const session = store.createSession({
+      sessionKey: "acp:test",
+      cwd: "/tmp",
+    });
+    const controller = new AbortController();
+    store.setActiveRun(session.sessionId, "run-1", controller);
+
+    expect(store.getSessionByRunId("run-1")?.sessionId).toBe(session.sessionId);
+
+    const cancelled = store.cancelActiveRun(session.sessionId);
+    expect(cancelled).toBe(true);
+    expect(store.getSessionByRunId("run-1")).toBeUndefined();
+  });
+});
diff --git a/src/acp/session.test.ts b/src/acp/session.test.ts
deleted file mode 100644
index a38b58f1703..00000000000
--- a/src/acp/session.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, expect, it, afterEach } from "vitest";
-import { createInMemorySessionStore } from "./session.js";
-
-describe("acp session manager", () => {
-  const store = createInMemorySessionStore();
-
-  afterEach(() => {
-    store.clearAllSessionsForTest();
-  });
-
-  it("tracks active runs and clears on cancel", () => {
-    const session = store.createSession({
-      sessionKey: "acp:test",
-      cwd: "/tmp",
-    });
-    const controller = new AbortController();
-    store.setActiveRun(session.sessionId, "run-1", controller);
-
-    expect(store.getSessionByRunId("run-1")?.sessionId).toBe(session.sessionId);
-
-    const cancelled = store.cancelActiveRun(session.sessionId);
-    expect(cancelled).toBe(true);
-    expect(store.getSessionByRunId("run-1")).toBeUndefined();
-  });
-});
diff --git a/src/agents/agent-paths.e2e.test.ts b/src/agents/agent-paths.e2e.test.ts
index f455f82862c..f0df2cbbdbc 100644
--- a/src/agents/agent-paths.e2e.test.ts
+++ b/src/agents/agent-paths.e2e.test.ts
@@ -2,12 +2,11 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { resolveOpenClawAgentDir } from "./agent-paths.js";
 
 describe("resolveOpenClawAgentDir", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const env = captureEnv(["OPENCLAW_STATE_DIR", "OPENCLAW_AGENT_DIR", "PI_CODING_AGENT_DIR"]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -15,21 +14,7 @@ describe("resolveOpenClawAgentDir", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
+    env.restore();
   });
 
   it("defaults to the multi-agent path when no overrides are set", async () => {
diff --git a/src/agents/agent-scope.e2e.test.ts b/src/agents/agent-scope.e2e.test.ts
index 8720d54d4c4..d1d3c900a49 100644
--- a/src/agents/agent-scope.e2e.test.ts
+++ b/src/agents/agent-scope.e2e.test.ts
@@ -4,6 +4,7 @@ import type { OpenClawConfig } from "../config/config.js";
 import {
   resolveAgentConfig,
   resolveAgentDir,
+  resolveEffectiveModelFallbacks,
   resolveAgentModelFallbacksOverride,
   resolveAgentModelPrimary,
   resolveAgentWorkspaceDir,
@@ -112,6 +113,60 @@ describe("resolveAgentConfig", () => {
       },
     };
     expect(resolveAgentModelFallbacksOverride(cfgDisable, "linus")).toEqual([]);
+
+    expect(
+      resolveEffectiveModelFallbacks({
+        cfg,
+        agentId: "linus",
+        hasSessionModelOverride: false,
+      }),
+    ).toEqual(["openai/gpt-5.2"]);
+    expect(
+      resolveEffectiveModelFallbacks({
+        cfg,
+        agentId: "linus",
+        hasSessionModelOverride: true,
+      }),
+    ).toEqual(["openai/gpt-5.2"]);
+    expect(
+      resolveEffectiveModelFallbacks({
+        cfg: cfgNoOverride,
+        agentId: "linus",
+        hasSessionModelOverride: true,
+      }),
+    ).toEqual([]);
+
+    const cfgInheritDefaults: OpenClawConfig = {
+      agents: {
+        defaults: {
+          model: {
+            fallbacks: ["openai/gpt-4.1"],
+          },
+        },
+        list: [
+          {
+            id: "linus",
+            model: {
+              primary: "anthropic/claude-opus-4",
+            },
+          },
+        ],
+      },
+    };
+    expect(
+      resolveEffectiveModelFallbacks({
+        cfg: cfgInheritDefaults,
+        agentId: "linus",
+        hasSessionModelOverride: true,
+      }),
+    ).toEqual(["openai/gpt-4.1"]);
+    expect(
+      resolveEffectiveModelFallbacks({
+        cfg: cfgDisable,
+        agentId: "linus",
+        hasSessionModelOverride: true,
+      }),
+    ).toEqual([]);
   });
 
   it("should return agent-specific sandbox config", () => {
diff --git a/src/agents/agent-scope.ts b/src/agents/agent-scope.ts
index fe7f0f6a508..178bd1ec7e4 100644
--- a/src/agents/agent-scope.ts
+++ b/src/agents/agent-scope.ts
@@ -7,6 +7,7 @@ import {
   parseAgentSessionKey,
 } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
+import { normalizeSkillFilter } from "./skills/filter.js";
 import { resolveDefaultAgentWorkspaceDir } from "./workspace.js";
 
 export { resolveAgentIdFromSessionKey } from "../routing/session-key.js";
@@ -128,12 +129,7 @@ export function resolveAgentSkillsFilter(
   cfg: OpenClawConfig,
   agentId: string,
 ): string[] | undefined {
-  const raw = resolveAgentConfig(cfg, agentId)?.skills;
-  if (!raw) {
-    return undefined;
-  }
-  const normalized = raw.map((entry) => String(entry).trim()).filter(Boolean);
-  return normalized.length > 0 ? normalized : [];
+  return normalizeSkillFilter(resolveAgentConfig(cfg, agentId)?.skills);
 }
 
 export function resolveAgentModelPrimary(cfg: OpenClawConfig, agentId: string): string | undefined {
@@ -163,6 +159,22 @@ export function resolveAgentModelFallbacksOverride(
   return Array.isArray(raw.fallbacks) ? raw.fallbacks : undefined;
 }
 
+export function resolveEffectiveModelFallbacks(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  hasSessionModelOverride: boolean;
+}): string[] | undefined {
+  const agentFallbacksOverride = resolveAgentModelFallbacksOverride(params.cfg, params.agentId);
+  if (!params.hasSessionModelOverride) {
+    return agentFallbacksOverride;
+  }
+  const defaultFallbacks =
+    typeof params.cfg.agents?.defaults?.model === "object"
+      ? (params.cfg.agents.defaults.model.fallbacks ?? [])
+      : [];
+  return agentFallbacksOverride ?? defaultFallbacks;
+}
+
 export function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string) {
   const id = normalizeAgentId(agentId);
   const configured = resolveAgentConfig(cfg, id)?.workspace?.trim();
diff --git a/src/agents/auth-profiles.auth-profile-cooldowns.e2e.test.ts b/src/agents/auth-profiles.auth-profile-cooldowns.e2e.test.ts
deleted file mode 100644
index e5fe3900ad0..00000000000
--- a/src/agents/auth-profiles.auth-profile-cooldowns.e2e.test.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { calculateAuthProfileCooldownMs } from "./auth-profiles.js";
-
-describe("auth profile cooldowns", () => {
-  it("applies exponential backoff with a 1h cap", () => {
-    expect(calculateAuthProfileCooldownMs(1)).toBe(60_000);
-    expect(calculateAuthProfileCooldownMs(2)).toBe(5 * 60_000);
-    expect(calculateAuthProfileCooldownMs(3)).toBe(25 * 60_000);
-    expect(calculateAuthProfileCooldownMs(4)).toBe(60 * 60_000);
-    expect(calculateAuthProfileCooldownMs(5)).toBe(60 * 60_000);
-  });
-});
diff --git a/src/agents/auth-profiles.chutes.e2e.test.ts b/src/agents/auth-profiles.chutes.e2e.test.ts
index 317ce9c771a..c21f37ed1ca 100644
--- a/src/agents/auth-profiles.chutes.e2e.test.ts
+++ b/src/agents/auth-profiles.chutes.e2e.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import {
   type AuthProfileStore,
   ensureAuthProfileStore,
@@ -10,10 +11,7 @@ import {
 import { CHUTES_TOKEN_ENDPOINT, type ChutesStoredOAuth } from "./chutes-oauth.js";
 
 describe("auth-profiles (chutes)", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
-  const previousChutesClientId = process.env.CHUTES_CLIENT_ID;
+  let envSnapshot: ReturnType<typeof captureEnv> | undefined;
   let tempDir: string | null = null;
 
   afterEach(async () => {
@@ -22,29 +20,17 @@ describe("auth-profiles (chutes)", () => {
       await fs.rm(tempDir, { recursive: true, force: true });
       tempDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
-    if (previousChutesClientId === undefined) {
-      delete process.env.CHUTES_CLIENT_ID;
-    } else {
-      process.env.CHUTES_CLIENT_ID = previousChutesClientId;
-    }
+    envSnapshot?.restore();
+    envSnapshot = undefined;
   });
 
   it("refreshes expired Chutes OAuth credentials", async () => {
+    envSnapshot = captureEnv([
+      "OPENCLAW_STATE_DIR",
+      "OPENCLAW_AGENT_DIR",
+      "PI_CODING_AGENT_DIR",
+      "CHUTES_CLIENT_ID",
+    ]);
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chutes-"));
     process.env.OPENCLAW_STATE_DIR = tempDir;
     process.env.OPENCLAW_AGENT_DIR = path.join(tempDir, "agents", "main", "agent");
diff --git a/src/agents/auth-profiles.markauthprofilefailure.e2e.test.ts b/src/agents/auth-profiles.markauthprofilefailure.e2e.test.ts
index 0fc86907d1c..1a8cfb16ebd 100644
--- a/src/agents/auth-profiles.markauthprofilefailure.e2e.test.ts
+++ b/src/agents/auth-profiles.markauthprofilefailure.e2e.test.ts
@@ -2,7 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { ensureAuthProfileStore, markAuthProfileFailure } from "./auth-profiles.js";
+import {
+  calculateAuthProfileCooldownMs,
+  ensureAuthProfileStore,
+  markAuthProfileFailure,
+} from "./auth-profiles.js";
 
 describe("markAuthProfileFailure", () => {
   it("disables billing failures for ~5 hours by default", async () => {
@@ -129,3 +133,13 @@ describe("markAuthProfileFailure", () => {
     }
   });
 });
+
+describe("calculateAuthProfileCooldownMs", () => {
+  it("applies exponential backoff with a 1h cap", () => {
+    expect(calculateAuthProfileCooldownMs(1)).toBe(60_000);
+    expect(calculateAuthProfileCooldownMs(2)).toBe(5 * 60_000);
+    expect(calculateAuthProfileCooldownMs(3)).toBe(25 * 60_000);
+    expect(calculateAuthProfileCooldownMs(4)).toBe(60 * 60_000);
+    expect(calculateAuthProfileCooldownMs(5)).toBe(60 * 60_000);
+  });
+});
diff --git a/src/agents/auth-profiles.resolve-auth-profile-order.does-not-prioritize-lastgood-round-robin-ordering.e2e.test.ts b/src/agents/auth-profiles.resolve-auth-profile-order.does-not-prioritize-lastgood-round-robin-ordering.e2e.test.ts
index 692b67a01cf..79f22798949 100644
--- a/src/agents/auth-profiles.resolve-auth-profile-order.does-not-prioritize-lastgood-round-robin-ordering.e2e.test.ts
+++ b/src/agents/auth-profiles.resolve-auth-profile-order.does-not-prioritize-lastgood-round-robin-ordering.e2e.test.ts
@@ -1,30 +1,13 @@
 import { describe, expect, it } from "vitest";
 import { resolveAuthProfileOrder } from "./auth-profiles.js";
+import {
+  ANTHROPIC_CFG,
+  ANTHROPIC_STORE,
+} from "./auth-profiles.resolve-auth-profile-order.fixtures.js";
 
 describe("resolveAuthProfileOrder", () => {
-  const store: AuthProfileStore = {
-    version: 1,
-    profiles: {
-      "anthropic:default": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-default",
-      },
-      "anthropic:work": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-work",
-      },
-    },
-  };
-  const cfg = {
-    auth: {
-      profiles: {
-        "anthropic:default": { provider: "anthropic", mode: "api_key" },
-        "anthropic:work": { provider: "anthropic", mode: "api_key" },
-      },
-    },
-  };
+  const store = ANTHROPIC_STORE;
+  const cfg = ANTHROPIC_CFG;
 
   it("does not prioritize lastGood over round-robin ordering", () => {
     const order = resolveAuthProfileOrder({
diff --git a/src/agents/auth-profiles.resolve-auth-profile-order.fixtures.ts b/src/agents/auth-profiles.resolve-auth-profile-order.fixtures.ts
new file mode 100644
index 00000000000..bc7b5cf983d
--- /dev/null
+++ b/src/agents/auth-profiles.resolve-auth-profile-order.fixtures.ts
@@ -0,0 +1,26 @@
+import type { AuthProfileStore } from "./auth-profiles.js";
+
+export const ANTHROPIC_STORE: AuthProfileStore = {
+  version: 1,
+  profiles: {
+    "anthropic:default": {
+      type: "api_key",
+      provider: "anthropic",
+      key: "sk-default",
+    },
+    "anthropic:work": {
+      type: "api_key",
+      provider: "anthropic",
+      key: "sk-work",
+    },
+  },
+};
+
+export const ANTHROPIC_CFG = {
+  auth: {
+    profiles: {
+      "anthropic:default": { provider: "anthropic", mode: "api_key" },
+      "anthropic:work": { provider: "anthropic", mode: "api_key" },
+    },
+  },
+};
diff --git a/src/agents/auth-profiles.resolve-auth-profile-order.normalizes-z-ai-aliases-auth-order.e2e.test.ts b/src/agents/auth-profiles.resolve-auth-profile-order.normalizes-z-ai-aliases-auth-order.e2e.test.ts
index a6bd59b3bb6..0817f2280ea 100644
--- a/src/agents/auth-profiles.resolve-auth-profile-order.normalizes-z-ai-aliases-auth-order.e2e.test.ts
+++ b/src/agents/auth-profiles.resolve-auth-profile-order.normalizes-z-ai-aliases-auth-order.e2e.test.ts
@@ -2,30 +2,6 @@ import { describe, expect, it } from "vitest";
 import { resolveAuthProfileOrder } from "./auth-profiles.js";
 
 describe("resolveAuthProfileOrder", () => {
-  const _store: AuthProfileStore = {
-    version: 1,
-    profiles: {
-      "anthropic:default": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-default",
-      },
-      "anthropic:work": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-work",
-      },
-    },
-  };
-  const _cfg = {
-    auth: {
-      profiles: {
-        "anthropic:default": { provider: "anthropic", mode: "api_key" },
-        "anthropic:work": { provider: "anthropic", mode: "api_key" },
-      },
-    },
-  };
-
   it("normalizes z.ai aliases in auth.order", () => {
     const order = resolveAuthProfileOrder({
       cfg: {
diff --git a/src/agents/auth-profiles.resolve-auth-profile-order.orders-by-lastused-no-explicit-order-exists.e2e.test.ts b/src/agents/auth-profiles.resolve-auth-profile-order.orders-by-lastused-no-explicit-order-exists.e2e.test.ts
index 55816522c27..2842fb48e15 100644
--- a/src/agents/auth-profiles.resolve-auth-profile-order.orders-by-lastused-no-explicit-order-exists.e2e.test.ts
+++ b/src/agents/auth-profiles.resolve-auth-profile-order.orders-by-lastused-no-explicit-order-exists.e2e.test.ts
@@ -2,30 +2,6 @@ import { describe, expect, it } from "vitest";
 import { resolveAuthProfileOrder } from "./auth-profiles.js";
 
 describe("resolveAuthProfileOrder", () => {
-  const _store: AuthProfileStore = {
-    version: 1,
-    profiles: {
-      "anthropic:default": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-default",
-      },
-      "anthropic:work": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-work",
-      },
-    },
-  };
-  const _cfg = {
-    auth: {
-      profiles: {
-        "anthropic:default": { provider: "anthropic", mode: "api_key" },
-        "anthropic:work": { provider: "anthropic", mode: "api_key" },
-      },
-    },
-  };
-
   it("orders by lastUsed when no explicit order exists", () => {
     const order = resolveAuthProfileOrder({
       store: {
diff --git a/src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.e2e.test.ts b/src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.e2e.test.ts
index 0a4344bb6b1..c5ec9826e36 100644
--- a/src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.e2e.test.ts
+++ b/src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.e2e.test.ts
@@ -1,30 +1,13 @@
 import { describe, expect, it } from "vitest";
 import { resolveAuthProfileOrder } from "./auth-profiles.js";
+import {
+  ANTHROPIC_CFG,
+  ANTHROPIC_STORE,
+} from "./auth-profiles.resolve-auth-profile-order.fixtures.js";
 
 describe("resolveAuthProfileOrder", () => {
-  const store: AuthProfileStore = {
-    version: 1,
-    profiles: {
-      "anthropic:default": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-default",
-      },
-      "anthropic:work": {
-        type: "api_key",
-        provider: "anthropic",
-        key: "sk-work",
-      },
-    },
-  };
-  const cfg = {
-    auth: {
-      profiles: {
-        "anthropic:default": { provider: "anthropic", mode: "api_key" },
-        "anthropic:work": { provider: "anthropic", mode: "api_key" },
-      },
-    },
-  };
+  const store = ANTHROPIC_STORE;
+  const cfg = ANTHROPIC_CFG;
 
   it("uses stored profiles when no config exists", () => {
     const order = resolveAuthProfileOrder({
diff --git a/src/agents/auth-profiles/oauth.fallback-to-main-agent.e2e.test.ts b/src/agents/auth-profiles/oauth.fallback-to-main-agent.e2e.test.ts
index 9379d387913..ea15d462f01 100644
--- a/src/agents/auth-profiles/oauth.fallback-to-main-agent.e2e.test.ts
+++ b/src/agents/auth-profiles/oauth.fallback-to-main-agent.e2e.test.ts
@@ -3,13 +3,16 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { AuthProfileStore } from "./types.js";
+import { captureEnv } from "../../test-utils/env.js";
 import { resolveApiKeyForProfile } from "./oauth.js";
 import { ensureAuthProfileStore } from "./store.js";
 
 describe("resolveApiKeyForProfile fallback to main agent", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const envSnapshot = captureEnv([
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+  ]);
   let tmpDir: string;
   let mainAgentDir: string;
   let secondaryAgentDir: string;
@@ -30,22 +33,7 @@ describe("resolveApiKeyForProfile fallback to main agent", () => {
   afterEach(async () => {
     vi.unstubAllGlobals();
 
-    // Restore original environment
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
+    envSnapshot.restore();
 
     await fs.rm(tmpDir, { recursive: true, force: true });
   });
diff --git a/src/agents/bash-tools.exec-runtime.ts b/src/agents/bash-tools.exec-runtime.ts
index 2af4e4a7f6a..d458df01d1e 100644
--- a/src/agents/bash-tools.exec-runtime.ts
+++ b/src/agents/bash-tools.exec-runtime.ts
@@ -1,17 +1,17 @@
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { Type } from "@sinclair/typebox";
 import path from "node:path";
 import type { ExecAsk, ExecHost, ExecSecurity } from "../infra/exec-approvals.js";
-import type { ProcessSession, SessionStdin } from "./bash-process-registry.js";
+import type { ProcessSession } from "./bash-process-registry.js";
 import type { ExecToolDetails } from "./bash-tools.exec.js";
 import type { BashSandboxConfig } from "./bash-tools.shared.js";
 import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
 import { mergePathPrepend } from "../infra/path-prepend.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 export { applyPathPrepend, normalizePathPrepend } from "../infra/path-prepend.js";
+import type { ManagedRun } from "../process/supervisor/index.js";
 import { logWarn } from "../logger.js";
-import { formatSpawnError, spawnWithFallback } from "../process/spawn-utils.js";
+import { getProcessSupervisor } from "../process/supervisor/index.js";
 import {
   addSession,
   appendOutput,
@@ -23,7 +23,6 @@ import {
   buildDockerExecArgs,
   chunkString,
   clampWithDefault,
-  killSession,
   readEnvInt,
 } from "./bash-tools.shared.js";
 import { buildCursorPositionResponse, stripDsrRequests } from "./pty-dsr.js";
@@ -147,26 +146,6 @@ export const execSchema = Type.Object({
   ),
 });
 
-type PtyExitEvent = { exitCode: number; signal?: number };
-type PtyListener<T> = (event: T) => void;
-type PtyHandle = {
-  pid: number;
-  write: (data: string | Buffer) => void;
-  onData: (listener: PtyListener<string>) => void;
-  onExit: (listener: PtyListener<PtyExitEvent>) => void;
-};
-type PtySpawn = (
-  file: string,
-  args: string[] | string,
-  options: {
-    name?: string;
-    cols?: number;
-    rows?: number;
-    cwd?: string;
-    env?: Record<string, string>;
-  },
-) => PtyHandle;
-
 export type ExecProcessOutcome = {
   status: "completed" | "failed";
   exitCode: number | null;
@@ -319,138 +298,10 @@ export async function runExecProcess(opts: {
 }): Promise<ExecProcessHandle> {
   const startedAt = Date.now();
   const sessionId = createSessionSlug();
-  let child: ChildProcessWithoutNullStreams | null = null;
-  let pty: PtyHandle | null = null;
-  let stdin: SessionStdin | undefined;
   const execCommand = opts.execCommand ?? opts.command;
+  const supervisor = getProcessSupervisor();
 
-  const spawnFallbacks = [
-    {
-      label: "no-detach",
-      options: { detached: false },
-    },
-  ];
-
-  const handleSpawnFallback = (err: unknown, fallback: { label: string }) => {
-    const errText = formatSpawnError(err);
-    const warning = `Warning: spawn failed (${errText}); retrying with ${fallback.label}.`;
-    logWarn(`exec: spawn failed (${errText}); retrying with ${fallback.label}.`);
-    opts.warnings.push(warning);
-  };
-
-  const spawnShellChild = async (
-    shell: string,
-    shellArgs: string[],
-  ): Promise<ChildProcessWithoutNullStreams> => {
-    const { child: spawned } = await spawnWithFallback({
-      argv: [shell, ...shellArgs, execCommand],
-      options: {
-        cwd: opts.workdir,
-        env: opts.env,
-        detached: process.platform !== "win32",
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
-      },
-      fallbacks: spawnFallbacks,
-      onFallback: handleSpawnFallback,
-    });
-    return spawned as ChildProcessWithoutNullStreams;
-  };
-
-  // `exec` does not currently accept tool-provided stdin content. For non-PTY runs,
-  // keeping stdin open can cause commands like `wc -l` (or safeBins-hardened segments)
-  // to block forever waiting for input, leading to accidental backgrounding.
-  // For interactive flows, callers should use `pty: true` (stdin kept open).
-  const maybeCloseNonPtyStdin = () => {
-    if (opts.usePty) {
-      return;
-    }
-    try {
-      // Signal EOF immediately so stdin-only commands can terminate.
-      child?.stdin?.end();
-    } catch {
-      // ignore stdin close errors
-    }
-  };
-
-  if (opts.sandbox) {
-    const { child: spawned } = await spawnWithFallback({
-      argv: [
-        "docker",
-        ...buildDockerExecArgs({
-          containerName: opts.sandbox.containerName,
-          command: execCommand,
-          workdir: opts.containerWorkdir ?? opts.sandbox.containerWorkdir,
-          env: opts.env,
-          tty: opts.usePty,
-        }),
-      ],
-      options: {
-        cwd: opts.workdir,
-        env: process.env,
-        detached: process.platform !== "win32",
-        stdio: ["pipe", "pipe", "pipe"],
-        windowsHide: true,
-      },
-      fallbacks: spawnFallbacks,
-      onFallback: handleSpawnFallback,
-    });
-    child = spawned as ChildProcessWithoutNullStreams;
-    stdin = child.stdin;
-    maybeCloseNonPtyStdin();
-  } else if (opts.usePty) {
-    const { shell, args: shellArgs } = getShellConfig();
-    try {
-      const ptyModule = (await import("@lydell/node-pty")) as unknown as {
-        spawn?: PtySpawn;
-        default?: { spawn?: PtySpawn };
-      };
-      const spawnPty = ptyModule.spawn ?? ptyModule.default?.spawn;
-      if (!spawnPty) {
-        throw new Error("PTY support is unavailable (node-pty spawn not found).");
-      }
-      pty = spawnPty(shell, [...shellArgs, execCommand], {
-        cwd: opts.workdir,
-        env: opts.env,
-        name: process.env.TERM ?? "xterm-256color",
-        cols: 120,
-        rows: 30,
-      });
-      stdin = {
-        destroyed: false,
-        write: (data, cb) => {
-          try {
-            pty?.write(data);
-            cb?.(null);
-          } catch (err) {
-            cb?.(err as Error);
-          }
-        },
-        end: () => {
-          try {
-            const eof = process.platform === "win32" ? "\x1a" : "\x04";
-            pty?.write(eof);
-          } catch {
-            // ignore EOF errors
-          }
-        },
-      };
-    } catch (err) {
-      const errText = String(err);
-      const warning = `Warning: PTY spawn failed (${errText}); retrying without PTY for \`${opts.command}\`.`;
-      logWarn(`exec: PTY spawn failed (${errText}); retrying without PTY for "${opts.command}".`);
-      opts.warnings.push(warning);
-      child = await spawnShellChild(shell, shellArgs);
-      stdin = child.stdin;
-    }
-  } else {
-    const { shell, args: shellArgs } = getShellConfig();
-    child = await spawnShellChild(shell, shellArgs);
-    stdin = child.stdin;
-    maybeCloseNonPtyStdin();
-  }
-
-  const session = {
+  const session: ProcessSession = {
     id: sessionId,
     command: opts.command,
     scopeKey: opts.scopeKey,
@@ -458,9 +309,9 @@ export async function runExecProcess(opts: {
     notifyOnExit: opts.notifyOnExit,
     notifyOnExitEmptySuccess: opts.notifyOnExitEmptySuccess === true,
     exitNotified: false,
-    child: child ?? undefined,
-    stdin,
-    pid: child?.pid ?? pty?.pid,
+    child: undefined,
+    stdin: undefined,
+    pid: undefined,
     startedAt,
     cwd: opts.workdir,
     maxOutputChars: opts.maxOutput,
@@ -477,59 +328,9 @@ export async function runExecProcess(opts: {
     exitSignal: undefined as NodeJS.Signals | number | null | undefined,
     truncated: false,
     backgrounded: false,
-  } satisfies ProcessSession;
+  };
   addSession(session);
 
-  let settled = false;
-  let timeoutTimer: NodeJS.Timeout | null = null;
-  let timeoutFinalizeTimer: NodeJS.Timeout | null = null;
-  let timedOut = false;
-  const timeoutFinalizeMs = 1000;
-  let resolveFn: ((outcome: ExecProcessOutcome) => void) | null = null;
-
-  const settle = (outcome: ExecProcessOutcome) => {
-    if (settled) {
-      return;
-    }
-    settled = true;
-    resolveFn?.(outcome);
-  };
-
-  const finalizeTimeout = () => {
-    if (session.exited) {
-      return;
-    }
-    markExited(session, null, "SIGKILL", "failed");
-    maybeNotifyOnExit(session, "failed");
-    const aggregated = session.aggregated.trim();
-    const reason = `Command timed out after ${opts.timeoutSec} seconds`;
-    settle({
-      status: "failed",
-      exitCode: null,
-      exitSignal: "SIGKILL",
-      durationMs: Date.now() - startedAt,
-      aggregated,
-      timedOut: true,
-      reason: aggregated ? `${aggregated}\n\n${reason}` : reason,
-    });
-  };
-
-  const onTimeout = () => {
-    timedOut = true;
-    killSession(session);
-    if (!timeoutFinalizeTimer) {
-      timeoutFinalizeTimer = setTimeout(() => {
-        finalizeTimeout();
-      }, timeoutFinalizeMs);
-    }
-  };
-
-  if (opts.timeoutSec > 0) {
-    timeoutTimer = setTimeout(() => {
-      onTimeout();
-    }, opts.timeoutSec * 1000);
-  }
-
   const emitUpdate = () => {
     if (!opts.onUpdate) {
       return;
@@ -565,116 +366,208 @@ export async function runExecProcess(opts: {
     }
   };
 
-  if (pty) {
-    const cursorResponse = buildCursorPositionResponse();
-    pty.onData((data) => {
-      const raw = data.toString();
-      const { cleaned, requests } = stripDsrRequests(raw);
-      if (requests > 0) {
+  const timeoutMs =
+    typeof opts.timeoutSec === "number" && opts.timeoutSec > 0
+      ? Math.floor(opts.timeoutSec * 1000)
+      : undefined;
+
+  const spawnSpec:
+    | {
+        mode: "child";
+        argv: string[];
+        env: NodeJS.ProcessEnv;
+        stdinMode: "pipe-open" | "pipe-closed";
+      }
+    | {
+        mode: "pty";
+        ptyCommand: string;
+        childFallbackArgv: string[];
+        env: NodeJS.ProcessEnv;
+        stdinMode: "pipe-open";
+      } = (() => {
+    if (opts.sandbox) {
+      return {
+        mode: "child" as const,
+        argv: [
+          "docker",
+          ...buildDockerExecArgs({
+            containerName: opts.sandbox.containerName,
+            command: execCommand,
+            workdir: opts.containerWorkdir ?? opts.sandbox.containerWorkdir,
+            env: opts.env,
+            tty: opts.usePty,
+          }),
+        ],
+        env: process.env,
+        stdinMode: opts.usePty ? ("pipe-open" as const) : ("pipe-closed" as const),
+      };
+    }
+    const { shell, args: shellArgs } = getShellConfig();
+    const childArgv = [shell, ...shellArgs, execCommand];
+    if (opts.usePty) {
+      return {
+        mode: "pty" as const,
+        ptyCommand: execCommand,
+        childFallbackArgv: childArgv,
+        env: opts.env,
+        stdinMode: "pipe-open" as const,
+      };
+    }
+    return {
+      mode: "child" as const,
+      argv: childArgv,
+      env: opts.env,
+      stdinMode: "pipe-closed" as const,
+    };
+  })();
+
+  let managedRun: ManagedRun | null = null;
+  let usingPty = spawnSpec.mode === "pty";
+  const cursorResponse = buildCursorPositionResponse();
+
+  const onSupervisorStdout = (chunk: string) => {
+    if (usingPty) {
+      const { cleaned, requests } = stripDsrRequests(chunk);
+      if (requests > 0 && managedRun?.stdin) {
         for (let i = 0; i < requests; i += 1) {
-          pty.write(cursorResponse);
+          managedRun.stdin.write(cursorResponse);
         }
       }
       handleStdout(cleaned);
-    });
-  } else if (child) {
-    child.stdout.on("data", handleStdout);
-    child.stderr.on("data", handleStderr);
-  }
+      return;
+    }
+    handleStdout(chunk);
+  };
 
-  const promise = new Promise<ExecProcessOutcome>((resolve) => {
-    resolveFn = resolve;
-    const handleExit = (code: number | null, exitSignal: NodeJS.Signals | number | null) => {
-      if (timeoutTimer) {
-        clearTimeout(timeoutTimer);
-      }
-      if (timeoutFinalizeTimer) {
-        clearTimeout(timeoutFinalizeTimer);
+  try {
+    const spawnBase = {
+      runId: sessionId,
+      sessionId: opts.sessionKey?.trim() || sessionId,
+      backendId: opts.sandbox ? "exec-sandbox" : "exec-host",
+      scopeKey: opts.scopeKey,
+      cwd: opts.workdir,
+      env: spawnSpec.env,
+      timeoutMs,
+      captureOutput: false,
+      onStdout: onSupervisorStdout,
+      onStderr: handleStderr,
+    };
+    managedRun =
+      spawnSpec.mode === "pty"
+        ? await supervisor.spawn({
+            ...spawnBase,
+            mode: "pty",
+            ptyCommand: spawnSpec.ptyCommand,
+          })
+        : await supervisor.spawn({
+            ...spawnBase,
+            mode: "child",
+            argv: spawnSpec.argv,
+            stdinMode: spawnSpec.stdinMode,
+          });
+  } catch (err) {
+    if (spawnSpec.mode === "pty") {
+      const warning = `Warning: PTY spawn failed (${String(err)}); retrying without PTY for \`${opts.command}\`.`;
+      logWarn(
+        `exec: PTY spawn failed (${String(err)}); retrying without PTY for "${opts.command}".`,
+      );
+      opts.warnings.push(warning);
+      usingPty = false;
+      try {
+        managedRun = await supervisor.spawn({
+          runId: sessionId,
+          sessionId: opts.sessionKey?.trim() || sessionId,
+          backendId: "exec-host",
+          scopeKey: opts.scopeKey,
+          mode: "child",
+          argv: spawnSpec.childFallbackArgv,
+          cwd: opts.workdir,
+          env: spawnSpec.env,
+          stdinMode: "pipe-open",
+          timeoutMs,
+          captureOutput: false,
+          onStdout: handleStdout,
+          onStderr: handleStderr,
+        });
+      } catch (retryErr) {
+        markExited(session, null, null, "failed");
+        maybeNotifyOnExit(session, "failed");
+        throw retryErr;
       }
+    } else {
+      markExited(session, null, null, "failed");
+      maybeNotifyOnExit(session, "failed");
+      throw err;
+    }
+  }
+  session.stdin = managedRun.stdin;
+  session.pid = managedRun.pid;
+
+  const promise = managedRun
+    .wait()
+    .then((exit): ExecProcessOutcome => {
       const durationMs = Date.now() - startedAt;
-      const wasSignal = exitSignal != null;
-      const isSuccess = code === 0 && !wasSignal && !timedOut;
-      const status: "completed" | "failed" = isSuccess ? "completed" : "failed";
-      markExited(session, code, exitSignal, status);
+      const status: "completed" | "failed" =
+        exit.exitCode === 0 && exit.reason === "exit" ? "completed" : "failed";
+      markExited(session, exit.exitCode, exit.exitSignal, status);
       maybeNotifyOnExit(session, status);
       if (!session.child && session.stdin) {
         session.stdin.destroyed = true;
       }
-
-      if (settled) {
-        return;
-      }
       const aggregated = session.aggregated.trim();
-      if (!isSuccess) {
-        const reason = timedOut
-          ? `Command timed out after ${opts.timeoutSec} seconds`
-          : wasSignal && exitSignal
-            ? `Command aborted by signal ${exitSignal}`
-            : code === null
-              ? "Command aborted before exit code was captured"
-              : `Command exited with code ${code}`;
-        const message = aggregated ? `${aggregated}\n\n${reason}` : reason;
-        settle({
-          status: "failed",
-          exitCode: code ?? null,
-          exitSignal: exitSignal ?? null,
+      if (status === "completed") {
+        return {
+          status: "completed",
+          exitCode: exit.exitCode ?? 0,
+          exitSignal: exit.exitSignal,
           durationMs,
           aggregated,
-          timedOut,
-          reason: message,
-        });
-        return;
+          timedOut: false,
+        };
       }
-      settle({
-        status: "completed",
-        exitCode: code ?? 0,
-        exitSignal: exitSignal ?? null,
+      const reason =
+        exit.reason === "overall-timeout"
+          ? `Command timed out after ${opts.timeoutSec} seconds`
+          : exit.reason === "no-output-timeout"
+            ? "Command timed out waiting for output"
+            : exit.exitSignal != null
+              ? `Command aborted by signal ${exit.exitSignal}`
+              : exit.exitCode == null
+                ? "Command aborted before exit code was captured"
+                : `Command exited with code ${exit.exitCode}`;
+      return {
+        status: "failed",
+        exitCode: exit.exitCode,
+        exitSignal: exit.exitSignal,
         durationMs,
         aggregated,
+        timedOut: exit.timedOut,
+        reason: aggregated ? `${aggregated}\n\n${reason}` : reason,
+      };
+    })
+    .catch((err): ExecProcessOutcome => {
+      markExited(session, null, null, "failed");
+      maybeNotifyOnExit(session, "failed");
+      const aggregated = session.aggregated.trim();
+      const message = aggregated ? `${aggregated}\n\n${String(err)}` : String(err);
+      return {
+        status: "failed",
+        exitCode: null,
+        exitSignal: null,
+        durationMs: Date.now() - startedAt,
+        aggregated,
         timedOut: false,
-      });
-    };
-
-    if (pty) {
-      pty.onExit((event) => {
-        const rawSignal = event.signal ?? null;
-        const normalizedSignal = rawSignal === 0 ? null : rawSignal;
-        handleExit(event.exitCode ?? null, normalizedSignal);
-      });
-    } else if (child) {
-      child.once("close", (code, exitSignal) => {
-        handleExit(code, exitSignal);
-      });
-
-      child.once("error", (err) => {
-        if (timeoutTimer) {
-          clearTimeout(timeoutTimer);
-        }
-        if (timeoutFinalizeTimer) {
-          clearTimeout(timeoutFinalizeTimer);
-        }
-        markExited(session, null, null, "failed");
-        maybeNotifyOnExit(session, "failed");
-        const aggregated = session.aggregated.trim();
-        const message = aggregated ? `${aggregated}\n\n${String(err)}` : String(err);
-        settle({
-          status: "failed",
-          exitCode: null,
-          exitSignal: null,
-          durationMs: Date.now() - startedAt,
-          aggregated,
-          timedOut,
-          reason: message,
-        });
-      });
-    }
-  });
+        reason: message,
+      };
+    });
 
   return {
     session,
     startedAt,
     pid: session.pid ?? undefined,
     promise,
-    kill: () => killSession(session),
+    kill: () => {
+      managedRun?.cancel("manual-cancel");
+    },
   };
 }
diff --git a/src/agents/bash-tools.exec.pty-cleanup.test.ts b/src/agents/bash-tools.exec.pty-cleanup.test.ts
new file mode 100644
index 00000000000..efe6f01d606
--- /dev/null
+++ b/src/agents/bash-tools.exec.pty-cleanup.test.ts
@@ -0,0 +1,71 @@
+import { afterEach, expect, test, vi } from "vitest";
+import { resetProcessRegistryForTests } from "./bash-process-registry";
+import { createExecTool } from "./bash-tools.exec";
+
+const { ptySpawnMock } = vi.hoisted(() => ({
+  ptySpawnMock: vi.fn(),
+}));
+
+vi.mock("@lydell/node-pty", () => ({
+  spawn: (...args: unknown[]) => ptySpawnMock(...args),
+}));
+
+afterEach(() => {
+  resetProcessRegistryForTests();
+  vi.clearAllMocks();
+});
+
+test("exec disposes PTY listeners after normal exit", async () => {
+  const disposeData = vi.fn();
+  const disposeExit = vi.fn();
+
+  ptySpawnMock.mockImplementation(() => ({
+    pid: 0,
+    write: vi.fn(),
+    onData: (listener: (value: string) => void) => {
+      listener("ok");
+      return { dispose: disposeData };
+    },
+    onExit: (listener: (event: { exitCode: number; signal?: number }) => void) => {
+      listener({ exitCode: 0 });
+      return { dispose: disposeExit };
+    },
+    kill: vi.fn(),
+  }));
+
+  const tool = createExecTool({ allowBackground: false });
+  const result = await tool.execute("toolcall", {
+    command: "echo ok",
+    pty: true,
+  });
+
+  expect(result.details.status).toBe("completed");
+  expect(disposeData).toHaveBeenCalledTimes(1);
+  expect(disposeExit).toHaveBeenCalledTimes(1);
+});
+
+test("exec tears down PTY resources on timeout", async () => {
+  const disposeData = vi.fn();
+  const disposeExit = vi.fn();
+  const kill = vi.fn();
+
+  ptySpawnMock.mockImplementation(() => ({
+    pid: 0,
+    write: vi.fn(),
+    onData: () => ({ dispose: disposeData }),
+    onExit: () => ({ dispose: disposeExit }),
+    kill,
+  }));
+
+  const tool = createExecTool({ allowBackground: false });
+  await expect(
+    tool.execute("toolcall", {
+      command: "sleep 5",
+      pty: true,
+      timeout: 0.01,
+    }),
+  ).rejects.toThrow("Command timed out");
+  expect(kill).toHaveBeenCalledTimes(1);
+  expect(disposeData).toHaveBeenCalledTimes(1);
+  expect(disposeExit).toHaveBeenCalledTimes(1);
+});
diff --git a/src/agents/bash-tools.exec.pty-fallback-failure.test.ts b/src/agents/bash-tools.exec.pty-fallback-failure.test.ts
new file mode 100644
index 00000000000..2caad66a83f
--- /dev/null
+++ b/src/agents/bash-tools.exec.pty-fallback-failure.test.ts
@@ -0,0 +1,39 @@
+import { afterEach, expect, test, vi } from "vitest";
+import { listRunningSessions, resetProcessRegistryForTests } from "./bash-process-registry";
+import { createExecTool } from "./bash-tools.exec";
+
+const { supervisorSpawnMock } = vi.hoisted(() => ({
+  supervisorSpawnMock: vi.fn(),
+}));
+
+vi.mock("../process/supervisor/index.js", () => ({
+  getProcessSupervisor: () => ({
+    spawn: (...args: unknown[]) => supervisorSpawnMock(...args),
+    cancel: vi.fn(),
+    cancelScope: vi.fn(),
+    reconcileOrphans: vi.fn(),
+    getRecord: vi.fn(),
+  }),
+}));
+
+afterEach(() => {
+  resetProcessRegistryForTests();
+  vi.clearAllMocks();
+});
+
+test("exec cleans session state when PTY fallback spawn also fails", async () => {
+  supervisorSpawnMock
+    .mockRejectedValueOnce(new Error("pty spawn failed"))
+    .mockRejectedValueOnce(new Error("child fallback failed"));
+
+  const tool = createExecTool({ allowBackground: false });
+
+  await expect(
+    tool.execute("toolcall", {
+      command: "echo ok",
+      pty: true,
+    }),
+  ).rejects.toThrow("child fallback failed");
+
+  expect(listRunningSessions()).toHaveLength(0);
+});
diff --git a/src/agents/bash-tools.process.poll-timeout.test.ts b/src/agents/bash-tools.process.poll-timeout.test.ts
index e72d95a3426..44e3bb74153 100644
--- a/src/agents/bash-tools.process.poll-timeout.test.ts
+++ b/src/agents/bash-tools.process.poll-timeout.test.ts
@@ -1,56 +1,100 @@
-import { afterEach, expect, test } from "vitest";
-import { resetProcessRegistryForTests } from "./bash-process-registry.js";
-import { createExecTool } from "./bash-tools.exec.js";
+import { afterEach, expect, test, vi } from "vitest";
+import type { ProcessSession } from "./bash-process-registry.js";
+import {
+  addSession,
+  appendOutput,
+  markExited,
+  resetProcessRegistryForTests,
+} from "./bash-process-registry.js";
 import { createProcessTool } from "./bash-tools.process.js";
 
 afterEach(() => {
   resetProcessRegistryForTests();
 });
 
-const sleepAndEcho =
-  process.platform === "win32"
-    ? "Start-Sleep -Milliseconds 300; Write-Output done"
-    : "sleep 0.3; echo done";
+function createBackgroundSession(id: string): ProcessSession {
+  return {
+    id,
+    command: "test",
+    startedAt: Date.now(),
+    cwd: "/tmp",
+    maxOutputChars: 10_000,
+    pendingMaxOutputChars: 30_000,
+    totalOutputChars: 0,
+    pendingStdout: [],
+    pendingStderr: [],
+    pendingStdoutChars: 0,
+    pendingStderrChars: 0,
+    aggregated: "",
+    tail: "",
+    exited: false,
+    exitCode: undefined,
+    exitSignal: undefined,
+    truncated: false,
+    backgrounded: true,
+  };
+}
 
 test("process poll waits for completion when timeout is provided", async () => {
-  const execTool = createExecTool();
-  const processTool = createProcessTool();
-  const started = Date.now();
-  const run = await execTool.execute("toolcall", {
-    command: sleepAndEcho,
-    background: true,
-  });
-  expect(run.details.status).toBe("running");
-  const sessionId = run.details.sessionId;
+  vi.useFakeTimers();
+  try {
+    const processTool = createProcessTool();
+    const sessionId = "sess";
+    const session = createBackgroundSession(sessionId);
+    addSession(session);
 
-  const poll = await processTool.execute("toolcall", {
-    action: "poll",
-    sessionId,
-    timeout: 2000,
-  });
-  const elapsedMs = Date.now() - started;
-  const details = poll.details as { status?: string; aggregated?: string };
-  expect(details.status).toBe("completed");
-  expect(details.aggregated ?? "").toContain("done");
-  expect(elapsedMs).toBeGreaterThanOrEqual(200);
+    setTimeout(() => {
+      appendOutput(session, "stdout", "done\n");
+      markExited(session, 0, null, "completed");
+    }, 10);
+
+    const pollPromise = processTool.execute("toolcall", {
+      action: "poll",
+      sessionId,
+      timeout: 2000,
+    });
+
+    let resolved = false;
+    void pollPromise.finally(() => {
+      resolved = true;
+    });
+
+    await vi.advanceTimersByTimeAsync(200);
+    expect(resolved).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(100);
+    const poll = await pollPromise;
+    const details = poll.details as { status?: string; aggregated?: string };
+    expect(details.status).toBe("completed");
+    expect(details.aggregated ?? "").toContain("done");
+  } finally {
+    vi.useRealTimers();
+  }
 });
 
 test("process poll accepts string timeout values", async () => {
-  const execTool = createExecTool();
-  const processTool = createProcessTool();
-  const run = await execTool.execute("toolcall", {
-    command: sleepAndEcho,
-    background: true,
-  });
-  expect(run.details.status).toBe("running");
-  const sessionId = run.details.sessionId;
+  vi.useFakeTimers();
+  try {
+    const processTool = createProcessTool();
+    const sessionId = "sess-2";
+    const session = createBackgroundSession(sessionId);
+    addSession(session);
+    setTimeout(() => {
+      appendOutput(session, "stdout", "done\n");
+      markExited(session, 0, null, "completed");
+    }, 10);
 
-  const poll = await processTool.execute("toolcall", {
-    action: "poll",
-    sessionId,
-    timeout: "2000",
-  });
-  const details = poll.details as { status?: string; aggregated?: string };
-  expect(details.status).toBe("completed");
-  expect(details.aggregated ?? "").toContain("done");
+    const pollPromise = processTool.execute("toolcall", {
+      action: "poll",
+      sessionId,
+      timeout: "2000",
+    });
+    await vi.advanceTimersByTimeAsync(350);
+    const poll = await pollPromise;
+    const details = poll.details as { status?: string; aggregated?: string };
+    expect(details.status).toBe("completed");
+    expect(details.aggregated ?? "").toContain("done");
+  } finally {
+    vi.useRealTimers();
+  }
 });
diff --git a/src/agents/bash-tools.process.supervisor.test.ts b/src/agents/bash-tools.process.supervisor.test.ts
new file mode 100644
index 00000000000..e6d026595f4
--- /dev/null
+++ b/src/agents/bash-tools.process.supervisor.test.ts
@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ProcessSession } from "./bash-process-registry.js";
+import {
+  addSession,
+  getFinishedSession,
+  getSession,
+  resetProcessRegistryForTests,
+} from "./bash-process-registry.js";
+import { createProcessTool } from "./bash-tools.process.js";
+
+const { supervisorMock } = vi.hoisted(() => ({
+  supervisorMock: {
+    spawn: vi.fn(),
+    cancel: vi.fn(),
+    cancelScope: vi.fn(),
+    reconcileOrphans: vi.fn(),
+    getRecord: vi.fn(),
+  },
+}));
+
+const { killProcessTreeMock } = vi.hoisted(() => ({
+  killProcessTreeMock: vi.fn(),
+}));
+
+vi.mock("../process/supervisor/index.js", () => ({
+  getProcessSupervisor: () => supervisorMock,
+}));
+
+vi.mock("../process/kill-tree.js", () => ({
+  killProcessTree: (...args: unknown[]) => killProcessTreeMock(...args),
+}));
+
+function createBackgroundSession(id: string, pid?: number): ProcessSession {
+  return {
+    id,
+    command: "sleep 999",
+    startedAt: Date.now(),
+    cwd: "/tmp",
+    maxOutputChars: 10_000,
+    pendingMaxOutputChars: 30_000,
+    totalOutputChars: 0,
+    pendingStdout: [],
+    pendingStderr: [],
+    pendingStdoutChars: 0,
+    pendingStderrChars: 0,
+    aggregated: "",
+    tail: "",
+    pid,
+    exited: false,
+    exitCode: undefined,
+    exitSignal: undefined,
+    truncated: false,
+    backgrounded: true,
+  };
+}
+
+describe("process tool supervisor cancellation", () => {
+  beforeEach(() => {
+    supervisorMock.spawn.mockReset();
+    supervisorMock.cancel.mockReset();
+    supervisorMock.cancelScope.mockReset();
+    supervisorMock.reconcileOrphans.mockReset();
+    supervisorMock.getRecord.mockReset();
+    killProcessTreeMock.mockReset();
+  });
+
+  afterEach(() => {
+    resetProcessRegistryForTests();
+  });
+
+  it("routes kill through supervisor when run is managed", async () => {
+    supervisorMock.getRecord.mockReturnValue({
+      runId: "sess",
+      state: "running",
+    });
+    addSession(createBackgroundSession("sess"));
+    const processTool = createProcessTool();
+
+    const result = await processTool.execute("toolcall", {
+      action: "kill",
+      sessionId: "sess",
+    });
+
+    expect(supervisorMock.cancel).toHaveBeenCalledWith("sess", "manual-cancel");
+    expect(getSession("sess")).toBeDefined();
+    expect(getSession("sess")?.exited).toBe(false);
+    expect(result.content[0]).toMatchObject({
+      type: "text",
+      text: "Termination requested for session sess.",
+    });
+  });
+
+  it("remove drops running session immediately when cancellation is requested", async () => {
+    supervisorMock.getRecord.mockReturnValue({
+      runId: "sess",
+      state: "running",
+    });
+    addSession(createBackgroundSession("sess"));
+    const processTool = createProcessTool();
+
+    const result = await processTool.execute("toolcall", {
+      action: "remove",
+      sessionId: "sess",
+    });
+
+    expect(supervisorMock.cancel).toHaveBeenCalledWith("sess", "manual-cancel");
+    expect(getSession("sess")).toBeUndefined();
+    expect(getFinishedSession("sess")).toBeUndefined();
+    expect(result.content[0]).toMatchObject({
+      type: "text",
+      text: "Removed session sess (termination requested).",
+    });
+  });
+
+  it("falls back to process-tree kill when supervisor record is missing", async () => {
+    supervisorMock.getRecord.mockReturnValue(undefined);
+    addSession(createBackgroundSession("sess-fallback", 4242));
+    const processTool = createProcessTool();
+
+    const result = await processTool.execute("toolcall", {
+      action: "kill",
+      sessionId: "sess-fallback",
+    });
+
+    expect(killProcessTreeMock).toHaveBeenCalledWith(4242);
+    expect(getSession("sess-fallback")).toBeUndefined();
+    expect(getFinishedSession("sess-fallback")).toBeDefined();
+    expect(result.content[0]).toMatchObject({
+      type: "text",
+      text: "Killed session sess-fallback.",
+    });
+  });
+
+  it("fails remove when no supervisor record and no pid is available", async () => {
+    supervisorMock.getRecord.mockReturnValue(undefined);
+    addSession(createBackgroundSession("sess-no-pid"));
+    const processTool = createProcessTool();
+
+    const result = await processTool.execute("toolcall", {
+      action: "remove",
+      sessionId: "sess-no-pid",
+    });
+
+    expect(killProcessTreeMock).not.toHaveBeenCalled();
+    expect(getSession("sess-no-pid")).toBeDefined();
+    expect(result.details).toMatchObject({ status: "failed" });
+    expect(result.content[0]).toMatchObject({
+      type: "text",
+      text: "Unable to remove session sess-no-pid: no active supervisor run or process id.",
+    });
+  });
+});
diff --git a/src/agents/bash-tools.process.ts b/src/agents/bash-tools.process.ts
index b5966ab79b0..38a8ac357ab 100644
--- a/src/agents/bash-tools.process.ts
+++ b/src/agents/bash-tools.process.ts
@@ -1,7 +1,10 @@
 import type { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
 import { Type } from "@sinclair/typebox";
 import { formatDurationCompact } from "../infra/format-time/format-duration.ts";
+import { killProcessTree } from "../process/kill-tree.js";
+import { getProcessSupervisor } from "../process/supervisor/index.js";
 import {
+  type ProcessSession,
   deleteSession,
   drainSession,
   getFinishedSession,
@@ -11,13 +14,7 @@ import {
   markExited,
   setJobTtlMs,
 } from "./bash-process-registry.js";
-import {
-  deriveSessionName,
-  killSession,
-  pad,
-  sliceLogLines,
-  truncateMiddle,
-} from "./bash-tools.shared.js";
+import { deriveSessionName, pad, sliceLogLines, truncateMiddle } from "./bash-tools.shared.js";
 import { encodeKeySequence, encodePaste } from "./pty-keys.js";
 
 export type ProcessToolDefaults = {
@@ -65,8 +62,9 @@ const processSchema = Type.Object({
   offset: Type.Optional(Type.Number({ description: "Log offset" })),
   limit: Type.Optional(Type.Number({ description: "Log length" })),
   timeout: Type.Optional(
-    Type.Union([Type.Number(), Type.String()], {
+    Type.Number({
       description: "For poll: wait up to this many milliseconds before returning",
+      minimum: 0,
     }),
   ),
 });
@@ -106,9 +104,28 @@ export function createProcessTool(
     setJobTtlMs(defaults.cleanupMs);
   }
   const scopeKey = defaults?.scopeKey;
+  const supervisor = getProcessSupervisor();
   const isInScope = (session?: { scopeKey?: string } | null) =>
     !scopeKey || session?.scopeKey === scopeKey;
 
+  const cancelManagedSession = (sessionId: string) => {
+    const record = supervisor.getRecord(sessionId);
+    if (!record || record.state === "exited") {
+      return false;
+    }
+    supervisor.cancel(sessionId, "manual-cancel");
+    return true;
+  };
+
+  const terminateSessionFallback = (session: ProcessSession) => {
+    const pid = session.pid ?? session.child?.pid;
+    if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0) {
+      return false;
+    }
+    killProcessTree(pid);
+    return true;
+  };
+
   return {
     name: "process",
     label: "process",
@@ -138,7 +155,7 @@ export function createProcessTool(
         eof?: boolean;
         offset?: number;
         limit?: number;
-        timeout?: number | string;
+        timeout?: unknown;
       };
 
       if (params.action === "list") {
@@ -522,10 +539,25 @@ export function createProcessTool(
           if (!scopedSession.backgrounded) {
             return failText(`Session ${params.sessionId} is not backgrounded.`);
           }
-          killSession(scopedSession);
-          markExited(scopedSession, null, "SIGKILL", "failed");
+          const canceled = cancelManagedSession(scopedSession.id);
+          if (!canceled) {
+            const terminated = terminateSessionFallback(scopedSession);
+            if (!terminated) {
+              return failText(
+                `Unable to terminate session ${params.sessionId}: no active supervisor run or process id.`,
+              );
+            }
+            markExited(scopedSession, null, "SIGKILL", "failed");
+          }
           return {
-            content: [{ type: "text", text: `Killed session ${params.sessionId}.` }],
+            content: [
+              {
+                type: "text",
+                text: canceled
+                  ? `Termination requested for session ${params.sessionId}.`
+                  : `Killed session ${params.sessionId}.`,
+              },
+            ],
             details: {
               status: "failed",
               name: scopedSession ? deriveSessionName(scopedSession.command) : undefined,
@@ -554,10 +586,30 @@ export function createProcessTool(
 
         case "remove": {
           if (scopedSession) {
-            killSession(scopedSession);
-            markExited(scopedSession, null, "SIGKILL", "failed");
+            const canceled = cancelManagedSession(scopedSession.id);
+            if (canceled) {
+              // Keep remove semantics deterministic: drop from process registry now.
+              scopedSession.backgrounded = false;
+              deleteSession(params.sessionId);
+            } else {
+              const terminated = terminateSessionFallback(scopedSession);
+              if (!terminated) {
+                return failText(
+                  `Unable to remove session ${params.sessionId}: no active supervisor run or process id.`,
+                );
+              }
+              markExited(scopedSession, null, "SIGKILL", "failed");
+              deleteSession(params.sessionId);
+            }
             return {
-              content: [{ type: "text", text: `Removed session ${params.sessionId}.` }],
+              content: [
+                {
+                  type: "text",
+                  text: canceled
+                    ? `Removed session ${params.sessionId} (termination requested).`
+                    : `Removed session ${params.sessionId}.`,
+                },
+              ],
               details: {
                 status: "failed",
                 name: scopedSession ? deriveSessionName(scopedSession.command) : undefined,
diff --git a/src/agents/bash-tools.shared.ts b/src/agents/bash-tools.shared.ts
index 99a7a4b792f..07b12266006 100644
--- a/src/agents/bash-tools.shared.ts
+++ b/src/agents/bash-tools.shared.ts
@@ -1,11 +1,9 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import { sliceUtf16Safe } from "../utils.js";
 import { assertSandboxPath } from "./sandbox-paths.js";
-import { killProcessTree } from "./shell-utils.js";
 
 const CHUNK_LIMIT = 8 * 1024;
 
@@ -115,13 +113,6 @@ export async function resolveSandboxWorkdir(params: {
   }
 }
 
-export function killSession(session: { pid?: number; child?: ChildProcessWithoutNullStreams }) {
-  const pid = session.pid ?? session.child?.pid;
-  if (pid) {
-    killProcessTree(pid);
-  }
-}
-
 export function resolveWorkdir(workdir: string, warnings: string[]) {
   const current = safeCwd();
   const fallback = current ?? homedir();
diff --git a/src/agents/claude-cli-runner.e2e.test.ts b/src/agents/claude-cli-runner.e2e.test.ts
index 587a13ff2dd..afa353daba3 100644
--- a/src/agents/claude-cli-runner.e2e.test.ts
+++ b/src/agents/claude-cli-runner.e2e.test.ts
@@ -2,7 +2,19 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { sleep } from "../utils.js";
 import { runClaudeCliAgent } from "./claude-cli-runner.js";
 
-const runCommandWithTimeoutMock = vi.fn();
+const mocks = vi.hoisted(() => ({
+  spawn: vi.fn(),
+}));
+
+vi.mock("../process/supervisor/index.js", () => ({
+  getProcessSupervisor: () => ({
+    spawn: (...args: unknown[]) => mocks.spawn(...args),
+    cancel: vi.fn(),
+    cancelScope: vi.fn(),
+    reconcileOrphans: async () => {},
+    getRecord: vi.fn(),
+  }),
+}));
 
 function createDeferred<T>() {
   let resolve: (value: T) => void;
@@ -18,6 +30,40 @@ function createDeferred<T>() {
   };
 }
 
+function createManagedRun(
+  exit: Promise<{
+    reason: "exit" | "overall-timeout" | "no-output-timeout" | "signal" | "manual-cancel";
+    exitCode: number | null;
+    exitSignal: NodeJS.Signals | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    noOutputTimedOut: boolean;
+  }>,
+) {
+  return {
+    runId: "run-test",
+    pid: 12345,
+    startedAtMs: Date.now(),
+    wait: async () => await exit,
+    cancel: vi.fn(),
+  };
+}
+
+function successExit(payload: { message: string; session_id: string }) {
+  return {
+    reason: "exit" as const,
+    exitCode: 0,
+    exitSignal: null,
+    durationMs: 1,
+    stdout: JSON.stringify(payload),
+    stderr: "",
+    timedOut: false,
+    noOutputTimedOut: false,
+  };
+}
+
 async function waitForCalls(mockFn: { mock: { calls: unknown[][] } }, count: number) {
   for (let i = 0; i < 50; i += 1) {
     if (mockFn.mock.calls.length >= count) {
@@ -28,23 +74,15 @@ async function waitForCalls(mockFn: { mock: { calls: unknown[][] } }, count: num
   throw new Error(`Expected ${count} calls, got ${mockFn.mock.calls.length}`);
 }
 
-vi.mock("../process/exec.js", () => ({
-  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
-}));
-
 describe("runClaudeCliAgent", () => {
   beforeEach(() => {
-    runCommandWithTimeoutMock.mockReset();
+    mocks.spawn.mockReset();
   });
 
   it("starts a new session with --session-id when none is provided", async () => {
-    runCommandWithTimeoutMock.mockResolvedValueOnce({
-      stdout: JSON.stringify({ message: "ok", session_id: "sid-1" }),
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+    mocks.spawn.mockResolvedValueOnce(
+      createManagedRun(Promise.resolve(successExit({ message: "ok", session_id: "sid-1" }))),
+    );
 
     await runClaudeCliAgent({
       sessionId: "openclaw-session",
@@ -56,21 +94,18 @@ describe("runClaudeCliAgent", () => {
       runId: "run-1",
     });
 
-    expect(runCommandWithTimeoutMock).toHaveBeenCalledTimes(1);
-    const argv = runCommandWithTimeoutMock.mock.calls[0]?.[0] as string[];
-    expect(argv).toContain("claude");
-    expect(argv).toContain("--session-id");
-    expect(argv).toContain("hi");
+    expect(mocks.spawn).toHaveBeenCalledTimes(1);
+    const spawnInput = mocks.spawn.mock.calls[0]?.[0] as { argv: string[]; mode: string };
+    expect(spawnInput.mode).toBe("child");
+    expect(spawnInput.argv).toContain("claude");
+    expect(spawnInput.argv).toContain("--session-id");
+    expect(spawnInput.argv).toContain("hi");
   });
 
   it("uses --resume when a claude session id is provided", async () => {
-    runCommandWithTimeoutMock.mockResolvedValueOnce({
-      stdout: JSON.stringify({ message: "ok", session_id: "sid-2" }),
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+    mocks.spawn.mockResolvedValueOnce(
+      createManagedRun(Promise.resolve(successExit({ message: "ok", session_id: "sid-2" }))),
+    );
 
     await runClaudeCliAgent({
       sessionId: "openclaw-session",
@@ -83,32 +118,21 @@ describe("runClaudeCliAgent", () => {
       claudeSessionId: "c9d7b831-1c31-4d22-80b9-1e50ca207d4b",
     });
 
-    expect(runCommandWithTimeoutMock).toHaveBeenCalledTimes(1);
-    const argv = runCommandWithTimeoutMock.mock.calls[0]?.[0] as string[];
-    expect(argv).toContain("--resume");
-    expect(argv).toContain("c9d7b831-1c31-4d22-80b9-1e50ca207d4b");
-    expect(argv).toContain("hi");
+    expect(mocks.spawn).toHaveBeenCalledTimes(1);
+    const spawnInput = mocks.spawn.mock.calls[0]?.[0] as { argv: string[] };
+    expect(spawnInput.argv).toContain("--resume");
+    expect(spawnInput.argv).toContain("c9d7b831-1c31-4d22-80b9-1e50ca207d4b");
+    expect(spawnInput.argv).not.toContain("--session-id");
+    expect(spawnInput.argv).toContain("hi");
   });
 
   it("serializes concurrent claude-cli runs", async () => {
-    const firstDeferred = createDeferred<{
-      stdout: string;
-      stderr: string;
-      code: number | null;
-      signal: NodeJS.Signals | null;
-      killed: boolean;
-    }>();
-    const secondDeferred = createDeferred<{
-      stdout: string;
-      stderr: string;
-      code: number | null;
-      signal: NodeJS.Signals | null;
-      killed: boolean;
-    }>();
+    const firstDeferred = createDeferred<ReturnType<typeof successExit>>();
+    const secondDeferred = createDeferred<ReturnType<typeof successExit>>();
 
-    runCommandWithTimeoutMock
-      .mockImplementationOnce(() => firstDeferred.promise)
-      .mockImplementationOnce(() => secondDeferred.promise);
+    mocks.spawn
+      .mockResolvedValueOnce(createManagedRun(firstDeferred.promise))
+      .mockResolvedValueOnce(createManagedRun(secondDeferred.promise));
 
     const firstRun = runClaudeCliAgent({
       sessionId: "s1",
@@ -130,25 +154,13 @@ describe("runClaudeCliAgent", () => {
       runId: "run-2",
     });
 
-    await waitForCalls(runCommandWithTimeoutMock, 1);
+    await waitForCalls(mocks.spawn, 1);
 
-    firstDeferred.resolve({
-      stdout: JSON.stringify({ message: "ok", session_id: "sid-1" }),
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+    firstDeferred.resolve(successExit({ message: "ok", session_id: "sid-1" }));
 
-    await waitForCalls(runCommandWithTimeoutMock, 2);
+    await waitForCalls(mocks.spawn, 2);
 
-    secondDeferred.resolve({
-      stdout: JSON.stringify({ message: "ok", session_id: "sid-2" }),
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+    secondDeferred.resolve(successExit({ message: "ok", session_id: "sid-2" }));
 
     await Promise.all([firstRun, secondRun]);
   });
diff --git a/src/agents/cli-backends.test.ts b/src/agents/cli-backends.test.ts
new file mode 100644
index 00000000000..c78dfdb87fc
--- /dev/null
+++ b/src/agents/cli-backends.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import { resolveCliBackendConfig } from "./cli-backends.js";
+
+describe("resolveCliBackendConfig reliability merge", () => {
+  it("deep-merges reliability watchdog overrides for codex", () => {
+    const cfg = {
+      agents: {
+        defaults: {
+          cliBackends: {
+            "codex-cli": {
+              command: "codex",
+              reliability: {
+                watchdog: {
+                  resume: {
+                    noOutputTimeoutMs: 42_000,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    } satisfies OpenClawConfig;
+
+    const resolved = resolveCliBackendConfig("codex-cli", cfg);
+
+    expect(resolved).not.toBeNull();
+    expect(resolved?.config.reliability?.watchdog?.resume?.noOutputTimeoutMs).toBe(42_000);
+    // Ensure defaults are retained when only one field is overridden.
+    expect(resolved?.config.reliability?.watchdog?.resume?.noOutputTimeoutRatio).toBe(0.3);
+    expect(resolved?.config.reliability?.watchdog?.resume?.minMs).toBe(60_000);
+    expect(resolved?.config.reliability?.watchdog?.resume?.maxMs).toBe(180_000);
+    expect(resolved?.config.reliability?.watchdog?.fresh?.noOutputTimeoutRatio).toBe(0.8);
+  });
+});
diff --git a/src/agents/cli-backends.ts b/src/agents/cli-backends.ts
index 5f6b2253fb2..2f1db0f87a6 100644
--- a/src/agents/cli-backends.ts
+++ b/src/agents/cli-backends.ts
@@ -1,5 +1,9 @@
 import type { OpenClawConfig } from "../config/config.js";
 import type { CliBackendConfig } from "../config/types.js";
+import {
+  CLI_FRESH_WATCHDOG_DEFAULTS,
+  CLI_RESUME_WATCHDOG_DEFAULTS,
+} from "./cli-watchdog-defaults.js";
 import { normalizeProviderId } from "./model-selection.js";
 
 export type ResolvedCliBackend = {
@@ -49,6 +53,12 @@ const DEFAULT_CLAUDE_BACKEND: CliBackendConfig = {
   systemPromptMode: "append",
   systemPromptWhen: "first",
   clearEnv: ["ANTHROPIC_API_KEY", "ANTHROPIC_API_KEY_OLD"],
+  reliability: {
+    watchdog: {
+      fresh: { ...CLI_FRESH_WATCHDOG_DEFAULTS },
+      resume: { ...CLI_RESUME_WATCHDOG_DEFAULTS },
+    },
+  },
   serialize: true,
 };
 
@@ -73,6 +83,12 @@ const DEFAULT_CODEX_BACKEND: CliBackendConfig = {
   sessionMode: "existing",
   imageArg: "--image",
   imageMode: "repeat",
+  reliability: {
+    watchdog: {
+      fresh: { ...CLI_FRESH_WATCHDOG_DEFAULTS },
+      resume: { ...CLI_RESUME_WATCHDOG_DEFAULTS },
+    },
+  },
   serialize: true,
 };
 
@@ -96,6 +112,10 @@ function mergeBackendConfig(base: CliBackendConfig, override?: CliBackendConfig)
   if (!override) {
     return { ...base };
   }
+  const baseFresh = base.reliability?.watchdog?.fresh ?? {};
+  const baseResume = base.reliability?.watchdog?.resume ?? {};
+  const overrideFresh = override.reliability?.watchdog?.fresh ?? {};
+  const overrideResume = override.reliability?.watchdog?.resume ?? {};
   return {
     ...base,
     ...override,
@@ -106,6 +126,22 @@ function mergeBackendConfig(base: CliBackendConfig, override?: CliBackendConfig)
     sessionIdFields: override.sessionIdFields ?? base.sessionIdFields,
     sessionArgs: override.sessionArgs ?? base.sessionArgs,
     resumeArgs: override.resumeArgs ?? base.resumeArgs,
+    reliability: {
+      ...base.reliability,
+      ...override.reliability,
+      watchdog: {
+        ...base.reliability?.watchdog,
+        ...override.reliability?.watchdog,
+        fresh: {
+          ...baseFresh,
+          ...overrideFresh,
+        },
+        resume: {
+          ...baseResume,
+          ...overrideResume,
+        },
+      },
+    },
   };
 }
 
diff --git a/src/agents/cli-runner.e2e.test.ts b/src/agents/cli-runner.e2e.test.ts
index 1383be1edb3..16f563d9e7c 100644
--- a/src/agents/cli-runner.e2e.test.ts
+++ b/src/agents/cli-runner.e2e.test.ts
@@ -3,50 +3,69 @@ import os from "node:os";
 import path from "node:path";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
-import type { CliBackendConfig } from "../config/types.js";
 import { runCliAgent } from "./cli-runner.js";
-import { cleanupResumeProcesses, cleanupSuspendedCliProcesses } from "./cli-runner/helpers.js";
+import { resolveCliNoOutputTimeoutMs } from "./cli-runner/helpers.js";
 
-const runCommandWithTimeoutMock = vi.fn();
-const runExecMock = vi.fn();
+const supervisorSpawnMock = vi.fn();
 
-vi.mock("../process/exec.js", () => ({
-  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
-  runExec: (...args: unknown[]) => runExecMock(...args),
+vi.mock("../process/supervisor/index.js", () => ({
+  getProcessSupervisor: () => ({
+    spawn: (...args: unknown[]) => supervisorSpawnMock(...args),
+    cancel: vi.fn(),
+    cancelScope: vi.fn(),
+    reconcileOrphans: vi.fn(),
+    getRecord: vi.fn(),
+  }),
 }));
 
-describe("runCliAgent resume cleanup", () => {
+type MockRunExit = {
+  reason:
+    | "manual-cancel"
+    | "overall-timeout"
+    | "no-output-timeout"
+    | "spawn-error"
+    | "signal"
+    | "exit";
+  exitCode: number | null;
+  exitSignal: NodeJS.Signals | number | null;
+  durationMs: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  noOutputTimedOut: boolean;
+};
+
+function createManagedRun(exit: MockRunExit, pid = 1234) {
+  return {
+    runId: "run-supervisor",
+    pid,
+    startedAtMs: Date.now(),
+    stdin: undefined,
+    wait: vi.fn().mockResolvedValue(exit),
+    cancel: vi.fn(),
+  };
+}
+
+describe("runCliAgent with process supervisor", () => {
   beforeEach(() => {
-    runCommandWithTimeoutMock.mockReset();
-    runExecMock.mockReset();
+    supervisorSpawnMock.mockReset();
   });
 
-  it("kills stale resume processes for codex sessions", async () => {
-    const selfPid = process.pid;
-
-    runExecMock
-      .mockResolvedValueOnce({
-        stdout: "  1 999 S /bin/launchd\n",
+  it("runs CLI through supervisor and returns payload", async () => {
+    supervisorSpawnMock.mockResolvedValueOnce(
+      createManagedRun({
+        reason: "exit",
+        exitCode: 0,
+        exitSignal: null,
+        durationMs: 50,
+        stdout: "ok",
         stderr: "",
-      }) // cleanupSuspendedCliProcesses (ps) — ppid 999 != selfPid, no match
-      .mockResolvedValueOnce({
-        stdout: [
-          `  ${selfPid + 1} ${selfPid} codex exec resume thread-123 --color never --sandbox read-only --skip-git-repo-check`,
-          `  ${selfPid + 2} 999 codex exec resume thread-123 --color never --sandbox read-only --skip-git-repo-check`,
-        ].join("\n"),
-        stderr: "",
-      }) // cleanupResumeProcesses (ps)
-      .mockResolvedValueOnce({ stdout: "", stderr: "" }) // cleanupResumeProcesses (kill -TERM)
-      .mockResolvedValueOnce({ stdout: "", stderr: "" }); // cleanupResumeProcesses (kill -9)
-    runCommandWithTimeoutMock.mockResolvedValueOnce({
-      stdout: "ok",
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+        timedOut: false,
+        noOutputTimedOut: false,
+      }),
+    );
 
-    await runCliAgent({
+    const result = await runCliAgent({
       sessionId: "s1",
       sessionFile: "/tmp/session.jsonl",
       workspaceDir: "/tmp",
@@ -58,28 +77,80 @@ describe("runCliAgent resume cleanup", () => {
       cliSessionId: "thread-123",
     });
 
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
+    expect(result.payloads?.[0]?.text).toBe("ok");
+    expect(supervisorSpawnMock).toHaveBeenCalledTimes(1);
+    const input = supervisorSpawnMock.mock.calls[0]?.[0] as {
+      argv?: string[];
+      mode?: string;
+      timeoutMs?: number;
+      noOutputTimeoutMs?: number;
+      replaceExistingScope?: boolean;
+      scopeKey?: string;
+    };
+    expect(input.mode).toBe("child");
+    expect(input.argv?.[0]).toBe("codex");
+    expect(input.timeoutMs).toBe(1_000);
+    expect(input.noOutputTimeoutMs).toBeGreaterThanOrEqual(1_000);
+    expect(input.replaceExistingScope).toBe(true);
+    expect(input.scopeKey).toContain("thread-123");
+  });
 
-    expect(runExecMock).toHaveBeenCalledTimes(4);
+  it("fails with timeout when no-output watchdog trips", async () => {
+    supervisorSpawnMock.mockResolvedValueOnce(
+      createManagedRun({
+        reason: "no-output-timeout",
+        exitCode: null,
+        exitSignal: "SIGKILL",
+        durationMs: 200,
+        stdout: "",
+        stderr: "",
+        timedOut: true,
+        noOutputTimedOut: true,
+      }),
+    );
 
-    // Second call: cleanupResumeProcesses ps
-    const psCall = runExecMock.mock.calls[1] ?? [];
-    expect(psCall[0]).toBe("ps");
+    await expect(
+      runCliAgent({
+        sessionId: "s1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp",
+        prompt: "hi",
+        provider: "codex-cli",
+        model: "gpt-5.2-codex",
+        timeoutMs: 1_000,
+        runId: "run-2",
+        cliSessionId: "thread-123",
+      }),
+    ).rejects.toThrow("produced no output");
+  });
 
-    // Third call: TERM, only the child PID
-    const termCall = runExecMock.mock.calls[2] ?? [];
-    expect(termCall[0]).toBe("kill");
-    const termArgs = termCall[1] as string[];
-    expect(termArgs).toEqual(["-TERM", String(selfPid + 1)]);
+  it("fails with timeout when overall timeout trips", async () => {
+    supervisorSpawnMock.mockResolvedValueOnce(
+      createManagedRun({
+        reason: "overall-timeout",
+        exitCode: null,
+        exitSignal: "SIGKILL",
+        durationMs: 200,
+        stdout: "",
+        stderr: "",
+        timedOut: true,
+        noOutputTimedOut: false,
+      }),
+    );
 
-    // Fourth call: KILL, only the child PID
-    const killCall = runExecMock.mock.calls[3] ?? [];
-    expect(killCall[0]).toBe("kill");
-    const killArgs = killCall[1] as string[];
-    expect(killArgs).toEqual(["-9", String(selfPid + 1)]);
+    await expect(
+      runCliAgent({
+        sessionId: "s1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp",
+        prompt: "hi",
+        provider: "codex-cli",
+        model: "gpt-5.2-codex",
+        timeoutMs: 1_000,
+        runId: "run-3",
+        cliSessionId: "thread-123",
+      }),
+    ).rejects.toThrow("exceeded timeout");
   });
 
   it("falls back to per-agent workspace when workspaceDir is missing", async () => {
@@ -94,14 +165,18 @@ describe("runCliAgent resume cleanup", () => {
       },
     } satisfies OpenClawConfig;
 
-    runExecMock.mockResolvedValue({ stdout: "", stderr: "" });
-    runCommandWithTimeoutMock.mockResolvedValueOnce({
-      stdout: "ok",
-      stderr: "",
-      code: 0,
-      signal: null,
-      killed: false,
-    });
+    supervisorSpawnMock.mockResolvedValueOnce(
+      createManagedRun({
+        reason: "exit",
+        exitCode: 0,
+        exitSignal: null,
+        durationMs: 25,
+        stdout: "ok",
+        stderr: "",
+        timedOut: false,
+        noOutputTimedOut: false,
+      }),
+    );
 
     try {
       await runCliAgent({
@@ -114,264 +189,33 @@ describe("runCliAgent resume cleanup", () => {
         provider: "codex-cli",
         model: "gpt-5.2-codex",
         timeoutMs: 1_000,
-        runId: "run-1",
+        runId: "run-4",
       });
     } finally {
       await fs.rm(tempDir, { recursive: true, force: true });
     }
 
-    const options = runCommandWithTimeoutMock.mock.calls[0]?.[1] as { cwd?: string };
-    expect(options.cwd).toBe(path.resolve(fallbackWorkspace));
+    const input = supervisorSpawnMock.mock.calls[0]?.[0] as { cwd?: string };
+    expect(input.cwd).toBe(path.resolve(fallbackWorkspace));
   });
+});
 
-  it("throws when sessionKey is malformed", async () => {
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-cli-runner-"));
-    const mainWorkspace = path.join(tempDir, "workspace-main");
-    const researchWorkspace = path.join(tempDir, "workspace-research");
-    await fs.mkdir(mainWorkspace, { recursive: true });
-    await fs.mkdir(researchWorkspace, { recursive: true });
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: mainWorkspace,
+describe("resolveCliNoOutputTimeoutMs", () => {
+  it("uses backend-configured resume watchdog override", () => {
+    const timeoutMs = resolveCliNoOutputTimeoutMs({
+      backend: {
+        command: "codex",
+        reliability: {
+          watchdog: {
+            resume: {
+              noOutputTimeoutMs: 42_000,
+            },
+          },
         },
-        list: [{ id: "research", workspace: researchWorkspace }],
       },
-    } satisfies OpenClawConfig;
-
-    try {
-      await expect(
-        runCliAgent({
-          sessionId: "s1",
-          sessionKey: "agent::broken",
-          agentId: "research",
-          sessionFile: "/tmp/session.jsonl",
-          workspaceDir: undefined as unknown as string,
-          config: cfg,
-          prompt: "hi",
-          provider: "codex-cli",
-          model: "gpt-5.2-codex",
-          timeoutMs: 1_000,
-          runId: "run-2",
-        }),
-      ).rejects.toThrow("Malformed agent session key");
-    } finally {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    }
-    expect(runCommandWithTimeoutMock).not.toHaveBeenCalled();
-  });
-});
-
-describe("cleanupSuspendedCliProcesses", () => {
-  beforeEach(() => {
-    runExecMock.mockReset();
-  });
-
-  it("skips when no session tokens are configured", async () => {
-    await cleanupSuspendedCliProcesses(
-      {
-        command: "tool",
-      } as CliBackendConfig,
-      0,
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    expect(runExecMock).not.toHaveBeenCalled();
-  });
-
-  it("matches sessionArg-based commands", async () => {
-    const selfPid = process.pid;
-    runExecMock
-      .mockResolvedValueOnce({
-        stdout: [
-          `  40 ${selfPid} T+ claude --session-id thread-1 -p`,
-          `  41 ${selfPid} S  claude --session-id thread-2 -p`,
-        ].join("\n"),
-        stderr: "",
-      })
-      .mockResolvedValueOnce({ stdout: "", stderr: "" });
-
-    await cleanupSuspendedCliProcesses(
-      {
-        command: "claude",
-        sessionArg: "--session-id",
-      } as CliBackendConfig,
-      0,
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    expect(runExecMock).toHaveBeenCalledTimes(2);
-    const killCall = runExecMock.mock.calls[1] ?? [];
-    expect(killCall[0]).toBe("kill");
-    expect(killCall[1]).toEqual(["-9", "40"]);
-  });
-
-  it("matches resumeArgs with positional session id", async () => {
-    const selfPid = process.pid;
-    runExecMock
-      .mockResolvedValueOnce({
-        stdout: [
-          `  50 ${selfPid} T  codex exec resume thread-99 --color never --sandbox read-only`,
-          `  51 ${selfPid} T  codex exec resume other --color never --sandbox read-only`,
-        ].join("\n"),
-        stderr: "",
-      })
-      .mockResolvedValueOnce({ stdout: "", stderr: "" });
-
-    await cleanupSuspendedCliProcesses(
-      {
-        command: "codex",
-        resumeArgs: ["exec", "resume", "{sessionId}", "--color", "never", "--sandbox", "read-only"],
-      } as CliBackendConfig,
-      1,
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    expect(runExecMock).toHaveBeenCalledTimes(2);
-    const killCall = runExecMock.mock.calls[1] ?? [];
-    expect(killCall[0]).toBe("kill");
-    expect(killCall[1]).toEqual(["-9", "50", "51"]);
-  });
-
-  it("only kills child processes of current process (ppid validation)", async () => {
-    const selfPid = process.pid;
-    const childPid = selfPid + 1;
-    const unrelatedPid = 9999;
-
-    runExecMock
-      .mockResolvedValueOnce({
-        stdout: [
-          `  ${childPid} ${selfPid} T  claude --session-id thread-1 -p`,
-          `  ${unrelatedPid} 100 T  claude --session-id thread-2 -p`,
-        ].join("\n"),
-        stderr: "",
-      })
-      .mockResolvedValueOnce({ stdout: "", stderr: "" });
-
-    await cleanupSuspendedCliProcesses(
-      {
-        command: "claude",
-        sessionArg: "--session-id",
-      } as CliBackendConfig,
-      0,
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    expect(runExecMock).toHaveBeenCalledTimes(2);
-    const killCall = runExecMock.mock.calls[1] ?? [];
-    expect(killCall[0]).toBe("kill");
-    // Only childPid killed; unrelatedPid (ppid=100) excluded
-    expect(killCall[1]).toEqual(["-9", String(childPid)]);
-  });
-
-  it("skips all processes when none are children of current process", async () => {
-    runExecMock.mockResolvedValueOnce({
-      stdout: [
-        "  200 100 T  claude --session-id thread-1 -p",
-        "  201 100 T  claude --session-id thread-2 -p",
-      ].join("\n"),
-      stderr: "",
+      timeoutMs: 120_000,
+      useResume: true,
     });
-
-    await cleanupSuspendedCliProcesses(
-      {
-        command: "claude",
-        sessionArg: "--session-id",
-      } as CliBackendConfig,
-      0,
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    // Only ps called — no kill because no matching ppid
-    expect(runExecMock).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("cleanupResumeProcesses", () => {
-  beforeEach(() => {
-    runExecMock.mockReset();
-  });
-
-  it("only kills resume processes owned by current process", async () => {
-    const selfPid = process.pid;
-
-    runExecMock
-      .mockResolvedValueOnce({
-        stdout: [
-          `  ${selfPid + 1} ${selfPid} codex exec resume abc-123`,
-          `  ${selfPid + 2} 999 codex exec resume abc-123`,
-        ].join("\n"),
-        stderr: "",
-      })
-      .mockResolvedValueOnce({ stdout: "", stderr: "" })
-      .mockResolvedValueOnce({ stdout: "", stderr: "" });
-
-    await cleanupResumeProcesses(
-      {
-        command: "codex",
-        resumeArgs: ["exec", "resume", "{sessionId}"],
-      } as CliBackendConfig,
-      "abc-123",
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    expect(runExecMock).toHaveBeenCalledTimes(3);
-
-    const termCall = runExecMock.mock.calls[1] ?? [];
-    expect(termCall[0]).toBe("kill");
-    expect(termCall[1]).toEqual(["-TERM", String(selfPid + 1)]);
-
-    const killCall = runExecMock.mock.calls[2] ?? [];
-    expect(killCall[0]).toBe("kill");
-    expect(killCall[1]).toEqual(["-9", String(selfPid + 1)]);
-  });
-
-  it("skips kill when no resume processes match ppid", async () => {
-    runExecMock.mockResolvedValueOnce({
-      stdout: ["  300 100 codex exec resume abc-123", "  301 200 codex exec resume abc-123"].join(
-        "\n",
-      ),
-      stderr: "",
-    });
-
-    await cleanupResumeProcesses(
-      {
-        command: "codex",
-        resumeArgs: ["exec", "resume", "{sessionId}"],
-      } as CliBackendConfig,
-      "abc-123",
-    );
-
-    if (process.platform === "win32") {
-      expect(runExecMock).not.toHaveBeenCalled();
-      return;
-    }
-
-    // Only ps called — no kill because no matching ppid
-    expect(runExecMock).toHaveBeenCalledTimes(1);
+    expect(timeoutMs).toBe(42_000);
   });
 });
diff --git a/src/agents/cli-runner.ts b/src/agents/cli-runner.ts
index 68dbf0d5c22..5160611e8e5 100644
--- a/src/agents/cli-runner.ts
+++ b/src/agents/cli-runner.ts
@@ -6,20 +6,20 @@ import { resolveHeartbeatPrompt } from "../auto-reply/heartbeat.js";
 import { shouldLogVerbose } from "../globals.js";
 import { isTruthyEnvValue } from "../infra/env.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
-import { runCommandWithTimeout } from "../process/exec.js";
+import { getProcessSupervisor } from "../process/supervisor/index.js";
 import { resolveSessionAgentIds } from "./agent-scope.js";
 import { makeBootstrapWarn, resolveBootstrapContextForRun } from "./bootstrap-files.js";
 import { resolveCliBackendConfig } from "./cli-backends.js";
 import {
   appendImagePathsToPrompt,
+  buildCliSupervisorScopeKey,
   buildCliArgs,
   buildSystemPrompt,
-  cleanupResumeProcesses,
-  cleanupSuspendedCliProcesses,
   enqueueCliRun,
   normalizeCliModel,
   parseCliJson,
   parseCliJsonl,
+  resolveCliNoOutputTimeoutMs,
   resolvePromptInput,
   resolveSessionIdToSend,
   resolveSystemPromptUsage,
@@ -226,19 +226,32 @@ export async function runCliAgent(params: {
         }
         return next;
       })();
-
-      // Cleanup suspended processes that have accumulated (regardless of sessionId)
-      await cleanupSuspendedCliProcesses(backend);
-      if (useResume && cliSessionIdToSend) {
-        await cleanupResumeProcesses(backend, cliSessionIdToSend);
-      }
-
-      const result = await runCommandWithTimeout([backend.command, ...args], {
+      const noOutputTimeoutMs = resolveCliNoOutputTimeoutMs({
+        backend,
         timeoutMs: params.timeoutMs,
+        useResume,
+      });
+      const supervisor = getProcessSupervisor();
+      const scopeKey = buildCliSupervisorScopeKey({
+        backend,
+        backendId: backendResolved.id,
+        cliSessionId: useResume ? cliSessionIdToSend : undefined,
+      });
+
+      const managedRun = await supervisor.spawn({
+        sessionId: params.sessionId,
+        backendId: backendResolved.id,
+        scopeKey,
+        replaceExistingScope: Boolean(useResume && scopeKey),
+        mode: "child",
+        argv: [backend.command, ...args],
+        timeoutMs: params.timeoutMs,
+        noOutputTimeoutMs,
         cwd: workspaceDir,
         env,
         input: stdinPayload,
       });
+      const result = await managedRun.wait();
 
       const stdout = result.stdout.trim();
       const stderr = result.stderr.trim();
@@ -259,7 +272,28 @@ export async function runCliAgent(params: {
         }
       }
 
-      if (result.code !== 0) {
+      if (result.exitCode !== 0 || result.reason !== "exit") {
+        if (result.reason === "no-output-timeout" || result.noOutputTimedOut) {
+          const timeoutReason = `CLI produced no output for ${Math.round(noOutputTimeoutMs / 1000)}s and was terminated.`;
+          log.warn(
+            `cli watchdog timeout: provider=${params.provider} model=${modelId} session=${cliSessionIdToSend ?? params.sessionId} noOutputTimeoutMs=${noOutputTimeoutMs} pid=${managedRun.pid ?? "unknown"}`,
+          );
+          throw new FailoverError(timeoutReason, {
+            reason: "timeout",
+            provider: params.provider,
+            model: modelId,
+            status: resolveFailoverStatus("timeout"),
+          });
+        }
+        if (result.reason === "overall-timeout") {
+          const timeoutReason = `CLI exceeded timeout (${Math.round(params.timeoutMs / 1000)}s) and was terminated.`;
+          throw new FailoverError(timeoutReason, {
+            reason: "timeout",
+            provider: params.provider,
+            model: modelId,
+            status: resolveFailoverStatus("timeout"),
+          });
+        }
         const err = stderr || stdout || "CLI failed.";
         const reason = classifyFailoverReason(err) ?? "unknown";
         const status = resolveFailoverStatus(reason);
diff --git a/src/agents/cli-runner/helpers.ts b/src/agents/cli-runner/helpers.ts
index 572c3c1dea7..f11c3d0aa76 100644
--- a/src/agents/cli-runner/helpers.ts
+++ b/src/agents/cli-runner/helpers.ts
@@ -8,232 +8,27 @@ import type { ThinkLevel } from "../../auto-reply/thinking.js";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { CliBackendConfig } from "../../config/types.js";
 import type { EmbeddedContextFile } from "../pi-embedded-helpers.js";
-import { runExec } from "../../process/exec.js";
 import { buildTtsSystemPromptHint } from "../../tts/tts.js";
-import { escapeRegExp, isRecord } from "../../utils.js";
+import { isRecord } from "../../utils.js";
 import { buildModelAliasLines } from "../model-alias-lines.js";
 import { resolveDefaultModelForAgent } from "../model-selection.js";
 import { detectRuntimeShell } from "../shell-utils.js";
 import { buildSystemPromptParams } from "../system-prompt-params.js";
 import { buildAgentSystemPrompt } from "../system-prompt.js";
+export { buildCliSupervisorScopeKey, resolveCliNoOutputTimeoutMs } from "./reliability.js";
 
 const CLI_RUN_QUEUE = new Map<string, Promise<unknown>>();
-
-function buildLooseArgOrderRegex(tokens: string[]): RegExp {
-  // Scan `ps` output lines. Keep matching flexible, but require whitespace arg boundaries
-  // to avoid substring matches like `codexx` or `/path/to/codexx`.
-  const [head, ...rest] = tokens.map((t) => String(t ?? "").trim()).filter(Boolean);
-  if (!head) {
-    return /$^/;
-  }
-
-  const headEscaped = escapeRegExp(head);
-  const headFragment = `(?:^|\\s)(?:${headEscaped}|\\S+\\/${headEscaped})(?=\\s|$)`;
-  const restFragments = rest.map((t) => `(?:^|\\s)${escapeRegExp(t)}(?=\\s|$)`);
-  return new RegExp([headFragment, ...restFragments].join(".*"));
-}
-
-async function psWithFallback(argsA: string[], argsB: string[]): Promise<string> {
-  try {
-    const { stdout } = await runExec("ps", argsA);
-    return stdout;
-  } catch {
-    // fallthrough
-  }
-  const { stdout } = await runExec("ps", argsB);
-  return stdout;
-}
-
-export async function cleanupResumeProcesses(
-  backend: CliBackendConfig,
-  sessionId: string,
-): Promise<void> {
-  if (process.platform === "win32") {
-    return;
-  }
-  const resumeArgs = backend.resumeArgs ?? [];
-  if (resumeArgs.length === 0) {
-    return;
-  }
-  if (!resumeArgs.some((arg) => arg.includes("{sessionId}"))) {
-    return;
-  }
-  const commandToken = path.basename(backend.command ?? "").trim();
-  if (!commandToken) {
-    return;
-  }
-
-  const resumeTokens = resumeArgs.map((arg) => arg.replaceAll("{sessionId}", sessionId));
-  const pattern = [commandToken, ...resumeTokens]
-    .filter(Boolean)
-    .map((token) => escapeRegExp(token))
-    .join(".*");
-  if (!pattern) {
-    return;
-  }
-
-  try {
-    const stdout = await psWithFallback(
-      ["-axww", "-o", "pid=,ppid=,command="],
-      ["-ax", "-o", "pid=,ppid=,command="],
-    );
-    const patternRegex = buildLooseArgOrderRegex([commandToken, ...resumeTokens]);
-    const toKill: number[] = [];
-
-    for (const line of stdout.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) {
-        continue;
-      }
-      const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(trimmed);
-      if (!match) {
-        continue;
-      }
-      const pid = Number(match[1]);
-      const ppid = Number(match[2]);
-      const cmd = match[3] ?? "";
-      if (!Number.isFinite(pid)) {
-        continue;
-      }
-      if (ppid !== process.pid) {
-        continue;
-      }
-      if (!patternRegex.test(cmd)) {
-        continue;
-      }
-      toKill.push(pid);
-    }
-
-    if (toKill.length > 0) {
-      const pidArgs = toKill.map((pid) => String(pid));
-      try {
-        await runExec("kill", ["-TERM", ...pidArgs]);
-      } catch {
-        // ignore
-      }
-      await new Promise((resolve) => setTimeout(resolve, 250));
-      try {
-        await runExec("kill", ["-9", ...pidArgs]);
-      } catch {
-        // ignore
-      }
-    }
-  } catch {
-    // ignore errors - best effort cleanup
-  }
-}
-
-function buildSessionMatchers(backend: CliBackendConfig): RegExp[] {
-  const commandToken = path.basename(backend.command ?? "").trim();
-  if (!commandToken) {
-    return [];
-  }
-  const matchers: RegExp[] = [];
-  const sessionArg = backend.sessionArg?.trim();
-  const sessionArgs = backend.sessionArgs ?? [];
-  const resumeArgs = backend.resumeArgs ?? [];
-
-  const addMatcher = (args: string[]) => {
-    if (args.length === 0) {
-      return;
-    }
-    const tokens = [commandToken, ...args];
-    const pattern = tokens
-      .map((token, index) => {
-        const tokenPattern = tokenToRegex(token);
-        return index === 0 ? `(?:^|\\s)${tokenPattern}` : `\\s+${tokenPattern}`;
-      })
-      .join("");
-    matchers.push(new RegExp(pattern));
-  };
-
-  if (sessionArgs.some((arg) => arg.includes("{sessionId}"))) {
-    addMatcher(sessionArgs);
-  } else if (sessionArg) {
-    addMatcher([sessionArg, "{sessionId}"]);
-  }
-
-  if (resumeArgs.some((arg) => arg.includes("{sessionId}"))) {
-    addMatcher(resumeArgs);
-  }
-
-  return matchers;
-}
-
-function tokenToRegex(token: string): string {
-  if (!token.includes("{sessionId}")) {
-    return escapeRegExp(token);
-  }
-  const parts = token.split("{sessionId}").map((part) => escapeRegExp(part));
-  return parts.join("\\S+");
-}
-
-/**
- * Cleanup suspended OpenClaw CLI processes that have accumulated.
- * Only cleans up if there are more than the threshold (default: 10).
- */
-export async function cleanupSuspendedCliProcesses(
-  backend: CliBackendConfig,
-  threshold = 10,
-): Promise<void> {
-  if (process.platform === "win32") {
-    return;
-  }
-  const matchers = buildSessionMatchers(backend);
-  if (matchers.length === 0) {
-    return;
-  }
-
-  try {
-    const stdout = await psWithFallback(
-      ["-axww", "-o", "pid=,ppid=,stat=,command="],
-      ["-ax", "-o", "pid=,ppid=,stat=,command="],
-    );
-    const suspended: number[] = [];
-    for (const line of stdout.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) {
-        continue;
-      }
-      const match = /^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(trimmed);
-      if (!match) {
-        continue;
-      }
-      const pid = Number(match[1]);
-      const ppid = Number(match[2]);
-      const stat = match[3] ?? "";
-      const command = match[4] ?? "";
-      if (!Number.isFinite(pid)) {
-        continue;
-      }
-      if (ppid !== process.pid) {
-        continue;
-      }
-      if (!stat.includes("T")) {
-        continue;
-      }
-      if (!matchers.some((matcher) => matcher.test(command))) {
-        continue;
-      }
-      suspended.push(pid);
-    }
-
-    if (suspended.length > threshold) {
-      // Verified locally: stopped (T) processes ignore SIGTERM, so use SIGKILL.
-      await runExec("kill", ["-9", ...suspended.map((pid) => String(pid))]);
-    }
-  } catch {
-    // ignore errors - best effort cleanup
-  }
-}
 export function enqueueCliRun<T>(key: string, task: () => Promise<T>): Promise<T> {
   const prior = CLI_RUN_QUEUE.get(key) ?? Promise.resolve();
   const chained = prior.catch(() => undefined).then(task);
-  const tracked = chained.finally(() => {
-    if (CLI_RUN_QUEUE.get(key) === tracked) {
-      CLI_RUN_QUEUE.delete(key);
-    }
-  });
+  // Keep queue continuity even when a run rejects, without emitting unhandled rejections.
+  const tracked = chained
+    .catch(() => undefined)
+    .finally(() => {
+      if (CLI_RUN_QUEUE.get(key) === tracked) {
+        CLI_RUN_QUEUE.delete(key);
+      }
+    });
   CLI_RUN_QUEUE.set(key, tracked);
   return chained;
 }
diff --git a/src/agents/cli-runner/reliability.ts b/src/agents/cli-runner/reliability.ts
new file mode 100644
index 00000000000..cd1fefa9378
--- /dev/null
+++ b/src/agents/cli-runner/reliability.ts
@@ -0,0 +1,88 @@
+import path from "node:path";
+import type { CliBackendConfig } from "../../config/types.js";
+import {
+  CLI_FRESH_WATCHDOG_DEFAULTS,
+  CLI_RESUME_WATCHDOG_DEFAULTS,
+  CLI_WATCHDOG_MIN_TIMEOUT_MS,
+} from "../cli-watchdog-defaults.js";
+
+function pickWatchdogProfile(
+  backend: CliBackendConfig,
+  useResume: boolean,
+): {
+  noOutputTimeoutMs?: number;
+  noOutputTimeoutRatio: number;
+  minMs: number;
+  maxMs: number;
+} {
+  const defaults = useResume ? CLI_RESUME_WATCHDOG_DEFAULTS : CLI_FRESH_WATCHDOG_DEFAULTS;
+  const configured = useResume
+    ? backend.reliability?.watchdog?.resume
+    : backend.reliability?.watchdog?.fresh;
+
+  const ratio = (() => {
+    const value = configured?.noOutputTimeoutRatio;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      return defaults.noOutputTimeoutRatio;
+    }
+    return Math.max(0.05, Math.min(0.95, value));
+  })();
+  const minMs = (() => {
+    const value = configured?.minMs;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      return defaults.minMs;
+    }
+    return Math.max(CLI_WATCHDOG_MIN_TIMEOUT_MS, Math.floor(value));
+  })();
+  const maxMs = (() => {
+    const value = configured?.maxMs;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      return defaults.maxMs;
+    }
+    return Math.max(CLI_WATCHDOG_MIN_TIMEOUT_MS, Math.floor(value));
+  })();
+
+  return {
+    noOutputTimeoutMs:
+      typeof configured?.noOutputTimeoutMs === "number" &&
+      Number.isFinite(configured.noOutputTimeoutMs)
+        ? Math.max(CLI_WATCHDOG_MIN_TIMEOUT_MS, Math.floor(configured.noOutputTimeoutMs))
+        : undefined,
+    noOutputTimeoutRatio: ratio,
+    minMs: Math.min(minMs, maxMs),
+    maxMs: Math.max(minMs, maxMs),
+  };
+}
+
+export function resolveCliNoOutputTimeoutMs(params: {
+  backend: CliBackendConfig;
+  timeoutMs: number;
+  useResume: boolean;
+}): number {
+  const profile = pickWatchdogProfile(params.backend, params.useResume);
+  // Keep watchdog below global timeout in normal cases.
+  const cap = Math.max(CLI_WATCHDOG_MIN_TIMEOUT_MS, params.timeoutMs - 1_000);
+  if (profile.noOutputTimeoutMs !== undefined) {
+    return Math.min(profile.noOutputTimeoutMs, cap);
+  }
+  const computed = Math.floor(params.timeoutMs * profile.noOutputTimeoutRatio);
+  const bounded = Math.min(profile.maxMs, Math.max(profile.minMs, computed));
+  return Math.min(bounded, cap);
+}
+
+export function buildCliSupervisorScopeKey(params: {
+  backend: CliBackendConfig;
+  backendId: string;
+  cliSessionId?: string;
+}): string | undefined {
+  const commandToken = path
+    .basename(params.backend.command ?? "")
+    .trim()
+    .toLowerCase();
+  const backendToken = params.backendId.trim().toLowerCase();
+  const sessionToken = params.cliSessionId?.trim();
+  if (!sessionToken) {
+    return undefined;
+  }
+  return `cli:${backendToken}:${commandToken}:${sessionToken}`;
+}
diff --git a/src/agents/cli-watchdog-defaults.ts b/src/agents/cli-watchdog-defaults.ts
new file mode 100644
index 00000000000..c96f87e30b0
--- /dev/null
+++ b/src/agents/cli-watchdog-defaults.ts
@@ -0,0 +1,13 @@
+export const CLI_WATCHDOG_MIN_TIMEOUT_MS = 1_000;
+
+export const CLI_FRESH_WATCHDOG_DEFAULTS = {
+  noOutputTimeoutRatio: 0.8,
+  minMs: 180_000,
+  maxMs: 600_000,
+} as const;
+
+export const CLI_RESUME_WATCHDOG_DEFAULTS = {
+  noOutputTimeoutRatio: 0.3,
+  minMs: 60_000,
+  maxMs: 180_000,
+} as const;
diff --git a/src/agents/context.test.ts b/src/agents/context.test.ts
new file mode 100644
index 00000000000..34354fc85cd
--- /dev/null
+++ b/src/agents/context.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { applyConfiguredContextWindows, applyDiscoveredContextWindows } from "./context.js";
+import { createSessionManagerRuntimeRegistry } from "./pi-extensions/session-manager-runtime-registry.js";
+
+describe("applyDiscoveredContextWindows", () => {
+  it("keeps the smallest context window when duplicate model ids are discovered", () => {
+    const cache = new Map<string, number>();
+    applyDiscoveredContextWindows({
+      cache,
+      models: [
+        { id: "claude-sonnet-4-5", contextWindow: 1_000_000 },
+        { id: "claude-sonnet-4-5", contextWindow: 200_000 },
+      ],
+    });
+
+    expect(cache.get("claude-sonnet-4-5")).toBe(200_000);
+  });
+});
+
+describe("applyConfiguredContextWindows", () => {
+  it("overrides discovered cache values with explicit models.providers contextWindow", () => {
+    const cache = new Map<string, number>([["anthropic/claude-opus-4-6", 1_000_000]]);
+    applyConfiguredContextWindows({
+      cache,
+      modelsConfig: {
+        providers: {
+          openrouter: {
+            models: [{ id: "anthropic/claude-opus-4-6", contextWindow: 200_000 }],
+          },
+        },
+      },
+    });
+
+    expect(cache.get("anthropic/claude-opus-4-6")).toBe(200_000);
+  });
+
+  it("adds config-only model context windows and ignores invalid entries", () => {
+    const cache = new Map<string, number>();
+    applyConfiguredContextWindows({
+      cache,
+      modelsConfig: {
+        providers: {
+          openrouter: {
+            models: [
+              { id: "custom/model", contextWindow: 150_000 },
+              { id: "bad/model", contextWindow: 0 },
+              { id: "", contextWindow: 300_000 },
+            ],
+          },
+        },
+      },
+    });
+
+    expect(cache.get("custom/model")).toBe(150_000);
+    expect(cache.has("bad/model")).toBe(false);
+  });
+});
+
+describe("createSessionManagerRuntimeRegistry", () => {
+  it("stores, reads, and clears values by object identity", () => {
+    const registry = createSessionManagerRuntimeRegistry<{ value: number }>();
+    const key = {};
+    expect(registry.get(key)).toBeNull();
+    registry.set(key, { value: 1 });
+    expect(registry.get(key)).toEqual({ value: 1 });
+    registry.set(key, null);
+    expect(registry.get(key)).toBeNull();
+  });
+
+  it("ignores non-object keys", () => {
+    const registry = createSessionManagerRuntimeRegistry<{ value: number }>();
+    registry.set(null, { value: 1 });
+    registry.set(123, { value: 1 });
+    expect(registry.get(null)).toBeNull();
+    expect(registry.get(123)).toBeNull();
+  });
+});
diff --git a/src/agents/context.ts b/src/agents/context.ts
index b3683e235f2..ddfeb512e48 100644
--- a/src/agents/context.ts
+++ b/src/agents/context.ts
@@ -6,29 +6,100 @@ import { resolveOpenClawAgentDir } from "./agent-paths.js";
 import { ensureOpenClawModelsJson } from "./models-config.js";
 
 type ModelEntry = { id: string; contextWindow?: number };
+type ModelRegistryLike = {
+  getAvailable?: () => ModelEntry[];
+  getAll: () => ModelEntry[];
+};
+type ConfigModelEntry = { id?: string; contextWindow?: number };
+type ProviderConfigEntry = { models?: ConfigModelEntry[] };
+type ModelsConfig = { providers?: Record<string, ProviderConfigEntry | undefined> };
+
+export function applyDiscoveredContextWindows(params: {
+  cache: Map<string, number>;
+  models: ModelEntry[];
+}) {
+  for (const model of params.models) {
+    if (!model?.id) {
+      continue;
+    }
+    const contextWindow =
+      typeof model.contextWindow === "number" ? Math.trunc(model.contextWindow) : undefined;
+    if (!contextWindow || contextWindow <= 0) {
+      continue;
+    }
+    const existing = params.cache.get(model.id);
+    // When multiple providers expose the same model id with different limits,
+    // prefer the smaller window so token budgeting is fail-safe (no overestimation).
+    if (existing === undefined || contextWindow < existing) {
+      params.cache.set(model.id, contextWindow);
+    }
+  }
+}
+
+export function applyConfiguredContextWindows(params: {
+  cache: Map<string, number>;
+  modelsConfig: ModelsConfig | undefined;
+}) {
+  const providers = params.modelsConfig?.providers;
+  if (!providers || typeof providers !== "object") {
+    return;
+  }
+  for (const provider of Object.values(providers)) {
+    if (!Array.isArray(provider?.models)) {
+      continue;
+    }
+    for (const model of provider.models) {
+      const modelId = typeof model?.id === "string" ? model.id : undefined;
+      const contextWindow =
+        typeof model?.contextWindow === "number" ? model.contextWindow : undefined;
+      if (!modelId || !contextWindow || contextWindow <= 0) {
+        continue;
+      }
+      params.cache.set(modelId, contextWindow);
+    }
+  }
+}
 
 const MODEL_CACHE = new Map<string, number>();
 const loadPromise = (async () => {
+  let cfg: ReturnType<typeof loadConfig> | undefined;
+  try {
+    cfg = loadConfig();
+  } catch {
+    // If config can't be loaded, leave cache empty.
+    return;
+  }
+
+  try {
+    await ensureOpenClawModelsJson(cfg);
+  } catch {
+    // Continue with best-effort discovery/overrides.
+  }
+
   try {
     const { discoverAuthStorage, discoverModels } = await import("./pi-model-discovery.js");
-    const cfg = loadConfig();
-    await ensureOpenClawModelsJson(cfg);
     const agentDir = resolveOpenClawAgentDir();
     const authStorage = discoverAuthStorage(agentDir);
-    const modelRegistry = discoverModels(authStorage, agentDir);
-    const models = modelRegistry.getAll() as ModelEntry[];
-    for (const m of models) {
-      if (!m?.id) {
-        continue;
-      }
-      if (typeof m.contextWindow === "number" && m.contextWindow > 0) {
-        MODEL_CACHE.set(m.id, m.contextWindow);
-      }
-    }
+    const modelRegistry = discoverModels(authStorage, agentDir) as unknown as ModelRegistryLike;
+    const models =
+      typeof modelRegistry.getAvailable === "function"
+        ? modelRegistry.getAvailable()
+        : modelRegistry.getAll();
+    applyDiscoveredContextWindows({
+      cache: MODEL_CACHE,
+      models,
+    });
   } catch {
-    // If pi-ai isn't available, leave cache empty; lookup will fall back.
+    // If model discovery fails, continue with config overrides only.
   }
-})();
+
+  applyConfiguredContextWindows({
+    cache: MODEL_CACHE,
+    modelsConfig: cfg.models as ModelsConfig | undefined,
+  });
+})().catch(() => {
+  // Keep lookup best-effort.
+});
 
 export function lookupContextTokens(modelId?: string): number | undefined {
   if (!modelId) {
diff --git a/src/agents/identity.test.ts b/src/agents/identity.test.ts
new file mode 100644
index 00000000000..7ff865fe148
--- /dev/null
+++ b/src/agents/identity.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import { resolveAckReaction } from "./identity.js";
+
+describe("resolveAckReaction", () => {
+  it("prefers account-level overrides", () => {
+    const cfg: OpenClawConfig = {
+      messages: { ackReaction: "👀" },
+      agents: { list: [{ id: "main", identity: { emoji: "✅" } }] },
+      channels: {
+        slack: {
+          ackReaction: "eyes",
+          accounts: {
+            acct1: { ackReaction: " party_parrot " },
+          },
+        },
+      },
+    };
+
+    expect(resolveAckReaction(cfg, "main", { channel: "slack", accountId: "acct1" })).toBe(
+      "party_parrot",
+    );
+  });
+
+  it("falls back to channel-level overrides", () => {
+    const cfg: OpenClawConfig = {
+      messages: { ackReaction: "👀" },
+      agents: { list: [{ id: "main", identity: { emoji: "✅" } }] },
+      channels: {
+        slack: {
+          ackReaction: "eyes",
+          accounts: {
+            acct1: { ackReaction: "party_parrot" },
+          },
+        },
+      },
+    };
+
+    expect(resolveAckReaction(cfg, "main", { channel: "slack", accountId: "missing" })).toBe(
+      "eyes",
+    );
+  });
+
+  it("uses the global ackReaction when channel overrides are missing", () => {
+    const cfg: OpenClawConfig = {
+      messages: { ackReaction: "✅" },
+      agents: { list: [{ id: "main", identity: { emoji: "😺" } }] },
+    };
+
+    expect(resolveAckReaction(cfg, "main", { channel: "discord" })).toBe("✅");
+  });
+
+  it("falls back to the agent identity emoji when global config is unset", () => {
+    const cfg: OpenClawConfig = {
+      agents: { list: [{ id: "main", identity: { emoji: "🔥" } }] },
+    };
+
+    expect(resolveAckReaction(cfg, "main", { channel: "discord" })).toBe("🔥");
+  });
+
+  it("returns the default emoji when no config is present", () => {
+    const cfg: OpenClawConfig = {};
+
+    expect(resolveAckReaction(cfg, "main")).toBe("👀");
+  });
+
+  it("allows empty strings to disable reactions", () => {
+    const cfg: OpenClawConfig = {
+      messages: { ackReaction: "👀" },
+      channels: {
+        telegram: {
+          ackReaction: "",
+        },
+      },
+    };
+
+    expect(resolveAckReaction(cfg, "main", { channel: "telegram" })).toBe("");
+  });
+});
diff --git a/src/agents/identity.ts b/src/agents/identity.ts
index 1ce3831ad98..ae27c88149e 100644
--- a/src/agents/identity.ts
+++ b/src/agents/identity.ts
@@ -10,11 +10,37 @@ export function resolveAgentIdentity(
   return resolveAgentConfig(cfg, agentId)?.identity;
 }
 
-export function resolveAckReaction(cfg: OpenClawConfig, agentId: string): string {
+export function resolveAckReaction(
+  cfg: OpenClawConfig,
+  agentId: string,
+  opts?: { channel?: string; accountId?: string },
+): string {
+  // L1: Channel account level
+  if (opts?.channel && opts?.accountId) {
+    const channelCfg = getChannelConfig(cfg, opts.channel);
+    const accounts = channelCfg?.accounts as Record<string, Record<string, unknown>> | undefined;
+    const accountReaction = accounts?.[opts.accountId]?.ackReaction as string | undefined;
+    if (accountReaction !== undefined) {
+      return accountReaction.trim();
+    }
+  }
+
+  // L2: Channel level
+  if (opts?.channel) {
+    const channelCfg = getChannelConfig(cfg, opts.channel);
+    const channelReaction = channelCfg?.ackReaction as string | undefined;
+    if (channelReaction !== undefined) {
+      return channelReaction.trim();
+    }
+  }
+
+  // L3: Global messages level
   const configured = cfg.messages?.ackReaction;
   if (configured !== undefined) {
     return configured.trim();
   }
+
+  // L4: Agent identity emoji fallback
   const emoji = resolveAgentIdentity(cfg, agentId)?.emoji?.trim();
   return emoji || DEFAULT_ACK_REACTION;
 }
diff --git a/src/agents/model-auth.e2e.test.ts b/src/agents/model-auth.e2e.test.ts
index 7385f18ee3c..f3439c6feb9 100644
--- a/src/agents/model-auth.e2e.test.ts
+++ b/src/agents/model-auth.e2e.test.ts
@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { ensureAuthProfileStore } from "./auth-profiles.js";
 import { getApiKeyForModel, resolveApiKeyForProvider, resolveEnvApiKey } from "./model-auth.js";
 
@@ -15,9 +16,11 @@ const oauthFixture = {
 
 describe("getApiKeyForModel", () => {
   it("migrates legacy oauth.json into auth-profiles.json", async () => {
-    const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-    const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-    const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+    const envSnapshot = captureEnv([
+      "OPENCLAW_STATE_DIR",
+      "OPENCLAW_AGENT_DIR",
+      "PI_CODING_AGENT_DIR",
+    ]);
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-oauth-"));
 
     try {
@@ -73,30 +76,18 @@ describe("getApiKeyForModel", () => {
         },
       });
     } finally {
-      if (previousStateDir === undefined) {
-        delete process.env.OPENCLAW_STATE_DIR;
-      } else {
-        process.env.OPENCLAW_STATE_DIR = previousStateDir;
-      }
-      if (previousAgentDir === undefined) {
-        delete process.env.OPENCLAW_AGENT_DIR;
-      } else {
-        process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-      }
-      if (previousPiAgentDir === undefined) {
-        delete process.env.PI_CODING_AGENT_DIR;
-      } else {
-        process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-      }
+      envSnapshot.restore();
       await fs.rm(tempDir, { recursive: true, force: true });
     }
   });
 
   it("suggests openai-codex when only Codex OAuth is configured", async () => {
-    const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-    const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-    const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
-    const previousOpenAiKey = process.env.OPENAI_API_KEY;
+    const envSnapshot = captureEnv([
+      "OPENAI_API_KEY",
+      "OPENCLAW_STATE_DIR",
+      "OPENCLAW_AGENT_DIR",
+      "PI_CODING_AGENT_DIR",
+    ]);
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-auth-"));
 
     try {
@@ -137,26 +128,7 @@ describe("getApiKeyForModel", () => {
       }
       expect(String(error)).toContain("openai-codex/gpt-5.3-codex");
     } finally {
-      if (previousOpenAiKey === undefined) {
-        delete process.env.OPENAI_API_KEY;
-      } else {
-        process.env.OPENAI_API_KEY = previousOpenAiKey;
-      }
-      if (previousStateDir === undefined) {
-        delete process.env.OPENCLAW_STATE_DIR;
-      } else {
-        process.env.OPENCLAW_STATE_DIR = previousStateDir;
-      }
-      if (previousAgentDir === undefined) {
-        delete process.env.OPENCLAW_AGENT_DIR;
-      } else {
-        process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-      }
-      if (previousPiAgentDir === undefined) {
-        delete process.env.PI_CODING_AGENT_DIR;
-      } else {
-        process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-      }
+      envSnapshot.restore();
       await fs.rm(tempDir, { recursive: true, force: true });
     }
   });
diff --git a/src/agents/model-scan.e2e.test.ts b/src/agents/model-scan.e2e.test.ts
index 574ad51224a..59f50861ad6 100644
--- a/src/agents/model-scan.e2e.test.ts
+++ b/src/agents/model-scan.e2e.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { scanOpenRouterModels } from "./model-scan.js";
 
 function createFetchFixture(payload: unknown): typeof fetch {
@@ -66,7 +67,7 @@ describe("scanOpenRouterModels", () => {
 
   it("requires an API key when probing", async () => {
     const fetchImpl = createFetchFixture({ data: [] });
-    const previousKey = process.env.OPENROUTER_API_KEY;
+    const envSnapshot = captureEnv(["OPENROUTER_API_KEY"]);
     try {
       delete process.env.OPENROUTER_API_KEY;
       await expect(
@@ -77,11 +78,7 @@ describe("scanOpenRouterModels", () => {
         }),
       ).rejects.toThrow(/Missing OpenRouter API key/);
     } finally {
-      if (previousKey === undefined) {
-        delete process.env.OPENROUTER_API_KEY;
-      } else {
-        process.env.OPENROUTER_API_KEY = previousKey;
-      }
+      envSnapshot.restore();
     }
   });
 });
diff --git a/src/agents/models-config.auto-injects-github-copilot-provider-token-is.e2e.test.ts b/src/agents/models-config.auto-injects-github-copilot-provider-token-is.e2e.test.ts
index 72309c3e5b4..c5e9ac64369 100644
--- a/src/agents/models-config.auto-injects-github-copilot-provider-token-is.e2e.test.ts
+++ b/src/agents/models-config.auto-injects-github-copilot-provider-token-is.e2e.test.ts
@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import {
   installModelsConfigTestHooks,
   withModelsTempHome as withTempHome,
@@ -12,7 +13,7 @@ installModelsConfigTestHooks({ restoreFetch: true });
 describe("models-config", () => {
   it("auto-injects github-copilot provider when token is present", async () => {
     await withTempHome(async (home) => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN"]);
       process.env.COPILOT_GITHUB_TOKEN = "gh-token";
       const fetchMock = vi.fn().mockResolvedValue({
         ok: true,
@@ -36,20 +37,14 @@ describe("models-config", () => {
         expect(parsed.providers["github-copilot"]?.baseUrl).toBe("https://api.copilot.example");
         expect(parsed.providers["github-copilot"]?.models?.length ?? 0).toBe(0);
       } finally {
-        if (previous === undefined) {
-          delete process.env.COPILOT_GITHUB_TOKEN;
-        } else {
-          process.env.COPILOT_GITHUB_TOKEN = previous;
-        }
+        envSnapshot.restore();
       }
     });
   });
 
   it("prefers COPILOT_GITHUB_TOKEN over GH_TOKEN and GITHUB_TOKEN", async () => {
     await withTempHome(async () => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
-      const previousGh = process.env.GH_TOKEN;
-      const previousGithub = process.env.GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]);
       process.env.COPILOT_GITHUB_TOKEN = "copilot-token";
       process.env.GH_TOKEN = "gh-token";
       process.env.GITHUB_TOKEN = "github-token";
@@ -70,9 +65,7 @@ describe("models-config", () => {
         const [, opts] = fetchMock.mock.calls[0] as [string, { headers?: Record<string, string> }];
         expect(opts?.headers?.Authorization).toBe("Bearer copilot-token");
       } finally {
-        process.env.COPILOT_GITHUB_TOKEN = previous;
-        process.env.GH_TOKEN = previousGh;
-        process.env.GITHUB_TOKEN = previousGithub;
+        envSnapshot.restore();
       }
     });
   });
diff --git a/src/agents/models-config.falls-back-default-baseurl-token-exchange-fails.e2e.test.ts b/src/agents/models-config.falls-back-default-baseurl-token-exchange-fails.e2e.test.ts
index ee0e4580de7..8458f492f18 100644
--- a/src/agents/models-config.falls-back-default-baseurl-token-exchange-fails.e2e.test.ts
+++ b/src/agents/models-config.falls-back-default-baseurl-token-exchange-fails.e2e.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { DEFAULT_COPILOT_API_BASE_URL } from "../providers/github-copilot-token.js";
+import { captureEnv } from "../test-utils/env.js";
 import {
   installModelsConfigTestHooks,
   withModelsTempHome as withTempHome,
@@ -13,7 +14,7 @@ installModelsConfigTestHooks({ restoreFetch: true });
 describe("models-config", () => {
   it("falls back to default baseUrl when token exchange fails", async () => {
     await withTempHome(async () => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN"]);
       process.env.COPILOT_GITHUB_TOKEN = "gh-token";
       const fetchMock = vi.fn().mockResolvedValue({
         ok: false,
@@ -33,20 +34,14 @@ describe("models-config", () => {
 
         expect(parsed.providers["github-copilot"]?.baseUrl).toBe(DEFAULT_COPILOT_API_BASE_URL);
       } finally {
-        if (previous === undefined) {
-          delete process.env.COPILOT_GITHUB_TOKEN;
-        } else {
-          process.env.COPILOT_GITHUB_TOKEN = previous;
-        }
+        envSnapshot.restore();
       }
     });
   });
 
   it("uses agentDir override auth profiles for copilot injection", async () => {
     await withTempHome(async (home) => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
-      const previousGh = process.env.GH_TOKEN;
-      const previousGithub = process.env.GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]);
       delete process.env.COPILOT_GITHUB_TOKEN;
       delete process.env.GH_TOKEN;
       delete process.env.GITHUB_TOKEN;
@@ -91,21 +86,7 @@ describe("models-config", () => {
 
         expect(parsed.providers["github-copilot"]?.baseUrl).toBe("https://api.copilot.example");
       } finally {
-        if (previous === undefined) {
-          delete process.env.COPILOT_GITHUB_TOKEN;
-        } else {
-          process.env.COPILOT_GITHUB_TOKEN = previous;
-        }
-        if (previousGh === undefined) {
-          delete process.env.GH_TOKEN;
-        } else {
-          process.env.GH_TOKEN = previousGh;
-        }
-        if (previousGithub === undefined) {
-          delete process.env.GITHUB_TOKEN;
-        } else {
-          process.env.GITHUB_TOKEN = previousGithub;
-        }
+        envSnapshot.restore();
       }
     });
   });
diff --git a/src/agents/models-config.providers.minimax.test.ts b/src/agents/models-config.providers.minimax.test.ts
deleted file mode 100644
index 7832e483bce..00000000000
--- a/src/agents/models-config.providers.minimax.test.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { resolveImplicitProviders } from "./models-config.providers.js";
-
-describe("MiniMax implicit provider (#15275)", () => {
-  it("should use anthropic-messages API for API-key provider", async () => {
-    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    const previous = process.env.MINIMAX_API_KEY;
-    process.env.MINIMAX_API_KEY = "test-key";
-
-    try {
-      const providers = await resolveImplicitProviders({ agentDir });
-      expect(providers?.minimax).toBeDefined();
-      expect(providers?.minimax?.api).toBe("anthropic-messages");
-      expect(providers?.minimax?.baseUrl).toBe("https://api.minimax.io/anthropic");
-    } finally {
-      if (previous === undefined) {
-        delete process.env.MINIMAX_API_KEY;
-      } else {
-        process.env.MINIMAX_API_KEY = previous;
-      }
-    }
-  });
-});
diff --git a/src/agents/models-config.providers.nvidia.test.ts b/src/agents/models-config.providers.nvidia.test.ts
index 42a46ebe4a1..3a2f86e9829 100644
--- a/src/agents/models-config.providers.nvidia.test.ts
+++ b/src/agents/models-config.providers.nvidia.test.ts
@@ -2,13 +2,14 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { resolveApiKeyForProvider } from "./model-auth.js";
 import { buildNvidiaProvider, resolveImplicitProviders } from "./models-config.providers.js";
 
 describe("NVIDIA provider", () => {
   it("should include nvidia when NVIDIA_API_KEY is configured", async () => {
     const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    const previous = process.env.NVIDIA_API_KEY;
+    const envSnapshot = captureEnv(["NVIDIA_API_KEY"]);
     process.env.NVIDIA_API_KEY = "test-key";
 
     try {
@@ -16,17 +17,13 @@ describe("NVIDIA provider", () => {
       expect(providers?.nvidia).toBeDefined();
       expect(providers?.nvidia?.models?.length).toBeGreaterThan(0);
     } finally {
-      if (previous === undefined) {
-        delete process.env.NVIDIA_API_KEY;
-      } else {
-        process.env.NVIDIA_API_KEY = previous;
-      }
+      envSnapshot.restore();
     }
   });
 
   it("resolves the nvidia api key value from env", async () => {
     const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    const previous = process.env.NVIDIA_API_KEY;
+    const envSnapshot = captureEnv(["NVIDIA_API_KEY"]);
     process.env.NVIDIA_API_KEY = "nvidia-test-api-key";
 
     try {
@@ -39,11 +36,7 @@ describe("NVIDIA provider", () => {
       expect(auth.mode).toBe("api-key");
       expect(auth.source).toContain("NVIDIA_API_KEY");
     } finally {
-      if (previous === undefined) {
-        delete process.env.NVIDIA_API_KEY;
-      } else {
-        process.env.NVIDIA_API_KEY = previous;
-      }
+      envSnapshot.restore();
     }
   });
 
@@ -63,3 +56,55 @@ describe("NVIDIA provider", () => {
     expect(modelIds).toContain("nvidia/mistral-nemo-minitron-8b-8k-instruct");
   });
 });
+
+describe("MiniMax implicit provider (#15275)", () => {
+  it("should use anthropic-messages API for API-key provider", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    const envSnapshot = captureEnv(["MINIMAX_API_KEY"]);
+    process.env.MINIMAX_API_KEY = "test-key";
+
+    try {
+      const providers = await resolveImplicitProviders({ agentDir });
+      expect(providers?.minimax).toBeDefined();
+      expect(providers?.minimax?.api).toBe("anthropic-messages");
+      expect(providers?.minimax?.baseUrl).toBe("https://api.minimax.io/anthropic");
+    } finally {
+      envSnapshot.restore();
+    }
+  });
+});
+
+describe("vLLM provider", () => {
+  it("should not include vllm when no API key is configured", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    const envSnapshot = captureEnv(["VLLM_API_KEY"]);
+    delete process.env.VLLM_API_KEY;
+
+    try {
+      const providers = await resolveImplicitProviders({ agentDir });
+      expect(providers?.vllm).toBeUndefined();
+    } finally {
+      envSnapshot.restore();
+    }
+  });
+
+  it("should include vllm when VLLM_API_KEY is set", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
+    const envSnapshot = captureEnv(["VLLM_API_KEY"]);
+    process.env.VLLM_API_KEY = "test-key";
+
+    try {
+      const providers = await resolveImplicitProviders({ agentDir });
+
+      expect(providers?.vllm).toBeDefined();
+      expect(providers?.vllm?.apiKey).toBe("VLLM_API_KEY");
+      expect(providers?.vllm?.baseUrl).toBe("http://127.0.0.1:8000/v1");
+      expect(providers?.vllm?.api).toBe("openai-completions");
+
+      // Note: discovery is disabled in test environments (VITEST check)
+      expect(providers?.vllm?.models).toEqual([]);
+    } finally {
+      envSnapshot.restore();
+    }
+  });
+});
diff --git a/src/agents/models-config.providers.qianfan.e2e.test.ts b/src/agents/models-config.providers.qianfan.e2e.test.ts
index 17527262897..06f47787464 100644
--- a/src/agents/models-config.providers.qianfan.e2e.test.ts
+++ b/src/agents/models-config.providers.qianfan.e2e.test.ts
@@ -2,12 +2,13 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { resolveImplicitProviders } from "./models-config.providers.js";
 
 describe("Qianfan provider", () => {
   it("should include qianfan when QIANFAN_API_KEY is configured", async () => {
     const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    const previous = process.env.QIANFAN_API_KEY;
+    const envSnapshot = captureEnv(["QIANFAN_API_KEY"]);
     process.env.QIANFAN_API_KEY = "test-key";
 
     try {
@@ -15,11 +16,7 @@ describe("Qianfan provider", () => {
       expect(providers?.qianfan).toBeDefined();
       expect(providers?.qianfan?.apiKey).toBe("QIANFAN_API_KEY");
     } finally {
-      if (previous === undefined) {
-        delete process.env.QIANFAN_API_KEY;
-      } else {
-        process.env.QIANFAN_API_KEY = previous;
-      }
+      envSnapshot.restore();
     }
   });
 });
diff --git a/src/agents/models-config.providers.ts b/src/agents/models-config.providers.ts
index 393b333e250..84b0c4303e5 100644
--- a/src/agents/models-config.providers.ts
+++ b/src/agents/models-config.providers.ts
@@ -47,6 +47,33 @@ const MINIMAX_API_COST = {
   cacheWrite: 10,
 };
 
+type ProviderModelConfig = NonNullable<ProviderConfig["models"]>[number];
+
+function buildMinimaxModel(params: {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ProviderModelConfig["input"];
+}): ProviderModelConfig {
+  return {
+    id: params.id,
+    name: params.name,
+    reasoning: params.reasoning,
+    input: params.input,
+    cost: MINIMAX_API_COST,
+    contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
+    maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
+  };
+}
+
+function buildMinimaxTextModel(params: {
+  id: string;
+  name: string;
+  reasoning: boolean;
+}): ProviderModelConfig {
+  return buildMinimaxModel({ ...params, input: ["text"] });
+}
+
 const XIAOMI_BASE_URL = "https://api.xiaomimimo.com/anthropic";
 export const XIAOMI_DEFAULT_MODEL_ID = "mimo-v2-flash";
 const XIAOMI_DEFAULT_CONTEXT_WINDOW = 262144;
@@ -389,51 +416,32 @@ function buildMinimaxProvider(): ProviderConfig {
     baseUrl: MINIMAX_PORTAL_BASE_URL,
     api: "anthropic-messages",
     models: [
-      {
+      buildMinimaxTextModel({
         id: MINIMAX_DEFAULT_MODEL_ID,
         name: "MiniMax M2.1",
         reasoning: false,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
-      {
+      }),
+      buildMinimaxTextModel({
         id: "MiniMax-M2.1-lightning",
         name: "MiniMax M2.1 Lightning",
         reasoning: false,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
-      {
+      }),
+      buildMinimaxModel({
         id: MINIMAX_DEFAULT_VISION_MODEL_ID,
         name: "MiniMax VL 01",
         reasoning: false,
         input: ["text", "image"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
-      {
+      }),
+      buildMinimaxTextModel({
         id: "MiniMax-M2.5",
         name: "MiniMax M2.5",
         reasoning: true,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
-      {
+      }),
+      buildMinimaxTextModel({
         id: "MiniMax-M2.5-Lightning",
         name: "MiniMax M2.5 Lightning",
         reasoning: true,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
+      }),
     ],
   };
 }
@@ -443,24 +451,16 @@ function buildMinimaxPortalProvider(): ProviderConfig {
     baseUrl: MINIMAX_PORTAL_BASE_URL,
     api: "anthropic-messages",
     models: [
-      {
+      buildMinimaxTextModel({
         id: MINIMAX_DEFAULT_MODEL_ID,
         name: "MiniMax M2.1",
         reasoning: false,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
-      {
+      }),
+      buildMinimaxTextModel({
         id: "MiniMax-M2.5",
         name: "MiniMax M2.5",
         reasoning: true,
-        input: ["text"],
-        cost: MINIMAX_API_COST,
-        contextWindow: MINIMAX_DEFAULT_CONTEXT_WINDOW,
-        maxTokens: MINIMAX_DEFAULT_MAX_TOKENS,
-      },
+      }),
     ],
   };
 }
diff --git a/src/agents/models-config.providers.vllm.test.ts b/src/agents/models-config.providers.vllm.test.ts
deleted file mode 100644
index 441b4155ec7..00000000000
--- a/src/agents/models-config.providers.vllm.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { resolveImplicitProviders } from "./models-config.providers.js";
-
-describe("vLLM provider", () => {
-  it("should not include vllm when no API key is configured", async () => {
-    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    const providers = await resolveImplicitProviders({ agentDir });
-
-    expect(providers?.vllm).toBeUndefined();
-  });
-
-  it("should include vllm when VLLM_API_KEY is set", async () => {
-    const agentDir = mkdtempSync(join(tmpdir(), "openclaw-test-"));
-    process.env.VLLM_API_KEY = "test-key";
-
-    try {
-      const providers = await resolveImplicitProviders({ agentDir });
-
-      expect(providers?.vllm).toBeDefined();
-      expect(providers?.vllm?.apiKey).toBe("VLLM_API_KEY");
-      expect(providers?.vllm?.baseUrl).toBe("http://127.0.0.1:8000/v1");
-      expect(providers?.vllm?.api).toBe("openai-completions");
-
-      // Note: discovery is disabled in test environments (VITEST check)
-      expect(providers?.vllm?.models).toEqual([]);
-    } finally {
-      delete process.env.VLLM_API_KEY;
-    }
-  });
-});
diff --git a/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.e2e.test.ts b/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.e2e.test.ts
index b858a234a24..92b5d19dddf 100644
--- a/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.e2e.test.ts
+++ b/src/agents/models-config.uses-first-github-copilot-profile-env-tokens.e2e.test.ts
@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { resolveOpenClawAgentDir } from "./agent-paths.js";
 import {
   installModelsConfigTestHooks,
@@ -13,9 +14,7 @@ installModelsConfigTestHooks({ restoreFetch: true });
 describe("models-config", () => {
   it("uses the first github-copilot profile when env tokens are missing", async () => {
     await withTempHome(async (home) => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
-      const previousGh = process.env.GH_TOKEN;
-      const previousGithub = process.env.GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]);
       delete process.env.COPILOT_GITHUB_TOKEN;
       delete process.env.GH_TOKEN;
       delete process.env.GITHUB_TOKEN;
@@ -61,28 +60,14 @@ describe("models-config", () => {
         const [, opts] = fetchMock.mock.calls[0] as [string, { headers?: Record<string, string> }];
         expect(opts?.headers?.Authorization).toBe("Bearer alpha-token");
       } finally {
-        if (previous === undefined) {
-          delete process.env.COPILOT_GITHUB_TOKEN;
-        } else {
-          process.env.COPILOT_GITHUB_TOKEN = previous;
-        }
-        if (previousGh === undefined) {
-          delete process.env.GH_TOKEN;
-        } else {
-          process.env.GH_TOKEN = previousGh;
-        }
-        if (previousGithub === undefined) {
-          delete process.env.GITHUB_TOKEN;
-        } else {
-          process.env.GITHUB_TOKEN = previousGithub;
-        }
+        envSnapshot.restore();
       }
     });
   });
 
   it("does not override explicit github-copilot provider config", async () => {
     await withTempHome(async () => {
-      const previous = process.env.COPILOT_GITHUB_TOKEN;
+      const envSnapshot = captureEnv(["COPILOT_GITHUB_TOKEN"]);
       process.env.COPILOT_GITHUB_TOKEN = "gh-token";
       const fetchMock = vi.fn().mockResolvedValue({
         ok: true,
@@ -115,11 +100,7 @@ describe("models-config", () => {
 
         expect(parsed.providers["github-copilot"]?.baseUrl).toBe("https://copilot.local");
       } finally {
-        if (previous === undefined) {
-          delete process.env.COPILOT_GITHUB_TOKEN;
-        } else {
-          process.env.COPILOT_GITHUB_TOKEN = previous;
-        }
+        envSnapshot.restore();
       }
     });
   });
diff --git a/src/agents/openai-responses.reasoning-replay.test.ts b/src/agents/openai-responses.reasoning-replay.test.ts
index 2a94db7e3fd..0ef535d92d7 100644
--- a/src/agents/openai-responses.reasoning-replay.test.ts
+++ b/src/agents/openai-responses.reasoning-replay.test.ts
@@ -115,6 +115,15 @@ describe("openai-responses reasoning replay", () => {
     expect(types).toContain("reasoning");
     expect(types).toContain("function_call");
     expect(types.indexOf("reasoning")).toBeLessThan(types.indexOf("function_call"));
+
+    const functionCall = input.find(
+      (item) =>
+        item &&
+        typeof item === "object" &&
+        (item as Record<string, unknown>).type === "function_call",
+    ) as Record<string, unknown> | undefined;
+    expect(functionCall?.call_id).toBe("call_123");
+    expect(functionCall?.id).toBe("fc_123");
   });
 
   it("still replays reasoning when paired with an assistant message", async () => {
diff --git a/src/agents/openclaw-gateway-tool.e2e.test.ts b/src/agents/openclaw-gateway-tool.e2e.test.ts
index 716d7ee0ad2..66dfb9483e9 100644
--- a/src/agents/openclaw-gateway-tool.e2e.test.ts
+++ b/src/agents/openclaw-gateway-tool.e2e.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import "./test-helpers/fast-core-tools.js";
 import { createOpenClawTools } from "./openclaw-tools.js";
 
@@ -18,8 +19,7 @@ describe("gateway tool", () => {
   it("schedules SIGUSR1 restart", async () => {
     vi.useFakeTimers();
     const kill = vi.spyOn(process, "kill").mockImplementation(() => true);
-    const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-    const previousProfile = process.env.OPENCLAW_PROFILE;
+    const envSnapshot = captureEnv(["OPENCLAW_STATE_DIR", "OPENCLAW_PROFILE"]);
     const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-test-"));
     process.env.OPENCLAW_STATE_DIR = stateDir;
     process.env.OPENCLAW_PROFILE = "isolated";
@@ -60,16 +60,8 @@ describe("gateway tool", () => {
     } finally {
       kill.mockRestore();
       vi.useRealTimers();
-      if (previousStateDir === undefined) {
-        delete process.env.OPENCLAW_STATE_DIR;
-      } else {
-        process.env.OPENCLAW_STATE_DIR = previousStateDir;
-      }
-      if (previousProfile === undefined) {
-        delete process.env.OPENCLAW_PROFILE;
-      } else {
-        process.env.OPENCLAW_PROFILE = previousProfile;
-      }
+      envSnapshot.restore();
+      await fs.rm(stateDir, { recursive: true, force: true });
     }
   });
 
diff --git a/src/agents/openclaw-tools.sessions-visibility.e2e.test.ts b/src/agents/openclaw-tools.sessions-visibility.e2e.test.ts
new file mode 100644
index 00000000000..6f4cfdd03b3
--- /dev/null
+++ b/src/agents/openclaw-tools.sessions-visibility.e2e.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from "vitest";
+
+const callGatewayMock = vi.fn();
+vi.mock("../gateway/call.js", () => ({
+  callGateway: (opts: unknown) => callGatewayMock(opts),
+}));
+
+let mockConfig: Record<string, unknown> = {
+  session: { mainKey: "main", scope: "per-sender" },
+};
+vi.mock("../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () => mockConfig,
+    resolveGatewayPort: () => 18789,
+  };
+});
+
+import "./test-helpers/fast-core-tools.js";
+import { createOpenClawTools } from "./openclaw-tools.js";
+
+describe("sessions tools visibility", () => {
+  it("defaults to tree visibility (self + spawned) for sessions_history", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { agentToAgent: { enabled: false } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "sessions.list" && req.params?.spawnedBy === "main") {
+        return { sessions: [{ key: "subagent:child-1" }] };
+      }
+      if (req.method === "sessions.resolve") {
+        const key = typeof req.params?.key === "string" ? String(req.params?.key) : "";
+        return { key };
+      }
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main" }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const denied = await tool.execute("call1", {
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+    expect(denied.details).toMatchObject({ status: "forbidden" });
+
+    const allowed = await tool.execute("call2", { sessionKey: "subagent:child-1" });
+    expect(allowed.details).toMatchObject({
+      sessionKey: "subagent:child-1",
+    });
+  });
+
+  it("allows broader access when tools.sessions.visibility=all", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { sessions: { visibility: "all" }, agentToAgent: { enabled: false } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main" }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const result = await tool.execute("call3", {
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+    expect(result.details).toMatchObject({
+      sessionKey: "agent:main:discord:direct:someone-else",
+    });
+  });
+
+  it("clamps sandboxed sessions to tree when agents.defaults.sandbox.sessionToolsVisibility=spawned", async () => {
+    mockConfig = {
+      session: { mainKey: "main", scope: "per-sender" },
+      tools: { sessions: { visibility: "all" }, agentToAgent: { enabled: true, allow: ["*"] } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "spawned" } } },
+    };
+    callGatewayMock.mockReset();
+    callGatewayMock.mockImplementation(async (opts: unknown) => {
+      const req = opts as { method?: string; params?: Record<string, unknown> };
+      if (req.method === "sessions.list" && req.params?.spawnedBy === "main") {
+        return { sessions: [] };
+      }
+      if (req.method === "chat.history") {
+        return { messages: [{ role: "assistant", content: [{ type: "text", text: "ok" }] }] };
+      }
+      return {};
+    });
+
+    const tool = createOpenClawTools({ agentSessionKey: "main", sandboxed: true }).find(
+      (candidate) => candidate.name === "sessions_history",
+    );
+    expect(tool).toBeDefined();
+    if (!tool) {
+      throw new Error("missing sessions_history tool");
+    }
+
+    const denied = await tool.execute("call4", {
+      sessionKey: "agent:other:main",
+    });
+    expect(denied.details).toMatchObject({ status: "forbidden" });
+  });
+});
diff --git a/src/agents/openclaw-tools.sessions.e2e.test.ts b/src/agents/openclaw-tools.sessions.e2e.test.ts
index df8e1bb7186..14e0ffc1e98 100644
--- a/src/agents/openclaw-tools.sessions.e2e.test.ts
+++ b/src/agents/openclaw-tools.sessions.e2e.test.ts
@@ -20,6 +20,10 @@ vi.mock("../config/config.js", async (importOriginal) => {
         scope: "per-sender",
         agentToAgent: { maxPingPongTurns: 2 },
       },
+      tools: {
+        // Keep sessions tools permissive in this suite; dedicated visibility tests cover defaults.
+        sessions: { visibility: "all" },
+      },
     }),
     resolveGatewayPort: () => 18789,
   };
@@ -783,7 +787,7 @@ describe("sessions tools", () => {
         text?: string;
       };
       expect(details.status).toBe("ok");
-      expect(details.text).toContain("tokens 1k (in 12 / out 1k)");
+      expect(details.text).toMatch(/tokens 1(\.0)?k \(in 12 \/ out 1(\.0)?k\)/);
       expect(details.text).toContain("prompt/cache 197k");
       expect(details.text).not.toContain("1.0k io");
     } finally {
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn-applies-thinking-default.e2e.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn-applies-thinking-default.e2e.test.ts
index c9b7175717a..ecd32cab749 100644
--- a/src/agents/openclaw-tools.subagents.sessions-spawn-applies-thinking-default.e2e.test.ts
+++ b/src/agents/openclaw-tools.subagents.sessions-spawn-applies-thinking-default.e2e.test.ts
@@ -33,21 +33,37 @@ vi.mock("../gateway/call.js", () => {
   };
 });
 
+type GatewayCall = { method: string; params?: Record<string, unknown> };
+
+async function getGatewayCalls(): Promise<GatewayCall[]> {
+  const { callGateway } = await import("../gateway/call.js");
+  return (callGateway as unknown as ReturnType<typeof vi.fn>).mock.calls.map(
+    (call) => call[0] as GatewayCall,
+  );
+}
+
+function findLastCall(calls: GatewayCall[], predicate: (call: GatewayCall) => boolean) {
+  for (let i = calls.length - 1; i >= 0; i -= 1) {
+    const call = calls[i];
+    if (call && predicate(call)) {
+      return call;
+    }
+  }
+  return undefined;
+}
+
 describe("sessions_spawn thinking defaults", () => {
   it("applies agents.defaults.subagents.thinking when thinking is omitted", async () => {
     const tool = createSessionsSpawnTool({ agentSessionKey: "agent:test:main" });
     const result = await tool.execute("call-1", { task: "hello" });
     expect(result.details).toMatchObject({ status: "accepted" });
 
-    const { callGateway } = await import("../gateway/call.js");
-    const calls = (callGateway as unknown as ReturnType<typeof vi.fn>).mock.calls;
-
-    const agentCall = calls
-      .map((call) => call[0] as { method: string; params?: Record<string, unknown> })
-      .findLast((call) => call.method === "agent");
-    const thinkingPatch = calls
-      .map((call) => call[0] as { method: string; params?: Record<string, unknown> })
-      .findLast((call) => call.method === "sessions.patch" && call.params?.thinkingLevel);
+    const calls = await getGatewayCalls();
+    const agentCall = findLastCall(calls, (call) => call.method === "agent");
+    const thinkingPatch = findLastCall(
+      calls,
+      (call) => call.method === "sessions.patch" && call.params?.thinkingLevel !== undefined,
+    );
 
     expect(agentCall?.params?.thinking).toBe("high");
     expect(thinkingPatch?.params?.thinkingLevel).toBe("high");
@@ -58,15 +74,12 @@ describe("sessions_spawn thinking defaults", () => {
     const result = await tool.execute("call-2", { task: "hello", thinking: "low" });
     expect(result.details).toMatchObject({ status: "accepted" });
 
-    const { callGateway } = await import("../gateway/call.js");
-    const calls = (callGateway as unknown as ReturnType<typeof vi.fn>).mock.calls;
-
-    const agentCall = calls
-      .map((call) => call[0] as { method: string; params?: Record<string, unknown> })
-      .findLast((call) => call.method === "agent");
-    const thinkingPatch = calls
-      .map((call) => call[0] as { method: string; params?: Record<string, unknown> })
-      .findLast((call) => call.method === "sessions.patch" && call.params?.thinkingLevel);
+    const calls = await getGatewayCalls();
+    const agentCall = findLastCall(calls, (call) => call.method === "agent");
+    const thinkingPatch = findLastCall(
+      calls,
+      (call) => call.method === "sessions.patch" && call.params?.thinkingLevel !== undefined,
+    );
 
     expect(agentCall?.params?.thinking).toBe("low");
     expect(thinkingPatch?.params?.thinkingLevel).toBe("low");
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.e2e.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.e2e.test.ts
index b1c697064f5..2e568714b71 100644
--- a/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.e2e.test.ts
+++ b/src/agents/openclaw-tools.subagents.sessions-spawn.allowlist.e2e.test.ts
@@ -1,5 +1,4 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { createOpenClawTools } from "./openclaw-tools.js";
 import "./test-helpers/fast-core-tools.js";
 import {
   getCallGatewayMock,
@@ -10,6 +9,19 @@ import { resetSubagentRegistryForTests } from "./subagent-registry.js";
 
 const callGatewayMock = getCallGatewayMock();
 
+type CreateOpenClawTools = (typeof import("./openclaw-tools.js"))["createOpenClawTools"];
+type CreateOpenClawToolsOpts = Parameters<CreateOpenClawTools>[0];
+
+async function getSessionsSpawnTool(opts: CreateOpenClawToolsOpts) {
+  // Dynamic import: ensure harness mocks are installed before tool modules load.
+  const { createOpenClawTools } = await import("./openclaw-tools.js");
+  const tool = createOpenClawTools(opts).find((candidate) => candidate.name === "sessions_spawn");
+  if (!tool) {
+    throw new Error("missing sessions_spawn tool");
+  }
+  return tool;
+}
+
 describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
   beforeEach(() => {
     resetSessionsSpawnConfigOverride();
@@ -19,13 +31,10 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call6", {
       task: "do thing",
@@ -57,13 +66,10 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
       },
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call9", {
       task: "do thing",
@@ -78,7 +84,7 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
   it("sessions_spawn allows cross-agent spawning when configured", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    setConfigOverride({
+    setSessionsSpawnConfigOverride({
       session: {
         mainKey: "main",
         scope: "per-sender",
@@ -109,13 +115,10 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call7", {
       task: "do thing",
@@ -132,7 +135,7 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
   it("sessions_spawn allows any agent when allowlist is *", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    setConfigOverride({
+    setSessionsSpawnConfigOverride({
       session: {
         mainKey: "main",
         scope: "per-sender",
@@ -163,13 +166,10 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call8", {
       task: "do thing",
@@ -186,7 +186,7 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
   it("sessions_spawn normalizes allowlisted agent ids", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    setConfigOverride({
+    setSessionsSpawnConfigOverride({
       session: {
         mainKey: "main",
         scope: "per-sender",
@@ -217,13 +217,10 @@ describe("openclaw-tools: subagents (sessions_spawn allowlist)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call10", {
       task: "do thing",
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.e2e.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.e2e.test.ts
index 002683386be..e82d4e2dc6a 100644
--- a/src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.e2e.test.ts
+++ b/src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.e2e.test.ts
@@ -1,16 +1,140 @@
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { emitAgentEvent } from "../infra/agent-events.js";
-import { sleep } from "../utils.js";
-import { createOpenClawTools } from "./openclaw-tools.js";
 import "./test-helpers/fast-core-tools.js";
+import { sleep } from "../utils.js";
 import {
   getCallGatewayMock,
   resetSessionsSpawnConfigOverride,
 } from "./openclaw-tools.subagents.sessions-spawn.test-harness.js";
 import { resetSubagentRegistryForTests } from "./subagent-registry.js";
 
+vi.mock("./pi-embedded.js", () => ({
+  isEmbeddedPiRunActive: () => false,
+  isEmbeddedPiRunStreaming: () => false,
+  queueEmbeddedPiMessage: () => false,
+  waitForEmbeddedPiRunEnd: async () => true,
+}));
+
 const callGatewayMock = getCallGatewayMock();
 
+type CreateOpenClawTools = (typeof import("./openclaw-tools.js"))["createOpenClawTools"];
+type CreateOpenClawToolsOpts = Parameters<CreateOpenClawTools>[0];
+
+async function getSessionsSpawnTool(opts: CreateOpenClawToolsOpts) {
+  // Dynamic import: ensure harness mocks are installed before tool modules load.
+  const { createOpenClawTools } = await import("./openclaw-tools.js");
+  const tool = createOpenClawTools(opts).find((candidate) => candidate.name === "sessions_spawn");
+  if (!tool) {
+    throw new Error("missing sessions_spawn tool");
+  }
+  return tool;
+}
+
+type GatewayRequest = { method?: string; params?: unknown };
+type AgentWaitCall = { runId?: string; timeoutMs?: number };
+
+function setupSessionsSpawnGatewayMock(opts: {
+  includeSessionsList?: boolean;
+  includeChatHistory?: boolean;
+  onAgentSubagentSpawn?: (params: unknown) => void;
+  onSessionsPatch?: (params: unknown) => void;
+  onSessionsDelete?: (params: unknown) => void;
+  agentWaitResult?: { status: "ok" | "timeout"; startedAt: number; endedAt: number };
+}): {
+  calls: Array<GatewayRequest>;
+  waitCalls: Array<AgentWaitCall>;
+  getChild: () => { runId?: string; sessionKey?: string };
+} {
+  const calls: Array<GatewayRequest> = [];
+  const waitCalls: Array<AgentWaitCall> = [];
+  let agentCallCount = 0;
+  let childRunId: string | undefined;
+  let childSessionKey: string | undefined;
+
+  callGatewayMock.mockImplementation(async (optsUnknown: unknown) => {
+    const request = optsUnknown as GatewayRequest;
+    calls.push(request);
+
+    if (request.method === "sessions.list" && opts.includeSessionsList) {
+      return {
+        sessions: [
+          {
+            key: "main",
+            lastChannel: "whatsapp",
+            lastTo: "+123",
+          },
+        ],
+      };
+    }
+
+    if (request.method === "agent") {
+      agentCallCount += 1;
+      const runId = `run-${agentCallCount}`;
+      const params = request.params as { lane?: string; sessionKey?: string } | undefined;
+      // Only capture the first agent call (subagent spawn, not main agent trigger)
+      if (params?.lane === "subagent") {
+        childRunId = runId;
+        childSessionKey = params?.sessionKey ?? "";
+        opts.onAgentSubagentSpawn?.(params);
+      }
+      return {
+        runId,
+        status: "accepted",
+        acceptedAt: 1000 + agentCallCount,
+      };
+    }
+
+    if (request.method === "agent.wait") {
+      const params = request.params as AgentWaitCall | undefined;
+      waitCalls.push(params ?? {});
+      const res = opts.agentWaitResult ?? { status: "ok", startedAt: 1000, endedAt: 2000 };
+      return {
+        runId: params?.runId ?? "run-1",
+        ...res,
+      };
+    }
+
+    if (request.method === "sessions.patch") {
+      opts.onSessionsPatch?.(request.params);
+      return { ok: true };
+    }
+
+    if (request.method === "sessions.delete") {
+      opts.onSessionsDelete?.(request.params);
+      return { ok: true };
+    }
+
+    if (request.method === "chat.history" && opts.includeChatHistory) {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: [{ type: "text", text: "done" }],
+          },
+        ],
+      };
+    }
+
+    return {};
+  });
+
+  return {
+    calls,
+    waitCalls,
+    getChild: () => ({ runId: childRunId, sessionKey: childSessionKey }),
+  };
+}
+
+const waitFor = async (predicate: () => boolean, timeoutMs = 2000) => {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`timed out waiting for condition (timeoutMs=${timeoutMs})`);
+    }
+    await sleep(10);
+  }
+};
+
 describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
   beforeEach(() => {
     resetSessionsSpawnConfigOverride();
@@ -19,84 +143,21 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
   it("sessions_spawn runs cleanup flow after subagent completion", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    const calls: Array<{ method?: string; params?: unknown }> = [];
-    let agentCallCount = 0;
-    let childRunId: string | undefined;
-    let childSessionKey: string | undefined;
-    const waitCalls: Array<{ runId?: string; timeoutMs?: number }> = [];
-    let patchParams: { key?: string; label?: string } = {};
+    const patchCalls: Array<{ key?: string; label?: string }> = [];
 
-    callGatewayMock.mockImplementation(async (opts: unknown) => {
-      const request = opts as { method?: string; params?: unknown };
-      calls.push(request);
-      if (request.method === "sessions.list") {
-        return {
-          sessions: [
-            {
-              key: "main",
-              lastChannel: "whatsapp",
-              lastTo: "+123",
-            },
-          ],
-        };
-      }
-      if (request.method === "agent") {
-        agentCallCount += 1;
-        const runId = `run-${agentCallCount}`;
-        const params = request.params as {
-          message?: string;
-          sessionKey?: string;
-          lane?: string;
-        };
-        // Only capture the first agent call (subagent spawn, not main agent trigger)
-        if (params?.lane === "subagent") {
-          childRunId = runId;
-          childSessionKey = params?.sessionKey ?? "";
-        }
-        return {
-          runId,
-          status: "accepted",
-          acceptedAt: 2000 + agentCallCount,
-        };
-      }
-      if (request.method === "agent.wait") {
-        const params = request.params as { runId?: string; timeoutMs?: number } | undefined;
-        waitCalls.push(params ?? {});
-        return {
-          runId: params?.runId ?? "run-1",
-          status: "ok",
-          startedAt: 1000,
-          endedAt: 2000,
-        };
-      }
-      if (request.method === "sessions.patch") {
-        const params = request.params as { key?: string; label?: string } | undefined;
-        patchParams = { key: params?.key, label: params?.label };
-        return { ok: true };
-      }
-      if (request.method === "chat.history") {
-        return {
-          messages: [
-            {
-              role: "assistant",
-              content: [{ type: "text", text: "done" }],
-            },
-          ],
-        };
-      }
-      if (request.method === "sessions.delete") {
-        return { ok: true };
-      }
-      return {};
+    const ctx = setupSessionsSpawnGatewayMock({
+      includeSessionsList: true,
+      includeChatHistory: true,
+      onSessionsPatch: (params) => {
+        const rec = params as { key?: string; label?: string } | undefined;
+        patchCalls.push({ key: rec?.key, label: rec?.label });
+      },
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call2", {
       task: "do thing",
@@ -108,11 +169,12 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       runId: "run-1",
     });
 
-    if (!childRunId) {
+    const child = ctx.getChild();
+    if (!child.runId) {
       throw new Error("missing child runId");
     }
     emitAgentEvent({
-      runId: childRunId,
+      runId: child.runId,
       stream: "lifecycle",
       data: {
         phase: "end",
@@ -121,18 +183,19 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       },
     });
 
-    await sleep(0);
-    await sleep(0);
-    await sleep(0);
+    await waitFor(() => ctx.waitCalls.some((call) => call.runId === child.runId));
+    await waitFor(() => patchCalls.some((call) => call.label === "my-task"));
+    await waitFor(() => ctx.calls.filter((c) => c.method === "agent").length >= 2);
 
-    const childWait = waitCalls.find((call) => call.runId === childRunId);
+    const childWait = ctx.waitCalls.find((call) => call.runId === child.runId);
     expect(childWait?.timeoutMs).toBe(1000);
     // Cleanup should patch the label
-    expect(patchParams.key).toBe(childSessionKey);
-    expect(patchParams.label).toBe("my-task");
+    const labelPatch = patchCalls.find((call) => call.label === "my-task");
+    expect(labelPatch?.key).toBe(child.sessionKey);
+    expect(labelPatch?.label).toBe("my-task");
 
     // Two agent calls: subagent spawn + main agent trigger
-    const agentCalls = calls.filter((c) => c.method === "agent");
+    const agentCalls = ctx.calls.filter((c) => c.method === "agent");
     expect(agentCalls).toHaveLength(2);
 
     // First call: subagent spawn
@@ -145,71 +208,31 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(second?.message).toContain("subagent task");
 
     // No direct send to external channel (main agent handles delivery)
-    const sendCalls = calls.filter((c) => c.method === "send");
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
     expect(sendCalls.length).toBe(0);
-    expect(childSessionKey?.startsWith("agent:main:subagent:")).toBe(true);
+    expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
   });
 
   it("sessions_spawn runs cleanup via lifecycle events", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    const calls: Array<{ method?: string; params?: unknown }> = [];
-    let agentCallCount = 0;
     let deletedKey: string | undefined;
-    let childRunId: string | undefined;
-    let childSessionKey: string | undefined;
-    const waitCalls: Array<{ runId?: string; timeoutMs?: number }> = [];
-
-    callGatewayMock.mockImplementation(async (opts: unknown) => {
-      const request = opts as { method?: string; params?: unknown };
-      calls.push(request);
-      if (request.method === "agent") {
-        agentCallCount += 1;
-        const runId = `run-${agentCallCount}`;
-        const params = request.params as {
-          message?: string;
-          sessionKey?: string;
-          channel?: string;
-          timeout?: number;
-          lane?: string;
-        };
-        if (params?.lane === "subagent") {
-          childRunId = runId;
-          childSessionKey = params?.sessionKey ?? "";
-          expect(params?.channel).toBe("discord");
-          expect(params?.timeout).toBe(1);
-        }
-        return {
-          runId,
-          status: "accepted",
-          acceptedAt: 1000 + agentCallCount,
-        };
-      }
-      if (request.method === "agent.wait") {
-        const params = request.params as { runId?: string; timeoutMs?: number } | undefined;
-        waitCalls.push(params ?? {});
-        return {
-          runId: params?.runId ?? "run-1",
-          status: "ok",
-          startedAt: 1000,
-          endedAt: 2000,
-        };
-      }
-      if (request.method === "sessions.delete") {
-        const params = request.params as { key?: string } | undefined;
-        deletedKey = params?.key;
-        return { ok: true };
-      }
-      return {};
+    const ctx = setupSessionsSpawnGatewayMock({
+      onAgentSubagentSpawn: (params) => {
+        const rec = params as { channel?: string; timeout?: number } | undefined;
+        expect(rec?.channel).toBe("discord");
+        expect(rec?.timeout).toBe(1);
+      },
+      onSessionsDelete: (params) => {
+        const rec = params as { key?: string } | undefined;
+        deletedKey = rec?.key;
+      },
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call1", {
       task: "do thing",
@@ -221,13 +244,14 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       runId: "run-1",
     });
 
-    if (!childRunId) {
+    const child = ctx.getChild();
+    if (!child.runId) {
       throw new Error("missing child runId");
     }
     vi.useFakeTimers();
     try {
       emitAgentEvent({
-        runId: childRunId,
+        runId: child.runId,
         stream: "lifecycle",
         data: {
           phase: "end",
@@ -241,10 +265,10 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       vi.useRealTimers();
     }
 
-    const childWait = waitCalls.find((call) => call.runId === childRunId);
+    const childWait = ctx.waitCalls.find((call) => call.runId === child.runId);
     expect(childWait?.timeoutMs).toBe(1000);
 
-    const agentCalls = calls.filter((call) => call.method === "agent");
+    const agentCalls = ctx.calls.filter((call) => call.method === "agent");
     expect(agentCalls).toHaveLength(2);
 
     const first = agentCalls[0]?.params as
@@ -259,7 +283,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(first?.deliver).toBe(false);
     expect(first?.channel).toBe("discord");
     expect(first?.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
-    expect(childSessionKey?.startsWith("agent:main:subagent:")).toBe(true);
+    expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
 
     const second = agentCalls[1]?.params as
       | {
@@ -272,7 +296,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(second?.deliver).toBe(true);
     expect(second?.message).toContain("subagent task");
 
-    const sendCalls = calls.filter((c) => c.method === "send");
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
     expect(sendCalls.length).toBe(0);
 
     expect(deletedKey?.startsWith("agent:main:subagent:")).toBe(true);
@@ -281,74 +305,25 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
   it("sessions_spawn deletes session when cleanup=delete via agent.wait", async () => {
     resetSubagentRegistryForTests();
     callGatewayMock.mockReset();
-    const calls: Array<{ method?: string; params?: unknown }> = [];
-    let agentCallCount = 0;
     let deletedKey: string | undefined;
-    let childRunId: string | undefined;
-    let childSessionKey: string | undefined;
-    const waitCalls: Array<{ runId?: string; timeoutMs?: number }> = [];
-
-    callGatewayMock.mockImplementation(async (opts: unknown) => {
-      const request = opts as { method?: string; params?: unknown };
-      calls.push(request);
-      if (request.method === "agent") {
-        agentCallCount += 1;
-        const runId = `run-${agentCallCount}`;
-        const params = request.params as {
-          message?: string;
-          sessionKey?: string;
-          channel?: string;
-          timeout?: number;
-          lane?: string;
-        };
-        // Only capture the first agent call (subagent spawn, not main agent trigger)
-        if (params?.lane === "subagent") {
-          childRunId = runId;
-          childSessionKey = params?.sessionKey ?? "";
-          expect(params?.channel).toBe("discord");
-          expect(params?.timeout).toBe(1);
-        }
-        return {
-          runId,
-          status: "accepted",
-          acceptedAt: 2000 + agentCallCount,
-        };
-      }
-      if (request.method === "agent.wait") {
-        const params = request.params as { runId?: string; timeoutMs?: number } | undefined;
-        waitCalls.push(params ?? {});
-        return {
-          runId: params?.runId ?? "run-1",
-          status: "ok",
-          startedAt: 3000,
-          endedAt: 4000,
-        };
-      }
-      if (request.method === "chat.history") {
-        return {
-          messages: [
-            {
-              role: "assistant",
-              content: [{ type: "text", text: "done" }],
-            },
-          ],
-        };
-      }
-      if (request.method === "sessions.delete") {
-        const params = request.params as { key?: string } | undefined;
-        deletedKey = params?.key;
-        return { ok: true };
-      }
-      return {};
+    const ctx = setupSessionsSpawnGatewayMock({
+      includeChatHistory: true,
+      onAgentSubagentSpawn: (params) => {
+        const rec = params as { channel?: string; timeout?: number } | undefined;
+        expect(rec?.channel).toBe("discord");
+        expect(rec?.timeout).toBe(1);
+      },
+      onSessionsDelete: (params) => {
+        const rec = params as { key?: string } | undefined;
+        deletedKey = rec?.key;
+      },
+      agentWaitResult: { status: "ok", startedAt: 3000, endedAt: 4000 },
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call1b", {
       task: "do thing",
@@ -360,16 +335,20 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       runId: "run-1",
     });
 
-    await sleep(0);
-    await sleep(0);
-    await sleep(0);
+    const child = ctx.getChild();
+    if (!child.runId) {
+      throw new Error("missing child runId");
+    }
+    await waitFor(() => ctx.waitCalls.some((call) => call.runId === child.runId));
+    await waitFor(() => ctx.calls.filter((call) => call.method === "agent").length >= 2);
+    await waitFor(() => Boolean(deletedKey));
 
-    const childWait = waitCalls.find((call) => call.runId === childRunId);
+    const childWait = ctx.waitCalls.find((call) => call.runId === child.runId);
     expect(childWait?.timeoutMs).toBe(1000);
-    expect(childSessionKey?.startsWith("agent:main:subagent:")).toBe(true);
+    expect(child.sessionKey?.startsWith("agent:main:subagent:")).toBe(true);
 
     // Two agent calls: subagent spawn + main agent trigger
-    const agentCalls = calls.filter((call) => call.method === "agent");
+    const agentCalls = ctx.calls.filter((call) => call.method === "agent");
     expect(agentCalls).toHaveLength(2);
 
     // First call: subagent spawn
@@ -382,7 +361,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
     expect(second?.deliver).toBe(true);
 
     // No direct send to external channel (main agent handles delivery)
-    const sendCalls = calls.filter((c) => c.method === "send");
+    const sendCalls = ctx.calls.filter((c) => c.method === "send");
     expect(sendCalls.length).toBe(0);
 
     // Session should be deleted
@@ -428,13 +407,10 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-timeout", {
       task: "do thing",
@@ -446,9 +422,7 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       runId: "run-1",
     });
 
-    await sleep(0);
-    await sleep(0);
-    await sleep(0);
+    await waitFor(() => calls.filter((call) => call.method === "agent").length >= 2);
 
     const mainAgentCall = calls
       .filter((call) => call.method === "agent")
@@ -500,14 +474,11 @@ describe("openclaw-tools: subagents (sessions_spawn lifecycle)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
       agentAccountId: "kev",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-announce-account", {
       task: "do thing",
diff --git a/src/agents/openclaw-tools.subagents.sessions-spawn.model.e2e.test.ts b/src/agents/openclaw-tools.subagents.sessions-spawn.model.e2e.test.ts
index 7d3cd00d62d..288f3b44611 100644
--- a/src/agents/openclaw-tools.subagents.sessions-spawn.model.e2e.test.ts
+++ b/src/agents/openclaw-tools.subagents.sessions-spawn.model.e2e.test.ts
@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it } from "vitest";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js";
 import "./test-helpers/fast-core-tools.js";
-import { createOpenClawTools } from "./openclaw-tools.js";
 import {
   getCallGatewayMock,
   resetSessionsSpawnConfigOverride,
@@ -11,6 +10,19 @@ import { resetSubagentRegistryForTests } from "./subagent-registry.js";
 
 const callGatewayMock = getCallGatewayMock();
 
+type CreateOpenClawTools = (typeof import("./openclaw-tools.js"))["createOpenClawTools"];
+type CreateOpenClawToolsOpts = Parameters<CreateOpenClawTools>[0];
+
+async function getSessionsSpawnTool(opts: CreateOpenClawToolsOpts) {
+  // Dynamic import: ensure harness mocks are installed before tool modules load.
+  const { createOpenClawTools } = await import("./openclaw-tools.js");
+  const tool = createOpenClawTools(opts).find((candidate) => candidate.name === "sessions_spawn");
+  if (!tool) {
+    throw new Error("missing sessions_spawn tool");
+  }
+  return tool;
+}
+
 describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
   beforeEach(() => {
     resetSessionsSpawnConfigOverride();
@@ -46,13 +58,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call3", {
       task: "do thing",
@@ -93,13 +102,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-thinking", {
       task: "do thing",
@@ -126,13 +132,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "discord:group:req",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-thinking-invalid", {
       task: "do thing",
@@ -166,13 +169,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "agent:main:main",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-default-model", {
       task: "do thing",
@@ -207,13 +207,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "agent:main:main",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-runtime-default-model", {
       task: "do thing",
@@ -255,13 +252,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "agent:research:main",
       agentChannel: "discord",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call-agent-model", {
       task: "do thing",
@@ -271,7 +265,9 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       modelApplied: true,
     });
 
-    const patchCall = calls.find((call) => call.method === "sessions.patch");
+    const patchCall = calls.find(
+      (call) => call.method === "sessions.patch" && (call.params as { model?: string })?.model,
+    );
     expect(patchCall?.params).toMatchObject({
       model: "opencode/claude",
     });
@@ -287,7 +283,11 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       const request = opts as { method?: string; params?: unknown };
       calls.push(request);
       if (request.method === "sessions.patch") {
-        throw new Error("invalid model: bad-model");
+        const model = (request.params as { model?: unknown } | undefined)?.model;
+        if (model === "bad-model") {
+          throw new Error("invalid model: bad-model");
+        }
+        return { ok: true };
       }
       if (request.method === "agent") {
         agentCallCount += 1;
@@ -307,13 +307,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call4", {
       task: "do thing",
@@ -345,13 +342,10 @@ describe("openclaw-tools: subagents (sessions_spawn model + thinking)", () => {
       return {};
     });
 
-    const tool = createOpenClawTools({
+    const tool = await getSessionsSpawnTool({
       agentSessionKey: "main",
       agentChannel: "whatsapp",
-    }).find((candidate) => candidate.name === "sessions_spawn");
-    if (!tool) {
-      throw new Error("missing sessions_spawn tool");
-    }
+    });
 
     const result = await tool.execute("call5", {
       task: "do thing",
diff --git a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts
index 9cd60cb59e0..e4e852e69ef 100644
--- a/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts
+++ b/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts
@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
 import {
   buildBootstrapContextFiles,
   DEFAULT_BOOTSTRAP_MAX_CHARS,
   DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS,
+  resolveBootstrapMaxChars,
+  resolveBootstrapTotalMaxChars,
 } from "./pi-embedded-helpers.js";
 import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
 
@@ -100,3 +103,39 @@ describe("buildBootstrapContextFiles", () => {
     expect(result[0]?.content.startsWith("[MISSING]")).toBe(true);
   });
 });
+
+describe("resolveBootstrapMaxChars", () => {
+  it("returns default when unset", () => {
+    expect(resolveBootstrapMaxChars()).toBe(DEFAULT_BOOTSTRAP_MAX_CHARS);
+  });
+  it("uses configured value when valid", () => {
+    const cfg = {
+      agents: { defaults: { bootstrapMaxChars: 12345 } },
+    } as OpenClawConfig;
+    expect(resolveBootstrapMaxChars(cfg)).toBe(12345);
+  });
+  it("falls back when invalid", () => {
+    const cfg = {
+      agents: { defaults: { bootstrapMaxChars: -1 } },
+    } as OpenClawConfig;
+    expect(resolveBootstrapMaxChars(cfg)).toBe(DEFAULT_BOOTSTRAP_MAX_CHARS);
+  });
+});
+
+describe("resolveBootstrapTotalMaxChars", () => {
+  it("returns default when unset", () => {
+    expect(resolveBootstrapTotalMaxChars()).toBe(DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS);
+  });
+  it("uses configured value when valid", () => {
+    const cfg = {
+      agents: { defaults: { bootstrapTotalMaxChars: 12345 } },
+    } as OpenClawConfig;
+    expect(resolveBootstrapTotalMaxChars(cfg)).toBe(12345);
+  });
+  it("falls back when invalid", () => {
+    const cfg = {
+      agents: { defaults: { bootstrapTotalMaxChars: -1 } },
+    } as OpenClawConfig;
+    expect(resolveBootstrapTotalMaxChars(cfg)).toBe(DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS);
+  });
+});
diff --git a/src/agents/pi-embedded-helpers.classifyfailoverreason.e2e.test.ts b/src/agents/pi-embedded-helpers.classifyfailoverreason.e2e.test.ts
deleted file mode 100644
index daf9d9cf586..00000000000
--- a/src/agents/pi-embedded-helpers.classifyfailoverreason.e2e.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { classifyFailoverReason } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("classifyFailoverReason", () => {
-  it("returns a stable reason", () => {
-    expect(classifyFailoverReason("invalid api key")).toBe("auth");
-    expect(classifyFailoverReason("no credentials found")).toBe("auth");
-    expect(classifyFailoverReason("no api key found")).toBe("auth");
-    expect(classifyFailoverReason("429 too many requests")).toBe("rate_limit");
-    expect(classifyFailoverReason("resource has been exhausted")).toBe("rate_limit");
-    expect(
-      classifyFailoverReason(
-        '{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}',
-      ),
-    ).toBe("rate_limit");
-    expect(classifyFailoverReason("invalid request format")).toBe("format");
-    expect(classifyFailoverReason("credit balance too low")).toBe("billing");
-    expect(classifyFailoverReason("deadline exceeded")).toBe("timeout");
-    expect(classifyFailoverReason("request ended without sending any chunks")).toBe("timeout");
-    expect(
-      classifyFailoverReason(
-        "521 <!DOCTYPE html><html><head><title>Web server is down</title></head><body>Cloudflare</body></html>",
-      ),
-    ).toBe("timeout");
-    expect(classifyFailoverReason("string should match pattern")).toBe("format");
-    expect(classifyFailoverReason("bad request")).toBeNull();
-    expect(
-      classifyFailoverReason(
-        "messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels",
-      ),
-    ).toBeNull();
-    expect(classifyFailoverReason("image exceeds 5 MB maximum")).toBeNull();
-  });
-  it("classifies OpenAI usage limit errors as rate_limit", () => {
-    expect(classifyFailoverReason("You have hit your ChatGPT usage limit (plus plan)")).toBe(
-      "rate_limit",
-    );
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.downgradeopenai-reasoning.e2e.test.ts b/src/agents/pi-embedded-helpers.downgradeopenai-reasoning.e2e.test.ts
deleted file mode 100644
index ee156e5a70a..00000000000
--- a/src/agents/pi-embedded-helpers.downgradeopenai-reasoning.e2e.test.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { downgradeOpenAIReasoningBlocks } from "./pi-embedded-helpers.js";
-
-describe("downgradeOpenAIReasoningBlocks", () => {
-  it("keeps reasoning signatures when followed by content", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "thinking",
-            thinking: "internal reasoning",
-            thinkingSignature: JSON.stringify({ id: "rs_123", type: "reasoning" }),
-          },
-          { type: "text", text: "answer" },
-        ],
-      },
-    ];
-
-    // oxlint-disable-next-line typescript/no-explicit-any
-    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual(input);
-  });
-
-  it("drops orphaned reasoning blocks without following content", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "thinking",
-            thinkingSignature: JSON.stringify({ id: "rs_abc", type: "reasoning" }),
-          },
-        ],
-      },
-      { role: "user", content: "next" },
-    ];
-
-    // oxlint-disable-next-line typescript/no-explicit-any
-    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual([
-      { role: "user", content: "next" },
-    ]);
-  });
-
-  it("drops object-form orphaned signatures", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "thinking",
-            thinkingSignature: { id: "rs_obj", type: "reasoning" },
-          },
-        ],
-      },
-    ];
-
-    // oxlint-disable-next-line typescript/no-explicit-any
-    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual([]);
-  });
-
-  it("keeps non-reasoning thinking signatures", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "thinking",
-            thinking: "t",
-            thinkingSignature: "reasoning_content",
-          },
-        ],
-      },
-    ];
-
-    // oxlint-disable-next-line typescript/no-explicit-any
-    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual(input);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.formatassistanterrortext.e2e.test.ts b/src/agents/pi-embedded-helpers.formatassistanterrortext.e2e.test.ts
index 9ba67b6a147..c563ac948f3 100644
--- a/src/agents/pi-embedded-helpers.formatassistanterrortext.e2e.test.ts
+++ b/src/agents/pi-embedded-helpers.formatassistanterrortext.e2e.test.ts
@@ -4,6 +4,7 @@ import {
   BILLING_ERROR_USER_MESSAGE,
   formatBillingErrorMessage,
   formatAssistantErrorText,
+  formatRawAssistantErrorForUi,
 } from "./pi-embedded-helpers.js";
 
 describe("formatAssistantErrorText", () => {
@@ -114,3 +115,38 @@ describe("formatAssistantErrorText", () => {
     expect(formatAssistantErrorText(msg)).toBe("LLM request timed out.");
   });
 });
+
+describe("formatRawAssistantErrorForUi", () => {
+  it("renders HTTP code + type + message from Anthropic payloads", () => {
+    const text = formatRawAssistantErrorForUi(
+      '429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limited."},"request_id":"req_123"}',
+    );
+
+    expect(text).toContain("HTTP 429");
+    expect(text).toContain("rate_limit_error");
+    expect(text).toContain("Rate limited.");
+    expect(text).toContain("req_123");
+  });
+
+  it("renders a generic unknown error message when raw is empty", () => {
+    expect(formatRawAssistantErrorForUi("")).toContain("unknown error");
+  });
+
+  it("formats plain HTTP status lines", () => {
+    expect(formatRawAssistantErrorForUi("500 Internal Server Error")).toBe(
+      "HTTP 500: Internal Server Error",
+    );
+  });
+
+  it("sanitizes HTML error pages into a clean unavailable message", () => {
+    const htmlError = `521 <!DOCTYPE html>
+<html lang="en-US">
+  <head><title>Web server is down | example.com | Cloudflare</title></head>
+  <body>Ray ID: abc123</body>
+</html>`;
+
+    expect(formatRawAssistantErrorForUi(htmlError)).toBe(
+      "The AI service is temporarily unavailable (HTTP 521). Please try again in a moment.",
+    );
+  });
+});
diff --git a/src/agents/pi-embedded-helpers.formatrawassistanterrorforui.e2e.test.ts b/src/agents/pi-embedded-helpers.formatrawassistanterrorforui.e2e.test.ts
deleted file mode 100644
index 8fd0ed1aff8..00000000000
--- a/src/agents/pi-embedded-helpers.formatrawassistanterrorforui.e2e.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { formatRawAssistantErrorForUi } from "./pi-embedded-helpers.js";
-
-describe("formatRawAssistantErrorForUi", () => {
-  it("renders HTTP code + type + message from Anthropic payloads", () => {
-    const text = formatRawAssistantErrorForUi(
-      '429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limited."},"request_id":"req_123"}',
-    );
-
-    expect(text).toContain("HTTP 429");
-    expect(text).toContain("rate_limit_error");
-    expect(text).toContain("Rate limited.");
-    expect(text).toContain("req_123");
-  });
-
-  it("renders a generic unknown error message when raw is empty", () => {
-    expect(formatRawAssistantErrorForUi("")).toContain("unknown error");
-  });
-
-  it("formats plain HTTP status lines", () => {
-    expect(formatRawAssistantErrorForUi("500 Internal Server Error")).toBe(
-      "HTTP 500: Internal Server Error",
-    );
-  });
-
-  it("sanitizes HTML error pages into a clean unavailable message", () => {
-    const htmlError = `521 <!DOCTYPE html>
-<html lang="en-US">
-  <head><title>Web server is down | example.com | Cloudflare</title></head>
-  <body>Ray ID: abc123</body>
-</html>`;
-
-    expect(formatRawAssistantErrorForUi(htmlError)).toBe(
-      "The AI service is temporarily unavailable (HTTP 521). Please try again in a moment.",
-    );
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.image-dimension-error.e2e.test.ts b/src/agents/pi-embedded-helpers.image-dimension-error.e2e.test.ts
deleted file mode 100644
index 2c92ed68125..00000000000
--- a/src/agents/pi-embedded-helpers.image-dimension-error.e2e.test.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isImageDimensionErrorMessage, parseImageDimensionError } from "./pi-embedded-helpers.js";
-
-describe("image dimension errors", () => {
-  it("parses anthropic image dimension errors", () => {
-    const raw =
-      '400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}';
-    const parsed = parseImageDimensionError(raw);
-    expect(parsed).not.toBeNull();
-    expect(parsed?.maxDimensionPx).toBe(2000);
-    expect(parsed?.messageIndex).toBe(84);
-    expect(parsed?.contentIndex).toBe(1);
-    expect(isImageDimensionErrorMessage(raw)).toBe(true);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.image-size-error.e2e.test.ts b/src/agents/pi-embedded-helpers.image-size-error.e2e.test.ts
deleted file mode 100644
index d69a3c381ae..00000000000
--- a/src/agents/pi-embedded-helpers.image-size-error.e2e.test.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseImageSizeError } from "./pi-embedded-helpers.js";
-
-describe("parseImageSizeError", () => {
-  it("parses max MB values from error text", () => {
-    expect(parseImageSizeError("image exceeds 5 MB maximum")?.maxMb).toBe(5);
-    expect(parseImageSizeError("Image exceeds 5.5 MB limit")?.maxMb).toBe(5.5);
-  });
-
-  it("returns null for unrelated errors", () => {
-    expect(parseImageSizeError("context overflow")).toBeNull();
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.isautherrormessage.e2e.test.ts b/src/agents/pi-embedded-helpers.isautherrormessage.e2e.test.ts
deleted file mode 100644
index 2c8fd65d099..00000000000
--- a/src/agents/pi-embedded-helpers.isautherrormessage.e2e.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isAuthErrorMessage } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("isAuthErrorMessage", () => {
-  it("matches credential validation errors", () => {
-    const samples = [
-      'No credentials found for profile "anthropic:default".',
-      "No API key found for profile openai.",
-    ];
-    for (const sample of samples) {
-      expect(isAuthErrorMessage(sample)).toBe(true);
-    }
-  });
-  it("matches OAuth refresh failures", () => {
-    const samples = [
-      "OAuth token refresh failed for anthropic: Failed to refresh OAuth token for anthropic. Please try again or re-authenticate.",
-      "Please re-authenticate to continue.",
-    ];
-    for (const sample of samples) {
-      expect(isAuthErrorMessage(sample)).toBe(true);
-    }
-  });
-  it("ignores unrelated errors", () => {
-    expect(isAuthErrorMessage("rate limit exceeded")).toBe(false);
-    expect(isAuthErrorMessage("billing issue detected")).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.isbillingerrormessage.e2e.test.ts b/src/agents/pi-embedded-helpers.isbillingerrormessage.e2e.test.ts
index 69b04e8bb37..4f72364de1f 100644
--- a/src/agents/pi-embedded-helpers.isbillingerrormessage.e2e.test.ts
+++ b/src/agents/pi-embedded-helpers.isbillingerrormessage.e2e.test.ts
@@ -1,14 +1,45 @@
 import { describe, expect, it } from "vitest";
-import { isBillingErrorMessage } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
+import {
+  classifyFailoverReason,
+  isAuthErrorMessage,
+  isBillingErrorMessage,
+  isCloudCodeAssistFormatError,
+  isCloudflareOrHtmlErrorPage,
+  isCompactionFailureError,
+  isContextOverflowError,
+  isFailoverErrorMessage,
+  isImageDimensionErrorMessage,
+  isLikelyContextOverflowError,
+  isTransientHttpError,
+  parseImageDimensionError,
+  parseImageSizeError,
+} from "./pi-embedded-helpers.js";
 
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
+describe("isAuthErrorMessage", () => {
+  it("matches credential validation errors", () => {
+    const samples = [
+      'No credentials found for profile "anthropic:default".',
+      "No API key found for profile openai.",
+    ];
+    for (const sample of samples) {
+      expect(isAuthErrorMessage(sample)).toBe(true);
+    }
+  });
+  it("matches OAuth refresh failures", () => {
+    const samples = [
+      "OAuth token refresh failed for anthropic: Failed to refresh OAuth token for anthropic. Please try again or re-authenticate.",
+      "Please re-authenticate to continue.",
+    ];
+    for (const sample of samples) {
+      expect(isAuthErrorMessage(sample)).toBe(true);
+    }
+  });
+  it("ignores unrelated errors", () => {
+    expect(isAuthErrorMessage("rate limit exceeded")).toBe(false);
+    expect(isAuthErrorMessage("billing issue detected")).toBe(false);
+  });
 });
+
 describe("isBillingErrorMessage", () => {
   it("matches credit / payment failures", () => {
     const samples = [
@@ -65,3 +96,255 @@ describe("isBillingErrorMessage", () => {
     }
   });
 });
+
+describe("isCloudCodeAssistFormatError", () => {
+  it("matches format errors", () => {
+    const samples = [
+      "INVALID_REQUEST_ERROR: string should match pattern",
+      "messages.1.content.1.tool_use.id",
+      "tool_use.id should match pattern",
+      "invalid request format",
+    ];
+    for (const sample of samples) {
+      expect(isCloudCodeAssistFormatError(sample)).toBe(true);
+    }
+  });
+  it("ignores unrelated errors", () => {
+    expect(isCloudCodeAssistFormatError("rate limit exceeded")).toBe(false);
+    expect(
+      isCloudCodeAssistFormatError(
+        '400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}',
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("isCloudflareOrHtmlErrorPage", () => {
+  it("detects Cloudflare 521 HTML pages", () => {
+    const htmlError = `521 <!DOCTYPE html>
+<html lang="en-US">
+  <head><title>Web server is down | example.com | Cloudflare</title></head>
+  <body><h1>Web server is down</h1></body>
+</html>`;
+
+    expect(isCloudflareOrHtmlErrorPage(htmlError)).toBe(true);
+  });
+
+  it("detects generic 5xx HTML pages", () => {
+    const htmlError = `503 <html><head><title>Service Unavailable</title></head><body>down</body></html>`;
+    expect(isCloudflareOrHtmlErrorPage(htmlError)).toBe(true);
+  });
+
+  it("does not flag non-HTML status lines", () => {
+    expect(isCloudflareOrHtmlErrorPage("500 Internal Server Error")).toBe(false);
+    expect(isCloudflareOrHtmlErrorPage("429 Too Many Requests")).toBe(false);
+  });
+
+  it("does not flag quoted HTML without a closing html tag", () => {
+    const plainTextWithHtmlPrefix = "500 <!DOCTYPE html> upstream responded with partial HTML text";
+    expect(isCloudflareOrHtmlErrorPage(plainTextWithHtmlPrefix)).toBe(false);
+  });
+});
+
+describe("isCompactionFailureError", () => {
+  it("matches compaction overflow failures", () => {
+    const samples = [
+      'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
+      "auto-compaction failed due to context overflow",
+      "Compaction failed: prompt is too long",
+      "Summarization failed: context window exceeded for this request",
+    ];
+    for (const sample of samples) {
+      expect(isCompactionFailureError(sample)).toBe(true);
+    }
+  });
+  it("ignores non-compaction overflow errors", () => {
+    expect(isCompactionFailureError("Context overflow: prompt too large")).toBe(false);
+    expect(isCompactionFailureError("rate limit exceeded")).toBe(false);
+  });
+});
+
+describe("isContextOverflowError", () => {
+  it("matches known overflow hints", () => {
+    const samples = [
+      "request_too_large",
+      "Request exceeds the maximum size",
+      "context length exceeded",
+      "Maximum context length",
+      "prompt is too long: 208423 tokens > 200000 maximum",
+      "Context overflow: Summarization failed",
+      "413 Request Entity Too Large",
+    ];
+    for (const sample of samples) {
+      expect(isContextOverflowError(sample)).toBe(true);
+    }
+  });
+
+  it("matches Anthropic 'Request size exceeds model context window' error", () => {
+    // Anthropic returns this error format when the prompt exceeds the context window.
+    // Without this fix, auto-compaction is NOT triggered because neither
+    // isContextOverflowError nor pi-ai's isContextOverflow recognizes this pattern.
+    // The user sees: "LLM request rejected: Request size exceeds model context window"
+    // instead of automatic compaction + retry.
+    const anthropicRawError =
+      '{"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}';
+    expect(isContextOverflowError(anthropicRawError)).toBe(true);
+  });
+
+  it("matches 'exceeds model context window' in various formats", () => {
+    const samples = [
+      "Request size exceeds model context window",
+      "request size exceeds model context window",
+      '400 {"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}',
+      "The request size exceeds model context window limit",
+    ];
+    for (const sample of samples) {
+      expect(isContextOverflowError(sample)).toBe(true);
+    }
+  });
+
+  it("ignores unrelated errors", () => {
+    expect(isContextOverflowError("rate limit exceeded")).toBe(false);
+    expect(isContextOverflowError("request size exceeds upload limit")).toBe(false);
+    expect(isContextOverflowError("model not found")).toBe(false);
+    expect(isContextOverflowError("authentication failed")).toBe(false);
+  });
+
+  it("ignores normal conversation text mentioning context overflow", () => {
+    // These are legitimate conversation snippets, not error messages
+    expect(isContextOverflowError("Let's investigate the context overflow bug")).toBe(false);
+    expect(isContextOverflowError("The mystery context overflow errors are strange")).toBe(false);
+    expect(isContextOverflowError("We're debugging context overflow issues")).toBe(false);
+    expect(isContextOverflowError("Something is causing context overflow messages")).toBe(false);
+  });
+});
+
+describe("isLikelyContextOverflowError", () => {
+  it("matches context overflow hints", () => {
+    const samples = [
+      "Model context window is 128k tokens, you requested 256k tokens",
+      "Context window exceeded: requested 12000 tokens",
+      "Prompt too large for this model",
+    ];
+    for (const sample of samples) {
+      expect(isLikelyContextOverflowError(sample)).toBe(true);
+    }
+  });
+
+  it("excludes context window too small errors", () => {
+    const samples = [
+      "Model context window too small (minimum is 128k tokens)",
+      "Context window too small: minimum is 1000 tokens",
+    ];
+    for (const sample of samples) {
+      expect(isLikelyContextOverflowError(sample)).toBe(false);
+    }
+  });
+
+  it("excludes rate limit errors that match the broad hint regex", () => {
+    const samples = [
+      "request reached organization TPD rate limit, current: 1506556, limit: 1500000",
+      "rate limit exceeded",
+      "too many requests",
+      "429 Too Many Requests",
+      "exceeded your current quota",
+      "This request would exceed your account's rate limit",
+      "429 Too Many Requests: request exceeds rate limit",
+    ];
+    for (const sample of samples) {
+      expect(isLikelyContextOverflowError(sample)).toBe(false);
+    }
+  });
+});
+
+describe("isTransientHttpError", () => {
+  it("returns true for retryable 5xx status codes", () => {
+    expect(isTransientHttpError("500 Internal Server Error")).toBe(true);
+    expect(isTransientHttpError("502 Bad Gateway")).toBe(true);
+    expect(isTransientHttpError("503 Service Unavailable")).toBe(true);
+    expect(isTransientHttpError("521 <!DOCTYPE html><html></html>")).toBe(true);
+    expect(isTransientHttpError("529 Overloaded")).toBe(true);
+  });
+
+  it("returns false for non-retryable or non-http text", () => {
+    expect(isTransientHttpError("504 Gateway Timeout")).toBe(false);
+    expect(isTransientHttpError("429 Too Many Requests")).toBe(false);
+    expect(isTransientHttpError("network timeout")).toBe(false);
+  });
+});
+
+describe("isFailoverErrorMessage", () => {
+  it("matches auth/rate/billing/timeout", () => {
+    const samples = [
+      "invalid api key",
+      "429 rate limit exceeded",
+      "Your credit balance is too low",
+      "request timed out",
+      "invalid request format",
+    ];
+    for (const sample of samples) {
+      expect(isFailoverErrorMessage(sample)).toBe(true);
+    }
+  });
+});
+
+describe("parseImageSizeError", () => {
+  it("parses max MB values from error text", () => {
+    expect(parseImageSizeError("image exceeds 5 MB maximum")?.maxMb).toBe(5);
+    expect(parseImageSizeError("Image exceeds 5.5 MB limit")?.maxMb).toBe(5.5);
+  });
+
+  it("returns null for unrelated errors", () => {
+    expect(parseImageSizeError("context overflow")).toBeNull();
+  });
+});
+
+describe("image dimension errors", () => {
+  it("parses anthropic image dimension errors", () => {
+    const raw =
+      '400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}';
+    const parsed = parseImageDimensionError(raw);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.maxDimensionPx).toBe(2000);
+    expect(parsed?.messageIndex).toBe(84);
+    expect(parsed?.contentIndex).toBe(1);
+    expect(isImageDimensionErrorMessage(raw)).toBe(true);
+  });
+});
+
+describe("classifyFailoverReason", () => {
+  it("returns a stable reason", () => {
+    expect(classifyFailoverReason("invalid api key")).toBe("auth");
+    expect(classifyFailoverReason("no credentials found")).toBe("auth");
+    expect(classifyFailoverReason("no api key found")).toBe("auth");
+    expect(classifyFailoverReason("429 too many requests")).toBe("rate_limit");
+    expect(classifyFailoverReason("resource has been exhausted")).toBe("rate_limit");
+    expect(
+      classifyFailoverReason(
+        '{"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}',
+      ),
+    ).toBe("rate_limit");
+    expect(classifyFailoverReason("invalid request format")).toBe("format");
+    expect(classifyFailoverReason("credit balance too low")).toBe("billing");
+    expect(classifyFailoverReason("deadline exceeded")).toBe("timeout");
+    expect(classifyFailoverReason("request ended without sending any chunks")).toBe("timeout");
+    expect(
+      classifyFailoverReason(
+        "521 <!DOCTYPE html><html><head><title>Web server is down</title></head><body>Cloudflare</body></html>",
+      ),
+    ).toBe("timeout");
+    expect(classifyFailoverReason("string should match pattern")).toBe("format");
+    expect(classifyFailoverReason("bad request")).toBeNull();
+    expect(
+      classifyFailoverReason(
+        "messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels",
+      ),
+    ).toBeNull();
+    expect(classifyFailoverReason("image exceeds 5 MB maximum")).toBeNull();
+  });
+  it("classifies OpenAI usage limit errors as rate_limit", () => {
+    expect(classifyFailoverReason("You have hit your ChatGPT usage limit (plus plan)")).toBe(
+      "rate_limit",
+    );
+  });
+});
diff --git a/src/agents/pi-embedded-helpers.iscloudcodeassistformaterror.e2e.test.ts b/src/agents/pi-embedded-helpers.iscloudcodeassistformaterror.e2e.test.ts
deleted file mode 100644
index 2433642e46d..00000000000
--- a/src/agents/pi-embedded-helpers.iscloudcodeassistformaterror.e2e.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isCloudCodeAssistFormatError } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("isCloudCodeAssistFormatError", () => {
-  it("matches format errors", () => {
-    const samples = [
-      "INVALID_REQUEST_ERROR: string should match pattern",
-      "messages.1.content.1.tool_use.id",
-      "tool_use.id should match pattern",
-      "invalid request format",
-    ];
-    for (const sample of samples) {
-      expect(isCloudCodeAssistFormatError(sample)).toBe(true);
-    }
-  });
-  it("ignores unrelated errors", () => {
-    expect(isCloudCodeAssistFormatError("rate limit exceeded")).toBe(false);
-    expect(
-      isCloudCodeAssistFormatError(
-        '400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.84.content.1.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}',
-      ),
-    ).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.iscloudflareorhtmlerrorpage.e2e.test.ts b/src/agents/pi-embedded-helpers.iscloudflareorhtmlerrorpage.e2e.test.ts
deleted file mode 100644
index ebdb22c6c5d..00000000000
--- a/src/agents/pi-embedded-helpers.iscloudflareorhtmlerrorpage.e2e.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isCloudflareOrHtmlErrorPage } from "./pi-embedded-helpers.js";
-
-describe("isCloudflareOrHtmlErrorPage", () => {
-  it("detects Cloudflare 521 HTML pages", () => {
-    const htmlError = `521 <!DOCTYPE html>
-<html lang="en-US">
-  <head><title>Web server is down | example.com | Cloudflare</title></head>
-  <body><h1>Web server is down</h1></body>
-</html>`;
-
-    expect(isCloudflareOrHtmlErrorPage(htmlError)).toBe(true);
-  });
-
-  it("detects generic 5xx HTML pages", () => {
-    const htmlError = `503 <html><head><title>Service Unavailable</title></head><body>down</body></html>`;
-    expect(isCloudflareOrHtmlErrorPage(htmlError)).toBe(true);
-  });
-
-  it("does not flag non-HTML status lines", () => {
-    expect(isCloudflareOrHtmlErrorPage("500 Internal Server Error")).toBe(false);
-    expect(isCloudflareOrHtmlErrorPage("429 Too Many Requests")).toBe(false);
-  });
-
-  it("does not flag quoted HTML without a closing html tag", () => {
-    const plainTextWithHtmlPrefix = "500 <!DOCTYPE html> upstream responded with partial HTML text";
-    expect(isCloudflareOrHtmlErrorPage(plainTextWithHtmlPrefix)).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.iscompactionfailureerror.e2e.test.ts b/src/agents/pi-embedded-helpers.iscompactionfailureerror.e2e.test.ts
deleted file mode 100644
index 6abcabba5bd..00000000000
--- a/src/agents/pi-embedded-helpers.iscompactionfailureerror.e2e.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isCompactionFailureError } from "./pi-embedded-helpers/errors.js";
-describe("isCompactionFailureError", () => {
-  it("matches compaction overflow failures", () => {
-    const samples = [
-      'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
-      "auto-compaction failed due to context overflow",
-      "Compaction failed: prompt is too long",
-      "Summarization failed: context window exceeded for this request",
-    ];
-    for (const sample of samples) {
-      expect(isCompactionFailureError(sample)).toBe(true);
-    }
-  });
-  it("ignores non-compaction overflow errors", () => {
-    expect(isCompactionFailureError("Context overflow: prompt too large")).toBe(false);
-    expect(isCompactionFailureError("rate limit exceeded")).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.iscontextoverflowerror.e2e.test.ts b/src/agents/pi-embedded-helpers.iscontextoverflowerror.e2e.test.ts
deleted file mode 100644
index 79a19732640..00000000000
--- a/src/agents/pi-embedded-helpers.iscontextoverflowerror.e2e.test.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isContextOverflowError } from "./pi-embedded-helpers.js";
-
-describe("isContextOverflowError", () => {
-  it("matches known overflow hints", () => {
-    const samples = [
-      "request_too_large",
-      "Request exceeds the maximum size",
-      "context length exceeded",
-      "Maximum context length",
-      "prompt is too long: 208423 tokens > 200000 maximum",
-      "Context overflow: Summarization failed",
-      "413 Request Entity Too Large",
-    ];
-    for (const sample of samples) {
-      expect(isContextOverflowError(sample)).toBe(true);
-    }
-  });
-
-  it("matches Anthropic 'Request size exceeds model context window' error", () => {
-    // Anthropic returns this error format when the prompt exceeds the context window.
-    // Without this fix, auto-compaction is NOT triggered because neither
-    // isContextOverflowError nor pi-ai's isContextOverflow recognizes this pattern.
-    // The user sees: "LLM request rejected: Request size exceeds model context window"
-    // instead of automatic compaction + retry.
-    const anthropicRawError =
-      '{"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}';
-    expect(isContextOverflowError(anthropicRawError)).toBe(true);
-  });
-
-  it("matches 'exceeds model context window' in various formats", () => {
-    const samples = [
-      "Request size exceeds model context window",
-      "request size exceeds model context window",
-      '400 {"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}',
-      "The request size exceeds model context window limit",
-    ];
-    for (const sample of samples) {
-      expect(isContextOverflowError(sample)).toBe(true);
-    }
-  });
-
-  it("ignores unrelated errors", () => {
-    expect(isContextOverflowError("rate limit exceeded")).toBe(false);
-    expect(isContextOverflowError("request size exceeds upload limit")).toBe(false);
-    expect(isContextOverflowError("model not found")).toBe(false);
-    expect(isContextOverflowError("authentication failed")).toBe(false);
-  });
-
-  it("ignores normal conversation text mentioning context overflow", () => {
-    // These are legitimate conversation snippets, not error messages
-    expect(isContextOverflowError("Let's investigate the context overflow bug")).toBe(false);
-    expect(isContextOverflowError("The mystery context overflow errors are strange")).toBe(false);
-    expect(isContextOverflowError("We're debugging context overflow issues")).toBe(false);
-    expect(isContextOverflowError("Something is causing context overflow messages")).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.isfailovererrormessage.e2e.test.ts b/src/agents/pi-embedded-helpers.isfailovererrormessage.e2e.test.ts
deleted file mode 100644
index 2afb8557b2e..00000000000
--- a/src/agents/pi-embedded-helpers.isfailovererrormessage.e2e.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isFailoverErrorMessage } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("isFailoverErrorMessage", () => {
-  it("matches auth/rate/billing/timeout", () => {
-    const samples = [
-      "invalid api key",
-      "429 rate limit exceeded",
-      "Your credit balance is too low",
-      "request timed out",
-      "invalid request format",
-    ];
-    for (const sample of samples) {
-      expect(isFailoverErrorMessage(sample)).toBe(true);
-    }
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.islikelycontextoverflowerror.e2e.test.ts b/src/agents/pi-embedded-helpers.islikelycontextoverflowerror.e2e.test.ts
deleted file mode 100644
index e9ff9e457c3..00000000000
--- a/src/agents/pi-embedded-helpers.islikelycontextoverflowerror.e2e.test.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isLikelyContextOverflowError } from "./pi-embedded-helpers.js";
-
-describe("isLikelyContextOverflowError", () => {
-  it("matches context overflow hints", () => {
-    const samples = [
-      "Model context window is 128k tokens, you requested 256k tokens",
-      "Context window exceeded: requested 12000 tokens",
-      "Prompt too large for this model",
-    ];
-    for (const sample of samples) {
-      expect(isLikelyContextOverflowError(sample)).toBe(true);
-    }
-  });
-
-  it("excludes context window too small errors", () => {
-    const samples = [
-      "Model context window too small (minimum is 128k tokens)",
-      "Context window too small: minimum is 1000 tokens",
-    ];
-    for (const sample of samples) {
-      expect(isLikelyContextOverflowError(sample)).toBe(false);
-    }
-  });
-
-  it("excludes rate limit errors that match the broad hint regex", () => {
-    const samples = [
-      "request reached organization TPD rate limit, current: 1506556, limit: 1500000",
-      "rate limit exceeded",
-      "too many requests",
-      "429 Too Many Requests",
-      "exceeded your current quota",
-      "This request would exceed your account's rate limit",
-      "429 Too Many Requests: request exceeds rate limit",
-    ];
-    for (const sample of samples) {
-      expect(isLikelyContextOverflowError(sample)).toBe(false);
-    }
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.istransienthttperror.e2e.test.ts b/src/agents/pi-embedded-helpers.istransienthttperror.e2e.test.ts
deleted file mode 100644
index faaf4a20139..00000000000
--- a/src/agents/pi-embedded-helpers.istransienthttperror.e2e.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isTransientHttpError } from "./pi-embedded-helpers.js";
-
-describe("isTransientHttpError", () => {
-  it("returns true for retryable 5xx status codes", () => {
-    expect(isTransientHttpError("500 Internal Server Error")).toBe(true);
-    expect(isTransientHttpError("502 Bad Gateway")).toBe(true);
-    expect(isTransientHttpError("503 Service Unavailable")).toBe(true);
-    expect(isTransientHttpError("521 <!DOCTYPE html><html></html>")).toBe(true);
-    expect(isTransientHttpError("529 Overloaded")).toBe(true);
-  });
-
-  it("returns false for non-retryable or non-http text", () => {
-    expect(isTransientHttpError("504 Gateway Timeout")).toBe(false);
-    expect(isTransientHttpError("429 Too Many Requests")).toBe(false);
-    expect(isTransientHttpError("network timeout")).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.messaging-duplicate.e2e.test.ts b/src/agents/pi-embedded-helpers.messaging-duplicate.e2e.test.ts
deleted file mode 100644
index 04f88d023f2..00000000000
--- a/src/agents/pi-embedded-helpers.messaging-duplicate.e2e.test.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isMessagingToolDuplicate, normalizeTextForComparison } from "./pi-embedded-helpers.js";
-
-describe("normalizeTextForComparison", () => {
-  it("lowercases text", () => {
-    expect(normalizeTextForComparison("Hello World")).toBe("hello world");
-  });
-
-  it("trims whitespace", () => {
-    expect(normalizeTextForComparison("  hello  ")).toBe("hello");
-  });
-
-  it("collapses multiple spaces", () => {
-    expect(normalizeTextForComparison("hello    world")).toBe("hello world");
-  });
-
-  it("strips emoji", () => {
-    expect(normalizeTextForComparison("Hello 👋 World 🌍")).toBe("hello world");
-  });
-
-  it("handles mixed normalization", () => {
-    expect(normalizeTextForComparison("  Hello 👋   WORLD  🌍  ")).toBe("hello world");
-  });
-});
-
-describe("isMessagingToolDuplicate", () => {
-  it("returns false for empty sentTexts", () => {
-    expect(isMessagingToolDuplicate("hello world", [])).toBe(false);
-  });
-
-  it("returns false for short texts", () => {
-    expect(isMessagingToolDuplicate("short", ["short"])).toBe(false);
-  });
-
-  it("detects exact duplicates", () => {
-    expect(
-      isMessagingToolDuplicate("Hello, this is a test message!", [
-        "Hello, this is a test message!",
-      ]),
-    ).toBe(true);
-  });
-
-  it("detects duplicates with different casing", () => {
-    expect(
-      isMessagingToolDuplicate("HELLO, THIS IS A TEST MESSAGE!", [
-        "hello, this is a test message!",
-      ]),
-    ).toBe(true);
-  });
-
-  it("detects duplicates with emoji variations", () => {
-    expect(
-      isMessagingToolDuplicate("Hello! 👋 This is a test message!", [
-        "Hello! This is a test message!",
-      ]),
-    ).toBe(true);
-  });
-
-  it("detects substring duplicates (LLM elaboration)", () => {
-    expect(
-      isMessagingToolDuplicate('I sent the message: "Hello, this is a test message!"', [
-        "Hello, this is a test message!",
-      ]),
-    ).toBe(true);
-  });
-
-  it("detects when sent text contains block reply (reverse substring)", () => {
-    expect(
-      isMessagingToolDuplicate("Hello, this is a test message!", [
-        'I sent the message: "Hello, this is a test message!"',
-      ]),
-    ).toBe(true);
-  });
-
-  it("returns false for non-matching texts", () => {
-    expect(
-      isMessagingToolDuplicate("This is completely different content.", [
-        "Hello, this is a test message!",
-      ]),
-    ).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.normalizetextforcomparison.e2e.test.ts b/src/agents/pi-embedded-helpers.normalizetextforcomparison.e2e.test.ts
deleted file mode 100644
index 300dd234b36..00000000000
--- a/src/agents/pi-embedded-helpers.normalizetextforcomparison.e2e.test.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeTextForComparison } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("normalizeTextForComparison", () => {
-  it("lowercases text", () => {
-    expect(normalizeTextForComparison("Hello World")).toBe("hello world");
-  });
-  it("trims whitespace", () => {
-    expect(normalizeTextForComparison("  hello  ")).toBe("hello");
-  });
-  it("collapses multiple spaces", () => {
-    expect(normalizeTextForComparison("hello    world")).toBe("hello world");
-  });
-  it("strips emoji", () => {
-    expect(normalizeTextForComparison("Hello 👋 World 🌍")).toBe("hello world");
-  });
-  it("handles mixed normalization", () => {
-    expect(normalizeTextForComparison("  Hello 👋   WORLD  🌍  ")).toBe("hello world");
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.resolvebootstrapmaxchars.e2e.test.ts b/src/agents/pi-embedded-helpers.resolvebootstrapmaxchars.e2e.test.ts
deleted file mode 100644
index c4a0e7471c2..00000000000
--- a/src/agents/pi-embedded-helpers.resolvebootstrapmaxchars.e2e.test.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../config/config.js";
-import {
-  DEFAULT_BOOTSTRAP_MAX_CHARS,
-  DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS,
-  resolveBootstrapMaxChars,
-  resolveBootstrapTotalMaxChars,
-} from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("resolveBootstrapMaxChars", () => {
-  it("returns default when unset", () => {
-    expect(resolveBootstrapMaxChars()).toBe(DEFAULT_BOOTSTRAP_MAX_CHARS);
-  });
-  it("uses configured value when valid", () => {
-    const cfg = {
-      agents: { defaults: { bootstrapMaxChars: 12345 } },
-    } as OpenClawConfig;
-    expect(resolveBootstrapMaxChars(cfg)).toBe(12345);
-  });
-  it("falls back when invalid", () => {
-    const cfg = {
-      agents: { defaults: { bootstrapMaxChars: -1 } },
-    } as OpenClawConfig;
-    expect(resolveBootstrapMaxChars(cfg)).toBe(DEFAULT_BOOTSTRAP_MAX_CHARS);
-  });
-});
-
-describe("resolveBootstrapTotalMaxChars", () => {
-  it("returns default when unset", () => {
-    expect(resolveBootstrapTotalMaxChars()).toBe(DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS);
-  });
-  it("uses configured value when valid", () => {
-    const cfg = {
-      agents: { defaults: { bootstrapTotalMaxChars: 12345 } },
-    } as OpenClawConfig;
-    expect(resolveBootstrapTotalMaxChars(cfg)).toBe(12345);
-  });
-  it("falls back when invalid", () => {
-    const cfg = {
-      agents: { defaults: { bootstrapTotalMaxChars: -1 } },
-    } as OpenClawConfig;
-    expect(resolveBootstrapTotalMaxChars(cfg)).toBe(DEFAULT_BOOTSTRAP_TOTAL_MAX_CHARS);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.sanitize-session-messages-images.keeps-tool-call-tool-result-ids-unchanged.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitize-session-messages-images.keeps-tool-call-tool-result-ids-unchanged.e2e.test.ts
deleted file mode 100644
index 1b3210790cc..00000000000
--- a/src/agents/pi-embedded-helpers.sanitize-session-messages-images.keeps-tool-call-tool-result-ids-unchanged.e2e.test.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import type { AgentMessage } from "@mariozechner/pi-agent-core";
-import { describe, expect, it } from "vitest";
-import { sanitizeSessionMessagesImages } from "./pi-embedded-helpers.js";
-
-describe("sanitizeSessionMessagesImages", () => {
-  it("keeps tool call + tool result IDs unchanged by default", async () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "toolCall",
-            id: "call_123|fc_456",
-            name: "read",
-            arguments: { path: "package.json" },
-          },
-        ],
-      },
-      {
-        role: "toolResult",
-        toolCallId: "call_123|fc_456",
-        toolName: "read",
-        content: [{ type: "text", text: "ok" }],
-        isError: false,
-      },
-    ] satisfies AgentMessage[];
-
-    const out = await sanitizeSessionMessagesImages(input, "test");
-
-    const assistant = out[0] as unknown as { role?: string; content?: unknown };
-    expect(assistant.role).toBe("assistant");
-    expect(Array.isArray(assistant.content)).toBe(true);
-    const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
-      (b) => b.type === "toolCall",
-    );
-    expect(toolCall?.id).toBe("call_123|fc_456");
-
-    const toolResult = out[1] as unknown as {
-      role?: string;
-      toolCallId?: string;
-    };
-    expect(toolResult.role).toBe("toolResult");
-    expect(toolResult.toolCallId).toBe("call_123|fc_456");
-  });
-
-  it("sanitizes tool call + tool result IDs in strict mode (alphanumeric only)", async () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          {
-            type: "toolCall",
-            id: "call_123|fc_456",
-            name: "read",
-            arguments: { path: "package.json" },
-          },
-        ],
-      },
-      {
-        role: "toolResult",
-        toolCallId: "call_123|fc_456",
-        toolName: "read",
-        content: [{ type: "text", text: "ok" }],
-        isError: false,
-      },
-    ] satisfies AgentMessage[];
-
-    const out = await sanitizeSessionMessagesImages(input, "test", {
-      sanitizeToolCallIds: true,
-      toolCallIdMode: "strict",
-    });
-
-    const assistant = out[0] as unknown as { role?: string; content?: unknown };
-    expect(assistant.role).toBe("assistant");
-    expect(Array.isArray(assistant.content)).toBe(true);
-    const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
-      (b) => b.type === "toolCall",
-    );
-    // Strict mode strips all non-alphanumeric characters
-    expect(toolCall?.id).toBe("call123fc456");
-
-    const toolResult = out[1] as unknown as {
-      role?: string;
-      toolCallId?: string;
-    };
-    expect(toolResult.role).toBe("toolResult");
-    expect(toolResult.toolCallId).toBe("call123fc456");
-  });
-  it("does not synthesize tool call input when missing", async () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [{ type: "toolCall", id: "call_1", name: "read" }],
-      },
-    ] satisfies AgentMessage[];
-
-    const out = await sanitizeSessionMessagesImages(input, "test");
-    const assistant = out[0] as { content?: Array<Record<string, unknown>> };
-    const toolCall = assistant.content?.find((b) => b.type === "toolCall");
-    expect(toolCall).toBeTruthy();
-    expect("input" in (toolCall ?? {})).toBe(false);
-    expect("arguments" in (toolCall ?? {})).toBe(false);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.e2e.test.ts
index 4d03c3ffe7f..4770a4b4d34 100644
--- a/src/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.e2e.test.ts
+++ b/src/agents/pi-embedded-helpers.sanitize-session-messages-images.removes-empty-assistant-text-blocks-but-preserves.e2e.test.ts
@@ -1,8 +1,111 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import { describe, expect, it } from "vitest";
-import { sanitizeSessionMessagesImages } from "./pi-embedded-helpers.js";
+import {
+  sanitizeGoogleTurnOrdering,
+  sanitizeSessionMessagesImages,
+} from "./pi-embedded-helpers.js";
 
 describe("sanitizeSessionMessagesImages", () => {
+  it("keeps tool call + tool result IDs unchanged by default", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "call_123|fc_456",
+            name: "read",
+            arguments: { path: "package.json" },
+          },
+        ],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_123|fc_456",
+        toolName: "read",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test");
+
+    const assistant = out[0] as unknown as { role?: string; content?: unknown };
+    expect(assistant.role).toBe("assistant");
+    expect(Array.isArray(assistant.content)).toBe(true);
+    const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
+      (b) => b.type === "toolCall",
+    );
+    expect(toolCall?.id).toBe("call_123|fc_456");
+
+    const toolResult = out[1] as unknown as {
+      role?: string;
+      toolCallId?: string;
+    };
+    expect(toolResult.role).toBe("toolResult");
+    expect(toolResult.toolCallId).toBe("call_123|fc_456");
+  });
+
+  it("sanitizes tool call + tool result IDs in strict mode (alphanumeric only)", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "call_123|fc_456",
+            name: "read",
+            arguments: { path: "package.json" },
+          },
+        ],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_123|fc_456",
+        toolName: "read",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test", {
+      sanitizeToolCallIds: true,
+      toolCallIdMode: "strict",
+    });
+
+    const assistant = out[0] as unknown as { role?: string; content?: unknown };
+    expect(assistant.role).toBe("assistant");
+    expect(Array.isArray(assistant.content)).toBe(true);
+    const toolCall = (assistant.content as Array<{ type?: string; id?: string }>).find(
+      (b) => b.type === "toolCall",
+    );
+    // Strict mode strips all non-alphanumeric characters
+    expect(toolCall?.id).toBe("call123fc456");
+
+    const toolResult = out[1] as unknown as {
+      role?: string;
+      toolCallId?: string;
+    };
+    expect(toolResult.role).toBe("toolResult");
+    expect(toolResult.toolCallId).toBe("call123fc456");
+  });
+
+  it("does not synthesize tool call input when missing", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_1", name: "read" }],
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test");
+    const assistant = out[0] as { content?: Array<Record<string, unknown>> };
+    const toolCall = assistant.content?.find((b) => b.type === "toolCall");
+    expect(toolCall).toBeTruthy();
+    expect("input" in (toolCall ?? {})).toBe(false);
+    expect("arguments" in (toolCall ?? {})).toBe(false);
+  });
+
   it("removes empty assistant text blocks but preserves tool calls", async () => {
     const input = [
       {
@@ -57,6 +160,35 @@ describe("sanitizeSessionMessagesImages", () => {
     const toolResult = out[1] as { toolUseId?: string };
     expect(toolResult.toolUseId).toBe("callabcitem123");
   });
+
+  it("does not sanitize tool IDs in images-only mode", async () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_123|fc_456", name: "read", arguments: {} }],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_123|fc_456",
+        toolName: "read",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = await sanitizeSessionMessagesImages(input, "test", {
+      sanitizeMode: "images-only",
+      sanitizeToolCallIds: true,
+      toolCallIdMode: "strict",
+    });
+
+    const assistant = out[0] as unknown as { content?: Array<{ type?: string; id?: string }> };
+    const toolCall = assistant.content?.find((b) => b.type === "toolCall");
+    expect(toolCall?.id).toBe("call_123|fc_456");
+
+    const toolResult = out[1] as unknown as { toolCallId?: string };
+    expect(toolResult.toolCallId).toBe("call_123|fc_456");
+  });
   it("filters whitespace-only assistant text blocks", async () => {
     const input = [
       {
@@ -117,4 +249,50 @@ describe("sanitizeSessionMessagesImages", () => {
     expect(out[0]?.role).toBe("user");
     expect(out[1]?.role).toBe("toolResult");
   });
+
+  describe("thought_signature stripping", () => {
+    it("strips msg_-prefixed thought_signature from assistant message content blocks", async () => {
+      const input = [
+        {
+          role: "assistant",
+          content: [
+            { type: "text", text: "hello", thought_signature: "msg_abc123" },
+            {
+              type: "thinking",
+              thinking: "reasoning",
+              thought_signature: "AQID",
+            },
+          ],
+        },
+      ] satisfies AgentMessage[];
+
+      const out = await sanitizeSessionMessagesImages(input, "test");
+
+      expect(out).toHaveLength(1);
+      const content = (out[0] as { content?: unknown[] }).content;
+      expect(content).toHaveLength(2);
+      expect("thought_signature" in ((content?.[0] ?? {}) as object)).toBe(false);
+      expect((content?.[1] as { thought_signature?: unknown })?.thought_signature).toBe("AQID");
+    });
+  });
+});
+
+describe("sanitizeGoogleTurnOrdering", () => {
+  it("prepends a synthetic user turn when history starts with assistant", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_1", name: "exec", arguments: {} }],
+      },
+    ] satisfies AgentMessage[];
+
+    const out = sanitizeGoogleTurnOrdering(input);
+    expect(out[0]?.role).toBe("user");
+    expect(out[1]?.role).toBe("assistant");
+  });
+  it("is a no-op when history starts with user", () => {
+    const input = [{ role: "user", content: "hi" }] satisfies AgentMessage[];
+    const out = sanitizeGoogleTurnOrdering(input);
+    expect(out).toBe(input);
+  });
 });
diff --git a/src/agents/pi-embedded-helpers.sanitizegoogleturnordering.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitizegoogleturnordering.e2e.test.ts
deleted file mode 100644
index a12f82367c9..00000000000
--- a/src/agents/pi-embedded-helpers.sanitizegoogleturnordering.e2e.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import type { AgentMessage } from "@mariozechner/pi-agent-core";
-import { describe, expect, it } from "vitest";
-import { sanitizeGoogleTurnOrdering } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("sanitizeGoogleTurnOrdering", () => {
-  it("prepends a synthetic user turn when history starts with assistant", () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [{ type: "toolCall", id: "call_1", name: "exec", arguments: {} }],
-      },
-    ] satisfies AgentMessage[];
-
-    const out = sanitizeGoogleTurnOrdering(input);
-    expect(out[0]?.role).toBe("user");
-    expect(out[1]?.role).toBe("assistant");
-  });
-  it("is a no-op when history starts with user", () => {
-    const input = [{ role: "user", content: "hi" }] satisfies AgentMessage[];
-    const out = sanitizeGoogleTurnOrdering(input);
-    expect(out).toBe(input);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.sanitizesessionmessagesimages-thought-signature-stripping.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitizesessionmessagesimages-thought-signature-stripping.e2e.test.ts
deleted file mode 100644
index 977002ce9a6..00000000000
--- a/src/agents/pi-embedded-helpers.sanitizesessionmessagesimages-thought-signature-stripping.e2e.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import type { AgentMessage } from "@mariozechner/pi-agent-core";
-import { describe, expect, it } from "vitest";
-import { sanitizeSessionMessagesImages } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("sanitizeSessionMessagesImages - thought_signature stripping", () => {
-  it("strips msg_-prefixed thought_signature from assistant message content blocks", async () => {
-    const input = [
-      {
-        role: "assistant",
-        content: [
-          { type: "text", text: "hello", thought_signature: "msg_abc123" },
-          {
-            type: "thinking",
-            thinking: "reasoning",
-            thought_signature: "AQID",
-          },
-        ],
-      },
-    ] satisfies AgentMessage[];
-
-    const out = await sanitizeSessionMessagesImages(input, "test");
-
-    expect(out).toHaveLength(1);
-    const content = (out[0] as { content?: unknown[] }).content;
-    expect(content).toHaveLength(2);
-    expect("thought_signature" in ((content?.[0] ?? {}) as object)).toBe(false);
-    expect((content?.[1] as { thought_signature?: unknown })?.thought_signature).toBe("AQID");
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.sanitizetoolcallid.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitizetoolcallid.e2e.test.ts
deleted file mode 100644
index 71256a71dc6..00000000000
--- a/src/agents/pi-embedded-helpers.sanitizetoolcallid.e2e.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { sanitizeToolCallId } from "./pi-embedded-helpers.js";
-
-describe("sanitizeToolCallId", () => {
-  describe("strict mode (default)", () => {
-    it("keeps valid alphanumeric tool call IDs", () => {
-      expect(sanitizeToolCallId("callabc123")).toBe("callabc123");
-    });
-    it("strips underscores and hyphens", () => {
-      expect(sanitizeToolCallId("call_abc-123")).toBe("callabc123");
-      expect(sanitizeToolCallId("call_abc_def")).toBe("callabcdef");
-    });
-    it("strips invalid characters", () => {
-      expect(sanitizeToolCallId("call_abc|item:456")).toBe("callabcitem456");
-    });
-    it("returns default for empty IDs", () => {
-      expect(sanitizeToolCallId("")).toBe("defaulttoolid");
-    });
-  });
-
-  describe("strict mode (alphanumeric only)", () => {
-    it("strips all non-alphanumeric characters", () => {
-      expect(sanitizeToolCallId("call_abc-123", "strict")).toBe("callabc123");
-      expect(sanitizeToolCallId("call_abc|item:456", "strict")).toBe("callabcitem456");
-      expect(sanitizeToolCallId("whatsapp_login_1768799841527_1", "strict")).toBe(
-        "whatsapplogin17687998415271",
-      );
-    });
-    it("returns default for empty IDs", () => {
-      expect(sanitizeToolCallId("", "strict")).toBe("defaulttoolid");
-    });
-  });
-
-  describe("strict9 mode (Mistral tool call IDs)", () => {
-    it("returns alphanumeric IDs with length 9", () => {
-      const out = sanitizeToolCallId("call_abc|item:456", "strict9");
-      expect(out).toMatch(/^[a-zA-Z0-9]{9}$/);
-    });
-    it("returns default for empty IDs", () => {
-      expect(sanitizeToolCallId("", "strict9")).toMatch(/^[a-zA-Z0-9]{9}$/);
-    });
-  });
-});
diff --git a/src/agents/pi-embedded-helpers.sanitizeuserfacingtext.e2e.test.ts b/src/agents/pi-embedded-helpers.sanitizeuserfacingtext.e2e.test.ts
index 318bb3ce6d2..4d9817f59f6 100644
--- a/src/agents/pi-embedded-helpers.sanitizeuserfacingtext.e2e.test.ts
+++ b/src/agents/pi-embedded-helpers.sanitizeuserfacingtext.e2e.test.ts
@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { sanitizeUserFacingText } from "./pi-embedded-helpers.js";
+import {
+  downgradeOpenAIReasoningBlocks,
+  isMessagingToolDuplicate,
+  normalizeTextForComparison,
+  sanitizeToolCallId,
+  sanitizeUserFacingText,
+  stripThoughtSignatures,
+} from "./pi-embedded-helpers.js";
 
 describe("sanitizeUserFacingText", () => {
   it("strips final tags", () => {
@@ -114,3 +121,278 @@ describe("sanitizeUserFacingText", () => {
     expect(sanitizeUserFacingText("  \n  ")).toBe("");
   });
 });
+
+describe("stripThoughtSignatures", () => {
+  it("returns non-array content unchanged", () => {
+    expect(stripThoughtSignatures("hello")).toBe("hello");
+    expect(stripThoughtSignatures(null)).toBe(null);
+    expect(stripThoughtSignatures(undefined)).toBe(undefined);
+    expect(stripThoughtSignatures(123)).toBe(123);
+  });
+  it("removes msg_-prefixed thought_signature from content blocks", () => {
+    const input = [
+      { type: "text", text: "hello", thought_signature: "msg_abc123" },
+      { type: "thinking", thinking: "test", thought_signature: "AQID" },
+    ];
+    const result = stripThoughtSignatures(input);
+
+    expect(result).toHaveLength(2);
+    expect(result[0]).toEqual({ type: "text", text: "hello" });
+    expect(result[1]).toEqual({
+      type: "thinking",
+      thinking: "test",
+      thought_signature: "AQID",
+    });
+    expect("thought_signature" in result[0]).toBe(false);
+    expect("thought_signature" in result[1]).toBe(true);
+  });
+  it("preserves blocks without thought_signature", () => {
+    const input = [
+      { type: "text", text: "hello" },
+      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
+    ];
+    const result = stripThoughtSignatures(input);
+
+    expect(result).toEqual(input);
+  });
+  it("handles mixed blocks with and without thought_signature", () => {
+    const input = [
+      { type: "text", text: "hello", thought_signature: "msg_abc" },
+      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
+      { type: "thinking", thinking: "hmm", thought_signature: "msg_xyz" },
+    ];
+    const result = stripThoughtSignatures(input);
+
+    expect(result).toEqual([
+      { type: "text", text: "hello" },
+      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
+      { type: "thinking", thinking: "hmm" },
+    ]);
+  });
+  it("handles empty array", () => {
+    expect(stripThoughtSignatures([])).toEqual([]);
+  });
+  it("handles null/undefined blocks in array", () => {
+    const input = [null, undefined, { type: "text", text: "hello" }];
+    const result = stripThoughtSignatures(input);
+    expect(result).toEqual([null, undefined, { type: "text", text: "hello" }]);
+  });
+});
+
+describe("sanitizeToolCallId", () => {
+  describe("strict mode (default)", () => {
+    it("keeps valid alphanumeric tool call IDs", () => {
+      expect(sanitizeToolCallId("callabc123")).toBe("callabc123");
+    });
+    it("strips underscores and hyphens", () => {
+      expect(sanitizeToolCallId("call_abc-123")).toBe("callabc123");
+      expect(sanitizeToolCallId("call_abc_def")).toBe("callabcdef");
+    });
+    it("strips invalid characters", () => {
+      expect(sanitizeToolCallId("call_abc|item:456")).toBe("callabcitem456");
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("")).toBe("defaulttoolid");
+    });
+  });
+
+  describe("strict mode (alphanumeric only)", () => {
+    it("strips all non-alphanumeric characters", () => {
+      expect(sanitizeToolCallId("call_abc-123", "strict")).toBe("callabc123");
+      expect(sanitizeToolCallId("call_abc|item:456", "strict")).toBe("callabcitem456");
+      expect(sanitizeToolCallId("whatsapp_login_1768799841527_1", "strict")).toBe(
+        "whatsapplogin17687998415271",
+      );
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("", "strict")).toBe("defaulttoolid");
+    });
+  });
+
+  describe("strict9 mode (Mistral tool call IDs)", () => {
+    it("returns alphanumeric IDs with length 9", () => {
+      const out = sanitizeToolCallId("call_abc|item:456", "strict9");
+      expect(out).toMatch(/^[a-zA-Z0-9]{9}$/);
+    });
+    it("returns default for empty IDs", () => {
+      expect(sanitizeToolCallId("", "strict9")).toMatch(/^[a-zA-Z0-9]{9}$/);
+    });
+  });
+});
+
+describe("downgradeOpenAIReasoningBlocks", () => {
+  it("keeps reasoning signatures when followed by content", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "internal reasoning",
+            thinkingSignature: JSON.stringify({ id: "rs_123", type: "reasoning" }),
+          },
+          { type: "text", text: "answer" },
+        ],
+      },
+    ];
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual(input);
+  });
+
+  it("drops orphaned reasoning blocks without following content", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinkingSignature: JSON.stringify({ id: "rs_abc", type: "reasoning" }),
+          },
+        ],
+      },
+      { role: "user", content: "next" },
+    ];
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual([
+      { role: "user", content: "next" },
+    ]);
+  });
+
+  it("drops object-form orphaned signatures", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinkingSignature: { id: "rs_obj", type: "reasoning" },
+          },
+        ],
+      },
+    ];
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual([]);
+  });
+
+  it("keeps non-reasoning thinking signatures", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinking: "t",
+            thinkingSignature: "reasoning_content",
+          },
+        ],
+      },
+    ];
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    expect(downgradeOpenAIReasoningBlocks(input as any)).toEqual(input);
+  });
+
+  it("is idempotent for orphaned reasoning cleanup", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "thinking",
+            thinkingSignature: JSON.stringify({ id: "rs_orphan", type: "reasoning" }),
+          },
+        ],
+      },
+      { role: "user", content: "next" },
+    ];
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const once = downgradeOpenAIReasoningBlocks(input as any);
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const twice = downgradeOpenAIReasoningBlocks(once as any);
+    expect(twice).toEqual(once);
+  });
+});
+
+describe("normalizeTextForComparison", () => {
+  it("lowercases text", () => {
+    expect(normalizeTextForComparison("Hello World")).toBe("hello world");
+  });
+
+  it("trims whitespace", () => {
+    expect(normalizeTextForComparison("  hello  ")).toBe("hello");
+  });
+
+  it("collapses multiple spaces", () => {
+    expect(normalizeTextForComparison("hello    world")).toBe("hello world");
+  });
+
+  it("strips emoji", () => {
+    expect(normalizeTextForComparison("Hello 👋 World 🌍")).toBe("hello world");
+  });
+
+  it("handles mixed normalization", () => {
+    expect(normalizeTextForComparison("  Hello 👋   WORLD  🌍  ")).toBe("hello world");
+  });
+});
+
+describe("isMessagingToolDuplicate", () => {
+  it("returns false for empty sentTexts", () => {
+    expect(isMessagingToolDuplicate("hello world", [])).toBe(false);
+  });
+
+  it("returns false for short texts", () => {
+    expect(isMessagingToolDuplicate("short", ["short"])).toBe(false);
+  });
+
+  it("detects exact duplicates", () => {
+    expect(
+      isMessagingToolDuplicate("Hello, this is a test message!", [
+        "Hello, this is a test message!",
+      ]),
+    ).toBe(true);
+  });
+
+  it("detects duplicates with different casing", () => {
+    expect(
+      isMessagingToolDuplicate("HELLO, THIS IS A TEST MESSAGE!", [
+        "hello, this is a test message!",
+      ]),
+    ).toBe(true);
+  });
+
+  it("detects duplicates with emoji variations", () => {
+    expect(
+      isMessagingToolDuplicate("Hello! 👋 This is a test message!", [
+        "Hello! This is a test message!",
+      ]),
+    ).toBe(true);
+  });
+
+  it("detects substring duplicates (LLM elaboration)", () => {
+    expect(
+      isMessagingToolDuplicate('I sent the message: "Hello, this is a test message!"', [
+        "Hello, this is a test message!",
+      ]),
+    ).toBe(true);
+  });
+
+  it("detects when sent text contains block reply (reverse substring)", () => {
+    expect(
+      isMessagingToolDuplicate("Hello, this is a test message!", [
+        'I sent the message: "Hello, this is a test message!"',
+      ]),
+    ).toBe(true);
+  });
+
+  it("returns false for non-matching texts", () => {
+    expect(
+      isMessagingToolDuplicate("This is completely different content.", [
+        "Hello, this is a test message!",
+      ]),
+    ).toBe(false);
+  });
+});
diff --git a/src/agents/pi-embedded-helpers.stripthoughtsignatures.e2e.test.ts b/src/agents/pi-embedded-helpers.stripthoughtsignatures.e2e.test.ts
deleted file mode 100644
index 84ac4274fe4..00000000000
--- a/src/agents/pi-embedded-helpers.stripthoughtsignatures.e2e.test.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { stripThoughtSignatures } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";
-
-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
-describe("stripThoughtSignatures", () => {
-  it("returns non-array content unchanged", () => {
-    expect(stripThoughtSignatures("hello")).toBe("hello");
-    expect(stripThoughtSignatures(null)).toBe(null);
-    expect(stripThoughtSignatures(undefined)).toBe(undefined);
-    expect(stripThoughtSignatures(123)).toBe(123);
-  });
-  it("removes msg_-prefixed thought_signature from content blocks", () => {
-    const input = [
-      { type: "text", text: "hello", thought_signature: "msg_abc123" },
-      { type: "thinking", thinking: "test", thought_signature: "AQID" },
-    ];
-    const result = stripThoughtSignatures(input);
-
-    expect(result).toHaveLength(2);
-    expect(result[0]).toEqual({ type: "text", text: "hello" });
-    expect(result[1]).toEqual({
-      type: "thinking",
-      thinking: "test",
-      thought_signature: "AQID",
-    });
-    expect("thought_signature" in result[0]).toBe(false);
-    expect("thought_signature" in result[1]).toBe(true);
-  });
-  it("preserves blocks without thought_signature", () => {
-    const input = [
-      { type: "text", text: "hello" },
-      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
-    ];
-    const result = stripThoughtSignatures(input);
-
-    expect(result).toEqual(input);
-  });
-  it("handles mixed blocks with and without thought_signature", () => {
-    const input = [
-      { type: "text", text: "hello", thought_signature: "msg_abc" },
-      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
-      { type: "thinking", thinking: "hmm", thought_signature: "msg_xyz" },
-    ];
-    const result = stripThoughtSignatures(input);
-
-    expect(result).toEqual([
-      { type: "text", text: "hello" },
-      { type: "toolCall", id: "call_1", name: "read", arguments: {} },
-      { type: "thinking", thinking: "hmm" },
-    ]);
-  });
-  it("handles empty array", () => {
-    expect(stripThoughtSignatures([])).toEqual([]);
-  });
-  it("handles null/undefined blocks in array", () => {
-    const input = [null, undefined, { type: "text", text: "hello" }];
-    const result = stripThoughtSignatures(input);
-    expect(result).toEqual([null, undefined, { type: "text", text: "hello" }]);
-  });
-});
diff --git a/src/agents/pi-embedded-helpers/images.ts b/src/agents/pi-embedded-helpers/images.ts
index 3af4dd0a677..9162bb812b4 100644
--- a/src/agents/pi-embedded-helpers/images.ts
+++ b/src/agents/pi-embedded-helpers/images.ts
@@ -51,9 +51,10 @@ export async function sanitizeSessionMessagesImages(
   const allowNonImageSanitization = sanitizeMode === "full";
   // We sanitize historical session messages because Anthropic can reject a request
   // if the transcript contains oversized base64 images (see MAX_IMAGE_DIMENSION_PX).
-  const sanitizedIds = options?.sanitizeToolCallIds
-    ? sanitizeToolCallIdsForCloudCodeAssist(messages, options.toolCallIdMode)
-    : messages;
+  const sanitizedIds =
+    allowNonImageSanitization && options?.sanitizeToolCallIds
+      ? sanitizeToolCallIdsForCloudCodeAssist(messages, options.toolCallIdMode)
+      : messages;
   const out: AgentMessage[] = [];
   for (const msg of sanitizedIds) {
     if (!msg || typeof msg !== "object") {
diff --git a/src/agents/pi-embedded-runner.openai-tool-id-preservation.e2e.test.ts b/src/agents/pi-embedded-runner.openai-tool-id-preservation.e2e.test.ts
new file mode 100644
index 00000000000..115d0a22b67
--- /dev/null
+++ b/src/agents/pi-embedded-runner.openai-tool-id-preservation.e2e.test.ts
@@ -0,0 +1,50 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import { describe, expect, it } from "vitest";
+import {
+  makeInMemorySessionManager,
+  makeModelSnapshotEntry,
+} from "./pi-embedded-runner.sanitize-session-history.test-harness.js";
+import { sanitizeSessionHistory } from "./pi-embedded-runner/google.js";
+
+describe("sanitizeSessionHistory openai tool id preservation", () => {
+  it("keeps canonical call_id|fc_id pairings for same-model openai replay", async () => {
+    const sessionEntries = [
+      makeModelSnapshotEntry({
+        provider: "openai",
+        modelApi: "openai-responses",
+        modelId: "gpt-5.2-codex",
+      }),
+    ];
+    const sessionManager = makeInMemorySessionManager(sessionEntries);
+
+    const messages: AgentMessage[] = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_123|fc_123", name: "noop", arguments: {} }],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_123|fc_123",
+        toolName: "noop",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      } as unknown as AgentMessage,
+    ];
+
+    const result = await sanitizeSessionHistory({
+      messages,
+      modelApi: "openai-responses",
+      provider: "openai",
+      modelId: "gpt-5.2-codex",
+      sessionManager,
+      sessionId: "test-session",
+    });
+
+    const assistant = result[0] as { content?: Array<{ type?: string; id?: string }> };
+    const toolCall = assistant.content?.find((block) => block.type === "toolCall");
+    expect(toolCall?.id).toBe("call_123|fc_123");
+
+    const toolResult = result[1] as { toolCallId?: string };
+    expect(toolResult.toolCallId).toBe("call_123|fc_123");
+  });
+});
diff --git a/src/agents/pi-embedded-runner.sanitize-session-history.e2e.test.ts b/src/agents/pi-embedded-runner.sanitize-session-history.e2e.test.ts
index c3f58100662..d4f4488b6dc 100644
--- a/src/agents/pi-embedded-runner.sanitize-session-history.e2e.test.ts
+++ b/src/agents/pi-embedded-runner.sanitize-session-history.e2e.test.ts
@@ -52,7 +52,7 @@ describe("sanitizeSessionHistory e2e smoke", () => {
     );
   });
 
-  it("applies strict tool-call sanitization for openai-responses", async () => {
+  it("keeps images-only sanitize policy without tool-call id rewriting for openai-responses", async () => {
     vi.mocked(helpers.isGoogleModelApi).mockReturnValue(false);
 
     await sanitizeSessionHistory({
@@ -68,8 +68,7 @@ describe("sanitizeSessionHistory e2e smoke", () => {
       "session:history",
       expect.objectContaining({
         sanitizeMode: "images-only",
-        sanitizeToolCallIds: true,
-        toolCallIdMode: "strict",
+        sanitizeToolCallIds: false,
       }),
     );
   });
diff --git a/src/agents/pi-embedded-runner.sanitize-session-history.test.ts b/src/agents/pi-embedded-runner.sanitize-session-history.test.ts
index a36c5ba0b44..ca463a2e358 100644
--- a/src/agents/pi-embedded-runner.sanitize-session-history.test.ts
+++ b/src/agents/pi-embedded-runner.sanitize-session-history.test.ts
@@ -98,7 +98,7 @@ describe("sanitizeSessionHistory", () => {
     );
   });
 
-  it("sanitizes tool call ids for openai-responses while keeping images-only mode", async () => {
+  it("does not sanitize tool call ids for openai-responses", async () => {
     vi.mocked(helpers.isGoogleModelApi).mockReturnValue(false);
 
     await sanitizeSessionHistory({
@@ -112,11 +112,7 @@ describe("sanitizeSessionHistory", () => {
     expect(helpers.sanitizeSessionMessagesImages).toHaveBeenCalledWith(
       mockMessages,
       "session:history",
-      expect.objectContaining({
-        sanitizeMode: "images-only",
-        sanitizeToolCallIds: true,
-        toolCallIdMode: "strict",
-      }),
+      expect.objectContaining({ sanitizeMode: "images-only", sanitizeToolCallIds: false }),
     );
   });
 
@@ -243,7 +239,7 @@ describe("sanitizeSessionHistory", () => {
     expect(result).toEqual(messages);
   });
 
-  it("downgrades openai reasoning only when the model changes", async () => {
+  it("downgrades openai reasoning when the model changes", async () => {
     const sessionEntries = [
       makeModelSnapshotEntry({
         provider: "anthropic",
diff --git a/src/agents/pi-embedded-runner/compact.ts b/src/agents/pi-embedded-runner/compact.ts
index 48cf6a69de0..05f8cd4581e 100644
--- a/src/agents/pi-embedded-runner/compact.ts
+++ b/src/agents/pi-embedded-runner/compact.ts
@@ -252,16 +252,7 @@ export async function compactEmbeddedPiSessionDirect(
 
   const provider = (params.provider ?? DEFAULT_PROVIDER).trim() || DEFAULT_PROVIDER;
   const modelId = (params.model ?? DEFAULT_MODEL).trim() || DEFAULT_MODEL;
-  const agentDir = params.agentDir ?? resolveOpenClawAgentDir();
-  await ensureOpenClawModelsJson(params.config, agentDir);
-  const { model, error, authStorage, modelRegistry } = resolveModel(
-    provider,
-    modelId,
-    agentDir,
-    params.config,
-  );
-  if (!model) {
-    const reason = error ?? `Unknown model: ${provider}/${modelId}`;
+  const fail = (reason: string): EmbeddedPiCompactResult => {
     log.warn(
       `[compaction-diag] end runId=${runId} sessionKey=${params.sessionKey ?? params.sessionId} ` +
         `diagId=${diagId} trigger=${trigger} provider=${provider}/${modelId} ` +
@@ -273,6 +264,18 @@ export async function compactEmbeddedPiSessionDirect(
       compacted: false,
       reason,
     };
+  };
+  const agentDir = params.agentDir ?? resolveOpenClawAgentDir();
+  await ensureOpenClawModelsJson(params.config, agentDir);
+  const { model, error, authStorage, modelRegistry } = resolveModel(
+    provider,
+    modelId,
+    agentDir,
+    params.config,
+  );
+  if (!model) {
+    const reason = error ?? `Unknown model: ${provider}/${modelId}`;
+    return fail(reason);
   }
   try {
     const apiKeyInfo = await getApiKeyForModel({
@@ -299,17 +302,7 @@ export async function compactEmbeddedPiSessionDirect(
     }
   } catch (err) {
     const reason = describeUnknownError(err);
-    log.warn(
-      `[compaction-diag] end runId=${runId} sessionKey=${params.sessionKey ?? params.sessionId} ` +
-        `diagId=${diagId} trigger=${trigger} provider=${provider}/${modelId} ` +
-        `attempt=${attempt} maxAttempts=${maxAttempts} outcome=failed reason=${classifyCompactionReason(reason)} ` +
-        `durationMs=${Date.now() - startedAt}`,
-    );
-    return {
-      ok: false,
-      compacted: false,
-      reason,
-    };
+    return fail(reason);
   }
 
   await fs.mkdir(resolvedWorkspace, { recursive: true });
@@ -711,17 +704,7 @@ export async function compactEmbeddedPiSessionDirect(
     }
   } catch (err) {
     const reason = describeUnknownError(err);
-    log.warn(
-      `[compaction-diag] end runId=${runId} sessionKey=${params.sessionKey ?? params.sessionId} ` +
-        `diagId=${diagId} trigger=${trigger} provider=${provider}/${modelId} ` +
-        `attempt=${attempt} maxAttempts=${maxAttempts} outcome=failed reason=${classifyCompactionReason(reason)} ` +
-        `durationMs=${Date.now() - startedAt}`,
-    );
-    return {
-      ok: false,
-      compacted: false,
-      reason,
-    };
+    return fail(reason);
   } finally {
     restoreSkillEnv?.();
     process.chdir(prevCwd);
diff --git a/src/agents/pi-embedded-runner/run.overflow-compaction.e2e.test.ts b/src/agents/pi-embedded-runner/run.overflow-compaction.e2e.test.ts
index 20097404db5..2e51e8a2952 100644
--- a/src/agents/pi-embedded-runner/run.overflow-compaction.e2e.test.ts
+++ b/src/agents/pi-embedded-runner/run.overflow-compaction.e2e.test.ts
@@ -5,31 +5,6 @@ vi.mock("../../utils.js", () => ({
   resolveUserPath: vi.fn((p: string) => p),
 }));
 
-vi.mock("../auth-profiles.js", () => ({
-  markAuthProfileFailure: vi.fn(async () => {}),
-  markAuthProfileGood: vi.fn(async () => {}),
-  markAuthProfileUsed: vi.fn(async () => {}),
-}));
-
-vi.mock("../usage.js", () => ({
-  normalizeUsage: vi.fn((usage?: unknown) =>
-    usage && typeof usage === "object" ? usage : undefined,
-  ),
-  derivePromptTokens: vi.fn(
-    (usage?: { input?: number; cacheRead?: number; cacheWrite?: number }) => {
-      if (!usage) {
-        return undefined;
-      }
-      const input = usage.input ?? 0;
-      const cacheRead = usage.cacheRead ?? 0;
-      const cacheWrite = usage.cacheWrite ?? 0;
-      const sum = input + cacheRead + cacheWrite;
-      return sum > 0 ? sum : undefined;
-    },
-  ),
-  hasNonzeroUsage: vi.fn(() => false),
-}));
-
 vi.mock("../pi-embedded-helpers.js", async () => {
   return {
     isCompactionFailureError: (msg?: string) => {
diff --git a/src/agents/pi-embedded-runner/run.overflow-compaction.mocks.shared.ts b/src/agents/pi-embedded-runner/run.overflow-compaction.mocks.shared.ts
index 407788564ab..6a872721859 100644
--- a/src/agents/pi-embedded-runner/run.overflow-compaction.mocks.shared.ts
+++ b/src/agents/pi-embedded-runner/run.overflow-compaction.mocks.shared.ts
@@ -1,5 +1,31 @@
 import { vi } from "vitest";
 
+vi.mock("../auth-profiles.js", () => ({
+  isProfileInCooldown: vi.fn(() => false),
+  markAuthProfileFailure: vi.fn(async () => {}),
+  markAuthProfileGood: vi.fn(async () => {}),
+  markAuthProfileUsed: vi.fn(async () => {}),
+}));
+
+vi.mock("../usage.js", () => ({
+  normalizeUsage: vi.fn((usage?: unknown) =>
+    usage && typeof usage === "object" ? usage : undefined,
+  ),
+  derivePromptTokens: vi.fn(
+    (usage?: { input?: number; cacheRead?: number; cacheWrite?: number }) => {
+      if (!usage) {
+        return undefined;
+      }
+      const input = usage.input ?? 0;
+      const cacheRead = usage.cacheRead ?? 0;
+      const cacheWrite = usage.cacheWrite ?? 0;
+      const sum = input + cacheRead + cacheWrite;
+      return sum > 0 ? sum : undefined;
+    },
+  ),
+  hasNonzeroUsage: vi.fn(() => false),
+}));
+
 vi.mock("./run/attempt.js", () => ({
   runEmbeddedAttempt: vi.fn(),
 }));
diff --git a/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts b/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts
index ded9da42c02..20944a29bad 100644
--- a/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts
+++ b/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts
@@ -1,31 +1,6 @@
 import "./run.overflow-compaction.mocks.shared.js";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-vi.mock("../auth-profiles.js", () => ({
-  isProfileInCooldown: vi.fn(() => false),
-  markAuthProfileFailure: vi.fn(async () => {}),
-  markAuthProfileGood: vi.fn(async () => {}),
-  markAuthProfileUsed: vi.fn(async () => {}),
-}));
-
-vi.mock("../usage.js", () => ({
-  normalizeUsage: vi.fn((usage?: unknown) =>
-    usage && typeof usage === "object" ? usage : undefined,
-  ),
-  derivePromptTokens: vi.fn(
-    (usage?: { input?: number; cacheRead?: number; cacheWrite?: number }) => {
-      if (!usage) {
-        return undefined;
-      }
-      const input = usage.input ?? 0;
-      const cacheRead = usage.cacheRead ?? 0;
-      const cacheWrite = usage.cacheWrite ?? 0;
-      const sum = input + cacheRead + cacheWrite;
-      return sum > 0 ? sum : undefined;
-    },
-  ),
-}));
-
 vi.mock("../workspace-run.js", () => ({
   resolveRunWorkspaceDir: vi.fn((params: { workspaceDir: string }) => ({
     workspaceDir: params.workspaceDir,
diff --git a/src/agents/pi-embedded-runner/run/attempt.ts b/src/agents/pi-embedded-runner/run/attempt.ts
index 9fafd965c7c..dc648e44280 100644
--- a/src/agents/pi-embedded-runner/run/attempt.ts
+++ b/src/agents/pi-embedded-runner/run/attempt.ts
@@ -770,7 +770,7 @@ export async function runEmbeddedAttempt(
         isCompacting: () => subscription.isCompacting(),
         abort: abortRun,
       };
-      setActiveEmbeddedRun(params.sessionId, queueHandle);
+      setActiveEmbeddedRun(params.sessionId, queueHandle, params.sessionKey);
 
       let abortWarnTimer: NodeJS.Timeout | undefined;
       const isProbeSession = params.sessionId?.startsWith("probe-") ?? false;
@@ -954,6 +954,32 @@ export async function runEmbeddedAttempt(
             );
           }
 
+          if (hookRunner?.hasHooks("llm_input")) {
+            hookRunner
+              .runLlmInput(
+                {
+                  runId: params.runId,
+                  sessionId: params.sessionId,
+                  provider: params.provider,
+                  model: params.modelId,
+                  systemPrompt: systemPromptText,
+                  prompt: effectivePrompt,
+                  historyMessages: activeSession.messages,
+                  imagesCount: imageResult.images.length,
+                },
+                {
+                  agentId: hookAgentId,
+                  sessionKey: params.sessionKey,
+                  sessionId: params.sessionId,
+                  workspaceDir: params.workspaceDir,
+                  messageProvider: params.messageProvider ?? undefined,
+                },
+              )
+              .catch((err) => {
+                log.warn(`llm_input hook failed: ${String(err)}`);
+              });
+          }
+
           // Only pass images option if there are actually images to pass
           // This avoids potential issues with models that don't expect the images parameter
           if (imageResult.images.length > 0) {
@@ -1087,7 +1113,7 @@ export async function runEmbeddedAttempt(
             `CRITICAL: unsubscribe failed, possible resource leak: runId=${params.runId} ${String(err)}`,
           );
         }
-        clearActiveEmbeddedRun(params.sessionId, queueHandle);
+        clearActiveEmbeddedRun(params.sessionId, queueHandle, params.sessionKey);
         params.abortSignal?.removeEventListener?.("abort", onAbort);
       }
 
@@ -1103,6 +1129,31 @@ export async function runEmbeddedAttempt(
         )
         .map((entry) => ({ toolName: entry.toolName, meta: entry.meta }));
 
+      if (hookRunner?.hasHooks("llm_output")) {
+        hookRunner
+          .runLlmOutput(
+            {
+              runId: params.runId,
+              sessionId: params.sessionId,
+              provider: params.provider,
+              model: params.modelId,
+              assistantTexts,
+              lastAssistant,
+              usage: getUsageTotals(),
+            },
+            {
+              agentId: hookAgentId,
+              sessionKey: params.sessionKey,
+              sessionId: params.sessionId,
+              workspaceDir: params.workspaceDir,
+              messageProvider: params.messageProvider ?? undefined,
+            },
+          )
+          .catch((err) => {
+            log.warn(`llm_output hook failed: ${String(err)}`);
+          });
+      }
+
       return {
         aborted,
         timedOut,
diff --git a/src/agents/pi-embedded-runner/runs.ts b/src/agents/pi-embedded-runner/runs.ts
index e0155874028..41dad4df582 100644
--- a/src/agents/pi-embedded-runner/runs.ts
+++ b/src/agents/pi-embedded-runner/runs.ts
@@ -115,11 +115,16 @@ function notifyEmbeddedRunEnded(sessionId: string) {
   }
 }
 
-export function setActiveEmbeddedRun(sessionId: string, handle: EmbeddedPiQueueHandle) {
+export function setActiveEmbeddedRun(
+  sessionId: string,
+  handle: EmbeddedPiQueueHandle,
+  sessionKey?: string,
+) {
   const wasActive = ACTIVE_EMBEDDED_RUNS.has(sessionId);
   ACTIVE_EMBEDDED_RUNS.set(sessionId, handle);
   logSessionStateChange({
     sessionId,
+    sessionKey,
     state: "processing",
     reason: wasActive ? "run_replaced" : "run_started",
   });
@@ -128,10 +133,14 @@ export function setActiveEmbeddedRun(sessionId: string, handle: EmbeddedPiQueueH
   }
 }
 
-export function clearActiveEmbeddedRun(sessionId: string, handle: EmbeddedPiQueueHandle) {
+export function clearActiveEmbeddedRun(
+  sessionId: string,
+  handle: EmbeddedPiQueueHandle,
+  sessionKey?: string,
+) {
   if (ACTIVE_EMBEDDED_RUNS.get(sessionId) === handle) {
     ACTIVE_EMBEDDED_RUNS.delete(sessionId);
-    logSessionStateChange({ sessionId, state: "idle", reason: "run_completed" });
+    logSessionStateChange({ sessionId, sessionKey, state: "idle", reason: "run_completed" });
     if (!sessionId.startsWith("probe-")) {
       diag.debug(`run cleared: sessionId=${sessionId} totalActive=${ACTIVE_EMBEDDED_RUNS.size}`);
     }
diff --git a/src/agents/pi-embedded-subscribe.e2e-harness.ts b/src/agents/pi-embedded-subscribe.e2e-harness.ts
new file mode 100644
index 00000000000..64975e8c72c
--- /dev/null
+++ b/src/agents/pi-embedded-subscribe.e2e-harness.ts
@@ -0,0 +1,28 @@
+type SubscribeEmbeddedPiSession =
+  typeof import("./pi-embedded-subscribe.js").subscribeEmbeddedPiSession;
+type PiSession = Parameters<SubscribeEmbeddedPiSession>[0]["session"];
+
+export function createStubSessionHarness(): {
+  session: PiSession;
+  emit: (evt: unknown) => void;
+} {
+  let handler: ((evt: unknown) => void) | undefined;
+  const session = {
+    subscribe: (fn: (evt: unknown) => void) => {
+      handler = fn;
+      return () => {};
+    },
+  } as unknown as PiSession;
+
+  return { session, emit: (evt: unknown) => handler?.(evt) };
+}
+
+export function extractAgentEventPayloads(calls: Array<unknown[]>): Array<Record<string, unknown>> {
+  return calls
+    .map((call) => {
+      const first = call?.[0] as { data?: unknown } | undefined;
+      const data = first?.data;
+      return data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
+    })
+    .filter((value): value is Record<string, unknown> => Boolean(value));
+}
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.calls-onblockreplyflush-before-tool-execution-start-preserve.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.calls-onblockreplyflush-before-tool-execution-start-preserve.e2e.test.ts
index 30336ed38ec..020d7e939d4 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.calls-onblockreplyflush-before-tool-execution-start-preserve.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.calls-onblockreplyflush-before-tool-execution-start-preserve.e2e.test.ts
@@ -8,13 +8,6 @@ type StubSession = {
 type SessionEventHandler = (evt: unknown) => void;
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("calls onBlockReplyFlush before tool_execution_start to preserve message boundaries", () => {
     let handler: SessionEventHandler | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-append-text-end-content-is.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-append-text-end-content-is.e2e.test.ts
index 690a1d7abf4..c268c11ff86 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-append-text-end-content-is.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-append-text-end-content-is.e2e.test.ts
@@ -6,13 +6,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   function setupTextEndSubscription() {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-call-onblockreplyflush-callback-is-not.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-call-onblockreplyflush-callback-is-not.e2e.test.ts
index 60460571309..1a909ae2746 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-call-onblockreplyflush-callback-is-not.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-call-onblockreplyflush-callback-is-not.e2e.test.ts
@@ -8,13 +8,6 @@ type StubSession = {
 type SessionEventHandler = (evt: unknown) => void;
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("does not call onBlockReplyFlush when callback is not provided", () => {
     let handler: SessionEventHandler | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-duplicate-text-end-repeats-full.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-duplicate-text-end-repeats-full.e2e.test.ts
index 00138a7f9ab..a68984b272d 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-duplicate-text-end-repeats-full.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-duplicate-text-end-repeats-full.e2e.test.ts
@@ -6,13 +6,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("does not duplicate when text_end repeats full content", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-emit-duplicate-block-replies-text.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-emit-duplicate-block-replies-text.e2e.test.ts
index 827c58193fd..ee7037a24c0 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-emit-duplicate-block-replies-text.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.does-not-emit-duplicate-block-replies-text.e2e.test.ts
@@ -1,40 +1,22 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { describe, expect, it, vi } from "vitest";
+import { createStubSessionHarness } from "./pi-embedded-subscribe.e2e-harness.js";
 import { subscribeEmbeddedPiSession } from "./pi-embedded-subscribe.js";
 
-type StubSession = {
-  subscribe: (fn: (evt: unknown) => void) => () => void;
-};
-
-type SessionEventHandler = (evt: unknown) => void;
-
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("does not emit duplicate block replies when text_end repeats", () => {
-    let handler: SessionEventHandler | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onBlockReply = vi.fn();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       onBlockReply,
       blockReplyBreak: "text_end",
     });
 
-    handler?.({
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -43,7 +25,7 @@ describe("subscribeEmbeddedPiSession", () => {
       },
     });
 
-    handler?.({
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -51,7 +33,7 @@ describe("subscribeEmbeddedPiSession", () => {
       },
     });
 
-    handler?.({
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -63,16 +45,10 @@ describe("subscribeEmbeddedPiSession", () => {
     expect(subscription.assistantTexts).toEqual(["Hello block"]);
   });
   it("does not duplicate assistantTexts when message_end repeats", () => {
-    let handler: SessionEventHandler | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
     });
 
@@ -81,22 +57,16 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text: "Hello world" }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessage });
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
     expect(subscription.assistantTexts).toEqual(["Hello world"]);
   });
   it("does not duplicate assistantTexts when message_end repeats with trailing whitespace changes", () => {
-    let handler: SessionEventHandler | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
     });
 
@@ -110,22 +80,16 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text: "Hello world" }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessageWithNewline });
-    handler?.({ type: "message_end", message: assistantMessageTrimmed });
+    emit({ type: "message_end", message: assistantMessageWithNewline });
+    emit({ type: "message_end", message: assistantMessageTrimmed });
 
     expect(subscription.assistantTexts).toEqual(["Hello world"]);
   });
   it("does not duplicate assistantTexts when message_end repeats with reasoning blocks", () => {
-    let handler: SessionEventHandler | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       reasoningMode: "on",
     });
@@ -138,37 +102,31 @@ describe("subscribeEmbeddedPiSession", () => {
       ],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessage });
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
     expect(subscription.assistantTexts).toEqual(["Hello world"]);
   });
   it("populates assistantTexts for non-streaming models with chunking enabled", () => {
     // Non-streaming models (e.g. zai/glm-4.7): no text_delta events; message_end
     // must still populate assistantTexts so providers can deliver a final reply.
-    let handler: SessionEventHandler | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       blockReplyChunking: { minChars: 50, maxChars: 200 }, // Chunking enabled
     });
 
     // Simulate non-streaming model: only message_start and message_end, no text_delta
-    handler?.({ type: "message_start", message: { role: "assistant" } });
+    emit({ type: "message_start", message: { role: "assistant" } });
 
     const assistantMessage = {
       role: "assistant",
       content: [{ type: "text", text: "Response from non-streaming model" }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
     expect(subscription.assistantTexts).toEqual(["Response from non-streaming model"]);
   });
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.e2e.test.ts
index d8fcf94c91e..7ce844c55a9 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("emits block replies on text_end and does not duplicate on message_end", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.filters-final-suppresses-output-without-start-tag.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.filters-final-suppresses-output-without-start-tag.e2e.test.ts
index ad7bdfd81cb..76a51a89197 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.filters-final-suppresses-output-without-start-tag.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.filters-final-suppresses-output-without-start-tag.e2e.test.ts
@@ -1,41 +1,28 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { describe, expect, it, vi } from "vitest";
+import {
+  createStubSessionHarness,
+  extractAgentEventPayloads,
+} from "./pi-embedded-subscribe.e2e-harness.js";
 import { subscribeEmbeddedPiSession } from "./pi-embedded-subscribe.js";
 
-type StubSession = {
-  subscribe: (fn: (evt: unknown) => void) => () => void;
-};
-
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("filters to <final> and suppresses output without a start tag", () => {
-    let handler: ((evt: unknown) => void) | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onPartialReply = vi.fn();
     const onAgentEvent = vi.fn();
 
     subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       enforceFinalTag: true,
       onPartialReply,
       onAgentEvent,
     });
 
-    handler?.({ type: "message_start", message: { role: "assistant" } });
-    handler?.({
+    emit({ type: "message_start", message: { role: "assistant" } });
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -50,8 +37,8 @@ describe("subscribeEmbeddedPiSession", () => {
 
     onPartialReply.mockReset();
 
-    handler?.({ type: "message_start", message: { role: "assistant" } });
-    handler?.({
+    emit({ type: "message_start", message: { role: "assistant" } });
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -63,18 +50,12 @@ describe("subscribeEmbeddedPiSession", () => {
     expect(onPartialReply).not.toHaveBeenCalled();
   });
   it("emits agent events on message_end even without <final> tags", () => {
-    let handler: ((evt: unknown) => void) | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onAgentEvent = vi.fn();
 
     subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       enforceFinalTag: true,
       onAgentEvent,
@@ -85,12 +66,10 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text: "Hello world" }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_start", message: assistantMessage });
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_start", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
-    const payloads = onAgentEvent.mock.calls
-      .map((call) => call[0]?.data as Record<string, unknown> | undefined)
-      .filter((value): value is Record<string, unknown> => Boolean(value));
+    const payloads = extractAgentEventPayloads(onAgentEvent.mock.calls);
     expect(payloads).toHaveLength(1);
     expect(payloads[0]?.text).toBe("Hello world");
     expect(payloads[0]?.delta).toBe("Hello world");
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.includes-canvas-action-metadata-tool-summaries.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.includes-canvas-action-metadata-tool-summaries.e2e.test.ts
index 37532c48a86..3b04100219b 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.includes-canvas-action-metadata-tool-summaries.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.includes-canvas-action-metadata-tool-summaries.e2e.test.ts
@@ -6,13 +6,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("includes canvas action metadata in tool summaries", async () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-assistanttexts-final-answer-block-replies-are.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-assistanttexts-final-answer-block-replies-are.e2e.test.ts
index 8b4d539465c..0bb70f3d8b5 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-assistanttexts-final-answer-block-replies-are.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-assistanttexts-final-answer-block-replies-are.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("keeps assistantTexts to the final answer when block replies are disabled", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-indented-fenced-blocks-intact.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-indented-fenced-blocks-intact.e2e.test.ts
index d8d868541ad..507ca49da7b 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-indented-fenced-blocks-intact.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.keeps-indented-fenced-blocks-intact.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("keeps indented fenced blocks intact", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.reopens-fenced-blocks-splitting-inside-them.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.reopens-fenced-blocks-splitting-inside-them.e2e.test.ts
index f786b104f1f..b3d800af04b 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.reopens-fenced-blocks-splitting-inside-them.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.reopens-fenced-blocks-splitting-inside-them.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("reopens fenced blocks when splitting inside them", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.splits-long-single-line-fenced-blocks-reopen.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.splits-long-single-line-fenced-blocks-reopen.e2e.test.ts
index 19cbeaa2a40..f6eeb24a27d 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.splits-long-single-line-fenced-blocks-reopen.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.splits-long-single-line-fenced-blocks-reopen.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("splits long single-line fenced blocks with reopen/close", () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.streams-soft-chunks-paragraph-preference.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.streams-soft-chunks-paragraph-preference.e2e.test.ts
index 59973be7e21..6c1bd3f0b13 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.streams-soft-chunks-paragraph-preference.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.streams-soft-chunks-paragraph-preference.e2e.test.ts
@@ -1,32 +1,16 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { describe, expect, it, vi } from "vitest";
+import { createStubSessionHarness } from "./pi-embedded-subscribe.e2e-harness.js";
 import { subscribeEmbeddedPiSession } from "./pi-embedded-subscribe.js";
 
-type StubSession = {
-  subscribe: (fn: (evt: unknown) => void) => () => void;
-};
-
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("streams soft chunks with paragraph preference", () => {
-    let handler: ((evt: unknown) => void) | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onBlockReply = vi.fn();
 
     const subscription = subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       onBlockReply,
       blockReplyBreak: "message_end",
@@ -39,7 +23,7 @@ describe("subscribeEmbeddedPiSession", () => {
 
     const text = "First block line\n\nSecond block line";
 
-    handler?.({
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -53,7 +37,7 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
     expect(onBlockReply).toHaveBeenCalledTimes(2);
     expect(onBlockReply.mock.calls[0][0].text).toBe("First block line");
@@ -61,18 +45,12 @@ describe("subscribeEmbeddedPiSession", () => {
     expect(subscription.assistantTexts).toEqual(["First block line", "Second block line"]);
   });
   it("avoids splitting inside fenced code blocks", () => {
-    let handler: ((evt: unknown) => void) | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onBlockReply = vi.fn();
 
     subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       onBlockReply,
       blockReplyBreak: "message_end",
@@ -85,7 +63,7 @@ describe("subscribeEmbeddedPiSession", () => {
 
     const text = "Intro\n\n```bash\nline1\nline2\n```\n\nOutro";
 
-    handler?.({
+    emit({
       type: "message_update",
       message: { role: "assistant" },
       assistantMessageEvent: {
@@ -99,7 +77,7 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
     expect(onBlockReply).toHaveBeenCalledTimes(3);
     expect(onBlockReply.mock.calls[0][0].text).toBe("Intro");
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.subscribeembeddedpisession.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.subscribeembeddedpisession.e2e.test.ts
index b53ffa62e53..1371a697d75 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.subscribeembeddedpisession.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.subscribeembeddedpisession.e2e.test.ts
@@ -1,5 +1,9 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { describe, expect, it, vi } from "vitest";
+import {
+  createStubSessionHarness,
+  extractAgentEventPayloads,
+} from "./pi-embedded-subscribe.e2e-harness.js";
 import { subscribeEmbeddedPiSession } from "./pi-embedded-subscribe.js";
 
 type StubSession = {
@@ -186,18 +190,12 @@ describe("subscribeEmbeddedPiSession", () => {
   });
 
   it("emits agent events on message_end for non-streaming assistant text", () => {
-    let handler: ((evt: unknown) => void) | undefined;
-    const session: StubSession = {
-      subscribe: (fn) => {
-        handler = fn;
-        return () => {};
-      },
-    };
+    const { session, emit } = createStubSessionHarness();
 
     const onAgentEvent = vi.fn();
 
     subscribeEmbeddedPiSession({
-      session: session as unknown as Parameters<typeof subscribeEmbeddedPiSession>[0]["session"],
+      session,
       runId: "run",
       onAgentEvent,
     });
@@ -207,12 +205,10 @@ describe("subscribeEmbeddedPiSession", () => {
       content: [{ type: "text", text: "Hello world" }],
     } as AssistantMessage;
 
-    handler?.({ type: "message_start", message: assistantMessage });
-    handler?.({ type: "message_end", message: assistantMessage });
+    emit({ type: "message_start", message: assistantMessage });
+    emit({ type: "message_end", message: assistantMessage });
 
-    const payloads = onAgentEvent.mock.calls
-      .map((call) => call[0]?.data as Record<string, unknown> | undefined)
-      .filter((value): value is Record<string, unknown> => Boolean(value));
+    const payloads = extractAgentEventPayloads(onAgentEvent.mock.calls);
     expect(payloads).toHaveLength(1);
     expect(payloads[0]?.text).toBe("Hello world");
     expect(payloads[0]?.delta).toBe("Hello world");
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.suppresses-message-end-block-replies-message-tool.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.suppresses-message-end-block-replies-message-tool.e2e.test.ts
index a28d55358b4..bb0fff53264 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.suppresses-message-end-block-replies-message-tool.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.suppresses-message-end-block-replies-message-tool.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("suppresses message_end block replies when the message tool already sent", async () => {
     let handler: ((evt: unknown) => void) | undefined;
     const session: StubSession = {
diff --git a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.waits-multiple-compaction-retries-before-resolving.e2e.test.ts b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.waits-multiple-compaction-retries-before-resolving.e2e.test.ts
index 2f961082555..319baf58bf8 100644
--- a/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.waits-multiple-compaction-retries-before-resolving.e2e.test.ts
+++ b/src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.waits-multiple-compaction-retries-before-resolving.e2e.test.ts
@@ -7,13 +7,6 @@ type StubSession = {
 };
 
 describe("subscribeEmbeddedPiSession", () => {
-  const _THINKING_TAG_CASES = [
-    { tag: "think", open: "<think>", close: "</think>" },
-    { tag: "thinking", open: "<thinking>", close: "</thinking>" },
-    { tag: "thought", open: "<thought>", close: "</thought>" },
-    { tag: "antthinking", open: "<antthinking>", close: "</antthinking>" },
-  ] as const;
-
   it("waits for multiple compaction retries before resolving", async () => {
     const listeners: SessionEventHandler[] = [];
     const session = {
diff --git a/src/agents/pi-extensions/compaction-safeguard-runtime.ts b/src/agents/pi-extensions/compaction-safeguard-runtime.ts
index bda1b1de638..df3919cf815 100644
--- a/src/agents/pi-extensions/compaction-safeguard-runtime.ts
+++ b/src/agents/pi-extensions/compaction-safeguard-runtime.ts
@@ -1,35 +1,12 @@
+import { createSessionManagerRuntimeRegistry } from "./session-manager-runtime-registry.js";
+
 export type CompactionSafeguardRuntimeValue = {
   maxHistoryShare?: number;
   contextWindowTokens?: number;
 };
 
-// Session-scoped runtime registry keyed by object identity.
-// Follows the same WeakMap pattern as context-pruning/runtime.ts.
-const REGISTRY = new WeakMap<object, CompactionSafeguardRuntimeValue>();
+const registry = createSessionManagerRuntimeRegistry<CompactionSafeguardRuntimeValue>();
 
-export function setCompactionSafeguardRuntime(
-  sessionManager: unknown,
-  value: CompactionSafeguardRuntimeValue | null,
-): void {
-  if (!sessionManager || typeof sessionManager !== "object") {
-    return;
-  }
+export const setCompactionSafeguardRuntime = registry.set;
 
-  const key = sessionManager;
-  if (value === null) {
-    REGISTRY.delete(key);
-    return;
-  }
-
-  REGISTRY.set(key, value);
-}
-
-export function getCompactionSafeguardRuntime(
-  sessionManager: unknown,
-): CompactionSafeguardRuntimeValue | null {
-  if (!sessionManager || typeof sessionManager !== "object") {
-    return null;
-  }
-
-  return REGISTRY.get(sessionManager) ?? null;
-}
+export const getCompactionSafeguardRuntime = registry.get;
diff --git a/src/agents/pi-extensions/context-pruning/runtime.ts b/src/agents/pi-extensions/context-pruning/runtime.ts
index 7780464d1da..6d4fd07a2fb 100644
--- a/src/agents/pi-extensions/context-pruning/runtime.ts
+++ b/src/agents/pi-extensions/context-pruning/runtime.ts
@@ -1,4 +1,5 @@
 import type { EffectiveContextPruningSettings } from "./settings.js";
+import { createSessionManagerRuntimeRegistry } from "../session-manager-runtime-registry.js";
 
 export type ContextPruningRuntimeValue = {
   settings: EffectiveContextPruningSettings;
@@ -7,34 +8,10 @@ export type ContextPruningRuntimeValue = {
   lastCacheTouchAt?: number | null;
 };
 
-// Session-scoped runtime registry keyed by object identity.
 // Important: this relies on Pi passing the same SessionManager object instance into
 // ExtensionContext (ctx.sessionManager) that we used when calling setContextPruningRuntime.
-const REGISTRY = new WeakMap<object, ContextPruningRuntimeValue>();
+const registry = createSessionManagerRuntimeRegistry<ContextPruningRuntimeValue>();
 
-export function setContextPruningRuntime(
-  sessionManager: unknown,
-  value: ContextPruningRuntimeValue | null,
-): void {
-  if (!sessionManager || typeof sessionManager !== "object") {
-    return;
-  }
+export const setContextPruningRuntime = registry.set;
 
-  const key = sessionManager;
-  if (value === null) {
-    REGISTRY.delete(key);
-    return;
-  }
-
-  REGISTRY.set(key, value);
-}
-
-export function getContextPruningRuntime(
-  sessionManager: unknown,
-): ContextPruningRuntimeValue | null {
-  if (!sessionManager || typeof sessionManager !== "object") {
-    return null;
-  }
-
-  return REGISTRY.get(sessionManager) ?? null;
-}
+export const getContextPruningRuntime = registry.get;
diff --git a/src/agents/pi-extensions/session-manager-runtime-registry.ts b/src/agents/pi-extensions/session-manager-runtime-registry.ts
new file mode 100644
index 00000000000..a23a7385d6a
--- /dev/null
+++ b/src/agents/pi-extensions/session-manager-runtime-registry.ts
@@ -0,0 +1,29 @@
+export function createSessionManagerRuntimeRegistry<TValue>() {
+  // Session-scoped runtime registry keyed by object identity.
+  // The SessionManager instance must stay stable across set/get calls.
+  const registry = new WeakMap<object, TValue>();
+
+  const set = (sessionManager: unknown, value: TValue | null): void => {
+    if (!sessionManager || typeof sessionManager !== "object") {
+      return;
+    }
+
+    const key = sessionManager;
+    if (value === null) {
+      registry.delete(key);
+      return;
+    }
+
+    registry.set(key, value);
+  };
+
+  const get = (sessionManager: unknown): TValue | null => {
+    if (!sessionManager || typeof sessionManager !== "object") {
+      return null;
+    }
+
+    return registry.get(sessionManager) ?? null;
+  };
+
+  return { set, get };
+}
diff --git a/src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping.e2e.test.ts b/src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping.e2e.test.ts
index 6104fc16936..51ccca68c42 100644
--- a/src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping.e2e.test.ts
+++ b/src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping.e2e.test.ts
@@ -102,7 +102,10 @@ describe("createOpenClawCodingTools", () => {
         execute,
       };
 
-      const wrapped = __testing.wrapToolParamNormalization(tool, [{ keys: ["path", "file_path"] }]);
+      const wrapped = __testing.wrapToolParamNormalization(tool, [
+        { keys: ["path", "file_path"], label: "path (path or file_path)" },
+        { keys: ["content"], label: "content" },
+      ]);
 
       await wrapped.execute("tool-1", { file_path: "foo.txt", content: "x" });
       expect(execute).toHaveBeenCalledWith(
@@ -115,9 +118,21 @@ describe("createOpenClawCodingTools", () => {
       await expect(wrapped.execute("tool-2", { content: "x" })).rejects.toThrow(
         /Missing required parameter/,
       );
+      await expect(wrapped.execute("tool-2", { content: "x" })).rejects.toThrow(
+        /Supply correct parameters before retrying\./,
+      );
       await expect(wrapped.execute("tool-3", { file_path: "   ", content: "x" })).rejects.toThrow(
         /Missing required parameter/,
       );
+      await expect(wrapped.execute("tool-3", { file_path: "   ", content: "x" })).rejects.toThrow(
+        /Supply correct parameters before retrying\./,
+      );
+      await expect(wrapped.execute("tool-4", {})).rejects.toThrow(
+        /Missing required parameters: path \(path or file_path\), content/,
+      );
+      await expect(wrapped.execute("tool-4", {})).rejects.toThrow(
+        /Supply correct parameters before retrying\./,
+      );
     });
   });
 
diff --git a/src/agents/pi-tools.read.ts b/src/agents/pi-tools.read.ts
index 3798c6dd8b1..71e9bb72348 100644
--- a/src/agents/pi-tools.read.ts
+++ b/src/agents/pi-tools.read.ts
@@ -87,6 +87,12 @@ type RequiredParamGroup = {
   label?: string;
 };
 
+const RETRY_GUIDANCE_SUFFIX = " Supply correct parameters before retrying.";
+
+function parameterValidationError(message: string): Error {
+  return new Error(`${message}.${RETRY_GUIDANCE_SUFFIX}`);
+}
+
 export const CLAUDE_PARAM_GROUPS = {
   read: [{ keys: ["path", "file_path"], label: "path (path or file_path)" }],
   write: [
@@ -245,9 +251,10 @@ export function assertRequiredParams(
   toolName: string,
 ): void {
   if (!record || typeof record !== "object") {
-    throw new Error(`Missing parameters for ${toolName}`);
+    throw parameterValidationError(`Missing parameters for ${toolName}`);
   }
 
+  const missingLabels: string[] = [];
   for (const group of groups) {
     const satisfied = group.keys.some((key) => {
       if (!(key in record)) {
@@ -265,9 +272,15 @@ export function assertRequiredParams(
 
     if (!satisfied) {
       const label = group.label ?? group.keys.join(" or ");
-      throw new Error(`Missing required parameter: ${label}`);
+      missingLabels.push(label);
     }
   }
+
+  if (missingLabels.length > 0) {
+    const joined = missingLabels.join(", ");
+    const noun = missingLabels.length === 1 ? "parameter" : "parameters";
+    throw parameterValidationError(`Missing required ${noun}: ${joined}`);
+  }
 }
 
 // Generic wrapper to normalize parameters for any tool
diff --git a/src/agents/pi-tools.safe-bins.e2e.test.ts b/src/agents/pi-tools.safe-bins.e2e.test.ts
index 665059035d2..f022a84abc1 100644
--- a/src/agents/pi-tools.safe-bins.e2e.test.ts
+++ b/src/agents/pi-tools.safe-bins.e2e.test.ts
@@ -4,8 +4,9 @@ import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { ExecApprovalsResolved } from "../infra/exec-approvals.js";
+import { captureEnv } from "../test-utils/env.js";
 
-const previousBundledPluginsDir = process.env.OPENCLAW_BUNDLED_PLUGINS_DIR;
+const bundledPluginsDirSnapshot = captureEnv(["OPENCLAW_BUNDLED_PLUGINS_DIR"]);
 
 beforeAll(() => {
   process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = path.join(
@@ -15,32 +16,18 @@ beforeAll(() => {
 });
 
 afterAll(() => {
-  if (previousBundledPluginsDir === undefined) {
-    delete process.env.OPENCLAW_BUNDLED_PLUGINS_DIR;
-  } else {
-    process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = previousBundledPluginsDir;
-  }
+  bundledPluginsDirSnapshot.restore();
 });
 
 vi.mock("../infra/shell-env.js", async (importOriginal) => {
   const mod = await importOriginal<typeof import("../infra/shell-env.js")>();
   return {
     ...mod,
-    getShellPathFromLoginShell: vi.fn(() => "/usr/bin:/bin"),
+    getShellPathFromLoginShell: vi.fn(() => null),
     resolveShellEnvFallbackTimeoutMs: vi.fn(() => 500),
   };
 });
 
-vi.mock("../plugins/tools.js", () => ({
-  getPluginToolMeta: () => undefined,
-  resolvePluginTools: () => [],
-}));
-
-vi.mock("../infra/shell-env.js", async (importOriginal) => {
-  const mod = await importOriginal<typeof import("../infra/shell-env.js")>();
-  return { ...mod, getShellPathFromLoginShell: () => null };
-});
-
 vi.mock("../plugins/tools.js", () => ({
   resolvePluginTools: () => [],
   getPluginToolMeta: () => undefined,
@@ -109,20 +96,16 @@ describe("createOpenClawCodingTools safeBins", () => {
     expect(execTool).toBeDefined();
 
     const marker = `safe-bins-${Date.now()}`;
-    const prevShellEnvTimeoutMs = process.env.OPENCLAW_SHELL_ENV_TIMEOUT_MS;
-    process.env.OPENCLAW_SHELL_ENV_TIMEOUT_MS = "1000";
+    const envSnapshot = captureEnv(["OPENCLAW_SHELL_ENV_TIMEOUT_MS"]);
     const result = await (async () => {
       try {
+        process.env.OPENCLAW_SHELL_ENV_TIMEOUT_MS = "1000";
         return await execTool!.execute("call1", {
           command: `echo ${marker}`,
           workdir: tmpDir,
         });
       } finally {
-        if (prevShellEnvTimeoutMs === undefined) {
-          delete process.env.OPENCLAW_SHELL_ENV_TIMEOUT_MS;
-        } else {
-          process.env.OPENCLAW_SHELL_ENV_TIMEOUT_MS = prevShellEnvTimeoutMs;
-        }
+        envSnapshot.restore();
       }
     })();
     const text = result.content.find((content) => content.type === "text")?.text ?? "";
diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
index 5e72cdb5a19..7ba93ab3810 100644
--- a/src/agents/pi-tools.ts
+++ b/src/agents/pi-tools.ts
@@ -52,6 +52,7 @@ import {
 import {
   applyOwnerOnlyToolPolicy,
   collectExplicitAllowlist,
+  mergeAlsoAllowPolicy,
   resolveToolProfilePolicy,
 } from "./tool-policy.js";
 import { resolveWorkspaceRoot } from "./workspace-dir.js";
@@ -219,15 +220,8 @@ export function createOpenClawCodingTools(options?: {
   const profilePolicy = resolveToolProfilePolicy(profile);
   const providerProfilePolicy = resolveToolProfilePolicy(providerProfile);
 
-  const mergeAlsoAllow = (policy: typeof profilePolicy, alsoAllow?: string[]) => {
-    if (!policy?.allow || !Array.isArray(alsoAllow) || alsoAllow.length === 0) {
-      return policy;
-    }
-    return { ...policy, allow: Array.from(new Set([...policy.allow, ...alsoAllow])) };
-  };
-
-  const profilePolicyWithAlsoAllow = mergeAlsoAllow(profilePolicy, profileAlsoAllow);
-  const providerProfilePolicyWithAlsoAllow = mergeAlsoAllow(
+  const profilePolicyWithAlsoAllow = mergeAlsoAllowPolicy(profilePolicy, profileAlsoAllow);
+  const providerProfilePolicyWithAlsoAllow = mergeAlsoAllowPolicy(
     providerProfilePolicy,
     providerProfileAlsoAllow,
   );
diff --git a/src/agents/pty-dsr.e2e.test.ts b/src/agents/pty-dsr.e2e.test.ts
deleted file mode 100644
index a71f95c0265..00000000000
--- a/src/agents/pty-dsr.e2e.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { expect, test } from "vitest";
-import { buildCursorPositionResponse, stripDsrRequests } from "./pty-dsr.js";
-
-test("stripDsrRequests removes cursor queries and counts them", () => {
-  const input = "hi\x1b[6nthere\x1b[?6n";
-  const { cleaned, requests } = stripDsrRequests(input);
-  expect(cleaned).toBe("hithere");
-  expect(requests).toBe(2);
-});
-
-test("buildCursorPositionResponse returns CPR sequence", () => {
-  expect(buildCursorPositionResponse()).toBe("\x1b[1;1R");
-  expect(buildCursorPositionResponse(12, 34)).toBe("\x1b[12;34R");
-});
diff --git a/src/agents/pty-keys.e2e.test.ts b/src/agents/pty-keys.e2e.test.ts
index a295a11b8b5..36fe6bcdf80 100644
--- a/src/agents/pty-keys.e2e.test.ts
+++ b/src/agents/pty-keys.e2e.test.ts
@@ -1,4 +1,5 @@
 import { expect, test } from "vitest";
+import { buildCursorPositionResponse, stripDsrRequests } from "./pty-dsr.js";
 import {
   BRACKETED_PASTE_END,
   BRACKETED_PASTE_START,
@@ -38,3 +39,15 @@ test("encodePaste wraps bracketed sequences by default", () => {
   expect(payload.startsWith(BRACKETED_PASTE_START)).toBe(true);
   expect(payload.endsWith(BRACKETED_PASTE_END)).toBe(true);
 });
+
+test("stripDsrRequests removes cursor queries and counts them", () => {
+  const input = "hi\x1b[6nthere\x1b[?6n";
+  const { cleaned, requests } = stripDsrRequests(input);
+  expect(cleaned).toBe("hithere");
+  expect(requests).toBe(2);
+});
+
+test("buildCursorPositionResponse returns CPR sequence", () => {
+  expect(buildCursorPositionResponse()).toBe("\x1b[1;1R");
+  expect(buildCursorPositionResponse(12, 34)).toBe("\x1b[12;34R");
+});
diff --git a/src/agents/sandbox-create-args.e2e.test.ts b/src/agents/sandbox-create-args.e2e.test.ts
index 5200572c86e..ccb9b3395ad 100644
--- a/src/agents/sandbox-create-args.e2e.test.ts
+++ b/src/agents/sandbox-create-args.e2e.test.ts
@@ -94,7 +94,7 @@ describe("buildSandboxCreateArgs", () => {
     );
   });
 
-  it("emits -v flags for custom binds", () => {
+  it("emits -v flags for safe custom binds", () => {
     const cfg: SandboxDockerConfig = {
       image: "openclaw-sandbox:bookworm-slim",
       containerPrefix: "openclaw-sbx-",
@@ -103,7 +103,7 @@ describe("buildSandboxCreateArgs", () => {
       tmpfs: [],
       network: "none",
       capDrop: [],
-      binds: ["/home/user/source:/source:rw", "/var/run/docker.sock:/var/run/docker.sock"],
+      binds: ["/home/user/source:/source:rw", "/var/data/myapp:/data:ro"],
     };
 
     const args = buildSandboxCreateArgs({
@@ -124,7 +124,116 @@ describe("buildSandboxCreateArgs", () => {
       }
     }
     expect(vFlags).toContain("/home/user/source:/source:rw");
-    expect(vFlags).toContain("/var/run/docker.sock:/var/run/docker.sock");
+    expect(vFlags).toContain("/var/data/myapp:/data:ro");
+  });
+
+  it("throws on dangerous bind mounts (Docker socket)", () => {
+    const cfg: SandboxDockerConfig = {
+      image: "openclaw-sandbox:bookworm-slim",
+      containerPrefix: "openclaw-sbx-",
+      workdir: "/workspace",
+      readOnlyRoot: false,
+      tmpfs: [],
+      network: "none",
+      capDrop: [],
+      binds: ["/var/run/docker.sock:/var/run/docker.sock"],
+    };
+
+    expect(() =>
+      buildSandboxCreateArgs({
+        name: "openclaw-sbx-dangerous",
+        cfg,
+        scopeKey: "main",
+        createdAtMs: 1700000000000,
+      }),
+    ).toThrow(/blocked path/);
+  });
+
+  it("throws on dangerous bind mounts (parent path)", () => {
+    const cfg: SandboxDockerConfig = {
+      image: "openclaw-sandbox:bookworm-slim",
+      containerPrefix: "openclaw-sbx-",
+      workdir: "/workspace",
+      readOnlyRoot: false,
+      tmpfs: [],
+      network: "none",
+      capDrop: [],
+      binds: ["/run:/run"],
+    };
+
+    expect(() =>
+      buildSandboxCreateArgs({
+        name: "openclaw-sbx-dangerous-parent",
+        cfg,
+        scopeKey: "main",
+        createdAtMs: 1700000000000,
+      }),
+    ).toThrow(/blocked path/);
+  });
+
+  it("throws on network host mode", () => {
+    const cfg: SandboxDockerConfig = {
+      image: "openclaw-sandbox:bookworm-slim",
+      containerPrefix: "openclaw-sbx-",
+      workdir: "/workspace",
+      readOnlyRoot: false,
+      tmpfs: [],
+      network: "host",
+      capDrop: [],
+    };
+
+    expect(() =>
+      buildSandboxCreateArgs({
+        name: "openclaw-sbx-host",
+        cfg,
+        scopeKey: "main",
+        createdAtMs: 1700000000000,
+      }),
+    ).toThrow(/network mode "host" is blocked/);
+  });
+
+  it("throws on seccomp unconfined", () => {
+    const cfg: SandboxDockerConfig = {
+      image: "openclaw-sandbox:bookworm-slim",
+      containerPrefix: "openclaw-sbx-",
+      workdir: "/workspace",
+      readOnlyRoot: false,
+      tmpfs: [],
+      network: "none",
+      capDrop: [],
+      seccompProfile: "unconfined",
+    };
+
+    expect(() =>
+      buildSandboxCreateArgs({
+        name: "openclaw-sbx-seccomp",
+        cfg,
+        scopeKey: "main",
+        createdAtMs: 1700000000000,
+      }),
+    ).toThrow(/seccomp profile "unconfined" is blocked/);
+  });
+
+  it("throws on apparmor unconfined", () => {
+    const cfg: SandboxDockerConfig = {
+      image: "openclaw-sandbox:bookworm-slim",
+      containerPrefix: "openclaw-sbx-",
+      workdir: "/workspace",
+      readOnlyRoot: false,
+      tmpfs: [],
+      network: "none",
+      capDrop: [],
+      apparmorProfile: "unconfined",
+    };
+
+    expect(() =>
+      buildSandboxCreateArgs({
+        name: "openclaw-sbx-apparmor",
+        cfg,
+        scopeKey: "main",
+        createdAtMs: 1700000000000,
+      }),
+    ).toThrow(/apparmor profile "unconfined" is blocked/);
   });
 
   it("omits -v flags when binds is empty or undefined", () => {
diff --git a/src/agents/sandbox-skills.e2e.test.ts b/src/agents/sandbox-skills.e2e.test.ts
index ae37f2a9fe9..0280c5d529a 100644
--- a/src/agents/sandbox-skills.e2e.test.ts
+++ b/src/agents/sandbox-skills.e2e.test.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
+import { captureFullEnv } from "../test-utils/env.js";
 import { resolveSandboxContext } from "./sandbox.js";
 
 vi.mock("./sandbox/docker.js", () => ({
@@ -27,30 +28,15 @@ async function writeSkill(params: { dir: string; name: string; description: stri
   );
 }
 
-function restoreEnv(snapshot: Record<string, string | undefined>) {
-  for (const key of Object.keys(process.env)) {
-    if (!(key in snapshot)) {
-      delete process.env[key];
-    }
-  }
-  for (const [key, value] of Object.entries(snapshot)) {
-    if (value === undefined) {
-      delete process.env[key];
-    } else {
-      process.env[key] = value;
-    }
-  }
-}
-
 describe("sandbox skill mirroring", () => {
-  let envSnapshot: Record<string, string | undefined>;
+  let envSnapshot: ReturnType<typeof captureFullEnv>;
 
   beforeEach(() => {
-    envSnapshot = { ...process.env };
+    envSnapshot = captureFullEnv();
   });
 
   afterEach(() => {
-    restoreEnv(envSnapshot);
+    envSnapshot.restore();
   });
 
   const runContext = async (workspaceAccess: "none" | "ro") => {
diff --git a/src/agents/sandbox/config-hash.test.ts b/src/agents/sandbox/config-hash.test.ts
new file mode 100644
index 00000000000..b00e42821c2
--- /dev/null
+++ b/src/agents/sandbox/config-hash.test.ts
@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import type { SandboxDockerConfig } from "./types.js";
+import { computeSandboxBrowserConfigHash, computeSandboxConfigHash } from "./config-hash.js";
+
+function createDockerConfig(overrides?: Partial<SandboxDockerConfig>): SandboxDockerConfig {
+  return {
+    image: "openclaw-sandbox:test",
+    containerPrefix: "openclaw-sbx-",
+    workdir: "/workspace",
+    readOnlyRoot: true,
+    tmpfs: ["/tmp", "/var/tmp", "/run"],
+    network: "none",
+    capDrop: ["ALL"],
+    env: { LANG: "C.UTF-8" },
+    dns: ["1.1.1.1", "8.8.8.8"],
+    extraHosts: ["host.docker.internal:host-gateway"],
+    binds: ["/tmp/workspace:/workspace:rw", "/tmp/cache:/cache:ro"],
+    ...overrides,
+  };
+}
+
+type DockerArrayField = "tmpfs" | "capDrop" | "dns" | "extraHosts" | "binds";
+
+const ORDER_SENSITIVE_ARRAY_CASES: ReadonlyArray<{
+  field: DockerArrayField;
+  before: string[];
+  after: string[];
+}> = [
+  {
+    field: "tmpfs",
+    before: ["/tmp", "/var/tmp", "/run"],
+    after: ["/run", "/var/tmp", "/tmp"],
+  },
+  {
+    field: "capDrop",
+    before: ["ALL", "CHOWN"],
+    after: ["CHOWN", "ALL"],
+  },
+  {
+    field: "dns",
+    before: ["1.1.1.1", "8.8.8.8"],
+    after: ["8.8.8.8", "1.1.1.1"],
+  },
+  {
+    field: "extraHosts",
+    before: ["host.docker.internal:host-gateway", "db.local:10.0.0.5"],
+    after: ["db.local:10.0.0.5", "host.docker.internal:host-gateway"],
+  },
+  {
+    field: "binds",
+    before: ["/tmp/workspace:/workspace:rw", "/tmp/cache:/cache:ro"],
+    after: ["/tmp/cache:/cache:ro", "/tmp/workspace:/workspace:rw"],
+  },
+];
+
+describe("computeSandboxConfigHash", () => {
+  it("ignores object key order", () => {
+    const shared = {
+      workspaceAccess: "rw" as const,
+      workspaceDir: "/tmp/workspace",
+      agentWorkspaceDir: "/tmp/workspace",
+    };
+    const left = computeSandboxConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        env: {
+          LANG: "C.UTF-8",
+          B: "2",
+          A: "1",
+        },
+      }),
+    });
+    const right = computeSandboxConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        env: {
+          A: "1",
+          B: "2",
+          LANG: "C.UTF-8",
+        },
+      }),
+    });
+    expect(left).toBe(right);
+  });
+
+  it.each(ORDER_SENSITIVE_ARRAY_CASES)("treats $field order as significant", (testCase) => {
+    const shared = {
+      workspaceAccess: "rw" as const,
+      workspaceDir: "/tmp/workspace",
+      agentWorkspaceDir: "/tmp/workspace",
+    };
+    const left = computeSandboxConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        [testCase.field]: testCase.before,
+      } as Partial<SandboxDockerConfig>),
+    });
+    const right = computeSandboxConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        [testCase.field]: testCase.after,
+      } as Partial<SandboxDockerConfig>),
+    });
+    expect(left).not.toBe(right);
+  });
+});
+
+describe("computeSandboxBrowserConfigHash", () => {
+  it("treats docker bind order as significant", () => {
+    const shared = {
+      browser: {
+        cdpPort: 9222,
+        vncPort: 5900,
+        noVncPort: 6080,
+        headless: false,
+        enableNoVnc: true,
+      },
+      workspaceAccess: "rw" as const,
+      workspaceDir: "/tmp/workspace",
+      agentWorkspaceDir: "/tmp/workspace",
+    };
+    const left = computeSandboxBrowserConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        binds: ["/tmp/workspace:/workspace:rw", "/tmp/cache:/cache:ro"],
+      }),
+    });
+    const right = computeSandboxBrowserConfigHash({
+      ...shared,
+      docker: createDockerConfig({
+        binds: ["/tmp/cache:/cache:ro", "/tmp/workspace:/workspace:rw"],
+      }),
+    });
+    expect(left).not.toBe(right);
+  });
+});
diff --git a/src/agents/sandbox/config-hash.ts b/src/agents/sandbox/config-hash.ts
index 3b7b580ef60..ca99dbf4ddb 100644
--- a/src/agents/sandbox/config-hash.ts
+++ b/src/agents/sandbox/config-hash.ts
@@ -1,5 +1,5 @@
-import crypto from "node:crypto";
 import type { SandboxBrowserConfig, SandboxDockerConfig, SandboxWorkspaceAccess } from "./types.js";
+import { hashTextSha256 } from "./hash.js";
 
 type SandboxHashInput = {
   docker: SandboxDockerConfig;
@@ -19,24 +19,12 @@ type SandboxBrowserHashInput = {
   agentWorkspaceDir: string;
 };
 
-function isPrimitive(value: unknown): value is string | number | boolean | bigint | symbol | null {
-  return value === null || (typeof value !== "object" && typeof value !== "function");
-}
 function normalizeForHash(value: unknown): unknown {
   if (value === undefined) {
     return undefined;
   }
   if (Array.isArray(value)) {
-    const normalized = value
-      .map(normalizeForHash)
-      .filter((item): item is unknown => item !== undefined);
-    const primitives = normalized.filter(isPrimitive);
-    if (primitives.length === normalized.length) {
-      return [...primitives].toSorted((a, b) =>
-        primitiveToString(a).localeCompare(primitiveToString(b)),
-      );
-    }
-    return normalized;
+    return value.map(normalizeForHash).filter((item): item is unknown => item !== undefined);
   }
   if (value && typeof value === "object") {
     const entries = Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b));
@@ -52,22 +40,6 @@ function normalizeForHash(value: unknown): unknown {
   return value;
 }
 
-function primitiveToString(value: unknown): string {
-  if (value === null) {
-    return "null";
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof value === "number") {
-    return String(value);
-  }
-  if (typeof value === "boolean") {
-    return value ? "true" : "false";
-  }
-  return JSON.stringify(value);
-}
-
 export function computeSandboxConfigHash(input: SandboxHashInput): string {
   return computeHash(input);
 }
@@ -79,5 +51,5 @@ export function computeSandboxBrowserConfigHash(input: SandboxBrowserHashInput):
 function computeHash(input: unknown): string {
   const payload = normalizeForHash(input);
   const raw = JSON.stringify(payload);
-  return crypto.createHash("sha1").update(raw).digest("hex");
+  return hashTextSha256(raw);
 }
diff --git a/src/agents/sandbox/context.ts b/src/agents/sandbox/context.ts
index 1d365210807..b0eb0ffd9e7 100644
--- a/src/agents/sandbox/context.ts
+++ b/src/agents/sandbox/context.ts
@@ -64,11 +64,7 @@ async function ensureSandboxWorkspaceLayout(params: {
   return { agentWorkspaceDir, scopeKey, sandboxWorkspaceDir, workspaceDir };
 }
 
-export async function resolveSandboxContext(params: {
-  config?: OpenClawConfig;
-  sessionKey?: string;
-  workspaceDir?: string;
-}): Promise<SandboxContext | null> {
+function resolveSandboxSession(params: { config?: OpenClawConfig; sessionKey?: string }) {
   const rawSessionKey = params.sessionKey?.trim();
   if (!rawSessionKey) {
     return null;
@@ -83,6 +79,19 @@ export async function resolveSandboxContext(params: {
   }
 
   const cfg = resolveSandboxConfigForAgent(params.config, runtime.agentId);
+  return { rawSessionKey, runtime, cfg };
+}
+
+export async function resolveSandboxContext(params: {
+  config?: OpenClawConfig;
+  sessionKey?: string;
+  workspaceDir?: string;
+}): Promise<SandboxContext | null> {
+  const resolved = resolveSandboxSession(params);
+  if (!resolved) {
+    return null;
+  }
+  const { rawSessionKey, cfg } = resolved;
 
   await maybePruneSandboxes(cfg);
 
@@ -152,20 +161,11 @@ export async function ensureSandboxWorkspaceForSession(params: {
   sessionKey?: string;
   workspaceDir?: string;
 }): Promise<SandboxWorkspaceInfo | null> {
-  const rawSessionKey = params.sessionKey?.trim();
-  if (!rawSessionKey) {
+  const resolved = resolveSandboxSession(params);
+  if (!resolved) {
     return null;
   }
-
-  const runtime = resolveSandboxRuntimeStatus({
-    cfg: params.config,
-    sessionKey: rawSessionKey,
-  });
-  if (!runtime.sandboxed) {
-    return null;
-  }
-
-  const cfg = resolveSandboxConfigForAgent(params.config, runtime.agentId);
+  const { rawSessionKey, cfg } = resolved;
 
   const { workspaceDir } = await ensureSandboxWorkspaceLayout({
     cfg,
diff --git a/src/agents/sandbox/docker.config-hash-recreate.test.ts b/src/agents/sandbox/docker.config-hash-recreate.test.ts
new file mode 100644
index 00000000000..ae8706a6b7f
--- /dev/null
+++ b/src/agents/sandbox/docker.config-hash-recreate.test.ts
@@ -0,0 +1,191 @@
+import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SandboxConfig } from "./types.js";
+import { computeSandboxConfigHash } from "./config-hash.js";
+import { ensureSandboxContainer } from "./docker.js";
+
+type SpawnCall = {
+  command: string;
+  args: string[];
+};
+
+const spawnState = vi.hoisted(() => ({
+  calls: [] as SpawnCall[],
+  inspectRunning: true,
+  labelHash: "",
+}));
+
+const registryMocks = vi.hoisted(() => ({
+  readRegistry: vi.fn(),
+  updateRegistry: vi.fn(),
+}));
+
+vi.mock("./registry.js", () => ({
+  readRegistry: registryMocks.readRegistry,
+  updateRegistry: registryMocks.updateRegistry,
+}));
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...actual,
+    spawn: (command: string, args: string[]) => {
+      spawnState.calls.push({ command, args });
+      const child = new EventEmitter() as EventEmitter & {
+        stdout: Readable;
+        stderr: Readable;
+        stdin: { end: (input?: string | Buffer) => void };
+        kill: (signal?: NodeJS.Signals) => void;
+      };
+      child.stdout = new Readable({ read() {} });
+      child.stderr = new Readable({ read() {} });
+      child.stdin = { end: () => undefined };
+      child.kill = () => undefined;
+
+      let code = 0;
+      let stdout = "";
+      let stderr = "";
+      if (command !== "docker") {
+        code = 1;
+        stderr = `unexpected command: ${command}`;
+      } else if (args[0] === "inspect" && args[1] === "-f" && args[2] === "{{.State.Running}}") {
+        stdout = spawnState.inspectRunning ? "true\n" : "false\n";
+      } else if (
+        args[0] === "inspect" &&
+        args[1] === "-f" &&
+        args[2]?.includes('index .Config.Labels "openclaw.configHash"')
+      ) {
+        stdout = `${spawnState.labelHash}\n`;
+      } else if (
+        (args[0] === "rm" && args[1] === "-f") ||
+        (args[0] === "image" && args[1] === "inspect") ||
+        args[0] === "create" ||
+        args[0] === "start"
+      ) {
+        code = 0;
+      } else {
+        code = 1;
+        stderr = `unexpected docker args: ${args.join(" ")}`;
+      }
+
+      queueMicrotask(() => {
+        if (stdout) {
+          child.stdout.emit("data", Buffer.from(stdout));
+        }
+        if (stderr) {
+          child.stderr.emit("data", Buffer.from(stderr));
+        }
+        child.emit("close", code);
+      });
+      return child;
+    },
+  };
+});
+
+function createSandboxConfig(dns: string[]): SandboxConfig {
+  return {
+    mode: "all",
+    scope: "shared",
+    workspaceAccess: "rw",
+    workspaceRoot: "~/.openclaw/sandboxes",
+    docker: {
+      image: "openclaw-sandbox:test",
+      containerPrefix: "oc-test-",
+      workdir: "/workspace",
+      readOnlyRoot: true,
+      tmpfs: ["/tmp", "/var/tmp", "/run"],
+      network: "none",
+      capDrop: ["ALL"],
+      env: { LANG: "C.UTF-8" },
+      dns,
+      extraHosts: ["host.docker.internal:host-gateway"],
+      binds: ["/tmp/workspace:/workspace:rw"],
+    },
+    browser: {
+      enabled: false,
+      image: "openclaw-browser:test",
+      containerPrefix: "oc-browser-",
+      cdpPort: 9222,
+      vncPort: 5900,
+      noVncPort: 6080,
+      headless: true,
+      enableNoVnc: false,
+      allowHostControl: false,
+      autoStart: false,
+      autoStartTimeoutMs: 5000,
+    },
+    tools: { allow: [], deny: [] },
+    prune: { idleHours: 24, maxAgeDays: 7 },
+  };
+}
+
+describe("ensureSandboxContainer config-hash recreation", () => {
+  beforeEach(() => {
+    spawnState.calls.length = 0;
+    spawnState.inspectRunning = true;
+    spawnState.labelHash = "";
+    registryMocks.readRegistry.mockReset();
+    registryMocks.updateRegistry.mockReset();
+    registryMocks.updateRegistry.mockResolvedValue(undefined);
+  });
+
+  it("recreates shared container when array-order change alters hash", async () => {
+    const workspaceDir = "/tmp/workspace";
+    const oldCfg = createSandboxConfig(["1.1.1.1", "8.8.8.8"]);
+    const newCfg = createSandboxConfig(["8.8.8.8", "1.1.1.1"]);
+
+    const oldHash = computeSandboxConfigHash({
+      docker: oldCfg.docker,
+      workspaceAccess: oldCfg.workspaceAccess,
+      workspaceDir,
+      agentWorkspaceDir: workspaceDir,
+    });
+    const newHash = computeSandboxConfigHash({
+      docker: newCfg.docker,
+      workspaceAccess: newCfg.workspaceAccess,
+      workspaceDir,
+      agentWorkspaceDir: workspaceDir,
+    });
+    expect(newHash).not.toBe(oldHash);
+
+    spawnState.labelHash = oldHash;
+    registryMocks.readRegistry.mockResolvedValue({
+      entries: [
+        {
+          containerName: "oc-test-shared",
+          sessionKey: "shared",
+          createdAtMs: 1,
+          lastUsedAtMs: 0,
+          image: newCfg.docker.image,
+          configHash: oldHash,
+        },
+      ],
+    });
+
+    const containerName = await ensureSandboxContainer({
+      sessionKey: "agent:main:session-1",
+      workspaceDir,
+      agentWorkspaceDir: workspaceDir,
+      cfg: newCfg,
+    });
+
+    expect(containerName).toBe("oc-test-shared");
+    const dockerCalls = spawnState.calls.filter((call) => call.command === "docker");
+    expect(
+      dockerCalls.some(
+        (call) =>
+          call.args[0] === "rm" && call.args[1] === "-f" && call.args[2] === "oc-test-shared",
+      ),
+    ).toBe(true);
+    const createCall = dockerCalls.find((call) => call.args[0] === "create");
+    expect(createCall).toBeDefined();
+    expect(createCall?.args).toContain(`openclaw.configHash=${newHash}`);
+    expect(registryMocks.updateRegistry).toHaveBeenCalledWith(
+      expect.objectContaining({
+        containerName: "oc-test-shared",
+        configHash: newHash,
+      }),
+    );
+  });
+});
diff --git a/src/agents/sandbox/docker.ts b/src/agents/sandbox/docker.ts
index f79885d8a13..f87f7d5f5b4 100644
--- a/src/agents/sandbox/docker.ts
+++ b/src/agents/sandbox/docker.ts
@@ -111,6 +111,7 @@ import { computeSandboxConfigHash } from "./config-hash.js";
 import { DEFAULT_SANDBOX_IMAGE, SANDBOX_AGENT_WORKSPACE_MOUNT } from "./constants.js";
 import { readRegistry, updateRegistry } from "./registry.js";
 import { resolveSandboxAgentId, resolveSandboxScopeKey, slugifySessionKey } from "./shared.js";
+import { validateSandboxSecurity } from "./validate-sandbox-security.js";
 
 const HOT_CONTAINER_WINDOW_MS = 5 * 60 * 1000;
 
@@ -240,6 +241,9 @@ export function buildSandboxCreateArgs(params: {
   labels?: Record<string, string>;
   configHash?: string;
 }) {
+  // Runtime security validation: blocks dangerous bind mounts, network modes, and profiles.
+  validateSandboxSecurity(params.cfg);
+
   const createdAtMs = params.createdAtMs ?? Date.now();
   const args = ["create", "--name", params.name];
   args.push("--label", "openclaw.sandbox=1");
diff --git a/src/agents/sandbox/hash.ts b/src/agents/sandbox/hash.ts
new file mode 100644
index 00000000000..d1d0e8dc430
--- /dev/null
+++ b/src/agents/sandbox/hash.ts
@@ -0,0 +1,5 @@
+import crypto from "node:crypto";
+
+export function hashTextSha256(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
diff --git a/src/agents/sandbox/manage.ts b/src/agents/sandbox/manage.ts
index 89c80f95bd8..f6988146e90 100644
--- a/src/agents/sandbox/manage.ts
+++ b/src/agents/sandbox/manage.ts
@@ -23,14 +23,18 @@ export type SandboxBrowserInfo = SandboxBrowserRegistryEntry & {
   imageMatch: boolean;
 };
 
-export async function listSandboxContainers(): Promise<SandboxContainerInfo[]> {
-  const config = loadConfig();
-  const registry = await readRegistry();
-  const results: SandboxContainerInfo[] = [];
+async function listSandboxRegistryItems<
+  TEntry extends { containerName: string; image: string; sessionKey: string },
+>(params: {
+  read: () => Promise<{ entries: TEntry[] }>;
+  resolveConfiguredImage: (agentId?: string) => string;
+}): Promise<Array<TEntry & { running: boolean; imageMatch: boolean }>> {
+  const registry = await params.read();
+  const results: Array<TEntry & { running: boolean; imageMatch: boolean }> = [];
 
   for (const entry of registry.entries) {
     const state = await dockerContainerState(entry.containerName);
-    // Get actual image from container
+    // Get actual image from container.
     let actualImage = entry.image;
     if (state.exists) {
       try {
@@ -46,7 +50,7 @@ export async function listSandboxContainers(): Promise<SandboxContainerInfo[]> {
       }
     }
     const agentId = resolveSandboxAgentId(entry.sessionKey);
-    const configuredImage = resolveSandboxConfigForAgent(config, agentId).docker.image;
+    const configuredImage = params.resolveConfiguredImage(agentId);
     results.push({
       ...entry,
       image: actualImage,
@@ -58,38 +62,21 @@ export async function listSandboxContainers(): Promise<SandboxContainerInfo[]> {
   return results;
 }
 
+export async function listSandboxContainers(): Promise<SandboxContainerInfo[]> {
+  const config = loadConfig();
+  return listSandboxRegistryItems<SandboxRegistryEntry>({
+    read: readRegistry,
+    resolveConfiguredImage: (agentId) => resolveSandboxConfigForAgent(config, agentId).docker.image,
+  });
+}
+
 export async function listSandboxBrowsers(): Promise<SandboxBrowserInfo[]> {
   const config = loadConfig();
-  const registry = await readBrowserRegistry();
-  const results: SandboxBrowserInfo[] = [];
-
-  for (const entry of registry.entries) {
-    const state = await dockerContainerState(entry.containerName);
-    let actualImage = entry.image;
-    if (state.exists) {
-      try {
-        const result = await execDocker(
-          ["inspect", "-f", "{{.Config.Image}}", entry.containerName],
-          { allowFailure: true },
-        );
-        if (result.code === 0) {
-          actualImage = result.stdout.trim();
-        }
-      } catch {
-        // ignore
-      }
-    }
-    const agentId = resolveSandboxAgentId(entry.sessionKey);
-    const configuredImage = resolveSandboxConfigForAgent(config, agentId).browser.image;
-    results.push({
-      ...entry,
-      image: actualImage,
-      running: state.running,
-      imageMatch: actualImage === configuredImage,
-    });
-  }
-
-  return results;
+  return listSandboxRegistryItems<SandboxBrowserRegistryEntry>({
+    read: readBrowserRegistry,
+    resolveConfiguredImage: (agentId) =>
+      resolveSandboxConfigForAgent(config, agentId).browser.image,
+  });
 }
 
 export async function removeSandboxContainer(containerName: string): Promise<void> {
diff --git a/src/agents/sandbox/prune.ts b/src/agents/sandbox/prune.ts
index de3616f7e49..c3b37534e36 100644
--- a/src/agents/sandbox/prune.ts
+++ b/src/agents/sandbox/prune.ts
@@ -8,69 +8,80 @@ import {
   readRegistry,
   removeBrowserRegistryEntry,
   removeRegistryEntry,
+  type SandboxBrowserRegistryEntry,
+  type SandboxRegistryEntry,
 } from "./registry.js";
 
 let lastPruneAtMs = 0;
 
-async function pruneSandboxContainers(cfg: SandboxConfig) {
-  const now = Date.now();
+type PruneableRegistryEntry = Pick<
+  SandboxRegistryEntry,
+  "containerName" | "createdAtMs" | "lastUsedAtMs"
+>;
+
+function shouldPruneSandboxEntry(cfg: SandboxConfig, now: number, entry: PruneableRegistryEntry) {
   const idleHours = cfg.prune.idleHours;
   const maxAgeDays = cfg.prune.maxAgeDays;
   if (idleHours === 0 && maxAgeDays === 0) {
+    return false;
+  }
+  const idleMs = now - entry.lastUsedAtMs;
+  const ageMs = now - entry.createdAtMs;
+  return (
+    (idleHours > 0 && idleMs > idleHours * 60 * 60 * 1000) ||
+    (maxAgeDays > 0 && ageMs > maxAgeDays * 24 * 60 * 60 * 1000)
+  );
+}
+
+async function pruneSandboxRegistryEntries<TEntry extends PruneableRegistryEntry>(params: {
+  cfg: SandboxConfig;
+  read: () => Promise<{ entries: TEntry[] }>;
+  remove: (containerName: string) => Promise<void>;
+  onRemoved?: (entry: TEntry) => Promise<void>;
+}) {
+  const now = Date.now();
+  if (params.cfg.prune.idleHours === 0 && params.cfg.prune.maxAgeDays === 0) {
     return;
   }
-  const registry = await readRegistry();
+  const registry = await params.read();
   for (const entry of registry.entries) {
-    const idleMs = now - entry.lastUsedAtMs;
-    const ageMs = now - entry.createdAtMs;
-    if (
-      (idleHours > 0 && idleMs > idleHours * 60 * 60 * 1000) ||
-      (maxAgeDays > 0 && ageMs > maxAgeDays * 24 * 60 * 60 * 1000)
-    ) {
-      try {
-        await execDocker(["rm", "-f", entry.containerName], {
-          allowFailure: true,
-        });
-      } catch {
-        // ignore prune failures
-      } finally {
-        await removeRegistryEntry(entry.containerName);
-      }
+    if (!shouldPruneSandboxEntry(params.cfg, now, entry)) {
+      continue;
+    }
+    try {
+      await execDocker(["rm", "-f", entry.containerName], {
+        allowFailure: true,
+      });
+    } catch {
+      // ignore prune failures
+    } finally {
+      await params.remove(entry.containerName);
+      await params.onRemoved?.(entry);
     }
   }
 }
 
+async function pruneSandboxContainers(cfg: SandboxConfig) {
+  await pruneSandboxRegistryEntries<SandboxRegistryEntry>({
+    cfg,
+    read: readRegistry,
+    remove: removeRegistryEntry,
+  });
+}
+
 async function pruneSandboxBrowsers(cfg: SandboxConfig) {
-  const now = Date.now();
-  const idleHours = cfg.prune.idleHours;
-  const maxAgeDays = cfg.prune.maxAgeDays;
-  if (idleHours === 0 && maxAgeDays === 0) {
-    return;
-  }
-  const registry = await readBrowserRegistry();
-  for (const entry of registry.entries) {
-    const idleMs = now - entry.lastUsedAtMs;
-    const ageMs = now - entry.createdAtMs;
-    if (
-      (idleHours > 0 && idleMs > idleHours * 60 * 60 * 1000) ||
-      (maxAgeDays > 0 && ageMs > maxAgeDays * 24 * 60 * 60 * 1000)
-    ) {
-      try {
-        await execDocker(["rm", "-f", entry.containerName], {
-          allowFailure: true,
-        });
-      } catch {
-        // ignore prune failures
-      } finally {
-        await removeBrowserRegistryEntry(entry.containerName);
-        const bridge = BROWSER_BRIDGES.get(entry.sessionKey);
-        if (bridge?.containerName === entry.containerName) {
-          await stopBrowserBridgeServer(bridge.bridge.server).catch(() => undefined);
-          BROWSER_BRIDGES.delete(entry.sessionKey);
-        }
+  await pruneSandboxRegistryEntries<SandboxBrowserRegistryEntry>({
+    cfg,
+    read: readBrowserRegistry,
+    remove: removeBrowserRegistryEntry,
+    onRemoved: async (entry) => {
+      const bridge = BROWSER_BRIDGES.get(entry.sessionKey);
+      if (bridge?.containerName === entry.containerName) {
+        await stopBrowserBridgeServer(bridge.bridge.server).catch(() => undefined);
+        BROWSER_BRIDGES.delete(entry.sessionKey);
       }
-    }
-  }
+    },
+  });
 }
 
 export async function maybePruneSandboxes(cfg: SandboxConfig) {
diff --git a/src/agents/sandbox/shared.ts b/src/agents/sandbox/shared.ts
index 0c9bc849c4d..cb3585aad77 100644
--- a/src/agents/sandbox/shared.ts
+++ b/src/agents/sandbox/shared.ts
@@ -1,12 +1,12 @@
-import crypto from "node:crypto";
 import path from "node:path";
 import { normalizeAgentId } from "../../routing/session-key.js";
 import { resolveUserPath } from "../../utils.js";
 import { resolveAgentIdFromSessionKey } from "../agent-scope.js";
+import { hashTextSha256 } from "./hash.js";
 
 export function slugifySessionKey(value: string) {
   const trimmed = value.trim() || "session";
-  const hash = crypto.createHash("sha1").update(trimmed).digest("hex").slice(0, 8);
+  const hash = hashTextSha256(trimmed).slice(0, 8);
   const safe = trimmed
     .toLowerCase()
     .replace(/[^a-z0-9._-]+/g, "-")
diff --git a/src/agents/sandbox/tool-policy.e2e.test.ts b/src/agents/sandbox/tool-policy.e2e.test.ts
deleted file mode 100644
index 319a84a9749..00000000000
--- a/src/agents/sandbox/tool-policy.e2e.test.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { SandboxToolPolicy } from "./types.js";
-import { isToolAllowed } from "./tool-policy.js";
-
-describe("sandbox tool policy", () => {
-  it("allows all tools with * allow", () => {
-    const policy: SandboxToolPolicy = { allow: ["*"], deny: [] };
-    expect(isToolAllowed(policy, "browser")).toBe(true);
-  });
-
-  it("denies all tools with * deny", () => {
-    const policy: SandboxToolPolicy = { allow: [], deny: ["*"] };
-    expect(isToolAllowed(policy, "read")).toBe(false);
-  });
-
-  it("supports wildcard patterns", () => {
-    const policy: SandboxToolPolicy = { allow: ["web_*"] };
-    expect(isToolAllowed(policy, "web_fetch")).toBe(true);
-    expect(isToolAllowed(policy, "read")).toBe(false);
-  });
-});
diff --git a/src/agents/sandbox/tool-policy.ts b/src/agents/sandbox/tool-policy.ts
index b50a363846b..083cfcac4af 100644
--- a/src/agents/sandbox/tool-policy.ts
+++ b/src/agents/sandbox/tool-policy.ts
@@ -89,6 +89,9 @@ export function resolveSandboxToolPolicyForAgent(
   // `image` is essential for multimodal workflows; always include it in sandboxed
   // sessions unless explicitly denied.
   if (
+    // Empty allowlist means "allow all" for `isToolAllowed`, so don't inject a
+    // single tool that would accidentally turn it into an explicit allowlist.
+    expandedAllow.length > 0 &&
     !expandedDeny.map((v) => v.toLowerCase()).includes("image") &&
     !expandedAllow.map((v) => v.toLowerCase()).includes("image")
   ) {
diff --git a/src/agents/sandbox/validate-sandbox-security.test.ts b/src/agents/sandbox/validate-sandbox-security.test.ts
new file mode 100644
index 00000000000..4b3ff9d698c
--- /dev/null
+++ b/src/agents/sandbox/validate-sandbox-security.test.ts
@@ -0,0 +1,153 @@
+import { mkdtempSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  getBlockedBindReason,
+  validateBindMounts,
+  validateNetworkMode,
+  validateSeccompProfile,
+  validateApparmorProfile,
+  validateSandboxSecurity,
+} from "./validate-sandbox-security.js";
+
+describe("getBlockedBindReason", () => {
+  it("blocks common Docker socket directories", () => {
+    expect(getBlockedBindReason("/run:/run")).toEqual(expect.objectContaining({ kind: "targets" }));
+    expect(getBlockedBindReason("/var/run:/var/run:ro")).toEqual(
+      expect.objectContaining({ kind: "targets" }),
+    );
+  });
+
+  it("does not block /var by default", () => {
+    expect(getBlockedBindReason("/var:/var")).toBeNull();
+  });
+});
+
+describe("validateBindMounts", () => {
+  it("allows legitimate project directory mounts", () => {
+    expect(() =>
+      validateBindMounts([
+        "/home/user/source:/source:rw",
+        "/home/user/projects:/projects:ro",
+        "/var/data/myapp:/data",
+        "/opt/myapp/config:/config:ro",
+      ]),
+    ).not.toThrow();
+  });
+
+  it("allows undefined or empty binds", () => {
+    expect(() => validateBindMounts(undefined)).not.toThrow();
+    expect(() => validateBindMounts([])).not.toThrow();
+  });
+
+  it("blocks /etc mount", () => {
+    expect(() => validateBindMounts(["/etc/passwd:/mnt/passwd:ro"])).toThrow(
+      /blocked path "\/etc"/,
+    );
+  });
+
+  it("blocks /proc mount", () => {
+    expect(() => validateBindMounts(["/proc:/proc:ro"])).toThrow(/blocked path "\/proc"/);
+  });
+
+  it("blocks Docker socket mounts (/var/run + /run)", () => {
+    expect(() => validateBindMounts(["/var/run/docker.sock:/var/run/docker.sock"])).toThrow(
+      /docker\.sock/,
+    );
+    expect(() => validateBindMounts(["/run/docker.sock:/run/docker.sock"])).toThrow(/docker\.sock/);
+  });
+
+  it("blocks parent mounts that would expose the Docker socket", () => {
+    expect(() => validateBindMounts(["/run:/run"])).toThrow(/blocked path/);
+    expect(() => validateBindMounts(["/var/run:/var/run"])).toThrow(/blocked path/);
+    expect(() => validateBindMounts(["/var:/var"])).not.toThrow();
+  });
+
+  it("blocks paths with .. traversal to dangerous directories", () => {
+    expect(() => validateBindMounts(["/home/user/../../etc/shadow:/mnt/shadow"])).toThrow(
+      /blocked path "\/etc"/,
+    );
+  });
+
+  it("blocks paths with double slashes normalizing to dangerous dirs", () => {
+    expect(() => validateBindMounts(["//etc//passwd:/mnt/passwd"])).toThrow(/blocked path "\/etc"/);
+  });
+
+  it("blocks symlink escapes into blocked directories", () => {
+    const dir = mkdtempSync(join(tmpdir(), "openclaw-sbx-"));
+    const link = join(dir, "etc-link");
+    symlinkSync("/etc", link);
+    const run = () => validateBindMounts([`${link}/passwd:/mnt/passwd:ro`]);
+
+    if (process.platform === "win32") {
+      // Windows source paths (e.g. C:\...) are intentionally rejected as non-POSIX.
+      expect(run).toThrow(/non-absolute source path/);
+      return;
+    }
+
+    expect(run).toThrow(/blocked path/);
+  });
+
+  it("rejects non-absolute source paths (relative or named volumes)", () => {
+    expect(() => validateBindMounts(["../etc/passwd:/mnt/passwd"])).toThrow(/non-absolute/);
+    expect(() => validateBindMounts(["etc/passwd:/mnt/passwd"])).toThrow(/non-absolute/);
+    expect(() => validateBindMounts(["myvol:/mnt"])).toThrow(/non-absolute/);
+  });
+});
+
+describe("validateNetworkMode", () => {
+  it("allows bridge/none/custom/undefined", () => {
+    expect(() => validateNetworkMode("bridge")).not.toThrow();
+    expect(() => validateNetworkMode("none")).not.toThrow();
+    expect(() => validateNetworkMode("my-custom-network")).not.toThrow();
+    expect(() => validateNetworkMode(undefined)).not.toThrow();
+  });
+
+  it("blocks host mode (case-insensitive)", () => {
+    expect(() => validateNetworkMode("host")).toThrow(/network mode "host" is blocked/);
+    expect(() => validateNetworkMode("HOST")).toThrow(/network mode "HOST" is blocked/);
+  });
+});
+
+describe("validateSeccompProfile", () => {
+  it("allows custom profile paths/undefined", () => {
+    expect(() => validateSeccompProfile("/tmp/seccomp.json")).not.toThrow();
+    expect(() => validateSeccompProfile(undefined)).not.toThrow();
+  });
+
+  it("blocks unconfined (case-insensitive)", () => {
+    expect(() => validateSeccompProfile("unconfined")).toThrow(
+      /seccomp profile "unconfined" is blocked/,
+    );
+    expect(() => validateSeccompProfile("Unconfined")).toThrow(
+      /seccomp profile "Unconfined" is blocked/,
+    );
+  });
+});
+
+describe("validateApparmorProfile", () => {
+  it("allows named profile/undefined", () => {
+    expect(() => validateApparmorProfile("openclaw-sandbox")).not.toThrow();
+    expect(() => validateApparmorProfile(undefined)).not.toThrow();
+  });
+
+  it("blocks unconfined (case-insensitive)", () => {
+    expect(() => validateApparmorProfile("unconfined")).toThrow(
+      /apparmor profile "unconfined" is blocked/,
+    );
+  });
+});
+
+describe("validateSandboxSecurity", () => {
+  it("passes with safe config", () => {
+    expect(() =>
+      validateSandboxSecurity({
+        binds: ["/home/user/src:/src:rw"],
+        network: "none",
+        seccompProfile: "/tmp/seccomp.json",
+        apparmorProfile: "openclaw-sandbox",
+      }),
+    ).not.toThrow();
+  });
+});
diff --git a/src/agents/sandbox/validate-sandbox-security.ts b/src/agents/sandbox/validate-sandbox-security.ts
new file mode 100644
index 00000000000..2ed84e9c93d
--- /dev/null
+++ b/src/agents/sandbox/validate-sandbox-security.ts
@@ -0,0 +1,195 @@
+/**
+ * Sandbox security validation — blocks dangerous Docker configurations.
+ *
+ * Threat model: local-trusted config, but protect against foot-guns and config injection.
+ * Enforced at runtime when creating sandbox containers.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { posix } from "node:path";
+
+// Targeted denylist: host paths that should never be exposed inside sandbox containers.
+// Exported for reuse in security audit collectors.
+export const BLOCKED_HOST_PATHS = [
+  "/etc",
+  "/private/etc",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/root",
+  "/boot",
+  // Directories that commonly contain (or alias) the Docker socket.
+  "/run",
+  "/var/run",
+  "/private/var/run",
+  "/var/run/docker.sock",
+  "/private/var/run/docker.sock",
+  "/run/docker.sock",
+];
+
+const BLOCKED_NETWORK_MODES = new Set(["host"]);
+const BLOCKED_SECCOMP_PROFILES = new Set(["unconfined"]);
+const BLOCKED_APPARMOR_PROFILES = new Set(["unconfined"]);
+
+export type BlockedBindReason =
+  | { kind: "targets"; blockedPath: string }
+  | { kind: "covers"; blockedPath: string }
+  | { kind: "non_absolute"; sourcePath: string };
+
+/**
+ * Parse the host/source path from a Docker bind mount string.
+ * Format: `source:target[:mode]`
+ */
+export function parseBindSourcePath(bind: string): string {
+  const trimmed = bind.trim();
+  const firstColon = trimmed.indexOf(":");
+  if (firstColon <= 0) {
+    // No colon or starts with colon — treat as source.
+    return trimmed;
+  }
+  return trimmed.slice(0, firstColon);
+}
+
+/**
+ * Normalize a POSIX path: resolve `.`, `..`, collapse `//`, strip trailing `/`.
+ */
+export function normalizeHostPath(raw: string): string {
+  const trimmed = raw.trim();
+  return posix.normalize(trimmed).replace(/\/+$/, "") || "/";
+}
+
+/**
+ * String-only blocked-path check (no filesystem I/O).
+ * Blocks:
+ * - binds that target blocked paths (equal or under)
+ * - binds that cover the system root (mounting "/" is never safe)
+ * - non-absolute source paths (relative / volume names) because they are hard to validate safely
+ */
+export function getBlockedBindReason(bind: string): BlockedBindReason | null {
+  const sourceRaw = parseBindSourcePath(bind);
+  if (!sourceRaw.startsWith("/")) {
+    return { kind: "non_absolute", sourcePath: sourceRaw };
+  }
+
+  const normalized = normalizeHostPath(sourceRaw);
+  return getBlockedReasonForSourcePath(normalized);
+}
+
+export function getBlockedReasonForSourcePath(sourceNormalized: string): BlockedBindReason | null {
+  if (sourceNormalized === "/") {
+    return { kind: "covers", blockedPath: "/" };
+  }
+  for (const blocked of BLOCKED_HOST_PATHS) {
+    if (sourceNormalized === blocked || sourceNormalized.startsWith(blocked + "/")) {
+      return { kind: "targets", blockedPath: blocked };
+    }
+  }
+
+  return null;
+}
+
+function tryRealpathAbsolute(path: string): string {
+  if (!path.startsWith("/")) {
+    return path;
+  }
+  if (!existsSync(path)) {
+    return path;
+  }
+  try {
+    // Use native when available (keeps platform semantics); normalize for prefix checks.
+    return normalizeHostPath(realpathSync.native(path));
+  } catch {
+    return path;
+  }
+}
+
+function formatBindBlockedError(params: { bind: string; reason: BlockedBindReason }): Error {
+  if (params.reason.kind === "non_absolute") {
+    return new Error(
+      `Sandbox security: bind mount "${params.bind}" uses a non-absolute source path ` +
+        `"${params.reason.sourcePath}". Only absolute POSIX paths are supported for sandbox binds.`,
+    );
+  }
+  const verb = params.reason.kind === "covers" ? "covers" : "targets";
+  return new Error(
+    `Sandbox security: bind mount "${params.bind}" ${verb} blocked path "${params.reason.blockedPath}". ` +
+      "Mounting system directories (or Docker socket paths) into sandbox containers is not allowed. " +
+      "Use project-specific paths instead (e.g. /home/user/myproject).",
+  );
+}
+
+/**
+ * Validate bind mounts — throws if any source path is dangerous.
+ * Includes a symlink/realpath pass when the source path exists.
+ */
+export function validateBindMounts(binds: string[] | undefined): void {
+  if (!binds?.length) {
+    return;
+  }
+
+  for (const rawBind of binds) {
+    const bind = rawBind.trim();
+    if (!bind) {
+      continue;
+    }
+
+    // Fast string-only check (covers .., //, ancestor/descendant logic).
+    const blocked = getBlockedBindReason(bind);
+    if (blocked) {
+      throw formatBindBlockedError({ bind, reason: blocked });
+    }
+
+    // Symlink escape hardening: resolve existing absolute paths and re-check.
+    const sourceRaw = parseBindSourcePath(bind);
+    const sourceNormalized = normalizeHostPath(sourceRaw);
+    const sourceReal = tryRealpathAbsolute(sourceNormalized);
+    if (sourceReal !== sourceNormalized) {
+      const reason = getBlockedReasonForSourcePath(sourceReal);
+      if (reason) {
+        throw formatBindBlockedError({ bind, reason });
+      }
+    }
+  }
+}
+
+export function validateNetworkMode(network: string | undefined): void {
+  if (network && BLOCKED_NETWORK_MODES.has(network.trim().toLowerCase())) {
+    throw new Error(
+      `Sandbox security: network mode "${network}" is blocked. ` +
+        'Network "host" mode bypasses container network isolation. ' +
+        'Use "bridge" or "none" instead.',
+    );
+  }
+}
+
+export function validateSeccompProfile(profile: string | undefined): void {
+  if (profile && BLOCKED_SECCOMP_PROFILES.has(profile.trim().toLowerCase())) {
+    throw new Error(
+      `Sandbox security: seccomp profile "${profile}" is blocked. ` +
+        "Disabling seccomp removes syscall filtering and weakens sandbox isolation. " +
+        "Use a custom seccomp profile file or omit this setting.",
+    );
+  }
+}
+
+export function validateApparmorProfile(profile: string | undefined): void {
+  if (profile && BLOCKED_APPARMOR_PROFILES.has(profile.trim().toLowerCase())) {
+    throw new Error(
+      `Sandbox security: apparmor profile "${profile}" is blocked. ` +
+        "Disabling AppArmor removes mandatory access controls and weakens sandbox isolation. " +
+        "Use a named AppArmor profile or omit this setting.",
+    );
+  }
+}
+
+export function validateSandboxSecurity(cfg: {
+  binds?: string[];
+  network?: string;
+  seccompProfile?: string;
+  apparmorProfile?: string;
+}): void {
+  validateBindMounts(cfg.binds);
+  validateNetworkMode(cfg.network);
+  validateSeccompProfile(cfg.seccompProfile);
+  validateApparmorProfile(cfg.apparmorProfile);
+}
diff --git a/src/agents/sanitize-for-prompt.test.ts b/src/agents/sanitize-for-prompt.test.ts
new file mode 100644
index 00000000000..32a4ce3d86e
--- /dev/null
+++ b/src/agents/sanitize-for-prompt.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
+import { buildAgentSystemPrompt } from "./system-prompt.js";
+
+describe("sanitizeForPromptLiteral (OC-19 hardening)", () => {
+  it("strips ASCII control chars (CR/LF/NUL/tab)", () => {
+    expect(sanitizeForPromptLiteral("/tmp/a\nb\rc\x00d\te")).toBe("/tmp/abcde");
+  });
+
+  it("strips Unicode line/paragraph separators", () => {
+    expect(sanitizeForPromptLiteral(`/tmp/a\u2028b\u2029c`)).toBe("/tmp/abc");
+  });
+
+  it("strips Unicode format chars (bidi override)", () => {
+    // U+202E RIGHT-TO-LEFT OVERRIDE (Cf) can spoof rendered text.
+    expect(sanitizeForPromptLiteral(`/tmp/a\u202Eb`)).toBe("/tmp/ab");
+  });
+
+  it("preserves ordinary Unicode + spaces", () => {
+    const value = "/tmp/my project/日本語-folder.v2";
+    expect(sanitizeForPromptLiteral(value)).toBe(value);
+  });
+});
+
+describe("buildAgentSystemPrompt uses sanitized workspace/sandbox strings", () => {
+  it("sanitizes workspaceDir (no newlines / separators)", () => {
+    const prompt = buildAgentSystemPrompt({
+      workspaceDir: "/tmp/project\nINJECT\u2028MORE",
+    });
+    expect(prompt).toContain("Your working directory is: /tmp/projectINJECTMORE");
+    expect(prompt).not.toContain("Your working directory is: /tmp/project\n");
+    expect(prompt).not.toContain("\u2028");
+  });
+
+  it("sanitizes sandbox workspace/mount/url strings", () => {
+    const prompt = buildAgentSystemPrompt({
+      workspaceDir: "/tmp/test",
+      sandboxInfo: {
+        enabled: true,
+        containerWorkspaceDir: "/work\u2029space",
+        workspaceDir: "/host\nspace",
+        workspaceAccess: "read-write",
+        agentWorkspaceMount: "/mnt\u2028mount",
+        browserNoVncUrl: "http://example.test/\nui",
+      },
+    });
+    expect(prompt).toContain("Sandbox container workdir: /workspace");
+    expect(prompt).toContain(
+      "Sandbox host mount source (file tools bridge only; not valid inside sandbox exec): /hostspace",
+    );
+    expect(prompt).toContain("(mounted at /mntmount)");
+    expect(prompt).toContain("Sandbox browser observer (noVNC): http://example.test/ui");
+    expect(prompt).not.toContain("\nui");
+  });
+});
diff --git a/src/agents/sanitize-for-prompt.ts b/src/agents/sanitize-for-prompt.ts
new file mode 100644
index 00000000000..7692cf306da
--- /dev/null
+++ b/src/agents/sanitize-for-prompt.ts
@@ -0,0 +1,18 @@
+/**
+ * Sanitize untrusted strings before embedding them into an LLM prompt.
+ *
+ * Threat model (OC-19): attacker-controlled directory names (or other runtime strings)
+ * that contain newline/control characters can break prompt structure and inject
+ * arbitrary instructions.
+ *
+ * Strategy (Option 3 hardening):
+ * - Strip Unicode "control" (Cc) + "format" (Cf) characters (includes CR/LF/NUL, bidi marks, zero-width chars).
+ * - Strip explicit line/paragraph separators (Zl/Zp): U+2028/U+2029.
+ *
+ * Notes:
+ * - This is intentionally lossy; it trades edge-case path fidelity for prompt integrity.
+ * - If you need lossless representation, escape instead of stripping.
+ */
+export function sanitizeForPromptLiteral(value: string): string {
+  return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, "");
+}
diff --git a/src/agents/session-write-lock.ts b/src/agents/session-write-lock.ts
index 1164598b774..94d43d5ac8d 100644
--- a/src/agents/session-write-lock.ts
+++ b/src/agents/session-write-lock.ts
@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isPidAlive } from "../shared/pid-alive.js";
 
 type LockFilePayload = {
   pid: number;
@@ -48,18 +49,6 @@ function resolveCleanupState(): CleanupState {
   return proc[CLEANUP_STATE_KEY];
 }
 
-function isAlive(pid: number): boolean {
-  if (!Number.isFinite(pid) || pid <= 0) {
-    return false;
-  }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Synchronously release all held locks.
  * Used during process exit when async operations aren't reliable.
@@ -162,24 +151,25 @@ export async function acquireSessionWriteLock(params: {
   }
   const normalizedSessionFile = path.join(normalizedDir, path.basename(sessionFile));
   const lockPath = `${normalizedSessionFile}.lock`;
+  const release = async () => {
+    const current = HELD_LOCKS.get(normalizedSessionFile);
+    if (!current) {
+      return;
+    }
+    current.count -= 1;
+    if (current.count > 0) {
+      return;
+    }
+    HELD_LOCKS.delete(normalizedSessionFile);
+    await current.handle.close();
+    await fs.rm(current.lockPath, { force: true });
+  };
 
   const held = HELD_LOCKS.get(normalizedSessionFile);
   if (held) {
     held.count += 1;
     return {
-      release: async () => {
-        const current = HELD_LOCKS.get(normalizedSessionFile);
-        if (!current) {
-          return;
-        }
-        current.count -= 1;
-        if (current.count > 0) {
-          return;
-        }
-        HELD_LOCKS.delete(normalizedSessionFile);
-        await current.handle.close();
-        await fs.rm(current.lockPath, { force: true });
-      },
+      release,
     };
   }
 
@@ -195,19 +185,7 @@ export async function acquireSessionWriteLock(params: {
       );
       HELD_LOCKS.set(normalizedSessionFile, { count: 1, handle, lockPath });
       return {
-        release: async () => {
-          const current = HELD_LOCKS.get(normalizedSessionFile);
-          if (!current) {
-            return;
-          }
-          current.count -= 1;
-          if (current.count > 0) {
-            return;
-          }
-          HELD_LOCKS.delete(normalizedSessionFile);
-          await current.handle.close();
-          await fs.rm(current.lockPath, { force: true });
-        },
+        release,
       };
     } catch (err) {
       const code = (err as { code?: unknown }).code;
@@ -217,7 +195,7 @@ export async function acquireSessionWriteLock(params: {
       const payload = await readLockPayload(lockPath);
       const createdAt = payload?.createdAt ? Date.parse(payload.createdAt) : NaN;
       const stale = !Number.isFinite(createdAt) || Date.now() - createdAt > staleMs;
-      const alive = payload?.pid ? isAlive(payload.pid) : false;
+      const alive = payload?.pid ? isPidAlive(payload.pid) : false;
       if (stale || !alive) {
         await fs.rm(lockPath, { force: true });
         continue;
diff --git a/src/agents/skills-install-download.ts b/src/agents/skills-install-download.ts
new file mode 100644
index 00000000000..f9b2ff2837c
--- /dev/null
+++ b/src/agents/skills-install-download.ts
@@ -0,0 +1,376 @@
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { SkillInstallResult } from "./skills-install.js";
+import type { SkillEntry, SkillInstallSpec } from "./skills.js";
+import { extractArchive as extractArchiveSafe } from "../infra/archive.js";
+import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
+import { isWithinDir, resolveSafeBaseDir } from "../infra/path-safety.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { ensureDir, resolveUserPath } from "../utils.js";
+import { hasBinary } from "./skills.js";
+import { resolveSkillToolsRootDir } from "./skills/tools-dir.js";
+
+function isNodeReadableStream(value: unknown): value is NodeJS.ReadableStream {
+  return Boolean(value && typeof (value as NodeJS.ReadableStream).pipe === "function");
+}
+
+function summarizeInstallOutput(text: string): string | undefined {
+  const raw = text.trim();
+  if (!raw) {
+    return undefined;
+  }
+  const lines = raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) {
+    return undefined;
+  }
+
+  const preferred =
+    lines.find((line) => /^error\b/i.test(line)) ??
+    lines.find((line) => /\b(err!|error:|failed)\b/i.test(line)) ??
+    lines.at(-1);
+
+  if (!preferred) {
+    return undefined;
+  }
+  const normalized = preferred.replace(/\s+/g, " ").trim();
+  const maxLen = 200;
+  return normalized.length > maxLen ? `${normalized.slice(0, maxLen - 1)}…` : normalized;
+}
+
+function formatInstallFailureMessage(result: {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}): string {
+  const code = typeof result.code === "number" ? `exit ${result.code}` : "unknown exit";
+  const summary = summarizeInstallOutput(result.stderr) ?? summarizeInstallOutput(result.stdout);
+  if (!summary) {
+    return `Install failed (${code})`;
+  }
+  return `Install failed (${code}): ${summary}`;
+}
+
+function isWindowsDrivePath(p: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(p);
+}
+
+function resolveDownloadTargetDir(entry: SkillEntry, spec: SkillInstallSpec): string {
+  const safeRoot = resolveSkillToolsRootDir(entry);
+  const raw = spec.targetDir?.trim();
+  if (!raw) {
+    return safeRoot;
+  }
+
+  // Treat non-absolute paths as relative to the per-skill tools root.
+  const resolved =
+    raw.startsWith("~") || path.isAbsolute(raw) || isWindowsDrivePath(raw)
+      ? resolveUserPath(raw)
+      : path.resolve(safeRoot, raw);
+
+  if (!isWithinDir(safeRoot, resolved)) {
+    throw new Error(
+      `Refusing to install outside the skill tools directory. targetDir="${raw}" resolves to "${resolved}". Allowed root: "${safeRoot}".`,
+    );
+  }
+  return resolved;
+}
+
+function resolveArchiveType(spec: SkillInstallSpec, filename: string): string | undefined {
+  const explicit = spec.archive?.trim().toLowerCase();
+  if (explicit) {
+    return explicit;
+  }
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".tar.gz") || lower.endsWith(".tgz")) {
+    return "tar.gz";
+  }
+  if (lower.endsWith(".tar.bz2") || lower.endsWith(".tbz2")) {
+    return "tar.bz2";
+  }
+  if (lower.endsWith(".zip")) {
+    return "zip";
+  }
+  return undefined;
+}
+
+function normalizeArchiveEntryPath(raw: string): string {
+  return raw.replaceAll("\\", "/");
+}
+
+function validateArchiveEntryPath(entryPath: string): void {
+  if (!entryPath || entryPath === "." || entryPath === "./") {
+    return;
+  }
+  if (isWindowsDrivePath(entryPath)) {
+    throw new Error(`archive entry uses a drive path: ${entryPath}`);
+  }
+  const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(`archive entry escapes targetDir: ${entryPath}`);
+  }
+  if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
+    throw new Error(`archive entry is absolute: ${entryPath}`);
+  }
+}
+
+function stripArchivePath(entryPath: string, stripComponents: number): string | null {
+  const raw = normalizeArchiveEntryPath(entryPath);
+  if (!raw || raw === "." || raw === "./") {
+    return null;
+  }
+
+  // Important: tar's --strip-components semantics operate on raw path segments,
+  // before any normalization that would collapse "..". We mimic that so we
+  // can detect strip-induced escapes like "a/../b" with stripComponents=1.
+  const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
+  const strip = Math.max(0, Math.floor(stripComponents));
+  const stripped = strip === 0 ? parts.join("/") : parts.slice(strip).join("/");
+  const result = path.posix.normalize(stripped);
+  if (!result || result === "." || result === "./") {
+    return null;
+  }
+  return result;
+}
+
+function validateExtractedPathWithinRoot(params: {
+  rootDir: string;
+  relPath: string;
+  originalPath: string;
+}): void {
+  const safeBase = resolveSafeBaseDir(params.rootDir);
+  const outPath = path.resolve(params.rootDir, params.relPath);
+  if (!outPath.startsWith(safeBase)) {
+    throw new Error(`archive entry escapes targetDir: ${params.originalPath}`);
+  }
+}
+
+async function downloadFile(
+  url: string,
+  destPath: string,
+  timeoutMs: number,
+): Promise<{ bytes: number }> {
+  const { response, release } = await fetchWithSsrFGuard({
+    url,
+    timeoutMs: Math.max(1_000, timeoutMs),
+  });
+  try {
+    if (!response.ok || !response.body) {
+      throw new Error(`Download failed (${response.status} ${response.statusText})`);
+    }
+    await ensureDir(path.dirname(destPath));
+    const file = fs.createWriteStream(destPath);
+    const body = response.body as unknown;
+    const readable = isNodeReadableStream(body)
+      ? body
+      : Readable.fromWeb(body as NodeReadableStream);
+    await pipeline(readable, file);
+    const stat = await fs.promises.stat(destPath);
+    return { bytes: stat.size };
+  } finally {
+    await release();
+  }
+}
+
+async function extractArchive(params: {
+  archivePath: string;
+  archiveType: string;
+  targetDir: string;
+  stripComponents?: number;
+  timeoutMs: number;
+}): Promise<{ stdout: string; stderr: string; code: number | null }> {
+  const { archivePath, archiveType, targetDir, stripComponents, timeoutMs } = params;
+  const strip =
+    typeof stripComponents === "number" && Number.isFinite(stripComponents)
+      ? Math.max(0, Math.floor(stripComponents))
+      : 0;
+
+  try {
+    if (archiveType === "zip") {
+      await extractArchiveSafe({
+        archivePath,
+        destDir: targetDir,
+        timeoutMs,
+        kind: "zip",
+        stripComponents: strip,
+      });
+      return { stdout: "", stderr: "", code: 0 };
+    }
+
+    if (archiveType === "tar.gz") {
+      await extractArchiveSafe({
+        archivePath,
+        destDir: targetDir,
+        timeoutMs,
+        kind: "tar",
+        stripComponents: strip,
+        tarGzip: true,
+      });
+      return { stdout: "", stderr: "", code: 0 };
+    }
+
+    if (archiveType === "tar.bz2") {
+      if (!hasBinary("tar")) {
+        return { stdout: "", stderr: "tar not found on PATH", code: null };
+      }
+
+      // Preflight list to prevent zip-slip style traversal before extraction.
+      const listResult = await runCommandWithTimeout(["tar", "tf", archivePath], { timeoutMs });
+      if (listResult.code !== 0) {
+        return {
+          stdout: listResult.stdout,
+          stderr: listResult.stderr || "tar list failed",
+          code: listResult.code,
+        };
+      }
+      const entries = listResult.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+      const verboseResult = await runCommandWithTimeout(["tar", "tvf", archivePath], { timeoutMs });
+      if (verboseResult.code !== 0) {
+        return {
+          stdout: verboseResult.stdout,
+          stderr: verboseResult.stderr || "tar verbose list failed",
+          code: verboseResult.code,
+        };
+      }
+      for (const line of verboseResult.stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+          continue;
+        }
+        const typeChar = trimmed[0];
+        if (typeChar === "l" || typeChar === "h" || trimmed.includes(" -> ")) {
+          return {
+            stdout: verboseResult.stdout,
+            stderr: "tar archive contains link entries; refusing to extract for safety",
+            code: 1,
+          };
+        }
+      }
+
+      for (const entry of entries) {
+        validateArchiveEntryPath(entry);
+        const relPath = stripArchivePath(entry, strip);
+        if (!relPath) {
+          continue;
+        }
+        validateArchiveEntryPath(relPath);
+        validateExtractedPathWithinRoot({ rootDir: targetDir, relPath, originalPath: entry });
+      }
+
+      const argv = ["tar", "xf", archivePath, "-C", targetDir];
+      if (strip > 0) {
+        argv.push("--strip-components", String(strip));
+      }
+      return await runCommandWithTimeout(argv, { timeoutMs });
+    }
+
+    return { stdout: "", stderr: `unsupported archive type: ${archiveType}`, code: null };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { stdout: "", stderr: message, code: 1 };
+  }
+}
+
+export async function installDownloadSpec(params: {
+  entry: SkillEntry;
+  spec: SkillInstallSpec;
+  timeoutMs: number;
+}): Promise<SkillInstallResult> {
+  const { entry, spec, timeoutMs } = params;
+  const url = spec.url?.trim();
+  if (!url) {
+    return {
+      ok: false,
+      message: "missing download url",
+      stdout: "",
+      stderr: "",
+      code: null,
+    };
+  }
+
+  let filename = "";
+  try {
+    const parsed = new URL(url);
+    filename = path.basename(parsed.pathname);
+  } catch {
+    filename = path.basename(url);
+  }
+  if (!filename) {
+    filename = "download";
+  }
+
+  let targetDir = "";
+  try {
+    targetDir = resolveDownloadTargetDir(entry, spec);
+    await ensureDir(targetDir);
+    const stat = await fs.promises.lstat(targetDir);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`targetDir is a symlink: ${targetDir}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`targetDir is not a directory: ${targetDir}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, message, stdout: "", stderr: message, code: null };
+  }
+
+  const archivePath = path.join(targetDir, filename);
+  let downloaded = 0;
+  try {
+    const result = await downloadFile(url, archivePath, timeoutMs);
+    downloaded = result.bytes;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, message, stdout: "", stderr: message, code: null };
+  }
+
+  const archiveType = resolveArchiveType(spec, filename);
+  const shouldExtract = spec.extract ?? Boolean(archiveType);
+  if (!shouldExtract) {
+    return {
+      ok: true,
+      message: `Downloaded to ${archivePath}`,
+      stdout: `downloaded=${downloaded}`,
+      stderr: "",
+      code: 0,
+    };
+  }
+
+  if (!archiveType) {
+    return {
+      ok: false,
+      message: "extract requested but archive type could not be detected",
+      stdout: "",
+      stderr: "",
+      code: null,
+    };
+  }
+
+  const extractResult = await extractArchive({
+    archivePath,
+    archiveType,
+    targetDir,
+    stripComponents: spec.stripComponents,
+    timeoutMs,
+  });
+  const success = extractResult.code === 0;
+  return {
+    ok: success,
+    message: success
+      ? `Downloaded and extracted to ${targetDir}`
+      : formatInstallFailureMessage(extractResult),
+    stdout: extractResult.stdout.trim(),
+    stderr: extractResult.stderr.trim(),
+    code: extractResult.code,
+  };
+}
diff --git a/src/agents/skills-install-fallback.e2e.test.ts b/src/agents/skills-install-fallback.e2e.test.ts
new file mode 100644
index 00000000000..70c6a9270d4
--- /dev/null
+++ b/src/agents/skills-install-fallback.e2e.test.ts
@@ -0,0 +1,240 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { installSkill } from "./skills-install.js";
+import { buildWorkspaceSkillStatus } from "./skills-status.js";
+
+const runCommandWithTimeoutMock = vi.fn();
+const scanDirectoryWithSummaryMock = vi.fn();
+const hasBinaryMock = vi.fn();
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+
+vi.mock("../infra/net/fetch-guard.js", () => ({
+  fetchWithSsrFGuard: vi.fn(),
+}));
+
+vi.mock("../security/skill-scanner.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../security/skill-scanner.js")>();
+  return {
+    ...actual,
+    scanDirectoryWithSummary: (...args: unknown[]) => scanDirectoryWithSummaryMock(...args),
+  };
+});
+
+vi.mock("../shared/config-eval.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../shared/config-eval.js")>();
+  return {
+    ...actual,
+    hasBinary: (...args: unknown[]) => hasBinaryMock(...args),
+  };
+});
+
+vi.mock("../infra/brew.js", () => ({
+  resolveBrewExecutable: () => undefined,
+}));
+
+async function writeSkillWithInstallers(
+  workspaceDir: string,
+  name: string,
+  installSpecs: Array<Record<string, string>>,
+): Promise<string> {
+  const skillDir = path.join(workspaceDir, "skills", name);
+  await fs.mkdir(skillDir, { recursive: true });
+  await fs.writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---
+name: ${name}
+description: test skill
+metadata: ${JSON.stringify({ openclaw: { install: installSpecs } })}
+---
+
+# ${name}
+`,
+    "utf-8",
+  );
+  await fs.writeFile(path.join(skillDir, "runner.js"), "export {};\n", "utf-8");
+  return skillDir;
+}
+
+async function writeSkillWithInstaller(
+  workspaceDir: string,
+  name: string,
+  kind: string,
+  extra: Record<string, string>,
+): Promise<string> {
+  return writeSkillWithInstallers(workspaceDir, name, [{ id: "deps", kind, ...extra }]);
+}
+
+describe("skills-install fallback edge cases", () => {
+  let workspaceDir: string;
+
+  beforeAll(async () => {
+    workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-fallback-test-"));
+    await writeSkillWithInstaller(workspaceDir, "go-tool-single", "go", {
+      module: "example.com/tool@latest",
+    });
+    await writeSkillWithInstallers(workspaceDir, "go-tool-multi", [
+      { id: "brew", kind: "brew", formula: "go" },
+      { id: "go", kind: "go", module: "example.com/tool@latest" },
+    ]);
+    await writeSkillWithInstaller(workspaceDir, "py-tool", "uv", {
+      package: "example-package",
+    });
+  });
+
+  beforeEach(async () => {
+    runCommandWithTimeoutMock.mockReset();
+    scanDirectoryWithSummaryMock.mockReset();
+    hasBinaryMock.mockReset();
+    scanDirectoryWithSummaryMock.mockResolvedValue({ critical: 0, warn: 0, findings: [] });
+  });
+
+  afterAll(async () => {
+    await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+  });
+
+  it("apt-get available but sudo missing/unusable returns helpful error for go install", async () => {
+    // go not available, brew not available, apt-get + sudo are available, sudo check fails
+    hasBinaryMock.mockImplementation((bin: string) => {
+      if (bin === "go") {
+        return false;
+      }
+      if (bin === "brew") {
+        return false;
+      }
+      if (bin === "apt-get" || bin === "sudo") {
+        return true;
+      }
+      return false;
+    });
+
+    // sudo -n true fails (no passwordless sudo)
+    runCommandWithTimeoutMock.mockResolvedValueOnce({
+      code: 1,
+      stdout: "",
+      stderr: "sudo: a password is required",
+    });
+
+    const result = await installSkill({
+      workspaceDir,
+      skillName: "go-tool-single",
+      installId: "deps",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("sudo");
+    expect(result.message).toContain("https://go.dev/doc/install");
+
+    // Verify sudo -n true was called
+    expect(runCommandWithTimeoutMock).toHaveBeenCalledWith(
+      ["sudo", "-n", "true"],
+      expect.objectContaining({ timeoutMs: 5_000 }),
+    );
+
+    // Verify apt-get install was NOT called
+    const aptCalls = runCommandWithTimeoutMock.mock.calls.filter(
+      (call) => Array.isArray(call[0]) && (call[0] as string[]).includes("apt-get"),
+    );
+    expect(aptCalls).toHaveLength(0);
+  });
+
+  it("status-selected go installer fails gracefully when apt fallback needs sudo", async () => {
+    // no go/brew, but apt and sudo are present
+    hasBinaryMock.mockImplementation((bin: string) => {
+      if (bin === "go" || bin === "brew") {
+        return false;
+      }
+      if (bin === "apt-get" || bin === "sudo") {
+        return true;
+      }
+      return false;
+    });
+
+    runCommandWithTimeoutMock.mockResolvedValueOnce({
+      code: 1,
+      stdout: "",
+      stderr: "sudo: a password is required",
+    });
+
+    const status = buildWorkspaceSkillStatus(workspaceDir);
+    const skill = status.skills.find((entry) => entry.name === "go-tool-multi");
+    expect(skill?.install[0]?.id).toBe("go");
+
+    const result = await installSkill({
+      workspaceDir,
+      skillName: "go-tool-multi",
+      installId: skill?.install[0]?.id ?? "",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("sudo is not usable");
+  });
+
+  it("handles sudo probe spawn failures without throwing", async () => {
+    // go not available, brew not available, apt-get + sudo appear available
+    hasBinaryMock.mockImplementation((bin: string) => {
+      if (bin === "go") {
+        return false;
+      }
+      if (bin === "brew") {
+        return false;
+      }
+      if (bin === "apt-get" || bin === "sudo") {
+        return true;
+      }
+      return false;
+    });
+
+    runCommandWithTimeoutMock.mockRejectedValueOnce(
+      new Error('Executable not found in $PATH: "sudo"'),
+    );
+
+    const result = await installSkill({
+      workspaceDir,
+      skillName: "go-tool-single",
+      installId: "deps",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("sudo is not usable");
+    expect(result.stderr).toContain("Executable not found");
+
+    // Verify apt-get install was NOT called
+    const aptCalls = runCommandWithTimeoutMock.mock.calls.filter(
+      (call) => Array.isArray(call[0]) && (call[0] as string[]).includes("apt-get"),
+    );
+    expect(aptCalls).toHaveLength(0);
+  });
+
+  it("uv not installed and no brew returns helpful error without curl auto-install", async () => {
+    // uv not available, brew not available, curl IS available
+    hasBinaryMock.mockImplementation((bin: string) => {
+      if (bin === "uv") {
+        return false;
+      }
+      if (bin === "brew") {
+        return false;
+      }
+      if (bin === "curl") {
+        return true;
+      }
+      return false;
+    });
+
+    const result = await installSkill({
+      workspaceDir,
+      skillName: "py-tool",
+      installId: "deps",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("https://docs.astral.sh/uv/getting-started/installation/");
+
+    // Verify NO curl command was attempted (no auto-install)
+    expect(runCommandWithTimeoutMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/agents/skills-install.download-tarbz2.e2e.test.ts b/src/agents/skills-install.download-tarbz2.e2e.test.ts
new file mode 100644
index 00000000000..1cadeb621e6
--- /dev/null
+++ b/src/agents/skills-install.download-tarbz2.e2e.test.ts
@@ -0,0 +1,317 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installSkill } from "./skills-install.js";
+
+const runCommandWithTimeoutMock = vi.fn();
+const scanDirectoryWithSummaryMock = vi.fn();
+const fetchWithSsrFGuardMock = vi.fn();
+
+const originalOpenClawStateDir = process.env.OPENCLAW_STATE_DIR;
+
+afterEach(() => {
+  if (originalOpenClawStateDir === undefined) {
+    delete process.env.OPENCLAW_STATE_DIR;
+  } else {
+    process.env.OPENCLAW_STATE_DIR = originalOpenClawStateDir;
+  }
+});
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+
+vi.mock("../infra/net/fetch-guard.js", () => ({
+  fetchWithSsrFGuard: (...args: unknown[]) => fetchWithSsrFGuardMock(...args),
+}));
+
+vi.mock("../security/skill-scanner.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../security/skill-scanner.js")>();
+  return {
+    ...actual,
+    scanDirectoryWithSummary: (...args: unknown[]) => scanDirectoryWithSummaryMock(...args),
+  };
+});
+
+async function writeDownloadSkill(params: {
+  workspaceDir: string;
+  name: string;
+  installId: string;
+  url: string;
+  stripComponents?: number;
+  targetDir: string;
+}): Promise<string> {
+  const skillDir = path.join(params.workspaceDir, "skills", params.name);
+  await fs.mkdir(skillDir, { recursive: true });
+  const meta = {
+    openclaw: {
+      install: [
+        {
+          id: params.installId,
+          kind: "download",
+          url: params.url,
+          archive: "tar.bz2",
+          extract: true,
+          stripComponents: params.stripComponents,
+          targetDir: params.targetDir,
+        },
+      ],
+    },
+  };
+  await fs.writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---
+name: ${params.name}
+description: test skill
+metadata: ${JSON.stringify(meta)}
+---
+
+# ${params.name}
+`,
+    "utf-8",
+  );
+  await fs.writeFile(path.join(skillDir, "runner.js"), "export {};\n", "utf-8");
+  return skillDir;
+}
+
+function setTempStateDir(workspaceDir: string): string {
+  const stateDir = path.join(workspaceDir, "state");
+  process.env.OPENCLAW_STATE_DIR = stateDir;
+  return stateDir;
+}
+
+describe("installSkill download extraction safety (tar.bz2)", () => {
+  beforeEach(() => {
+    runCommandWithTimeoutMock.mockReset();
+    scanDirectoryWithSummaryMock.mockReset();
+    fetchWithSsrFGuardMock.mockReset();
+    scanDirectoryWithSummaryMock.mockResolvedValue({
+      scannedFiles: 0,
+      critical: 0,
+      warn: 0,
+      info: 0,
+      findings: [],
+    });
+  });
+
+  it("rejects tar.bz2 traversal before extraction", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "tbz2-slip", "target");
+      const url = "https://example.invalid/evil.tbz2";
+
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
+        release: async () => undefined,
+      });
+
+      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
+        const cmd = argv as string[];
+        if (cmd[0] === "tar" && cmd[1] === "tf") {
+          return { code: 0, stdout: "../outside.txt\n", stderr: "", signal: null, killed: false };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "tvf") {
+          return {
+            code: 0,
+            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 ../outside.txt\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "xf") {
+          throw new Error("should not extract");
+        }
+        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "tbz2-slip",
+        installId: "dl",
+        url,
+        targetDir,
+      });
+
+      const result = await installSkill({ workspaceDir, skillName: "tbz2-slip", installId: "dl" });
+      expect(result.ok).toBe(false);
+      expect(
+        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
+      ).toBe(false);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("rejects tar.bz2 archives containing symlinks", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "tbz2-symlink", "target");
+      const url = "https://example.invalid/evil.tbz2";
+
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
+        release: async () => undefined,
+      });
+
+      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
+        const cmd = argv as string[];
+        if (cmd[0] === "tar" && cmd[1] === "tf") {
+          return {
+            code: 0,
+            stdout: "link\nlink/pwned.txt\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "tvf") {
+          return {
+            code: 0,
+            stdout: "lrwxr-xr-x  0 0 0 0 Jan  1 00:00 link -> ../outside\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "xf") {
+          throw new Error("should not extract");
+        }
+        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "tbz2-symlink",
+        installId: "dl",
+        url,
+        targetDir,
+      });
+
+      const result = await installSkill({
+        workspaceDir,
+        skillName: "tbz2-symlink",
+        installId: "dl",
+      });
+      expect(result.ok).toBe(false);
+      expect(result.stderr.toLowerCase()).toContain("link");
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("extracts tar.bz2 with stripComponents safely (preflight only)", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "tbz2-ok", "target");
+      const url = "https://example.invalid/good.tbz2";
+
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
+        release: async () => undefined,
+      });
+
+      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
+        const cmd = argv as string[];
+        if (cmd[0] === "tar" && cmd[1] === "tf") {
+          return {
+            code: 0,
+            stdout: "package/hello.txt\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "tvf") {
+          return {
+            code: 0,
+            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 package/hello.txt\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "xf") {
+          return { code: 0, stdout: "ok", stderr: "", signal: null, killed: false };
+        }
+        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "tbz2-ok",
+        installId: "dl",
+        url,
+        stripComponents: 1,
+        targetDir,
+      });
+
+      const result = await installSkill({ workspaceDir, skillName: "tbz2-ok", installId: "dl" });
+      expect(result.ok).toBe(true);
+      expect(
+        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
+      ).toBe(true);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("rejects tar.bz2 stripComponents escape", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "tbz2-strip-escape", "target");
+      const url = "https://example.invalid/evil.tbz2";
+
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
+        release: async () => undefined,
+      });
+
+      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
+        const cmd = argv as string[];
+        if (cmd[0] === "tar" && cmd[1] === "tf") {
+          return { code: 0, stdout: "a/../b.txt\n", stderr: "", signal: null, killed: false };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "tvf") {
+          return {
+            code: 0,
+            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 a/../b.txt\n",
+            stderr: "",
+            signal: null,
+            killed: false,
+          };
+        }
+        if (cmd[0] === "tar" && cmd[1] === "xf") {
+          throw new Error("should not extract");
+        }
+        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "tbz2-strip-escape",
+        installId: "dl",
+        url,
+        stripComponents: 1,
+        targetDir,
+      });
+
+      const result = await installSkill({
+        workspaceDir,
+        skillName: "tbz2-strip-escape",
+        installId: "dl",
+      });
+      expect(result.ok).toBe(false);
+      expect(
+        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
+      ).toBe(false);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+});
diff --git a/src/agents/skills-install.download.e2e.test.ts b/src/agents/skills-install.download.e2e.test.ts
new file mode 100644
index 00000000000..540922ea6f1
--- /dev/null
+++ b/src/agents/skills-install.download.e2e.test.ts
@@ -0,0 +1,335 @@
+import JSZip from "jszip";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import * as tar from "tar";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installSkill } from "./skills-install.js";
+
+const runCommandWithTimeoutMock = vi.fn();
+const scanDirectoryWithSummaryMock = vi.fn();
+const fetchWithSsrFGuardMock = vi.fn();
+
+const originalOpenClawStateDir = process.env.OPENCLAW_STATE_DIR;
+
+afterEach(() => {
+  if (originalOpenClawStateDir === undefined) {
+    delete process.env.OPENCLAW_STATE_DIR;
+  } else {
+    process.env.OPENCLAW_STATE_DIR = originalOpenClawStateDir;
+  }
+});
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+
+vi.mock("../infra/net/fetch-guard.js", () => ({
+  fetchWithSsrFGuard: (...args: unknown[]) => fetchWithSsrFGuardMock(...args),
+}));
+
+vi.mock("../security/skill-scanner.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../security/skill-scanner.js")>();
+  return {
+    ...actual,
+    scanDirectoryWithSummary: (...args: unknown[]) => scanDirectoryWithSummaryMock(...args),
+  };
+});
+
+async function writeDownloadSkill(params: {
+  workspaceDir: string;
+  name: string;
+  installId: string;
+  url: string;
+  archive: "tar.gz" | "tar.bz2" | "zip";
+  stripComponents?: number;
+  targetDir: string;
+}): Promise<string> {
+  const skillDir = path.join(params.workspaceDir, "skills", params.name);
+  await fs.mkdir(skillDir, { recursive: true });
+  const meta = {
+    openclaw: {
+      install: [
+        {
+          id: params.installId,
+          kind: "download",
+          url: params.url,
+          archive: params.archive,
+          extract: true,
+          stripComponents: params.stripComponents,
+          targetDir: params.targetDir,
+        },
+      ],
+    },
+  };
+  await fs.writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---
+name: ${params.name}
+description: test skill
+metadata: ${JSON.stringify(meta)}
+---
+
+# ${params.name}
+`,
+    "utf-8",
+  );
+  await fs.writeFile(path.join(skillDir, "runner.js"), "export {};\n", "utf-8");
+  return skillDir;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function setTempStateDir(workspaceDir: string): string {
+  const stateDir = path.join(workspaceDir, "state");
+  process.env.OPENCLAW_STATE_DIR = stateDir;
+  return stateDir;
+}
+
+describe("installSkill download extraction safety", () => {
+  beforeEach(() => {
+    runCommandWithTimeoutMock.mockReset();
+    scanDirectoryWithSummaryMock.mockReset();
+    fetchWithSsrFGuardMock.mockReset();
+    scanDirectoryWithSummaryMock.mockResolvedValue({
+      scannedFiles: 0,
+      critical: 0,
+      warn: 0,
+      info: 0,
+      findings: [],
+    });
+  });
+
+  it("rejects zip slip traversal", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "zip-slip", "target");
+      const outsideWriteDir = path.join(workspaceDir, "outside-write");
+      const outsideWritePath = path.join(outsideWriteDir, "pwned.txt");
+      const url = "https://example.invalid/evil.zip";
+
+      const zip = new JSZip();
+      zip.file("../outside-write/pwned.txt", "pwnd");
+      const buffer = await zip.generateAsync({ type: "nodebuffer" });
+
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "zip-slip",
+        installId: "dl",
+        url,
+        archive: "zip",
+        targetDir,
+      });
+
+      const result = await installSkill({ workspaceDir, skillName: "zip-slip", installId: "dl" });
+      expect(result.ok).toBe(false);
+      expect(await fileExists(outsideWritePath)).toBe(false);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("rejects tar.gz traversal", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "tar-slip", "target");
+      const insideDir = path.join(workspaceDir, "inside");
+      const outsideWriteDir = path.join(workspaceDir, "outside-write");
+      const outsideWritePath = path.join(outsideWriteDir, "pwned.txt");
+      const archivePath = path.join(workspaceDir, "evil.tgz");
+      const url = "https://example.invalid/evil";
+
+      await fs.mkdir(insideDir, { recursive: true });
+      await fs.mkdir(outsideWriteDir, { recursive: true });
+      await fs.writeFile(outsideWritePath, "pwnd", "utf-8");
+
+      await tar.c({ cwd: insideDir, file: archivePath, gzip: true }, [
+        "../outside-write/pwned.txt",
+      ]);
+      await fs.rm(outsideWriteDir, { recursive: true, force: true });
+
+      const buffer = await fs.readFile(archivePath);
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "tar-slip",
+        installId: "dl",
+        url,
+        archive: "tar.gz",
+        targetDir,
+      });
+
+      const result = await installSkill({ workspaceDir, skillName: "tar-slip", installId: "dl" });
+      expect(result.ok).toBe(false);
+      expect(await fileExists(outsideWritePath)).toBe(false);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("extracts zip with stripComponents safely", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(stateDir, "tools", "zip-good", "target");
+      const url = "https://example.invalid/good.zip";
+
+      const zip = new JSZip();
+      zip.file("package/hello.txt", "hi");
+      const buffer = await zip.generateAsync({ type: "nodebuffer" });
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "zip-good",
+        installId: "dl",
+        url,
+        archive: "zip",
+        stripComponents: 1,
+        targetDir,
+      });
+
+      const result = await installSkill({ workspaceDir, skillName: "zip-good", installId: "dl" });
+      expect(result.ok).toBe(true);
+      expect(await fs.readFile(path.join(targetDir, "hello.txt"), "utf-8")).toBe("hi");
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("rejects targetDir outside the per-skill tools root", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const targetDir = path.join(workspaceDir, "outside");
+      const url = "https://example.invalid/good.zip";
+
+      const zip = new JSZip();
+      zip.file("hello.txt", "hi");
+      const buffer = await zip.generateAsync({ type: "nodebuffer" });
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "targetdir-escape",
+        installId: "dl",
+        url,
+        archive: "zip",
+        targetDir,
+      });
+
+      const result = await installSkill({
+        workspaceDir,
+        skillName: "targetdir-escape",
+        installId: "dl",
+      });
+      expect(result.ok).toBe(false);
+      expect(result.stderr).toContain("Refusing to install outside the skill tools directory");
+      expect(fetchWithSsrFGuardMock.mock.calls.length).toBe(0);
+
+      expect(stateDir.length).toBeGreaterThan(0);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("allows relative targetDir inside the per-skill tools root", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      const stateDir = setTempStateDir(workspaceDir);
+      const url = "https://example.invalid/good.zip";
+
+      const zip = new JSZip();
+      zip.file("hello.txt", "hi");
+      const buffer = await zip.generateAsync({ type: "nodebuffer" });
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "relative-targetdir",
+        installId: "dl",
+        url,
+        archive: "zip",
+        targetDir: "runtime",
+      });
+
+      const result = await installSkill({
+        workspaceDir,
+        skillName: "relative-targetdir",
+        installId: "dl",
+      });
+      expect(result.ok).toBe(true);
+      expect(
+        await fs.readFile(
+          path.join(stateDir, "tools", "relative-targetdir", "runtime", "hello.txt"),
+          "utf-8",
+        ),
+      ).toBe("hi");
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("rejects relative targetDir traversal", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
+    try {
+      setTempStateDir(workspaceDir);
+      const url = "https://example.invalid/good.zip";
+
+      const zip = new JSZip();
+      zip.file("hello.txt", "hi");
+      const buffer = await zip.generateAsync({ type: "nodebuffer" });
+      fetchWithSsrFGuardMock.mockResolvedValue({
+        response: new Response(buffer, { status: 200 }),
+        release: async () => undefined,
+      });
+
+      await writeDownloadSkill({
+        workspaceDir,
+        name: "relative-traversal",
+        installId: "dl",
+        url,
+        archive: "zip",
+        targetDir: "../outside",
+      });
+
+      const result = await installSkill({
+        workspaceDir,
+        skillName: "relative-traversal",
+        installId: "dl",
+      });
+      expect(result.ok).toBe(false);
+      expect(result.stderr).toContain("Refusing to install outside the skill tools directory");
+      expect(fetchWithSsrFGuardMock.mock.calls.length).toBe(0);
+    } finally {
+      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+});
diff --git a/src/agents/skills-install.e2e.test.ts b/src/agents/skills-install.e2e.test.ts
index eeb64121b20..696b03e828b 100644
--- a/src/agents/skills-install.e2e.test.ts
+++ b/src/agents/skills-install.e2e.test.ts
@@ -1,23 +1,16 @@
-import JSZip from "jszip";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import * as tar from "tar";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { installSkill } from "./skills-install.js";
 
 const runCommandWithTimeoutMock = vi.fn();
 const scanDirectoryWithSummaryMock = vi.fn();
-const fetchWithSsrFGuardMock = vi.fn();
 
 vi.mock("../process/exec.js", () => ({
   runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
 }));
 
-vi.mock("../infra/net/fetch-guard.js", () => ({
-  fetchWithSsrFGuard: (...args: unknown[]) => fetchWithSsrFGuardMock(...args),
-}));
-
 vi.mock("../security/skill-scanner.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../security/skill-scanner.js")>();
   return {
@@ -45,62 +38,10 @@ metadata: {"openclaw":{"install":[{"id":"deps","kind":"node","package":"example-
   return skillDir;
 }
 
-async function writeDownloadSkill(params: {
-  workspaceDir: string;
-  name: string;
-  installId: string;
-  url: string;
-  archive: "tar.gz" | "tar.bz2" | "zip";
-  stripComponents?: number;
-  targetDir: string;
-}): Promise<string> {
-  const skillDir = path.join(params.workspaceDir, "skills", params.name);
-  await fs.mkdir(skillDir, { recursive: true });
-  const meta = {
-    openclaw: {
-      install: [
-        {
-          id: params.installId,
-          kind: "download",
-          url: params.url,
-          archive: params.archive,
-          extract: true,
-          stripComponents: params.stripComponents,
-          targetDir: params.targetDir,
-        },
-      ],
-    },
-  };
-  await fs.writeFile(
-    path.join(skillDir, "SKILL.md"),
-    `---
-name: ${params.name}
-description: test skill
-metadata: ${JSON.stringify(meta)}
----
-
-# ${params.name}
-`,
-    "utf-8",
-  );
-  await fs.writeFile(path.join(skillDir, "runner.js"), "export {};\n", "utf-8");
-  return skillDir;
-}
-
-async function fileExists(filePath: string): Promise<boolean> {
-  try {
-    await fs.stat(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 describe("installSkill code safety scanning", () => {
   beforeEach(() => {
     runCommandWithTimeoutMock.mockReset();
     scanDirectoryWithSummaryMock.mockReset();
-    fetchWithSsrFGuardMock.mockReset();
     runCommandWithTimeoutMock.mockResolvedValue({
       code: 0,
       stdout: "ok",
@@ -171,346 +112,3 @@ describe("installSkill code safety scanning", () => {
     }
   });
 });
-
-describe("installSkill download extraction safety", () => {
-  beforeEach(() => {
-    runCommandWithTimeoutMock.mockReset();
-    scanDirectoryWithSummaryMock.mockReset();
-    fetchWithSsrFGuardMock.mockReset();
-    scanDirectoryWithSummaryMock.mockResolvedValue({
-      scannedFiles: 0,
-      critical: 0,
-      warn: 0,
-      info: 0,
-      findings: [],
-    });
-  });
-
-  it("rejects zip slip traversal", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const outsideWriteDir = path.join(workspaceDir, "outside-write");
-      const outsideWritePath = path.join(outsideWriteDir, "pwned.txt");
-      const url = "https://example.invalid/evil.zip";
-
-      const zip = new JSZip();
-      zip.file("../outside-write/pwned.txt", "pwnd");
-      const buffer = await zip.generateAsync({ type: "nodebuffer" });
-
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(buffer, { status: 200 }),
-        release: async () => undefined,
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "zip-slip",
-        installId: "dl",
-        url,
-        archive: "zip",
-        targetDir,
-      });
-
-      const result = await installSkill({ workspaceDir, skillName: "zip-slip", installId: "dl" });
-      expect(result.ok).toBe(false);
-      expect(await fileExists(outsideWritePath)).toBe(false);
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("rejects tar.gz traversal", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const insideDir = path.join(workspaceDir, "inside");
-      const outsideWriteDir = path.join(workspaceDir, "outside-write");
-      const outsideWritePath = path.join(outsideWriteDir, "pwned.txt");
-      const archivePath = path.join(workspaceDir, "evil.tgz");
-      const url = "https://example.invalid/evil";
-
-      await fs.mkdir(insideDir, { recursive: true });
-      await fs.mkdir(outsideWriteDir, { recursive: true });
-      await fs.writeFile(outsideWritePath, "pwnd", "utf-8");
-
-      await tar.c({ cwd: insideDir, file: archivePath, gzip: true }, [
-        "../outside-write/pwned.txt",
-      ]);
-      await fs.rm(outsideWriteDir, { recursive: true, force: true });
-
-      const buffer = await fs.readFile(archivePath);
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(buffer, { status: 200 }),
-        release: async () => undefined,
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "tar-slip",
-        installId: "dl",
-        url,
-        archive: "tar.gz",
-        targetDir,
-      });
-
-      const result = await installSkill({ workspaceDir, skillName: "tar-slip", installId: "dl" });
-      expect(result.ok).toBe(false);
-      expect(await fileExists(outsideWritePath)).toBe(false);
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("extracts zip with stripComponents safely", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const url = "https://example.invalid/good.zip";
-
-      const zip = new JSZip();
-      zip.file("package/hello.txt", "hi");
-      const buffer = await zip.generateAsync({ type: "nodebuffer" });
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(buffer, { status: 200 }),
-        release: async () => undefined,
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "zip-good",
-        installId: "dl",
-        url,
-        archive: "zip",
-        stripComponents: 1,
-        targetDir,
-      });
-
-      const result = await installSkill({ workspaceDir, skillName: "zip-good", installId: "dl" });
-      expect(result.ok).toBe(true);
-      expect(await fs.readFile(path.join(targetDir, "hello.txt"), "utf-8")).toBe("hi");
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("rejects tar.bz2 traversal before extraction", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const url = "https://example.invalid/evil.tbz2";
-
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
-        release: async () => undefined,
-      });
-
-      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
-        const cmd = argv as string[];
-        if (cmd[0] === "tar" && cmd[1] === "tf") {
-          return { code: 0, stdout: "../outside.txt\n", stderr: "", signal: null, killed: false };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "tvf") {
-          return {
-            code: 0,
-            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 ../outside.txt\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "xf") {
-          throw new Error("should not extract");
-        }
-        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "tbz2-slip",
-        installId: "dl",
-        url,
-        archive: "tar.bz2",
-        targetDir,
-      });
-
-      const result = await installSkill({ workspaceDir, skillName: "tbz2-slip", installId: "dl" });
-      expect(result.ok).toBe(false);
-      expect(
-        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
-      ).toBe(false);
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("rejects tar.bz2 archives containing symlinks", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const url = "https://example.invalid/evil.tbz2";
-
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
-        release: async () => undefined,
-      });
-
-      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
-        const cmd = argv as string[];
-        if (cmd[0] === "tar" && cmd[1] === "tf") {
-          return {
-            code: 0,
-            stdout: "link\nlink/pwned.txt\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "tvf") {
-          return {
-            code: 0,
-            stdout: "lrwxr-xr-x  0 0 0 0 Jan  1 00:00 link -> ../outside\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "xf") {
-          throw new Error("should not extract");
-        }
-        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "tbz2-symlink",
-        installId: "dl",
-        url,
-        archive: "tar.bz2",
-        targetDir,
-      });
-
-      const result = await installSkill({
-        workspaceDir,
-        skillName: "tbz2-symlink",
-        installId: "dl",
-      });
-      expect(result.ok).toBe(false);
-      expect(result.stderr.toLowerCase()).toContain("link");
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("extracts tar.bz2 with stripComponents safely (preflight only)", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const url = "https://example.invalid/good.tbz2";
-
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
-        release: async () => undefined,
-      });
-
-      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
-        const cmd = argv as string[];
-        if (cmd[0] === "tar" && cmd[1] === "tf") {
-          return {
-            code: 0,
-            stdout: "package/hello.txt\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "tvf") {
-          return {
-            code: 0,
-            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 package/hello.txt\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "xf") {
-          return { code: 0, stdout: "ok", stderr: "", signal: null, killed: false };
-        }
-        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "tbz2-ok",
-        installId: "dl",
-        url,
-        archive: "tar.bz2",
-        stripComponents: 1,
-        targetDir,
-      });
-
-      const result = await installSkill({ workspaceDir, skillName: "tbz2-ok", installId: "dl" });
-      expect(result.ok).toBe(true);
-      expect(
-        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
-      ).toBe(true);
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  it("rejects tar.bz2 stripComponents escape", async () => {
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-skills-install-"));
-    try {
-      const targetDir = path.join(workspaceDir, "target");
-      const url = "https://example.invalid/evil.tbz2";
-
-      fetchWithSsrFGuardMock.mockResolvedValue({
-        response: new Response(new Uint8Array([1, 2, 3]), { status: 200 }),
-        release: async () => undefined,
-      });
-
-      runCommandWithTimeoutMock.mockImplementation(async (argv: unknown[]) => {
-        const cmd = argv as string[];
-        if (cmd[0] === "tar" && cmd[1] === "tf") {
-          return { code: 0, stdout: "a/../b.txt\n", stderr: "", signal: null, killed: false };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "tvf") {
-          return {
-            code: 0,
-            stdout: "-rw-r--r--  0 0 0 0 Jan  1 00:00 a/../b.txt\n",
-            stderr: "",
-            signal: null,
-            killed: false,
-          };
-        }
-        if (cmd[0] === "tar" && cmd[1] === "xf") {
-          throw new Error("should not extract");
-        }
-        return { code: 0, stdout: "", stderr: "", signal: null, killed: false };
-      });
-
-      await writeDownloadSkill({
-        workspaceDir,
-        name: "tbz2-strip-escape",
-        installId: "dl",
-        url,
-        archive: "tar.bz2",
-        stripComponents: 1,
-        targetDir,
-      });
-
-      const result = await installSkill({
-        workspaceDir,
-        skillName: "tbz2-strip-escape",
-        installId: "dl",
-      });
-      expect(result.ok).toBe(false);
-      expect(
-        runCommandWithTimeoutMock.mock.calls.some((call) => (call[0] as string[])[1] === "xf"),
-      ).toBe(false);
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-});
diff --git a/src/agents/skills-install.ts b/src/agents/skills-install.ts
index deee4b425f7..e6528202ca5 100644
--- a/src/agents/skills-install.ts
+++ b/src/agents/skills-install.ts
@@ -1,15 +1,11 @@
-import type { ReadableStream as NodeReadableStream } from "node:stream/web";
 import fs from "node:fs";
 import path from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
 import type { OpenClawConfig } from "../config/config.js";
-import { extractArchive as extractArchiveSafe } from "../infra/archive.js";
 import { resolveBrewExecutable } from "../infra/brew.js";
-import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
-import { runCommandWithTimeout } from "../process/exec.js";
+import { runCommandWithTimeout, type CommandOptions } from "../process/exec.js";
 import { scanDirectoryWithSummary } from "../security/skill-scanner.js";
-import { CONFIG_DIR, ensureDir, resolveUserPath } from "../utils.js";
+import { resolveUserPath } from "../utils.js";
+import { installDownloadSpec } from "./skills-install-download.js";
 import {
   hasBinary,
   loadWorkspaceSkillEntries,
@@ -18,7 +14,6 @@ import {
   type SkillInstallSpec,
   type SkillsInstallPreferences,
 } from "./skills.js";
-import { resolveSkillKey } from "./skills/frontmatter.js";
 
 export type SkillInstallRequest = {
   workspaceDir: string;
@@ -37,10 +32,6 @@ export type SkillInstallResult = {
   warnings?: string[];
 };
 
-function isNodeReadableStream(value: unknown): value is NodeJS.ReadableStream {
-  return Boolean(value && typeof (value as NodeJS.ReadableStream).pipe === "function");
-}
-
 function summarizeInstallOutput(text: string): string | undefined {
   const raw = text.trim();
   if (!raw) {
@@ -200,304 +191,6 @@ function buildInstallCommand(
   }
 }
 
-function resolveDownloadTargetDir(entry: SkillEntry, spec: SkillInstallSpec): string {
-  if (spec.targetDir?.trim()) {
-    return resolveUserPath(spec.targetDir);
-  }
-  const key = resolveSkillKey(entry.skill, entry);
-  return path.join(CONFIG_DIR, "tools", key);
-}
-
-function resolveArchiveType(spec: SkillInstallSpec, filename: string): string | undefined {
-  const explicit = spec.archive?.trim().toLowerCase();
-  if (explicit) {
-    return explicit;
-  }
-  const lower = filename.toLowerCase();
-  if (lower.endsWith(".tar.gz") || lower.endsWith(".tgz")) {
-    return "tar.gz";
-  }
-  if (lower.endsWith(".tar.bz2") || lower.endsWith(".tbz2")) {
-    return "tar.bz2";
-  }
-  if (lower.endsWith(".zip")) {
-    return "zip";
-  }
-  return undefined;
-}
-
-function normalizeArchiveEntryPath(raw: string): string {
-  return raw.replaceAll("\\", "/");
-}
-
-function isWindowsDrivePath(p: string): boolean {
-  return /^[a-zA-Z]:[\\/]/.test(p);
-}
-
-function validateArchiveEntryPath(entryPath: string): void {
-  if (!entryPath || entryPath === "." || entryPath === "./") {
-    return;
-  }
-  if (isWindowsDrivePath(entryPath)) {
-    throw new Error(`archive entry uses a drive path: ${entryPath}`);
-  }
-  const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
-  if (normalized === ".." || normalized.startsWith("../")) {
-    throw new Error(`archive entry escapes targetDir: ${entryPath}`);
-  }
-  if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
-    throw new Error(`archive entry is absolute: ${entryPath}`);
-  }
-}
-
-function resolveSafeBaseDir(rootDir: string): string {
-  const resolved = path.resolve(rootDir);
-  return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
-}
-
-function stripArchivePath(entryPath: string, stripComponents: number): string | null {
-  const raw = normalizeArchiveEntryPath(entryPath);
-  if (!raw || raw === "." || raw === "./") {
-    return null;
-  }
-
-  // Important: tar's --strip-components semantics operate on raw path segments,
-  // before any normalization that would collapse "..". We mimic that so we
-  // can detect strip-induced escapes like "a/../b" with stripComponents=1.
-  const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
-  const strip = Math.max(0, Math.floor(stripComponents));
-  const stripped = strip === 0 ? parts.join("/") : parts.slice(strip).join("/");
-  const result = path.posix.normalize(stripped);
-  if (!result || result === "." || result === "./") {
-    return null;
-  }
-  return result;
-}
-
-function validateExtractedPathWithinRoot(params: {
-  rootDir: string;
-  relPath: string;
-  originalPath: string;
-}): void {
-  const safeBase = resolveSafeBaseDir(params.rootDir);
-  const outPath = path.resolve(params.rootDir, params.relPath);
-  if (!outPath.startsWith(safeBase)) {
-    throw new Error(`archive entry escapes targetDir: ${params.originalPath}`);
-  }
-}
-
-async function downloadFile(
-  url: string,
-  destPath: string,
-  timeoutMs: number,
-): Promise<{ bytes: number }> {
-  const { response, release } = await fetchWithSsrFGuard({
-    url,
-    timeoutMs: Math.max(1_000, timeoutMs),
-  });
-  try {
-    if (!response.ok || !response.body) {
-      throw new Error(`Download failed (${response.status} ${response.statusText})`);
-    }
-    await ensureDir(path.dirname(destPath));
-    const file = fs.createWriteStream(destPath);
-    const body = response.body as unknown;
-    const readable = isNodeReadableStream(body)
-      ? body
-      : Readable.fromWeb(body as NodeReadableStream);
-    await pipeline(readable, file);
-    const stat = await fs.promises.stat(destPath);
-    return { bytes: stat.size };
-  } finally {
-    await release();
-  }
-}
-
-async function extractArchive(params: {
-  archivePath: string;
-  archiveType: string;
-  targetDir: string;
-  stripComponents?: number;
-  timeoutMs: number;
-}): Promise<{ stdout: string; stderr: string; code: number | null }> {
-  const { archivePath, archiveType, targetDir, stripComponents, timeoutMs } = params;
-  const strip =
-    typeof stripComponents === "number" && Number.isFinite(stripComponents)
-      ? Math.max(0, Math.floor(stripComponents))
-      : 0;
-
-  try {
-    if (archiveType === "zip") {
-      await extractArchiveSafe({
-        archivePath,
-        destDir: targetDir,
-        timeoutMs,
-        kind: "zip",
-        stripComponents: strip,
-      });
-      return { stdout: "", stderr: "", code: 0 };
-    }
-
-    if (archiveType === "tar.gz") {
-      await extractArchiveSafe({
-        archivePath,
-        destDir: targetDir,
-        timeoutMs,
-        kind: "tar",
-        stripComponents: strip,
-        tarGzip: true,
-      });
-      return { stdout: "", stderr: "", code: 0 };
-    }
-
-    if (archiveType === "tar.bz2") {
-      if (!hasBinary("tar")) {
-        return { stdout: "", stderr: "tar not found on PATH", code: null };
-      }
-
-      // Preflight list to prevent zip-slip style traversal before extraction.
-      const listResult = await runCommandWithTimeout(["tar", "tf", archivePath], { timeoutMs });
-      if (listResult.code !== 0) {
-        return {
-          stdout: listResult.stdout,
-          stderr: listResult.stderr || "tar list failed",
-          code: listResult.code,
-        };
-      }
-      const entries = listResult.stdout
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean);
-
-      const verboseResult = await runCommandWithTimeout(["tar", "tvf", archivePath], { timeoutMs });
-      if (verboseResult.code !== 0) {
-        return {
-          stdout: verboseResult.stdout,
-          stderr: verboseResult.stderr || "tar verbose list failed",
-          code: verboseResult.code,
-        };
-      }
-      for (const line of verboseResult.stdout.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
-        const typeChar = trimmed[0];
-        if (typeChar === "l" || typeChar === "h" || trimmed.includes(" -> ")) {
-          return {
-            stdout: verboseResult.stdout,
-            stderr: "tar archive contains link entries; refusing to extract for safety",
-            code: 1,
-          };
-        }
-      }
-
-      for (const entry of entries) {
-        validateArchiveEntryPath(entry);
-        const relPath = stripArchivePath(entry, strip);
-        if (!relPath) {
-          continue;
-        }
-        validateArchiveEntryPath(relPath);
-        validateExtractedPathWithinRoot({ rootDir: targetDir, relPath, originalPath: entry });
-      }
-
-      const argv = ["tar", "xf", archivePath, "-C", targetDir];
-      if (strip > 0) {
-        argv.push("--strip-components", String(strip));
-      }
-      return await runCommandWithTimeout(argv, { timeoutMs });
-    }
-
-    return { stdout: "", stderr: `unsupported archive type: ${archiveType}`, code: null };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { stdout: "", stderr: message, code: 1 };
-  }
-}
-
-async function installDownloadSpec(params: {
-  entry: SkillEntry;
-  spec: SkillInstallSpec;
-  timeoutMs: number;
-}): Promise<SkillInstallResult> {
-  const { entry, spec, timeoutMs } = params;
-  const url = spec.url?.trim();
-  if (!url) {
-    return {
-      ok: false,
-      message: "missing download url",
-      stdout: "",
-      stderr: "",
-      code: null,
-    };
-  }
-
-  let filename = "";
-  try {
-    const parsed = new URL(url);
-    filename = path.basename(parsed.pathname);
-  } catch {
-    filename = path.basename(url);
-  }
-  if (!filename) {
-    filename = "download";
-  }
-
-  const targetDir = resolveDownloadTargetDir(entry, spec);
-  await ensureDir(targetDir);
-
-  const archivePath = path.join(targetDir, filename);
-  let downloaded = 0;
-  try {
-    const result = await downloadFile(url, archivePath, timeoutMs);
-    downloaded = result.bytes;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, message, stdout: "", stderr: message, code: null };
-  }
-
-  const archiveType = resolveArchiveType(spec, filename);
-  const shouldExtract = spec.extract ?? Boolean(archiveType);
-  if (!shouldExtract) {
-    return {
-      ok: true,
-      message: `Downloaded to ${archivePath}`,
-      stdout: `downloaded=${downloaded}`,
-      stderr: "",
-      code: 0,
-    };
-  }
-
-  if (!archiveType) {
-    return {
-      ok: false,
-      message: "extract requested but archive type could not be detected",
-      stdout: "",
-      stderr: "",
-      code: null,
-    };
-  }
-
-  const extractResult = await extractArchive({
-    archivePath,
-    archiveType,
-    targetDir,
-    stripComponents: spec.stripComponents,
-    timeoutMs,
-  });
-  const success = extractResult.code === 0;
-  return {
-    ok: success,
-    message: success
-      ? `Downloaded and extracted to ${targetDir}`
-      : formatInstallFailureMessage(extractResult),
-    stdout: extractResult.stdout.trim(),
-    stderr: extractResult.stderr.trim(),
-    code: extractResult.code,
-  };
-}
-
 async function resolveBrewBinDir(timeoutMs: number, brewExe?: string): Promise<string | undefined> {
   const exe = brewExe ?? (hasBinary("brew") ? "brew" : resolveBrewExecutable());
   if (!exe) {
@@ -531,6 +224,209 @@ async function resolveBrewBinDir(timeoutMs: number, brewExe?: string): Promise<s
   return undefined;
 }
 
+type CommandResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+function createInstallFailure(params: {
+  message: string;
+  stdout?: string;
+  stderr?: string;
+  code?: number | null;
+}): SkillInstallResult {
+  return {
+    ok: false,
+    message: params.message,
+    stdout: params.stdout?.trim() ?? "",
+    stderr: params.stderr?.trim() ?? "",
+    code: params.code ?? null,
+  };
+}
+
+function createInstallSuccess(result: CommandResult): SkillInstallResult {
+  return {
+    ok: true,
+    message: "Installed",
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+    code: result.code,
+  };
+}
+
+async function runCommandSafely(
+  argv: string[],
+  optionsOrTimeout: number | CommandOptions,
+): Promise<CommandResult> {
+  try {
+    const result = await runCommandWithTimeout(argv, optionsOrTimeout);
+    return {
+      code: result.code,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } catch (err) {
+    return {
+      code: null,
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+async function runBestEffortCommand(
+  argv: string[],
+  optionsOrTimeout: number | CommandOptions,
+): Promise<void> {
+  await runCommandSafely(argv, optionsOrTimeout);
+}
+
+function resolveBrewMissingFailure(spec: SkillInstallSpec): SkillInstallResult {
+  const formula = spec.formula ?? "this package";
+  const hint =
+    process.platform === "linux"
+      ? `Homebrew is not installed. Install it from https://brew.sh or install "${formula}" manually using your system package manager (e.g. apt, dnf, pacman).`
+      : "Homebrew is not installed. Install it from https://brew.sh";
+  return createInstallFailure({ message: `brew not installed — ${hint}` });
+}
+
+async function ensureUvInstalled(params: {
+  spec: SkillInstallSpec;
+  brewExe?: string;
+  timeoutMs: number;
+}): Promise<SkillInstallResult | undefined> {
+  if (params.spec.kind !== "uv" || hasBinary("uv")) {
+    return undefined;
+  }
+
+  if (!params.brewExe) {
+    return createInstallFailure({
+      message:
+        "uv not installed — install manually: https://docs.astral.sh/uv/getting-started/installation/",
+    });
+  }
+
+  const brewResult = await runCommandSafely([params.brewExe, "install", "uv"], {
+    timeoutMs: params.timeoutMs,
+  });
+  if (brewResult.code === 0) {
+    return undefined;
+  }
+
+  return createInstallFailure({
+    message: "Failed to install uv (brew)",
+    ...brewResult,
+  });
+}
+
+async function installGoViaApt(timeoutMs: number): Promise<SkillInstallResult | undefined> {
+  const aptInstallArgv = ["apt-get", "install", "-y", "golang-go"];
+  const aptUpdateArgv = ["apt-get", "update", "-qq"];
+  const aptFailureMessage =
+    "go not installed — automatic install via apt failed. Install manually: https://go.dev/doc/install";
+
+  const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+  if (isRoot) {
+    // Best effort: fresh containers often need package indexes populated.
+    await runBestEffortCommand(aptUpdateArgv, { timeoutMs });
+    const aptResult = await runCommandSafely(aptInstallArgv, { timeoutMs });
+    if (aptResult.code === 0) {
+      return undefined;
+    }
+    return createInstallFailure({
+      message: aptFailureMessage,
+      ...aptResult,
+    });
+  }
+
+  if (!hasBinary("sudo")) {
+    return createInstallFailure({
+      message:
+        "go not installed — apt-get is available but sudo is not installed. Install manually: https://go.dev/doc/install",
+    });
+  }
+
+  const sudoCheck = await runCommandSafely(["sudo", "-n", "true"], {
+    timeoutMs: 5_000,
+  });
+  if (sudoCheck.code !== 0) {
+    return createInstallFailure({
+      message:
+        "go not installed — apt-get is available but sudo is not usable (missing or requires a password). Install manually: https://go.dev/doc/install",
+      ...sudoCheck,
+    });
+  }
+
+  // Best effort: fresh containers often need package indexes populated.
+  await runBestEffortCommand(["sudo", ...aptUpdateArgv], { timeoutMs });
+  const aptResult = await runCommandSafely(["sudo", ...aptInstallArgv], {
+    timeoutMs,
+  });
+  if (aptResult.code === 0) {
+    return undefined;
+  }
+
+  return createInstallFailure({
+    message: aptFailureMessage,
+    ...aptResult,
+  });
+}
+
+async function ensureGoInstalled(params: {
+  spec: SkillInstallSpec;
+  brewExe?: string;
+  timeoutMs: number;
+}): Promise<SkillInstallResult | undefined> {
+  if (params.spec.kind !== "go" || hasBinary("go")) {
+    return undefined;
+  }
+
+  if (params.brewExe) {
+    const brewResult = await runCommandSafely([params.brewExe, "install", "go"], {
+      timeoutMs: params.timeoutMs,
+    });
+    if (brewResult.code === 0) {
+      return undefined;
+    }
+    return createInstallFailure({
+      message: "Failed to install go (brew)",
+      ...brewResult,
+    });
+  }
+
+  if (hasBinary("apt-get")) {
+    return installGoViaApt(params.timeoutMs);
+  }
+
+  return createInstallFailure({
+    message: "go not installed — install manually: https://go.dev/doc/install",
+  });
+}
+
+async function executeInstallCommand(params: {
+  argv: string[] | null;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<SkillInstallResult> {
+  if (!params.argv || params.argv.length === 0) {
+    return createInstallFailure({ message: "invalid install command" });
+  }
+
+  const result = await runCommandSafely(params.argv, {
+    timeoutMs: params.timeoutMs,
+    env: params.env,
+  });
+  if (result.code === 0) {
+    return createInstallSuccess(result);
+  }
+
+  return createInstallFailure({
+    message: formatInstallFailureMessage(result),
+    ...result,
+  });
+}
+
 export async function installSkill(params: SkillInstallRequest): Promise<SkillInstallResult> {
   const timeoutMs = Math.min(Math.max(params.timeoutMs ?? 300_000, 1_000), 900_000);
   const workspaceDir = resolveUserPath(params.workspaceDir);
@@ -582,93 +478,22 @@ export async function installSkill(params: SkillInstallRequest): Promise<SkillIn
 
   const brewExe = hasBinary("brew") ? "brew" : resolveBrewExecutable();
   if (spec.kind === "brew" && !brewExe) {
-    return withWarnings(
-      {
-        ok: false,
-        message: "brew not installed",
-        stdout: "",
-        stderr: "",
-        code: null,
-      },
-      warnings,
-    );
-  }
-  if (spec.kind === "uv" && !hasBinary("uv")) {
-    if (brewExe) {
-      const brewResult = await runCommandWithTimeout([brewExe, "install", "uv"], {
-        timeoutMs,
-      });
-      if (brewResult.code !== 0) {
-        return withWarnings(
-          {
-            ok: false,
-            message: "Failed to install uv (brew)",
-            stdout: brewResult.stdout.trim(),
-            stderr: brewResult.stderr.trim(),
-            code: brewResult.code,
-          },
-          warnings,
-        );
-      }
-    } else {
-      return withWarnings(
-        {
-          ok: false,
-          message: "uv not installed (install via brew)",
-          stdout: "",
-          stderr: "",
-          code: null,
-        },
-        warnings,
-      );
-    }
-  }
-  if (!command.argv || command.argv.length === 0) {
-    return withWarnings(
-      {
-        ok: false,
-        message: "invalid install command",
-        stdout: "",
-        stderr: "",
-        code: null,
-      },
-      warnings,
-    );
+    return withWarnings(resolveBrewMissingFailure(spec), warnings);
   }
 
-  if (spec.kind === "brew" && brewExe && command.argv[0] === "brew") {
-    command.argv[0] = brewExe;
+  const uvInstallFailure = await ensureUvInstalled({ spec, brewExe, timeoutMs });
+  if (uvInstallFailure) {
+    return withWarnings(uvInstallFailure, warnings);
   }
 
-  if (spec.kind === "go" && !hasBinary("go")) {
-    if (brewExe) {
-      const brewResult = await runCommandWithTimeout([brewExe, "install", "go"], {
-        timeoutMs,
-      });
-      if (brewResult.code !== 0) {
-        return withWarnings(
-          {
-            ok: false,
-            message: "Failed to install go (brew)",
-            stdout: brewResult.stdout.trim(),
-            stderr: brewResult.stderr.trim(),
-            code: brewResult.code,
-          },
-          warnings,
-        );
-      }
-    } else {
-      return withWarnings(
-        {
-          ok: false,
-          message: "go not installed (install via brew)",
-          stdout: "",
-          stderr: "",
-          code: null,
-        },
-        warnings,
-      );
-    }
+  const goInstallFailure = await ensureGoInstalled({ spec, brewExe, timeoutMs });
+  if (goInstallFailure) {
+    return withWarnings(goInstallFailure, warnings);
+  }
+
+  const argv = command.argv ? [...command.argv] : null;
+  if (spec.kind === "brew" && brewExe && argv?.[0] === "brew") {
+    argv[0] = brewExe;
   }
 
   let env: NodeJS.ProcessEnv | undefined;
@@ -679,31 +504,5 @@ export async function installSkill(params: SkillInstallRequest): Promise<SkillIn
     }
   }
 
-  const result = await (async () => {
-    const argv = command.argv;
-    if (!argv || argv.length === 0) {
-      return { code: null, stdout: "", stderr: "invalid install command" };
-    }
-    try {
-      return await runCommandWithTimeout(argv, {
-        timeoutMs,
-        env,
-      });
-    } catch (err) {
-      const stderr = err instanceof Error ? err.message : String(err);
-      return { code: null, stdout: "", stderr };
-    }
-  })();
-
-  const success = result.code === 0;
-  return withWarnings(
-    {
-      ok: success,
-      message: success ? "Installed" : formatInstallFailureMessage(result),
-      stdout: result.stdout.trim(),
-      stderr: result.stderr.trim(),
-      code: result.code,
-    },
-    warnings,
-  );
+  return withWarnings(await executeInstallCommand({ argv, timeoutMs, env }), warnings);
 }
diff --git a/src/agents/skills-status.ts b/src/agents/skills-status.ts
index 8bcf1cd6689..28409883ea3 100644
--- a/src/agents/skills-status.ts
+++ b/src/agents/skills-status.ts
@@ -1,7 +1,7 @@
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
-import { resolveEmojiAndHomepage } from "../shared/entry-metadata.js";
-import { evaluateRequirementsFromMetadataWithRemote } from "../shared/requirements.js";
+import type { RequirementConfigCheck, Requirements } from "../shared/requirements.js";
+import { evaluateEntryMetadataRequirements } from "../shared/entry-status.js";
 import { CONFIG_DIR } from "../utils.js";
 import {
   hasBinary,
@@ -18,10 +18,7 @@ import {
 } from "./skills.js";
 import { resolveBundledSkillsContext } from "./skills/bundled-context.js";
 
-export type SkillStatusConfigCheck = {
-  path: string;
-  satisfied: boolean;
-};
+export type SkillStatusConfigCheck = RequirementConfigCheck;
 
 export type SkillInstallOption = {
   id: string;
@@ -45,20 +42,8 @@ export type SkillStatusEntry = {
   disabled: boolean;
   blockedByAllowlist: boolean;
   eligible: boolean;
-  requirements: {
-    bins: string[];
-    anyBins: string[];
-    env: string[];
-    config: string[];
-    os: string[];
-  };
-  missing: {
-    bins: string[];
-    anyBins: string[];
-    env: string[];
-    config: string[];
-    os: string[];
-  };
+  requirements: Requirements;
+  missing: Requirements;
   configChecks: SkillStatusConfigCheck[];
   install: SkillInstallOption[];
 };
@@ -80,6 +65,7 @@ function selectPreferredInstallSpec(
   if (install.length === 0) {
     return undefined;
   }
+
   const indexed = install.map((spec, index) => ({ spec, index }));
   const findKind = (kind: SkillInstallSpec["kind"]) =>
     indexed.find((item) => item.spec.kind === kind);
@@ -88,23 +74,32 @@ function selectPreferredInstallSpec(
   const nodeSpec = findKind("node");
   const goSpec = findKind("go");
   const uvSpec = findKind("uv");
+  const downloadSpec = findKind("download");
+  const brewAvailable = hasBinary("brew");
 
-  if (prefs.preferBrew && hasBinary("brew") && brewSpec) {
-    return brewSpec;
+  // Table-driven preference chain; first match wins.
+  const pickers: Array<() => { spec: SkillInstallSpec; index: number } | undefined> = [
+    () => (prefs.preferBrew && brewAvailable ? brewSpec : undefined),
+    () => uvSpec,
+    () => nodeSpec,
+    // Only prefer brew when available to avoid guaranteed failure on Linux/Docker.
+    () => (brewAvailable ? brewSpec : undefined),
+    () => goSpec,
+    // Prefer download over an unavailable brew spec.
+    () => downloadSpec,
+    // Last resort: surface descriptive brew-missing error instead of "no installer found".
+    () => brewSpec,
+    () => indexed[0],
+  ];
+
+  for (const pick of pickers) {
+    const selected = pick();
+    if (selected) {
+      return selected;
+    }
   }
-  if (uvSpec) {
-    return uvSpec;
-  }
-  if (nodeSpec) {
-    return nodeSpec;
-  }
-  if (brewSpec) {
-    return brewSpec;
-  }
-  if (goSpec) {
-    return goSpec;
-  }
-  return indexed[0];
+
+  return undefined;
 }
 
 function normalizeInstallOptions(
@@ -184,34 +179,27 @@ function buildSkillStatus(
   const allowBundled = resolveBundledAllowlist(config);
   const blockedByAllowlist = !isBundledSkillAllowed(entry, allowBundled);
   const always = entry.metadata?.always === true;
-  const { emoji, homepage } = resolveEmojiAndHomepage({
-    metadata: entry.metadata,
-    frontmatter: entry.frontmatter,
-  });
   const bundled =
     bundledNames && bundledNames.size > 0
       ? bundledNames.has(entry.skill.name)
       : entry.skill.source === "openclaw-bundled";
 
-  const {
-    required,
-    missing,
-    eligible: requirementsSatisfied,
-    configChecks,
-  } = evaluateRequirementsFromMetadataWithRemote({
-    always,
-    metadata: entry.metadata,
-    hasLocalBin: hasBinary,
-    localPlatform: process.platform,
-    remote: eligibility?.remote,
-    isEnvSatisfied: (envName) =>
-      Boolean(
-        process.env[envName] ||
-        skillConfig?.env?.[envName] ||
-        (skillConfig?.apiKey && entry.metadata?.primaryEnv === envName),
-      ),
-    isConfigSatisfied: (pathStr) => isConfigPathTruthy(config, pathStr),
-  });
+  const { emoji, homepage, required, missing, requirementsSatisfied, configChecks } =
+    evaluateEntryMetadataRequirements({
+      always,
+      metadata: entry.metadata,
+      frontmatter: entry.frontmatter,
+      hasLocalBin: hasBinary,
+      localPlatform: process.platform,
+      remote: eligibility?.remote,
+      isEnvSatisfied: (envName) =>
+        Boolean(
+          process.env[envName] ||
+          skillConfig?.env?.[envName] ||
+          (skillConfig?.apiKey && entry.metadata?.primaryEnv === envName),
+        ),
+      isConfigSatisfied: (pathStr) => isConfigPathTruthy(config, pathStr),
+    });
   const eligible = !disabled && !blockedByAllowlist && requirementsSatisfied;
 
   return {
diff --git a/src/agents/skills.build-workspace-skills-prompt.applies-bundled-allowlist-without-affecting-workspace-skills.e2e.test.ts b/src/agents/skills.build-workspace-skills-prompt.applies-bundled-allowlist-without-affecting-workspace-skills.e2e.test.ts
index 44a8e0218a5..dad26e0fb74 100644
--- a/src/agents/skills.build-workspace-skills-prompt.applies-bundled-allowlist-without-affecting-workspace-skills.e2e.test.ts
+++ b/src/agents/skills.build-workspace-skills-prompt.applies-bundled-allowlist-without-affecting-workspace-skills.e2e.test.ts
@@ -2,30 +2,9 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { writeSkill } from "./skills.e2e-test-helpers.js";
 import { buildWorkspaceSkillsPrompt } from "./skills.js";
 
-async function writeSkill(params: {
-  dir: string;
-  name: string;
-  description: string;
-  metadata?: string;
-  body?: string;
-}) {
-  const { dir, name, description, metadata, body } = params;
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(
-    path.join(dir, "SKILL.md"),
-    `---
-name: ${name}
-description: ${description}${metadata ? `\nmetadata: ${metadata}` : ""}
----
-
-${body ?? `# ${name}\n`}
-`,
-    "utf-8",
-  );
-}
-
 describe("buildWorkspaceSkillsPrompt", () => {
   it("applies bundled allowlist without affecting workspace skills", async () => {
     const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-"));
diff --git a/src/agents/skills.build-workspace-skills-prompt.prefers-workspace-skills-managed-skills.e2e.test.ts b/src/agents/skills.build-workspace-skills-prompt.prefers-workspace-skills-managed-skills.e2e.test.ts
index cc85f1f5701..af9c651fc80 100644
--- a/src/agents/skills.build-workspace-skills-prompt.prefers-workspace-skills-managed-skills.e2e.test.ts
+++ b/src/agents/skills.build-workspace-skills-prompt.prefers-workspace-skills-managed-skills.e2e.test.ts
@@ -2,30 +2,9 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { writeSkill } from "./skills.e2e-test-helpers.js";
 import { buildWorkspaceSkillsPrompt } from "./skills.js";
 
-async function writeSkill(params: {
-  dir: string;
-  name: string;
-  description: string;
-  metadata?: string;
-  body?: string;
-}) {
-  const { dir, name, description, metadata, body } = params;
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(
-    path.join(dir, "SKILL.md"),
-    `---
-name: ${name}
-description: ${description}${metadata ? `\nmetadata: ${metadata}` : ""}
----
-
-${body ?? `# ${name}\n`}
-`,
-    "utf-8",
-  );
-}
-
 describe("buildWorkspaceSkillsPrompt", () => {
   it("prefers workspace skills over managed skills", async () => {
     const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-"));
diff --git a/src/agents/skills.e2e-test-helpers.ts b/src/agents/skills.e2e-test-helpers.ts
new file mode 100644
index 00000000000..43f6fb70398
--- /dev/null
+++ b/src/agents/skills.e2e-test-helpers.ts
@@ -0,0 +1,24 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function writeSkill(params: {
+  dir: string;
+  name: string;
+  description: string;
+  metadata?: string;
+  body?: string;
+}) {
+  const { dir, name, description, metadata, body } = params;
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(
+    path.join(dir, "SKILL.md"),
+    `---
+name: ${name}
+description: ${description}${metadata ? `\nmetadata: ${metadata}` : ""}
+---
+
+${body ?? `# ${name}\n`}
+`,
+    "utf-8",
+  );
+}
diff --git a/src/agents/skills/env-overrides.ts b/src/agents/skills/env-overrides.ts
index 4d6e97a2e32..281efc8a2a7 100644
--- a/src/agents/skills/env-overrides.ts
+++ b/src/agents/skills/env-overrides.ts
@@ -3,34 +3,32 @@ import type { SkillEntry, SkillSnapshot } from "./types.js";
 import { resolveSkillConfig } from "./config.js";
 import { resolveSkillKey } from "./frontmatter.js";
 
-export function applySkillEnvOverrides(params: { skills: SkillEntry[]; config?: OpenClawConfig }) {
-  const { skills, config } = params;
-  const updates: Array<{ key: string; prev: string | undefined }> = [];
+type EnvUpdate = { key: string; prev: string | undefined };
+type SkillConfig = NonNullable<ReturnType<typeof resolveSkillConfig>>;
 
-  for (const entry of skills) {
-    const skillKey = resolveSkillKey(entry.skill, entry);
-    const skillConfig = resolveSkillConfig(config, skillKey);
-    if (!skillConfig) {
-      continue;
-    }
-
-    if (skillConfig.env) {
-      for (const [envKey, envValue] of Object.entries(skillConfig.env)) {
-        if (!envValue || process.env[envKey]) {
-          continue;
-        }
-        updates.push({ key: envKey, prev: process.env[envKey] });
-        process.env[envKey] = envValue;
+function applySkillConfigEnvOverrides(params: {
+  updates: EnvUpdate[];
+  skillConfig: SkillConfig;
+  primaryEnv?: string | null;
+}) {
+  const { updates, skillConfig, primaryEnv } = params;
+  if (skillConfig.env) {
+    for (const [envKey, envValue] of Object.entries(skillConfig.env)) {
+      if (!envValue || process.env[envKey]) {
+        continue;
       }
-    }
-
-    const primaryEnv = entry.metadata?.primaryEnv;
-    if (primaryEnv && skillConfig.apiKey && !process.env[primaryEnv]) {
-      updates.push({ key: primaryEnv, prev: process.env[primaryEnv] });
-      process.env[primaryEnv] = skillConfig.apiKey;
+      updates.push({ key: envKey, prev: process.env[envKey] });
+      process.env[envKey] = envValue;
     }
   }
 
+  if (primaryEnv && skillConfig.apiKey && !process.env[primaryEnv]) {
+    updates.push({ key: primaryEnv, prev: process.env[primaryEnv] });
+    process.env[primaryEnv] = skillConfig.apiKey;
+  }
+}
+
+function createEnvReverter(updates: EnvUpdate[]) {
   return () => {
     for (const update of updates) {
       if (update.prev === undefined) {
@@ -42,6 +40,27 @@ export function applySkillEnvOverrides(params: { skills: SkillEntry[]; config?:
   };
 }
 
+export function applySkillEnvOverrides(params: { skills: SkillEntry[]; config?: OpenClawConfig }) {
+  const { skills, config } = params;
+  const updates: EnvUpdate[] = [];
+
+  for (const entry of skills) {
+    const skillKey = resolveSkillKey(entry.skill, entry);
+    const skillConfig = resolveSkillConfig(config, skillKey);
+    if (!skillConfig) {
+      continue;
+    }
+
+    applySkillConfigEnvOverrides({
+      updates,
+      skillConfig,
+      primaryEnv: entry.metadata?.primaryEnv,
+    });
+  }
+
+  return createEnvReverter(updates);
+}
+
 export function applySkillEnvOverridesFromSnapshot(params: {
   snapshot?: SkillSnapshot;
   config?: OpenClawConfig;
@@ -50,7 +69,7 @@ export function applySkillEnvOverridesFromSnapshot(params: {
   if (!snapshot) {
     return () => {};
   }
-  const updates: Array<{ key: string; prev: string | undefined }> = [];
+  const updates: EnvUpdate[] = [];
 
   for (const skill of snapshot.skills) {
     const skillConfig = resolveSkillConfig(config, skill.name);
@@ -58,32 +77,12 @@ export function applySkillEnvOverridesFromSnapshot(params: {
       continue;
     }
 
-    if (skillConfig.env) {
-      for (const [envKey, envValue] of Object.entries(skillConfig.env)) {
-        if (!envValue || process.env[envKey]) {
-          continue;
-        }
-        updates.push({ key: envKey, prev: process.env[envKey] });
-        process.env[envKey] = envValue;
-      }
-    }
-
-    if (skill.primaryEnv && skillConfig.apiKey && !process.env[skill.primaryEnv]) {
-      updates.push({
-        key: skill.primaryEnv,
-        prev: process.env[skill.primaryEnv],
-      });
-      process.env[skill.primaryEnv] = skillConfig.apiKey;
-    }
+    applySkillConfigEnvOverrides({
+      updates,
+      skillConfig,
+      primaryEnv: skill.primaryEnv,
+    });
   }
 
-  return () => {
-    for (const update of updates) {
-      if (update.prev === undefined) {
-        delete process.env[update.key];
-      } else {
-        process.env[update.key] = update.prev;
-      }
-    }
-  };
+  return createEnvReverter(updates);
 }
diff --git a/src/agents/skills/filter.test.ts b/src/agents/skills/filter.test.ts
new file mode 100644
index 00000000000..8cd64e429e3
--- /dev/null
+++ b/src/agents/skills/filter.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+  matchesSkillFilter,
+  normalizeSkillFilter,
+  normalizeSkillFilterForComparison,
+} from "./filter.js";
+
+describe("skills/filter", () => {
+  it("normalizes configured filters with trimming", () => {
+    expect(normalizeSkillFilter([" weather ", "", "meme-factory"])).toEqual([
+      "weather",
+      "meme-factory",
+    ]);
+  });
+
+  it("preserves explicit empty list as []", () => {
+    expect(normalizeSkillFilter([])).toEqual([]);
+    expect(normalizeSkillFilter(undefined)).toBeUndefined();
+  });
+
+  it("normalizes for comparison with dedupe + ordering", () => {
+    expect(normalizeSkillFilterForComparison(["weather", "meme-factory", "weather"])).toEqual([
+      "meme-factory",
+      "weather",
+    ]);
+  });
+
+  it("matches equivalent filters after normalization", () => {
+    expect(matchesSkillFilter(["weather", "meme-factory"], [" meme-factory ", "weather"])).toBe(
+      true,
+    );
+    expect(matchesSkillFilter(undefined, undefined)).toBe(true);
+    expect(matchesSkillFilter([], undefined)).toBe(false);
+  });
+});
diff --git a/src/agents/skills/filter.ts b/src/agents/skills/filter.ts
new file mode 100644
index 00000000000..a5fb8222874
--- /dev/null
+++ b/src/agents/skills/filter.ts
@@ -0,0 +1,31 @@
+export function normalizeSkillFilter(skillFilter?: ReadonlyArray<unknown>): string[] | undefined {
+  if (skillFilter === undefined) {
+    return undefined;
+  }
+  return skillFilter.map((entry) => String(entry).trim()).filter(Boolean);
+}
+
+export function normalizeSkillFilterForComparison(
+  skillFilter?: ReadonlyArray<unknown>,
+): string[] | undefined {
+  const normalized = normalizeSkillFilter(skillFilter);
+  if (normalized === undefined) {
+    return undefined;
+  }
+  return Array.from(new Set(normalized)).toSorted();
+}
+
+export function matchesSkillFilter(
+  cached?: ReadonlyArray<unknown>,
+  next?: ReadonlyArray<unknown>,
+): boolean {
+  const cachedNormalized = normalizeSkillFilterForComparison(cached);
+  const nextNormalized = normalizeSkillFilterForComparison(next);
+  if (cachedNormalized === undefined || nextNormalized === undefined) {
+    return cachedNormalized === nextNormalized;
+  }
+  if (cachedNormalized.length !== nextNormalized.length) {
+    return false;
+  }
+  return cachedNormalized.every((entry, index) => entry === nextNormalized[index]);
+}
diff --git a/src/agents/skills/frontmatter.ts b/src/agents/skills/frontmatter.ts
index 857bed643ea..e97b5ab68cd 100644
--- a/src/agents/skills/frontmatter.ts
+++ b/src/agents/skills/frontmatter.ts
@@ -12,6 +12,9 @@ import {
   normalizeStringList,
   parseFrontmatterBool,
   resolveOpenClawManifestBlock,
+  resolveOpenClawManifestInstall,
+  resolveOpenClawManifestOs,
+  resolveOpenClawManifestRequires,
 } from "../../shared/frontmatter.js";
 
 export function parseFrontmatter(content: string): ParsedSkillFrontmatter {
@@ -83,15 +86,9 @@ export function resolveOpenClawMetadata(
   if (!metadataObj) {
     return undefined;
   }
-  const requiresRaw =
-    typeof metadataObj.requires === "object" && metadataObj.requires !== null
-      ? (metadataObj.requires as Record<string, unknown>)
-      : undefined;
-  const installRaw = Array.isArray(metadataObj.install) ? (metadataObj.install as unknown[]) : [];
-  const install = installRaw
-    .map((entry) => parseInstallSpec(entry))
-    .filter((entry): entry is SkillInstallSpec => Boolean(entry));
-  const osRaw = normalizeStringList(metadataObj.os);
+  const requires = resolveOpenClawManifestRequires(metadataObj);
+  const install = resolveOpenClawManifestInstall(metadataObj, parseInstallSpec);
+  const osRaw = resolveOpenClawManifestOs(metadataObj);
   return {
     always: typeof metadataObj.always === "boolean" ? metadataObj.always : undefined,
     emoji: typeof metadataObj.emoji === "string" ? metadataObj.emoji : undefined,
@@ -99,14 +96,7 @@ export function resolveOpenClawMetadata(
     skillKey: typeof metadataObj.skillKey === "string" ? metadataObj.skillKey : undefined,
     primaryEnv: typeof metadataObj.primaryEnv === "string" ? metadataObj.primaryEnv : undefined,
     os: osRaw.length > 0 ? osRaw : undefined,
-    requires: requiresRaw
-      ? {
-          bins: normalizeStringList(requiresRaw.bins),
-          anyBins: normalizeStringList(requiresRaw.anyBins),
-          env: normalizeStringList(requiresRaw.env),
-          config: normalizeStringList(requiresRaw.config),
-        }
-      : undefined,
+    requires: requires,
     install: install.length > 0 ? install : undefined,
   };
 }
diff --git a/src/agents/skills/tools-dir.ts b/src/agents/skills/tools-dir.ts
new file mode 100644
index 00000000000..767ad3f79fd
--- /dev/null
+++ b/src/agents/skills/tools-dir.ts
@@ -0,0 +1,11 @@
+import path from "node:path";
+import type { SkillEntry } from "./types.js";
+import { safePathSegmentHashed } from "../../infra/install-safe-path.js";
+import { resolveConfigDir } from "../../utils.js";
+import { resolveSkillKey } from "./frontmatter.js";
+
+export function resolveSkillToolsRootDir(entry: SkillEntry): string {
+  const key = resolveSkillKey(entry.skill, entry);
+  const safeKey = safePathSegmentHashed(key);
+  return path.join(resolveConfigDir(), "tools", safeKey);
+}
diff --git a/src/agents/skills/types.ts b/src/agents/skills/types.ts
index b518d4bb601..abfb8743dd7 100644
--- a/src/agents/skills/types.ts
+++ b/src/agents/skills/types.ts
@@ -82,6 +82,8 @@ export type SkillEligibilityContext = {
 export type SkillSnapshot = {
   prompt: string;
   skills: Array<{ name: string; primaryEnv?: string }>;
+  /** Normalized agent-level filter used to build this snapshot; undefined means unrestricted. */
+  skillFilter?: string[];
   resolvedSkills?: Skill[];
   version?: number;
 };
diff --git a/src/agents/skills/workspace.ts b/src/agents/skills/workspace.ts
index ee666eacaab..51b0c2bbd1d 100644
--- a/src/agents/skills/workspace.ts
+++ b/src/agents/skills/workspace.ts
@@ -19,6 +19,7 @@ import { CONFIG_DIR, resolveUserPath } from "../../utils.js";
 import { resolveSandboxPath } from "../sandbox-paths.js";
 import { resolveBundledSkillsDir } from "./bundled-dir.js";
 import { shouldIncludeSkill } from "./config.js";
+import { normalizeSkillFilter } from "./filter.js";
 import {
   parseFrontmatter,
   resolveOpenClawMetadata,
@@ -52,14 +53,16 @@ function filterSkillEntries(
   let filtered = entries.filter((entry) => shouldIncludeSkill({ entry, config, eligibility }));
   // If skillFilter is provided, only include skills in the filter list.
   if (skillFilter !== undefined) {
-    const normalized = skillFilter.map((entry) => String(entry).trim()).filter(Boolean);
+    const normalized = normalizeSkillFilter(skillFilter) ?? [];
     const label = normalized.length > 0 ? normalized.join(", ") : "(none)";
-    console.log(`[skills] Applying skill filter: ${label}`);
+    skillsLogger.debug(`Applying skill filter: ${label}`);
     filtered =
       normalized.length > 0
         ? filtered.filter((entry) => normalized.includes(entry.skill.name))
         : [];
-    console.log(`[skills] After filter: ${filtered.map((entry) => entry.skill.name).join(", ")}`);
+    skillsLogger.debug(
+      `After skill filter: ${filtered.map((entry) => entry.skill.name).join(", ") || "(none)"}`,
+    );
   }
   return filtered;
 }
@@ -232,12 +235,14 @@ export function buildWorkspaceSkillSnapshot(
   const resolvedSkills = promptEntries.map((entry) => entry.skill);
   const remoteNote = opts?.eligibility?.remote?.note?.trim();
   const prompt = [remoteNote, formatSkillsForPrompt(resolvedSkills)].filter(Boolean).join("\n");
+  const skillFilter = normalizeSkillFilter(opts?.skillFilter);
   return {
     prompt,
     skills: eligible.map((entry) => ({
       name: entry.skill.name,
       primaryEnv: entry.metadata?.primaryEnv,
     })),
+    ...(skillFilter === undefined ? {} : { skillFilter }),
     resolvedSkills,
     version: opts?.snapshotVersion,
   };
diff --git a/src/agents/subagent-announce.format.e2e.test.ts b/src/agents/subagent-announce.format.e2e.test.ts
index 752b2a07db9..c1d4e5013d0 100644
--- a/src/agents/subagent-announce.format.e2e.test.ts
+++ b/src/agents/subagent-announce.format.e2e.test.ts
@@ -22,6 +22,17 @@ let configOverride: ReturnType<(typeof import("../config/config.js"))["loadConfi
   },
 };
 
+function loadSessionStoreFixture(): Record<string, Record<string, unknown>> {
+  return new Proxy(sessionStore, {
+    get(target, key: string | symbol) {
+      if (typeof key === "string" && !(key in target) && key.includes(":subagent:")) {
+        return { inputTokens: 1, outputTokens: 1, totalTokens: 2 };
+      }
+      return target[key as keyof typeof target];
+    },
+  });
+}
+
 vi.mock("../gateway/call.js", () => ({
   callGateway: vi.fn(async (req: unknown) => {
     const typed = req as { method?: string; params?: { message?: string; sessionKey?: string } };
@@ -47,7 +58,7 @@ vi.mock("./tools/agent-step.js", () => ({
 }));
 
 vi.mock("../config/sessions.js", () => ({
-  loadSessionStore: vi.fn(() => sessionStore),
+  loadSessionStore: vi.fn(() => loadSessionStoreFixture()),
   resolveAgentIdFromSessionKey: () => "main",
   resolveStorePath: () => "/tmp/sessions.json",
   resolveMainSessionKey: () => "agent:main:main",
@@ -93,6 +104,9 @@ describe("subagent announce formatting", () => {
     sessionStore = {
       "agent:main:subagent:test": {
         sessionId: "child-session-123",
+        inputTokens: 1,
+        outputTokens: 1,
+        totalTokens: 2,
       },
     };
     await runSubagentAnnounceFlow({
@@ -580,6 +594,9 @@ describe("subagent announce formatting", () => {
     sessionStore = {
       "agent:main:subagent:test": {
         sessionId: "child-session-1",
+        inputTokens: 1,
+        outputTokens: 1,
+        totalTokens: 2,
       },
     };
 
@@ -742,34 +759,6 @@ describe("subagent announce formatting", () => {
     expect(agentSpy).not.toHaveBeenCalled();
   });
 
-  it("does not delete child session when announce is deferred for an active run", async () => {
-    const { runSubagentAnnounceFlow } = await import("./subagent-announce.js");
-    embeddedRunMock.isEmbeddedPiRunActive.mockReturnValue(true);
-    embeddedRunMock.waitForEmbeddedPiRunEnd.mockResolvedValue(false);
-    sessionStore = {
-      "agent:main:subagent:test": {
-        sessionId: "child-session-active",
-      },
-    };
-
-    const didAnnounce = await runSubagentAnnounceFlow({
-      childSessionKey: "agent:main:subagent:test",
-      childRunId: "run-child-active-delete",
-      requesterSessionKey: "agent:main:main",
-      requesterDisplayKey: "main",
-      task: "context-stress-test",
-      timeoutMs: 1000,
-      cleanup: "delete",
-      waitForCompletion: false,
-      startedAt: 10,
-      endedAt: 20,
-      outcome: { status: "ok" },
-    });
-
-    expect(didAnnounce).toBe(false);
-    expect(sessionsDeleteSpy).not.toHaveBeenCalled();
-  });
-
   it("normalizes requesterOrigin for direct announce delivery", async () => {
     const { runSubagentAnnounceFlow } = await import("./subagent-announce.js");
     embeddedRunMock.isEmbeddedPiRunActive.mockReturnValue(false);
diff --git a/src/agents/subagent-depth.test.ts b/src/agents/subagent-depth.test.ts
index 66980d2d095..5d9427b7818 100644
--- a/src/agents/subagent-depth.test.ts
+++ b/src/agents/subagent-depth.test.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
+import { resolveAgentTimeoutMs } from "./timeout.js";
 
 describe("getSubagentDepthFromSessionStore", () => {
   it("uses spawnDepth from the session store when available", () => {
@@ -85,3 +86,15 @@ describe("getSubagentDepthFromSessionStore", () => {
     expect(depth).toBe(1);
   });
 });
+
+describe("resolveAgentTimeoutMs", () => {
+  it("uses a timer-safe sentinel for no-timeout overrides", () => {
+    expect(resolveAgentTimeoutMs({ overrideSeconds: 0 })).toBe(2_147_000_000);
+    expect(resolveAgentTimeoutMs({ overrideMs: 0 })).toBe(2_147_000_000);
+  });
+
+  it("clamps very large timeout overrides to timer-safe values", () => {
+    expect(resolveAgentTimeoutMs({ overrideSeconds: 9_999_999 })).toBe(2_147_000_000);
+    expect(resolveAgentTimeoutMs({ overrideMs: 9_999_999_999 })).toBe(2_147_000_000);
+  });
+});
diff --git a/src/agents/subagent-registry.nested.test.ts b/src/agents/subagent-registry.nested.test.ts
index 399917d1771..2ff207a79b2 100644
--- a/src/agents/subagent-registry.nested.test.ts
+++ b/src/agents/subagent-registry.nested.test.ts
@@ -14,15 +14,26 @@ vi.mock("../infra/agent-events.js", () => ({
   onAgentEvent: vi.fn(() => noop),
 }));
 
+vi.mock("../config/config.js", () => ({
+  loadConfig: vi.fn(() => ({
+    agents: { defaults: { subagents: { archiveAfterMinutes: 0 } } },
+  })),
+}));
+
 vi.mock("./subagent-announce.js", () => ({
   runSubagentAnnounceFlow: vi.fn(async () => true),
   buildSubagentSystemPrompt: vi.fn(() => "test prompt"),
 }));
 
+vi.mock("./subagent-registry.store.js", () => ({
+  loadSubagentRegistryFromDisk: vi.fn(() => new Map()),
+  saveSubagentRegistryToDisk: vi.fn(() => {}),
+}));
+
 describe("subagent registry nested agent tracking", () => {
   afterEach(async () => {
     const mod = await import("./subagent-registry.js");
-    mod.resetSubagentRegistryForTests();
+    mod.resetSubagentRegistryForTests({ persist: false });
   });
 
   it("listSubagentRunsForRequester returns children of the requesting session", async () => {
diff --git a/src/agents/subagent-registry.persistence.e2e.test.ts b/src/agents/subagent-registry.persistence.e2e.test.ts
index 9b3f5348c42..4a6620c4e57 100644
--- a/src/agents/subagent-registry.persistence.e2e.test.ts
+++ b/src/agents/subagent-registry.persistence.e2e.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import {
   initSubagentRegistry,
   registerSubagentRun,
@@ -29,7 +30,7 @@ vi.mock("./subagent-announce.js", () => ({
 }));
 
 describe("subagent registry persistence", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const envSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -39,11 +40,7 @@ describe("subagent registry persistence", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
+    envSnapshot.restore();
   });
 
   it("persists runs to disk and resumes after restart", async () => {
diff --git a/src/agents/subagent-registry.steer-restart.test.ts b/src/agents/subagent-registry.steer-restart.test.ts
index a4a0a70109d..b8aebb3ec73 100644
--- a/src/agents/subagent-registry.steer-restart.test.ts
+++ b/src/agents/subagent-registry.steer-restart.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
 const noop = () => {};
 let lifecycleHandler:
@@ -22,22 +22,41 @@ vi.mock("../infra/agent-events.js", () => ({
   }),
 }));
 
+vi.mock("../config/config.js", () => ({
+  loadConfig: vi.fn(() => ({
+    agents: { defaults: { subagents: { archiveAfterMinutes: 0 } } },
+  })),
+}));
+
 const announceSpy = vi.fn(async () => true);
 vi.mock("./subagent-announce.js", () => ({
   runSubagentAnnounceFlow: (...args: unknown[]) => announceSpy(...args),
 }));
 
+vi.mock("./subagent-registry.store.js", () => ({
+  loadSubagentRegistryFromDisk: vi.fn(() => new Map()),
+  saveSubagentRegistryToDisk: vi.fn(() => {}),
+}));
+
 describe("subagent registry steer restarts", () => {
+  let mod: typeof import("./subagent-registry.js");
+
+  beforeAll(async () => {
+    mod = await import("./subagent-registry.js");
+  });
+
+  const flushAnnounce = async () => {
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  };
+
   afterEach(async () => {
-    announceSpy.mockClear();
+    announceSpy.mockReset();
+    announceSpy.mockResolvedValue(true);
     lifecycleHandler = undefined;
-    const mod = await import("./subagent-registry.js");
-    mod.resetSubagentRegistryForTests();
+    mod.resetSubagentRegistryForTests({ persist: false });
   });
 
   it("suppresses announce for interrupted runs and only announces the replacement run", async () => {
-    const mod = await import("./subagent-registry.js");
-
     mod.registerSubagentRun({
       runId: "run-old",
       childSessionKey: "agent:main:subagent:steer",
@@ -59,7 +78,7 @@ describe("subagent registry steer restarts", () => {
       data: { phase: "end" },
     });
 
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
     expect(announceSpy).not.toHaveBeenCalled();
 
     const replaced = mod.replaceSubagentRunAfterSteer({
@@ -79,7 +98,7 @@ describe("subagent registry steer restarts", () => {
       data: { phase: "end" },
     });
 
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
     expect(announceSpy).toHaveBeenCalledTimes(1);
 
     const announce = announceSpy.mock.calls[0]?.[0] as { childRunId?: string };
@@ -87,8 +106,6 @@ describe("subagent registry steer restarts", () => {
   });
 
   it("restores announce for a finished run when steer replacement dispatch fails", async () => {
-    const mod = await import("./subagent-registry.js");
-
     mod.registerSubagentRun({
       runId: "run-failed-restart",
       childSessionKey: "agent:main:subagent:failed-restart",
@@ -106,11 +123,11 @@ describe("subagent registry steer restarts", () => {
       data: { phase: "end" },
     });
 
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
     expect(announceSpy).not.toHaveBeenCalled();
 
     expect(mod.clearSubagentRunSteerRestart("run-failed-restart")).toBe(true);
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
 
     expect(announceSpy).toHaveBeenCalledTimes(1);
     const announce = announceSpy.mock.calls[0]?.[0] as { childRunId?: string };
@@ -118,7 +135,6 @@ describe("subagent registry steer restarts", () => {
   });
 
   it("marks killed runs terminated and inactive", async () => {
-    const mod = await import("./subagent-registry.js");
     const childSessionKey = "agent:main:subagent:killed";
 
     mod.registerSubagentRun({
@@ -145,7 +161,6 @@ describe("subagent registry steer restarts", () => {
   });
 
   it("retries deferred parent cleanup after a descendant announces", async () => {
-    const mod = await import("./subagent-registry.js");
     let parentAttempts = 0;
     announceSpy.mockImplementation(async (params: unknown) => {
       const typed = params as { childRunId?: string };
@@ -178,14 +193,14 @@ describe("subagent registry steer restarts", () => {
       runId: "run-parent",
       data: { phase: "end" },
     });
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
 
     lifecycleHandler?.({
       stream: "lifecycle",
       runId: "run-child",
       data: { phase: "end" },
     });
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await flushAnnounce();
 
     const childRunIds = announceSpy.mock.calls.map(
       (call) => (call[0] as { childRunId?: string }).childRunId,
diff --git a/src/agents/system-prompt.e2e.test.ts b/src/agents/system-prompt.e2e.test.ts
index 65f8d7852d4..0b552fd62d3 100644
--- a/src/agents/system-prompt.e2e.test.ts
+++ b/src/agents/system-prompt.e2e.test.ts
@@ -48,6 +48,9 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).not.toContain("## Silent Replies");
     expect(prompt).not.toContain("## Heartbeats");
     expect(prompt).toContain("## Safety");
+    expect(prompt).toContain(
+      "For long waits, avoid rapid poll loops: use exec with enough yieldMs or process(action=poll, timeout=<ms>).",
+    );
     expect(prompt).toContain("You have no independent goals");
     expect(prompt).toContain("Prioritize safety and human oversight");
     expect(prompt).toContain("if instructions conflict");
@@ -120,6 +123,9 @@ describe("buildAgentSystemPrompt", () => {
       workspaceDir: "/tmp/openclaw",
     });
 
+    expect(prompt).toContain(
+      "For long waits, avoid rapid poll loops: use exec with enough yieldMs or process(action=poll, timeout=<ms>).",
+    );
     expect(prompt).toContain("Completion is push-based: it will auto-announce when done.");
     expect(prompt).toContain("Do not poll `subagents list` / `sessions_list` in a loop");
   });
@@ -448,10 +454,12 @@ describe("buildAgentSystemPrompt", () => {
 
     expect(prompt).toContain("Your working directory is: /workspace");
     expect(prompt).toContain(
-      "For read/write/edit/apply_patch, file paths resolve against host workspace: /tmp/openclaw.",
+      "For read/write/edit/apply_patch, file paths resolve against host workspace: /tmp/openclaw. For bash/exec commands, use sandbox container paths under /workspace (or relative paths from that workdir), not host paths.",
     );
     expect(prompt).toContain("Sandbox container workdir: /workspace");
-    expect(prompt).toContain("Sandbox host workspace: /tmp/sandbox");
+    expect(prompt).toContain(
+      "Sandbox host mount source (file tools bridge only; not valid inside sandbox exec): /tmp/sandbox",
+    );
     expect(prompt).toContain("You are running in a sandboxed runtime");
     expect(prompt).toContain("Sub-agents stay sandboxed");
     expect(prompt).toContain("User can toggle with /elevated on|off|ask|full.");
diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts
index 21a176ac8cf..5c7d312d459 100644
--- a/src/agents/system-prompt.ts
+++ b/src/agents/system-prompt.ts
@@ -4,6 +4,7 @@ import type { ResolvedTimeFormat } from "./date-time.js";
 import type { EmbeddedContextFile } from "./pi-embedded-helpers.js";
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { listDeliverableMessageChannels } from "../utils/message-channel.js";
+import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
 
 /**
  * Controls which hardcoded sections are included in the system prompt.
@@ -355,13 +356,17 @@ export function buildAgentSystemPrompt(params: {
   const promptMode = params.promptMode ?? "full";
   const isMinimal = promptMode === "minimal" || promptMode === "none";
   const sandboxContainerWorkspace = params.sandboxInfo?.containerWorkspaceDir?.trim();
+  const sanitizedWorkspaceDir = sanitizeForPromptLiteral(params.workspaceDir);
+  const sanitizedSandboxContainerWorkspace = sandboxContainerWorkspace
+    ? sanitizeForPromptLiteral(sandboxContainerWorkspace)
+    : "";
   const displayWorkspaceDir =
-    params.sandboxInfo?.enabled && sandboxContainerWorkspace
-      ? sandboxContainerWorkspace
-      : params.workspaceDir;
+    params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+      ? sanitizedSandboxContainerWorkspace
+      : sanitizedWorkspaceDir;
   const workspaceGuidance =
-    params.sandboxInfo?.enabled && sandboxContainerWorkspace
-      ? `For read/write/edit/apply_patch, file paths resolve against host workspace: ${params.workspaceDir}. Prefer relative paths so both sandboxed exec and file tools work consistently.`
+    params.sandboxInfo?.enabled && sanitizedSandboxContainerWorkspace
+      ? `For read/write/edit/apply_patch, file paths resolve against host workspace: ${sanitizedWorkspaceDir}. For bash/exec commands, use sandbox container paths under ${sanitizedSandboxContainerWorkspace} (or relative paths from that workdir), not host paths. Prefer relative paths so both sandboxed exec and file tools work consistently.`
       : "Treat this directory as the single global workspace for file operations unless explicitly instructed otherwise.";
   const safetySection = [
     "## Safety",
@@ -408,7 +413,6 @@ export function buildAgentSystemPrompt(params: {
           "- apply_patch: apply multi-file patches",
           `- ${execToolName}: run shell commands (supports background via yieldMs/background)`,
           `- ${processToolName}: manage background exec sessions`,
-          `- For long waits, avoid rapid poll loops: use ${execToolName} with enough yieldMs or ${processToolName}(action=poll, timeout=<ms>).`,
           "- browser: control OpenClaw's dedicated browser",
           "- canvas: present/eval/snapshot the Canvas",
           "- nodes: list/describe/notify/camera/screen on paired nodes",
@@ -420,6 +424,7 @@ export function buildAgentSystemPrompt(params: {
           '- session_status: show usage/time/model state and answer "what model are we using?"',
         ].join("\n"),
     "TOOLS.md does not control tool availability; it is user guidance for how to use external tools.",
+    `For long waits, avoid rapid poll loops: use ${execToolName} with enough yieldMs or ${processToolName}(action=poll, timeout=<ms>).`,
     "If a task is more complex or takes longer, spawn a sub-agent. Completion is push-based: it will auto-announce when done.",
     "Do not poll `subagents list` / `sessions_list` in a loop; only check status on-demand (for intervention, debugging, or when explicitly asked).",
     "",
@@ -480,21 +485,21 @@ export function buildAgentSystemPrompt(params: {
           "Some tools may be unavailable due to sandbox policy.",
           "Sub-agents stay sandboxed (no elevated/host access). Need outside-sandbox read/write? Don't spawn; ask first.",
           params.sandboxInfo.containerWorkspaceDir
-            ? `Sandbox container workdir: ${params.sandboxInfo.containerWorkspaceDir}`
+            ? `Sandbox container workdir: ${sanitizeForPromptLiteral(params.sandboxInfo.containerWorkspaceDir)}`
             : "",
           params.sandboxInfo.workspaceDir
-            ? `Sandbox host workspace: ${params.sandboxInfo.workspaceDir}`
+            ? `Sandbox host mount source (file tools bridge only; not valid inside sandbox exec): ${sanitizeForPromptLiteral(params.sandboxInfo.workspaceDir)}`
             : "",
           params.sandboxInfo.workspaceAccess
             ? `Agent workspace access: ${params.sandboxInfo.workspaceAccess}${
                 params.sandboxInfo.agentWorkspaceMount
-                  ? ` (mounted at ${params.sandboxInfo.agentWorkspaceMount})`
+                  ? ` (mounted at ${sanitizeForPromptLiteral(params.sandboxInfo.agentWorkspaceMount)})`
                   : ""
               }`
             : "",
           params.sandboxInfo.browserBridgeUrl ? "Sandbox browser: enabled." : "",
           params.sandboxInfo.browserNoVncUrl
-            ? `Sandbox browser observer (noVNC): ${params.sandboxInfo.browserNoVncUrl}`
+            ? `Sandbox browser observer (noVNC): ${sanitizeForPromptLiteral(params.sandboxInfo.browserNoVncUrl)}`
             : "",
           params.sandboxInfo.hostBrowserAllowed === true
             ? "Host browser control: allowed."
diff --git a/src/agents/test-helpers/fast-coding-tools.ts b/src/agents/test-helpers/fast-coding-tools.ts
index 99b4ab351c8..5cc92f38acb 100644
--- a/src/agents/test-helpers/fast-coding-tools.ts
+++ b/src/agents/test-helpers/fast-coding-tools.ts
@@ -1,22 +1 @@
-import { vi } from "vitest";
-
-const stubTool = (name: string) => ({
-  name,
-  description: `${name} stub`,
-  parameters: { type: "object", properties: {} },
-  execute: vi.fn(),
-});
-
-vi.mock("../tools/image-tool.js", () => ({
-  createImageTool: () => stubTool("image"),
-}));
-
-vi.mock("../tools/web-tools.js", () => ({
-  createWebSearchTool: () => null,
-  createWebFetchTool: () => null,
-}));
-
-vi.mock("../../plugins/tools.js", () => ({
-  resolvePluginTools: () => [],
-  getPluginToolMeta: () => undefined,
-}));
+import "./fast-tool-stubs.js";
diff --git a/src/agents/test-helpers/fast-core-tools.ts b/src/agents/test-helpers/fast-core-tools.ts
index d459c82765f..5bda64b09b6 100644
--- a/src/agents/test-helpers/fast-core-tools.ts
+++ b/src/agents/test-helpers/fast-core-tools.ts
@@ -1,11 +1,5 @@
 import { vi } from "vitest";
-
-const stubTool = (name: string) => ({
-  name,
-  description: `${name} stub`,
-  parameters: { type: "object", properties: {} },
-  execute: vi.fn(),
-});
+import { stubTool } from "./fast-tool-stubs.js";
 
 vi.mock("../tools/browser-tool.js", () => ({
   createBrowserTool: () => stubTool("browser"),
@@ -14,17 +8,3 @@ vi.mock("../tools/browser-tool.js", () => ({
 vi.mock("../tools/canvas-tool.js", () => ({
   createCanvasTool: () => stubTool("canvas"),
 }));
-
-vi.mock("../tools/image-tool.js", () => ({
-  createImageTool: () => stubTool("image"),
-}));
-
-vi.mock("../tools/web-tools.js", () => ({
-  createWebSearchTool: () => null,
-  createWebFetchTool: () => null,
-}));
-
-vi.mock("../../plugins/tools.js", () => ({
-  resolvePluginTools: () => [],
-  getPluginToolMeta: () => undefined,
-}));
diff --git a/src/agents/test-helpers/fast-tool-stubs.ts b/src/agents/test-helpers/fast-tool-stubs.ts
new file mode 100644
index 00000000000..da29363b50f
--- /dev/null
+++ b/src/agents/test-helpers/fast-tool-stubs.ts
@@ -0,0 +1,30 @@
+import { vi } from "vitest";
+
+export type StubTool = {
+  name: string;
+  description: string;
+  parameters: { type: "object"; properties: Record<string, unknown> };
+  // Keep the exported type portable: don't leak Vitest's mock types into .d.ts.
+  execute: (...args: unknown[]) => unknown;
+};
+
+export const stubTool = (name: string): StubTool => ({
+  name,
+  description: `${name} stub`,
+  parameters: { type: "object", properties: {} },
+  execute: vi.fn() as unknown as (...args: unknown[]) => unknown,
+});
+
+vi.mock("../tools/image-tool.js", () => ({
+  createImageTool: () => stubTool("image"),
+}));
+
+vi.mock("../tools/web-tools.js", () => ({
+  createWebSearchTool: () => null,
+  createWebFetchTool: () => null,
+}));
+
+vi.mock("../../plugins/tools.js", () => ({
+  resolvePluginTools: () => [],
+  getPluginToolMeta: () => undefined,
+}));
diff --git a/src/agents/timeout.e2e.test.ts b/src/agents/timeout.e2e.test.ts
deleted file mode 100644
index 37a96a9ff09..00000000000
--- a/src/agents/timeout.e2e.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveAgentTimeoutMs } from "./timeout.js";
-
-describe("resolveAgentTimeoutMs", () => {
-  it("uses a timer-safe sentinel for no-timeout overrides", () => {
-    expect(resolveAgentTimeoutMs({ overrideSeconds: 0 })).toBe(2_147_000_000);
-    expect(resolveAgentTimeoutMs({ overrideMs: 0 })).toBe(2_147_000_000);
-  });
-
-  it("clamps very large timeout overrides to timer-safe values", () => {
-    expect(resolveAgentTimeoutMs({ overrideSeconds: 9_999_999 })).toBe(2_147_000_000);
-    expect(resolveAgentTimeoutMs({ overrideMs: 9_999_999_999 })).toBe(2_147_000_000);
-  });
-});
diff --git a/src/agents/tool-policy.conformance.e2e.test.ts b/src/agents/tool-policy.conformance.e2e.test.ts
deleted file mode 100644
index 676a0b3023a..00000000000
--- a/src/agents/tool-policy.conformance.e2e.test.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { TOOL_POLICY_CONFORMANCE } from "./tool-policy.conformance.js";
-import { TOOL_GROUPS } from "./tool-policy.js";
-
-describe("TOOL_POLICY_CONFORMANCE", () => {
-  test("matches exported TOOL_GROUPS exactly", () => {
-    expect(TOOL_POLICY_CONFORMANCE.toolGroups).toEqual(TOOL_GROUPS);
-  });
-
-  test("is JSON-serializable", () => {
-    expect(() => JSON.stringify(TOOL_POLICY_CONFORMANCE)).not.toThrow();
-  });
-});
diff --git a/src/agents/tool-policy.e2e.test.ts b/src/agents/tool-policy.e2e.test.ts
index b4b9d20a086..9fb44696b6b 100644
--- a/src/agents/tool-policy.e2e.test.ts
+++ b/src/agents/tool-policy.e2e.test.ts
@@ -1,5 +1,17 @@
 import { describe, expect, it } from "vitest";
-import { expandToolGroups, resolveToolProfilePolicy, TOOL_GROUPS } from "./tool-policy.js";
+import type { OpenClawConfig } from "../config/config.js";
+import type { SandboxToolPolicy } from "./sandbox/types.js";
+import type { AnyAgentTool } from "./tools/common.js";
+import { isToolAllowed, resolveSandboxToolPolicyForAgent } from "./sandbox/tool-policy.js";
+import { TOOL_POLICY_CONFORMANCE } from "./tool-policy.conformance.js";
+import {
+  applyOwnerOnlyToolPolicy,
+  expandToolGroups,
+  isOwnerOnlyToolName,
+  normalizeToolName,
+  resolveToolProfilePolicy,
+  TOOL_GROUPS,
+} from "./tool-policy.js";
 
 describe("tool-policy", () => {
   it("expands groups and normalizes aliases", () => {
@@ -27,4 +39,146 @@ describe("tool-policy", () => {
     expect(group).toContain("subagents");
     expect(group).toContain("session_status");
   });
+
+  it("normalizes tool names and aliases", () => {
+    expect(normalizeToolName(" BASH ")).toBe("exec");
+    expect(normalizeToolName("apply-patch")).toBe("apply_patch");
+    expect(normalizeToolName("READ")).toBe("read");
+  });
+
+  it("identifies owner-only tools", () => {
+    expect(isOwnerOnlyToolName("whatsapp_login")).toBe(true);
+    expect(isOwnerOnlyToolName("read")).toBe(false);
+  });
+
+  it("strips owner-only tools for non-owner senders", async () => {
+    const tools = [
+      {
+        name: "read",
+        // oxlint-disable-next-line typescript/no-explicit-any
+        execute: async () => ({ content: [], details: {} }) as any,
+      },
+      {
+        name: "whatsapp_login",
+        // oxlint-disable-next-line typescript/no-explicit-any
+        execute: async () => ({ content: [], details: {} }) as any,
+      },
+    ] as unknown as AnyAgentTool[];
+
+    const filtered = applyOwnerOnlyToolPolicy(tools, false);
+    expect(filtered.map((t) => t.name)).toEqual(["read"]);
+  });
+
+  it("keeps owner-only tools for the owner sender", async () => {
+    const tools = [
+      {
+        name: "read",
+        // oxlint-disable-next-line typescript/no-explicit-any
+        execute: async () => ({ content: [], details: {} }) as any,
+      },
+      {
+        name: "whatsapp_login",
+        // oxlint-disable-next-line typescript/no-explicit-any
+        execute: async () => ({ content: [], details: {} }) as any,
+      },
+    ] as unknown as AnyAgentTool[];
+
+    const filtered = applyOwnerOnlyToolPolicy(tools, true);
+    expect(filtered.map((t) => t.name)).toEqual(["read", "whatsapp_login"]);
+  });
+});
+
+describe("TOOL_POLICY_CONFORMANCE", () => {
+  it("matches exported TOOL_GROUPS exactly", () => {
+    expect(TOOL_POLICY_CONFORMANCE.toolGroups).toEqual(TOOL_GROUPS);
+  });
+
+  it("is JSON-serializable", () => {
+    expect(() => JSON.stringify(TOOL_POLICY_CONFORMANCE)).not.toThrow();
+  });
+});
+
+describe("sandbox tool policy", () => {
+  it("allows all tools with * allow", () => {
+    const policy: SandboxToolPolicy = { allow: ["*"], deny: [] };
+    expect(isToolAllowed(policy, "browser")).toBe(true);
+  });
+
+  it("denies all tools with * deny", () => {
+    const policy: SandboxToolPolicy = { allow: [], deny: ["*"] };
+    expect(isToolAllowed(policy, "read")).toBe(false);
+  });
+
+  it("supports wildcard patterns", () => {
+    const policy: SandboxToolPolicy = { allow: ["web_*"] };
+    expect(isToolAllowed(policy, "web_fetch")).toBe(true);
+    expect(isToolAllowed(policy, "read")).toBe(false);
+  });
+
+  it("applies deny before allow", () => {
+    const policy: SandboxToolPolicy = { allow: ["*"], deny: ["web_*"] };
+    expect(isToolAllowed(policy, "web_fetch")).toBe(false);
+    expect(isToolAllowed(policy, "read")).toBe(true);
+  });
+
+  it("treats empty allowlist as allow-all (with deny exceptions)", () => {
+    const policy: SandboxToolPolicy = { allow: [], deny: ["web_*"] };
+    expect(isToolAllowed(policy, "web_fetch")).toBe(false);
+    expect(isToolAllowed(policy, "read")).toBe(true);
+  });
+
+  it("expands tool groups + aliases in patterns", () => {
+    const policy: SandboxToolPolicy = {
+      allow: ["group:fs", "BASH"],
+      deny: ["apply_*"],
+    };
+    expect(isToolAllowed(policy, "read")).toBe(true);
+    expect(isToolAllowed(policy, "exec")).toBe(true);
+    expect(isToolAllowed(policy, "apply_patch")).toBe(false);
+  });
+
+  it("normalizes whitespace + case", () => {
+    const policy: SandboxToolPolicy = { allow: [" WEB_* "] };
+    expect(isToolAllowed(policy, "WEB_FETCH")).toBe(true);
+  });
+});
+
+describe("resolveSandboxToolPolicyForAgent", () => {
+  it("keeps allow-all semantics when allow is []", () => {
+    const cfg = {
+      tools: { sandbox: { tools: { allow: [], deny: ["browser"] } } },
+    } as unknown as OpenClawConfig;
+
+    const resolved = resolveSandboxToolPolicyForAgent(cfg, undefined);
+    expect(resolved.sources.allow).toEqual({
+      source: "global",
+      key: "tools.sandbox.tools.allow",
+    });
+    expect(resolved.allow).toEqual([]);
+    expect(resolved.deny).toEqual(["browser"]);
+
+    const policy: SandboxToolPolicy = { allow: resolved.allow, deny: resolved.deny };
+    expect(isToolAllowed(policy, "read")).toBe(true);
+    expect(isToolAllowed(policy, "browser")).toBe(false);
+  });
+
+  it("auto-adds image to explicit allowlists unless denied", () => {
+    const cfg = {
+      tools: { sandbox: { tools: { allow: ["read"], deny: ["browser"] } } },
+    } as unknown as OpenClawConfig;
+
+    const resolved = resolveSandboxToolPolicyForAgent(cfg, undefined);
+    expect(resolved.allow).toEqual(["read", "image"]);
+    expect(resolved.deny).toEqual(["browser"]);
+  });
+
+  it("does not auto-add image when explicitly denied", () => {
+    const cfg = {
+      tools: { sandbox: { tools: { allow: ["read"], deny: ["image"] } } },
+    } as unknown as OpenClawConfig;
+
+    const resolved = resolveSandboxToolPolicyForAgent(cfg, undefined);
+    expect(resolved.allow).toEqual(["read"]);
+    expect(resolved.deny).toEqual(["image"]);
+  });
 });
diff --git a/src/agents/tool-policy.ts b/src/agents/tool-policy.ts
index d4fa9a69b15..310980474df 100644
--- a/src/agents/tool-policy.ts
+++ b/src/agents/tool-policy.ts
@@ -291,3 +291,13 @@ export function resolveToolProfilePolicy(profile?: string): ToolProfilePolicy |
     deny: resolved.deny ? [...resolved.deny] : undefined,
   };
 }
+
+export function mergeAlsoAllowPolicy<TPolicy extends { allow?: string[] }>(
+  policy: TPolicy | undefined,
+  alsoAllow?: string[],
+): TPolicy | undefined {
+  if (!policy?.allow || !Array.isArray(alsoAllow) || alsoAllow.length === 0) {
+    return policy;
+  }
+  return { ...policy, allow: Array.from(new Set([...policy.allow, ...alsoAllow])) };
+}
diff --git a/src/agents/tools/cron-tool.e2e.test.ts b/src/agents/tools/cron-tool.e2e.test.ts
index 1adbb2cd89e..a43552643bb 100644
--- a/src/agents/tools/cron-tool.e2e.test.ts
+++ b/src/agents/tools/cron-tool.e2e.test.ts
@@ -443,4 +443,61 @@ describe("cron tool", () => {
     };
     expect(call?.params?.delivery).toEqual({ mode: "none" });
   });
+
+  it("does not infer announce delivery when mode is webhook", async () => {
+    callGatewayMock.mockResolvedValueOnce({ ok: true });
+
+    const tool = createCronTool({ agentSessionKey: "agent:main:discord:dm:buddy" });
+    await tool.execute("call-webhook-explicit", {
+      action: "add",
+      job: {
+        name: "reminder",
+        schedule: { at: new Date(123).toISOString() },
+        payload: { kind: "agentTurn", message: "hello" },
+        delivery: { mode: "webhook", to: "https://example.invalid/cron-finished" },
+      },
+    });
+
+    const call = callGatewayMock.mock.calls[0]?.[0] as {
+      params?: { delivery?: { mode?: string; channel?: string; to?: string } };
+    };
+    expect(call?.params?.delivery).toEqual({
+      mode: "webhook",
+      to: "https://example.invalid/cron-finished",
+    });
+  });
+
+  it("fails fast when webhook mode is missing delivery.to", async () => {
+    const tool = createCronTool({ agentSessionKey: "agent:main:discord:dm:buddy" });
+
+    await expect(
+      tool.execute("call-webhook-missing", {
+        action: "add",
+        job: {
+          name: "reminder",
+          schedule: { at: new Date(123).toISOString() },
+          payload: { kind: "agentTurn", message: "hello" },
+          delivery: { mode: "webhook" },
+        },
+      }),
+    ).rejects.toThrow('delivery.mode="webhook" requires delivery.to to be a valid http(s) URL');
+    expect(callGatewayMock).toHaveBeenCalledTimes(0);
+  });
+
+  it("fails fast when webhook mode uses a non-http URL", async () => {
+    const tool = createCronTool({ agentSessionKey: "agent:main:discord:dm:buddy" });
+
+    await expect(
+      tool.execute("call-webhook-invalid", {
+        action: "add",
+        job: {
+          name: "reminder",
+          schedule: { at: new Date(123).toISOString() },
+          payload: { kind: "agentTurn", message: "hello" },
+          delivery: { mode: "webhook", to: "ftp://example.invalid/cron-finished" },
+        },
+      }),
+    ).rejects.toThrow('delivery.mode="webhook" requires delivery.to to be a valid http(s) URL');
+    expect(callGatewayMock).toHaveBeenCalledTimes(0);
+  });
 });
diff --git a/src/agents/tools/cron-tool.ts b/src/agents/tools/cron-tool.ts
index 29c86e646ed..be5f1e9b84d 100644
--- a/src/agents/tools/cron-tool.ts
+++ b/src/agents/tools/cron-tool.ts
@@ -2,7 +2,9 @@ import { Type } from "@sinclair/typebox";
 import type { CronDelivery, CronMessageChannel } from "../../cron/types.js";
 import { loadConfig } from "../../config/config.js";
 import { normalizeCronJobCreate, normalizeCronJobPatch } from "../../cron/normalize.js";
+import { normalizeHttpWebhookUrl } from "../../cron/webhook-url.js";
 import { parseAgentSessionKey } from "../../sessions/session-key-utils.js";
+import { extractTextFromChatContent } from "../../shared/chat-content.js";
 import { isRecord, truncateUtf16Safe } from "../../utils.js";
 import { resolveSessionAgentId } from "../agent-scope.js";
 import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
@@ -69,38 +71,13 @@ function truncateText(input: string, maxLen: number) {
   return `${truncated}...`;
 }
 
-function normalizeContextText(raw: string) {
-  return raw.replace(/\s+/g, " ").trim();
-}
-
 function extractMessageText(message: ChatMessage): { role: string; text: string } | null {
   const role = typeof message.role === "string" ? message.role : "";
   if (role !== "user" && role !== "assistant") {
     return null;
   }
-  const content = message.content;
-  if (typeof content === "string") {
-    const normalized = normalizeContextText(content);
-    return normalized ? { role, text: normalized } : null;
-  }
-  if (!Array.isArray(content)) {
-    return null;
-  }
-  const chunks: string[] = [];
-  for (const block of content) {
-    if (!block || typeof block !== "object") {
-      continue;
-    }
-    if ((block as { type?: unknown }).type !== "text") {
-      continue;
-    }
-    const text = (block as { text?: unknown }).text;
-    if (typeof text === "string" && text.trim()) {
-      chunks.push(text);
-    }
-  }
-  const joined = normalizeContextText(chunks.join(" "));
-  return joined ? { role, text: joined } : null;
+  const text = extractTextFromChatContent(message.content);
+  return text ? { role, text } : null;
 }
 
 async function buildReminderContextLines(params: {
@@ -241,7 +218,7 @@ JOB SCHEMA (for add action):
   "name": "string (optional)",
   "schedule": { ... },      // Required: when to run
   "payload": { ... },       // Required: what to execute
-  "delivery": { ... },      // Optional: announce summary (isolated only)
+  "delivery": { ... },      // Optional: announce summary or webhook POST
   "sessionTarget": "main" | "isolated",  // Required
   "enabled": true | false   // Optional, default true
 }
@@ -262,14 +239,17 @@ PAYLOAD TYPES (payload.kind):
 - "agentTurn": Runs agent with message (isolated sessions only)
   { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional> }
 
-DELIVERY (isolated-only, top-level):
-  { "mode": "none|announce", "channel": "<optional>", "to": "<optional>", "bestEffort": <optional-bool> }
+DELIVERY (top-level):
+  { "mode": "none|announce|webhook", "channel": "<optional>", "to": "<optional>", "bestEffort": <optional-bool> }
   - Default for isolated agentTurn jobs (when delivery omitted): "announce"
-  - If the task needs to send to a specific chat/recipient, set delivery.channel/to here; do not call messaging tools inside the run.
+  - announce: send to chat channel (optional channel/to target)
+  - webhook: send finished-run event as HTTP POST to delivery.to (URL required)
+  - If the task needs to send to a specific chat/recipient, set announce delivery.channel/to; do not call messaging tools inside the run.
 
 CRITICAL CONSTRAINTS:
 - sessionTarget="main" REQUIRES payload.kind="systemEvent"
 - sessionTarget="isolated" REQUIRES payload.kind="agentTurn"
+- For webhook callbacks, use delivery.mode="webhook" with delivery.to set to a URL.
 Default: prefer isolated agentTurn jobs unless the user explicitly wants a main-session system event.
 
 WAKE MODES (for wake action):
@@ -373,11 +353,25 @@ Use jobId as the canonical identifier; id is accepted for compatibility. Use con
             const delivery = isRecord(deliveryValue) ? deliveryValue : undefined;
             const modeRaw = typeof delivery?.mode === "string" ? delivery.mode : "";
             const mode = modeRaw.trim().toLowerCase();
+            if (mode === "webhook") {
+              const webhookUrl = normalizeHttpWebhookUrl(delivery?.to);
+              if (!webhookUrl) {
+                throw new Error(
+                  'delivery.mode="webhook" requires delivery.to to be a valid http(s) URL',
+                );
+              }
+              if (delivery) {
+                delivery.to = webhookUrl;
+              }
+            }
+
             const hasTarget =
               (typeof delivery?.channel === "string" && delivery.channel.trim()) ||
               (typeof delivery?.to === "string" && delivery.to.trim());
             const shouldInfer =
-              (deliveryValue == null || delivery) && mode !== "none" && !hasTarget;
+              (deliveryValue == null || delivery) &&
+              (mode === "" || mode === "announce") &&
+              !hasTarget;
             if (shouldInfer) {
               const inferred = inferDeliveryFromSessionKey(opts.agentSessionKey);
               if (inferred) {
diff --git a/src/agents/tools/discord-actions-messaging.ts b/src/agents/tools/discord-actions-messaging.ts
index 54f5e970bf1..a29f4b66235 100644
--- a/src/agents/tools/discord-actions-messaging.ts
+++ b/src/agents/tools/discord-actions-messaging.ts
@@ -1,5 +1,7 @@
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { DiscordActionConfig } from "../../config/config.js";
+import type { DiscordSendComponents, DiscordSendEmbeds } from "../../discord/send.shared.js";
+import { readDiscordComponentSpec } from "../../discord/components.js";
 import {
   createThreadDiscord,
   deleteMessageDiscord,
@@ -15,6 +17,7 @@ import {
   removeOwnReactionsDiscord,
   removeReactionDiscord,
   searchMessagesDiscord,
+  sendDiscordComponentMessage,
   sendMessageDiscord,
   sendPollDiscord,
   sendStickerDiscord,
@@ -232,17 +235,54 @@ export async function handleDiscordMessagingAction(
       const to = readStringParam(params, "to", { required: true });
       const asVoice = params.asVoice === true;
       const silent = params.silent === true;
+      const rawComponents = params.components;
+      const componentSpec =
+        rawComponents && typeof rawComponents === "object" && !Array.isArray(rawComponents)
+          ? readDiscordComponentSpec(rawComponents)
+          : null;
+      const components: DiscordSendComponents | undefined =
+        Array.isArray(rawComponents) || typeof rawComponents === "function"
+          ? (rawComponents as DiscordSendComponents)
+          : undefined;
       const content = readStringParam(params, "content", {
-        required: !asVoice,
+        required: !asVoice && !componentSpec && !components,
         allowEmpty: true,
       });
       const mediaUrl =
         readStringParam(params, "mediaUrl", { trim: false }) ??
         readStringParam(params, "path", { trim: false }) ??
         readStringParam(params, "filePath", { trim: false });
+      const filename = readStringParam(params, "filename");
       const replyTo = readStringParam(params, "replyTo");
-      const embeds =
-        Array.isArray(params.embeds) && params.embeds.length > 0 ? params.embeds : undefined;
+      const rawEmbeds = params.embeds;
+      const embeds: DiscordSendEmbeds | undefined = Array.isArray(rawEmbeds)
+        ? (rawEmbeds as DiscordSendEmbeds)
+        : undefined;
+      const sessionKey = readStringParam(params, "__sessionKey");
+      const agentId = readStringParam(params, "__agentId");
+
+      if (componentSpec) {
+        if (asVoice) {
+          throw new Error("Discord components cannot be sent as voice messages.");
+        }
+        if (embeds?.length) {
+          throw new Error("Discord components cannot include embeds.");
+        }
+        const normalizedContent = content?.trim() ? content : undefined;
+        const payload = componentSpec.text
+          ? componentSpec
+          : { ...componentSpec, text: normalizedContent };
+        const result = await sendDiscordComponentMessage(to, payload, {
+          ...(accountId ? { accountId } : {}),
+          silent,
+          replyTo: replyTo ?? undefined,
+          sessionKey: sessionKey ?? undefined,
+          agentId: agentId ?? undefined,
+          mediaUrl: mediaUrl ?? undefined,
+          filename: filename ?? undefined,
+        });
+        return jsonResult({ ok: true, result, components: true });
+      }
 
       // Handle voice message sending
       if (asVoice) {
@@ -269,6 +309,7 @@ export async function handleDiscordMessagingAction(
         ...(accountId ? { accountId } : {}),
         mediaUrl,
         replyTo,
+        components,
         embeds,
         silent,
       });
diff --git a/src/agents/tools/gateway-tool.ts b/src/agents/tools/gateway-tool.ts
index c8f9570f3fb..0a71b8a39c9 100644
--- a/src/agents/tools/gateway-tool.ts
+++ b/src/agents/tools/gateway-tool.ts
@@ -138,6 +138,24 @@ export function createGatewayTool(opts?: {
           : undefined;
       const gatewayOpts = { gatewayUrl, gatewayToken, timeoutMs };
 
+      const resolveGatewayWriteMeta = (): {
+        sessionKey: string | undefined;
+        note: string | undefined;
+        restartDelayMs: number | undefined;
+      } => {
+        const sessionKey =
+          typeof params.sessionKey === "string" && params.sessionKey.trim()
+            ? params.sessionKey.trim()
+            : opts?.agentSessionKey?.trim() || undefined;
+        const note =
+          typeof params.note === "string" && params.note.trim() ? params.note.trim() : undefined;
+        const restartDelayMs =
+          typeof params.restartDelayMs === "number" && Number.isFinite(params.restartDelayMs)
+            ? Math.floor(params.restartDelayMs)
+            : undefined;
+        return { sessionKey, note, restartDelayMs };
+      };
+
       const resolveConfigWriteParams = async (): Promise<{
         raw: string;
         baseHash: string;
@@ -154,17 +172,7 @@ export function createGatewayTool(opts?: {
         if (!baseHash) {
           throw new Error("Missing baseHash from config snapshot.");
         }
-        const sessionKey =
-          typeof params.sessionKey === "string" && params.sessionKey.trim()
-            ? params.sessionKey.trim()
-            : opts?.agentSessionKey?.trim() || undefined;
-        const note =
-          typeof params.note === "string" && params.note.trim() ? params.note.trim() : undefined;
-        const restartDelayMs =
-          typeof params.restartDelayMs === "number" && Number.isFinite(params.restartDelayMs)
-            ? Math.floor(params.restartDelayMs)
-            : undefined;
-        return { raw, baseHash, sessionKey, note, restartDelayMs };
+        return { raw, baseHash, ...resolveGatewayWriteMeta() };
       };
 
       if (action === "config.get") {
@@ -200,16 +208,7 @@ export function createGatewayTool(opts?: {
         return jsonResult({ ok: true, result });
       }
       if (action === "update.run") {
-        const sessionKey =
-          typeof params.sessionKey === "string" && params.sessionKey.trim()
-            ? params.sessionKey.trim()
-            : opts?.agentSessionKey?.trim() || undefined;
-        const note =
-          typeof params.note === "string" && params.note.trim() ? params.note.trim() : undefined;
-        const restartDelayMs =
-          typeof params.restartDelayMs === "number" && Number.isFinite(params.restartDelayMs)
-            ? Math.floor(params.restartDelayMs)
-            : undefined;
+        const { sessionKey, note, restartDelayMs } = resolveGatewayWriteMeta();
         const updateGatewayOpts = {
           ...gatewayOpts,
           timeoutMs: timeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS,
diff --git a/src/agents/tools/image-tool.e2e.test.ts b/src/agents/tools/image-tool.e2e.test.ts
index 5a93a32b13b..2b58753777c 100644
--- a/src/agents/tools/image-tool.e2e.test.ts
+++ b/src/agents/tools/image-tool.e2e.test.ts
@@ -16,6 +16,52 @@ async function writeAuthProfiles(agentDir: string, profiles: unknown) {
   );
 }
 
+const ONE_PIXEL_PNG_B64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/woAAn8B9FD5fHAAAAAASUVORK5CYII=";
+
+async function withTempWorkspacePng(
+  cb: (args: { workspaceDir: string; imagePath: string }) => Promise<void>,
+) {
+  const workspaceParent = await fs.mkdtemp(path.join(process.cwd(), ".openclaw-workspace-image-"));
+  try {
+    const workspaceDir = path.join(workspaceParent, "workspace");
+    await fs.mkdir(workspaceDir, { recursive: true });
+    const imagePath = path.join(workspaceDir, "photo.png");
+    await fs.writeFile(imagePath, Buffer.from(ONE_PIXEL_PNG_B64, "base64"));
+    await cb({ workspaceDir, imagePath });
+  } finally {
+    await fs.rm(workspaceParent, { recursive: true, force: true });
+  }
+}
+
+function stubMinimaxOkFetch() {
+  const fetch = vi.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    statusText: "OK",
+    headers: new Headers(),
+    json: async () => ({
+      content: "ok",
+      base_resp: { status_code: 0, status_msg: "" },
+    }),
+  });
+  // @ts-expect-error partial global
+  global.fetch = fetch;
+  vi.stubEnv("MINIMAX_API_KEY", "minimax-test");
+  return fetch;
+}
+
+function createMinimaxImageConfig(): OpenClawConfig {
+  return {
+    agents: {
+      defaults: {
+        model: { primary: "minimax/MiniMax-M2.1" },
+        imageModel: { primary: "minimax/MiniMax-VL-01" },
+      },
+    },
+  };
+}
+
 describe("image tool implicit imageModel config", () => {
   const priorFetch = global.fetch;
 
@@ -146,136 +192,78 @@ describe("image tool implicit imageModel config", () => {
     });
     const tool = createImageTool({ config: cfg, agentDir, modelHasVision: true });
     expect(tool).not.toBeNull();
-    expect(tool?.description).toContain(
-      "Only use this tool when the image was NOT already provided",
-    );
+    expect(tool?.description).toContain("Only use this tool when images were NOT already provided");
   });
 
   it("allows workspace images outside default local media roots", async () => {
-    const workspaceParent = await fs.mkdtemp(
-      path.join(process.cwd(), ".openclaw-workspace-image-"),
-    );
-    try {
-      const workspaceDir = path.join(workspaceParent, "workspace");
-      await fs.mkdir(workspaceDir, { recursive: true });
-      const imagePath = path.join(workspaceDir, "photo.png");
-      const pngB64 =
-        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/woAAn8B9FD5fHAAAAAASUVORK5CYII=";
-      await fs.writeFile(imagePath, Buffer.from(pngB64, "base64"));
-
-      const fetch = vi.fn().mockResolvedValue({
-        ok: true,
-        status: 200,
-        statusText: "OK",
-        headers: new Headers(),
-        json: async () => ({
-          content: "ok",
-          base_resp: { status_code: 0, status_msg: "" },
-        }),
-      });
-      // @ts-expect-error partial global
-      global.fetch = fetch;
-      vi.stubEnv("MINIMAX_API_KEY", "minimax-test");
-
+    await withTempWorkspacePng(async ({ workspaceDir, imagePath }) => {
+      const fetch = stubMinimaxOkFetch();
       const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-image-"));
-      const cfg: OpenClawConfig = {
-        agents: {
-          defaults: {
-            model: { primary: "minimax/MiniMax-M2.1" },
-            imageModel: { primary: "minimax/MiniMax-VL-01" },
-          },
-        },
-      };
+      try {
+        const cfg = createMinimaxImageConfig();
 
-      const withoutWorkspace = createImageTool({ config: cfg, agentDir });
-      expect(withoutWorkspace).not.toBeNull();
-      if (!withoutWorkspace) {
-        throw new Error("expected image tool");
+        const withoutWorkspace = createImageTool({ config: cfg, agentDir });
+        expect(withoutWorkspace).not.toBeNull();
+        if (!withoutWorkspace) {
+          throw new Error("expected image tool");
+        }
+        await expect(
+          withoutWorkspace.execute("t0", {
+            prompt: "Describe the image.",
+            image: imagePath,
+          }),
+        ).rejects.toThrow(/Local media path is not under an allowed directory/i);
+
+        const withWorkspace = createImageTool({ config: cfg, agentDir, workspaceDir });
+        expect(withWorkspace).not.toBeNull();
+        if (!withWorkspace) {
+          throw new Error("expected image tool");
+        }
+
+        await expect(
+          withWorkspace.execute("t1", {
+            prompt: "Describe the image.",
+            image: imagePath,
+          }),
+        ).resolves.toMatchObject({
+          content: [{ type: "text", text: "ok" }],
+        });
+
+        expect(fetch).toHaveBeenCalledTimes(1);
+      } finally {
+        await fs.rm(agentDir, { recursive: true, force: true });
       }
-      await expect(
-        withoutWorkspace.execute("t0", {
-          prompt: "Describe the image.",
-          image: imagePath,
-        }),
-      ).rejects.toThrow(/Local media path is not under an allowed directory/i);
-
-      const withWorkspace = createImageTool({ config: cfg, agentDir, workspaceDir });
-      expect(withWorkspace).not.toBeNull();
-      if (!withWorkspace) {
-        throw new Error("expected image tool");
-      }
-
-      await expect(
-        withWorkspace.execute("t1", {
-          prompt: "Describe the image.",
-          image: imagePath,
-        }),
-      ).resolves.toMatchObject({
-        content: [{ type: "text", text: "ok" }],
-      });
-
-      expect(fetch).toHaveBeenCalledTimes(1);
-    } finally {
-      await fs.rm(workspaceParent, { recursive: true, force: true });
-    }
+    });
   });
 
   it("allows workspace images via createOpenClawCodingTools default workspace root", async () => {
-    const workspaceParent = await fs.mkdtemp(
-      path.join(process.cwd(), ".openclaw-workspace-image-"),
-    );
-    try {
-      const workspaceDir = path.join(workspaceParent, "workspace");
-      await fs.mkdir(workspaceDir, { recursive: true });
-      const imagePath = path.join(workspaceDir, "photo.png");
-      const pngB64 =
-        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/woAAn8B9FD5fHAAAAAASUVORK5CYII=";
-      await fs.writeFile(imagePath, Buffer.from(pngB64, "base64"));
-
-      const fetch = vi.fn().mockResolvedValue({
-        ok: true,
-        status: 200,
-        statusText: "OK",
-        headers: new Headers(),
-        json: async () => ({
-          content: "ok",
-          base_resp: { status_code: 0, status_msg: "" },
-        }),
-      });
-      // @ts-expect-error partial global
-      global.fetch = fetch;
-      vi.stubEnv("MINIMAX_API_KEY", "minimax-test");
-
+    await withTempWorkspacePng(async ({ imagePath }) => {
+      const fetch = stubMinimaxOkFetch();
       const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-image-"));
-      const cfg: OpenClawConfig = {
-        agents: {
-          defaults: {
-            model: { primary: "minimax/MiniMax-M2.1" },
-            imageModel: { primary: "minimax/MiniMax-VL-01" },
-          },
-        },
-      };
+      try {
+        const cfg = createMinimaxImageConfig();
 
-      const tools = createOpenClawCodingTools({ config: cfg, agentDir });
-      const tool = tools.find((candidate) => candidate.name === "image");
-      expect(tool).not.toBeNull();
-      if (!tool) {
-        throw new Error("expected image tool");
+        const tools = createOpenClawCodingTools({ config: cfg, agentDir });
+        const tool = tools.find((candidate) => candidate.name === "image");
+        expect(tool).not.toBeNull();
+        if (!tool) {
+          throw new Error("expected image tool");
+        }
+
+        await expect(
+          tool.execute("t1", {
+            prompt: "Describe the image.",
+            image: imagePath,
+          }),
+        ).resolves.toMatchObject({
+          content: [{ type: "text", text: "ok" }],
+        });
+
+        expect(fetch).toHaveBeenCalledTimes(1);
+      } finally {
+        await fs.rm(agentDir, { recursive: true, force: true });
       }
-
-      await expect(
-        tool.execute("t1", {
-          prompt: "Describe the image.",
-          image: imagePath,
-        }),
-      ).resolves.toMatchObject({
-        content: [{ type: "text", text: "ok" }],
-      });
-
-      expect(fetch).toHaveBeenCalledTimes(1);
-    } finally {
-      await fs.rm(workspaceParent, { recursive: true, force: true });
-    }
+    });
   });
 
   it("sandboxes image paths like the read tool", async () => {
diff --git a/src/agents/tools/image-tool.ts b/src/agents/tools/image-tool.ts
index 896b7447138..3d63623b778 100644
--- a/src/agents/tools/image-tool.ts
+++ b/src/agents/tools/image-tool.ts
@@ -26,6 +26,7 @@ import {
 const DEFAULT_PROMPT = "Describe the image.";
 const ANTHROPIC_IMAGE_PRIMARY = "anthropic/claude-opus-4-6";
 const ANTHROPIC_IMAGE_FALLBACK = "anthropic/claude-opus-4-5";
+const DEFAULT_MAX_IMAGES = 20;
 
 export const __testing = {
   decodeDataUrl,
@@ -182,15 +183,21 @@ function pickMaxBytes(cfg?: OpenClawConfig, maxBytesMb?: number): number | undef
   return undefined;
 }
 
-function buildImageContext(prompt: string, base64: string, mimeType: string): Context {
+function buildImageContext(
+  prompt: string,
+  images: Array<{ base64: string; mimeType: string }>,
+): Context {
+  const content: Array<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+  > = [{ type: "text", text: prompt }];
+  for (const img of images) {
+    content.push({ type: "image", data: img.base64, mimeType: img.mimeType });
+  }
   return {
     messages: [
       {
         role: "user",
-        content: [
-          { type: "text", text: prompt },
-          { type: "image", data: base64, mimeType },
-        ],
+        content,
         timestamp: Date.now(),
       },
     ],
@@ -242,8 +249,7 @@ async function runImagePrompt(params: {
   imageModelConfig: ImageModelConfig;
   modelOverride?: string;
   prompt: string;
-  base64: string;
-  mimeType: string;
+  images: Array<{ base64: string; mimeType: string }>;
 }): Promise<{
   text: string;
   provider: string;
@@ -285,9 +291,11 @@ async function runImagePrompt(params: {
       });
       const apiKey = requireApiKey(apiKeyInfo, model.provider);
       authStorage.setRuntimeApiKey(model.provider, apiKey);
-      const imageDataUrl = `data:${params.mimeType};base64,${params.base64}`;
 
+      // MiniMax VLM only supports a single image; use the first one.
       if (model.provider === "minimax") {
+        const first = params.images[0];
+        const imageDataUrl = `data:${first.mimeType};base64,${first.base64}`;
         const text = await minimaxUnderstandImage({
           apiKey,
           prompt: params.prompt,
@@ -297,7 +305,7 @@ async function runImagePrompt(params: {
         return { text, provider: model.provider, model: model.id };
       }
 
-      const context = buildImageContext(params.prompt, params.base64, params.mimeType);
+      const context = buildImageContext(params.prompt, params.images);
       const message = await complete(model, context, {
         apiKey,
         maxTokens: resolveImageToolMaxTokens(model.maxTokens),
@@ -350,8 +358,8 @@ export function createImageTool(options?: {
   // If model has native vision, images in the prompt are auto-injected
   // so this tool is only needed when image wasn't provided in the prompt
   const description = options?.modelHasVision
-    ? "Analyze an image with a vision model. Only use this tool when the image was NOT already provided in the user's message. Images mentioned in the prompt are automatically visible to you."
-    : "Analyze an image with the configured image model (agents.defaults.imageModel). Provide a prompt and image path or URL.";
+    ? "Analyze one or more images with a vision model. Pass a single image path/URL or an array of up to 20. Only use this tool when images were NOT already provided in the user's message. Images mentioned in the prompt are automatically visible to you."
+    : "Analyze one or more images with the configured image model (agents.defaults.imageModel). Pass a single image path/URL or an array of up to 20. Provide a prompt describing what to analyze.";
 
   const localRoots = (() => {
     const roots = getDefaultLocalRoots();
@@ -368,44 +376,47 @@ export function createImageTool(options?: {
     description,
     parameters: Type.Object({
       prompt: Type.Optional(Type.String()),
-      image: Type.String(),
+      image: Type.Union([Type.String(), Type.Array(Type.String())]),
       model: Type.Optional(Type.String()),
       maxBytesMb: Type.Optional(Type.Number()),
+      maxImages: Type.Optional(Type.Number()),
     }),
     execute: async (_toolCallId, args) => {
       const record = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
-      const imageRawInput = typeof record.image === "string" ? record.image.trim() : "";
-      const imageRaw = imageRawInput.startsWith("@")
-        ? imageRawInput.slice(1).trim()
-        : imageRawInput;
-      if (!imageRaw) {
+
+      // MARK: - Normalize image input (string | string[])
+      const rawImageInput = record.image;
+      const imageInputs: string[] = (() => {
+        if (typeof rawImageInput === "string") {
+          return [rawImageInput];
+        }
+        if (Array.isArray(rawImageInput)) {
+          return rawImageInput.filter((v): v is string => typeof v === "string");
+        }
+        return [];
+      })();
+      if (imageInputs.length === 0) {
         throw new Error("image required");
       }
 
-      // The tool accepts file paths, file/data URLs, or http(s) URLs. In some
-      // agent/model contexts, images can be referenced as pseudo-URIs like
-      // `image:0` (e.g. "first image in the prompt"). We don't have access to a
-      // shared image registry here, so fail gracefully instead of attempting to
-      // `fs.readFile("image:0")` and producing a noisy ENOENT.
-      const looksLikeWindowsDrivePath = /^[a-zA-Z]:[\\/]/.test(imageRaw);
-      const hasScheme = /^[a-z][a-z0-9+.-]*:/i.test(imageRaw);
-      const isFileUrl = /^file:/i.test(imageRaw);
-      const isHttpUrl = /^https?:\/\//i.test(imageRaw);
-      const isDataUrl = /^data:/i.test(imageRaw);
-      if (hasScheme && !looksLikeWindowsDrivePath && !isFileUrl && !isHttpUrl && !isDataUrl) {
+      // MARK: - Enforce max images cap
+      const maxImagesRaw = typeof record.maxImages === "number" ? record.maxImages : undefined;
+      const maxImages =
+        typeof maxImagesRaw === "number" && Number.isFinite(maxImagesRaw) && maxImagesRaw > 0
+          ? Math.floor(maxImagesRaw)
+          : DEFAULT_MAX_IMAGES;
+      if (imageInputs.length > maxImages) {
         return {
           content: [
             {
               type: "text",
-              text: `Unsupported image reference: ${imageRawInput}. Use a file path, a file:// URL, a data: URL, or an http(s) URL.`,
+              text: `Too many images: ${imageInputs.length} provided, maximum is ${maxImages}. Please reduce the number of images.`,
             },
           ],
-          details: {
-            error: "unsupported_image_reference",
-            image: imageRawInput,
-          },
+          details: { error: "too_many_images", count: imageInputs.length, max: maxImages },
         };
       }
+
       const promptRaw =
         typeof record.prompt === "string" && record.prompt.trim()
           ? record.prompt.trim()
@@ -419,73 +430,136 @@ export function createImageTool(options?: {
         options?.sandbox && options?.sandbox.root.trim()
           ? { root: options.sandbox.root.trim(), bridge: options.sandbox.bridge }
           : null;
-      const isUrl = isHttpUrl;
-      if (sandboxConfig && isUrl) {
-        throw new Error("Sandboxed image tool does not allow remote URLs.");
-      }
 
-      const resolvedImage = (() => {
-        if (sandboxConfig) {
+      // MARK: - Load and resolve each image
+      const loadedImages: Array<{
+        base64: string;
+        mimeType: string;
+        resolvedImage: string;
+        rewrittenFrom?: string;
+      }> = [];
+
+      for (const imageRawInput of imageInputs) {
+        const trimmed = imageRawInput.trim();
+        const imageRaw = trimmed.startsWith("@") ? trimmed.slice(1).trim() : trimmed;
+        if (!imageRaw) {
+          throw new Error("image required (empty string in array)");
+        }
+
+        // The tool accepts file paths, file/data URLs, or http(s) URLs. In some
+        // agent/model contexts, images can be referenced as pseudo-URIs like
+        // `image:0` (e.g. "first image in the prompt"). We don't have access to a
+        // shared image registry here, so fail gracefully instead of attempting to
+        // `fs.readFile("image:0")` and producing a noisy ENOENT.
+        const looksLikeWindowsDrivePath = /^[a-zA-Z]:[\\/]/.test(imageRaw);
+        const hasScheme = /^[a-z][a-z0-9+.-]*:/i.test(imageRaw);
+        const isFileUrl = /^file:/i.test(imageRaw);
+        const isHttpUrl = /^https?:\/\//i.test(imageRaw);
+        const isDataUrl = /^data:/i.test(imageRaw);
+        if (hasScheme && !looksLikeWindowsDrivePath && !isFileUrl && !isHttpUrl && !isDataUrl) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Unsupported image reference: ${imageRawInput}. Use a file path, a file:// URL, a data: URL, or an http(s) URL.`,
+              },
+            ],
+            details: {
+              error: "unsupported_image_reference",
+              image: imageRawInput,
+            },
+          };
+        }
+
+        if (sandboxConfig && isHttpUrl) {
+          throw new Error("Sandboxed image tool does not allow remote URLs.");
+        }
+
+        const resolvedImage = (() => {
+          if (sandboxConfig) {
+            return imageRaw;
+          }
+          if (imageRaw.startsWith("~")) {
+            return resolveUserPath(imageRaw);
+          }
           return imageRaw;
-        }
-        if (imageRaw.startsWith("~")) {
-          return resolveUserPath(imageRaw);
-        }
-        return imageRaw;
-      })();
-      const resolvedPathInfo: { resolved: string; rewrittenFrom?: string } = isDataUrl
-        ? { resolved: "" }
-        : sandboxConfig
-          ? await resolveSandboxedImagePath({
-              sandbox: sandboxConfig,
-              imagePath: resolvedImage,
-            })
-          : {
-              resolved: resolvedImage.startsWith("file://")
-                ? resolvedImage.slice("file://".length)
-                : resolvedImage,
-            };
-      const resolvedPath = isDataUrl ? null : resolvedPathInfo.resolved;
+        })();
+        const resolvedPathInfo: { resolved: string; rewrittenFrom?: string } = isDataUrl
+          ? { resolved: "" }
+          : sandboxConfig
+            ? await resolveSandboxedImagePath({
+                sandbox: sandboxConfig,
+                imagePath: resolvedImage,
+              })
+            : {
+                resolved: resolvedImage.startsWith("file://")
+                  ? resolvedImage.slice("file://".length)
+                  : resolvedImage,
+              };
+        const resolvedPath = isDataUrl ? null : resolvedPathInfo.resolved;
 
-      const media = isDataUrl
-        ? decodeDataUrl(resolvedImage)
-        : sandboxConfig
-          ? await loadWebMedia(resolvedPath ?? resolvedImage, {
-              maxBytes,
-              sandboxValidated: true,
-              readFile: (filePath) =>
-                sandboxConfig.bridge.readFile({ filePath, cwd: sandboxConfig.root }),
-            })
-          : await loadWebMedia(resolvedPath ?? resolvedImage, {
-              maxBytes,
-              localRoots,
-            });
-      if (media.kind !== "image") {
-        throw new Error(`Unsupported media type: ${media.kind}`);
+        const media = isDataUrl
+          ? decodeDataUrl(resolvedImage)
+          : sandboxConfig
+            ? await loadWebMedia(resolvedPath ?? resolvedImage, {
+                maxBytes,
+                sandboxValidated: true,
+                readFile: (filePath) =>
+                  sandboxConfig.bridge.readFile({ filePath, cwd: sandboxConfig.root }),
+              })
+            : await loadWebMedia(resolvedPath ?? resolvedImage, {
+                maxBytes,
+                localRoots,
+              });
+        if (media.kind !== "image") {
+          throw new Error(`Unsupported media type: ${media.kind}`);
+        }
+
+        const mimeType =
+          ("contentType" in media && media.contentType) ||
+          ("mimeType" in media && media.mimeType) ||
+          "image/png";
+        const base64 = media.buffer.toString("base64");
+        loadedImages.push({
+          base64,
+          mimeType,
+          resolvedImage,
+          ...(resolvedPathInfo.rewrittenFrom
+            ? { rewrittenFrom: resolvedPathInfo.rewrittenFrom }
+            : {}),
+        });
       }
 
-      const mimeType =
-        ("contentType" in media && media.contentType) ||
-        ("mimeType" in media && media.mimeType) ||
-        "image/png";
-      const base64 = media.buffer.toString("base64");
+      // MARK: - Run image prompt with all loaded images
       const result = await runImagePrompt({
         cfg: options?.config,
         agentDir,
         imageModelConfig,
         modelOverride,
         prompt: promptRaw,
-        base64,
-        mimeType,
+        images: loadedImages.map((img) => ({ base64: img.base64, mimeType: img.mimeType })),
       });
+
+      const imageDetails =
+        loadedImages.length === 1
+          ? {
+              image: loadedImages[0].resolvedImage,
+              ...(loadedImages[0].rewrittenFrom
+                ? { rewrittenFrom: loadedImages[0].rewrittenFrom }
+                : {}),
+            }
+          : {
+              images: loadedImages.map((img) => ({
+                image: img.resolvedImage,
+                ...(img.rewrittenFrom ? { rewrittenFrom: img.rewrittenFrom } : {}),
+              })),
+            };
+
       return {
         content: [{ type: "text", text: result.text }],
         details: {
           model: `${result.provider}/${result.model}`,
-          image: resolvedImage,
-          ...(resolvedPathInfo.rewrittenFrom
-            ? { rewrittenFrom: resolvedPathInfo.rewrittenFrom }
-            : {}),
+          ...imageDetails,
           attempts: result.attempts,
         },
       };
diff --git a/src/agents/tools/memory-tool.does-not-crash-on-errors.e2e.test.ts b/src/agents/tools/memory-tool.does-not-crash-on-errors.e2e.test.ts
deleted file mode 100644
index 85535cedfe5..00000000000
--- a/src/agents/tools/memory-tool.does-not-crash-on-errors.e2e.test.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-vi.mock("../../memory/index.js", () => {
-  return {
-    getMemorySearchManager: async () => {
-      return {
-        manager: {
-          search: async () => {
-            throw new Error("openai embeddings failed: 429 insufficient_quota");
-          },
-          readFile: async () => {
-            throw new Error("path required");
-          },
-          status: () => ({
-            files: 0,
-            chunks: 0,
-            dirty: true,
-            workspaceDir: "/tmp",
-            dbPath: "/tmp/index.sqlite",
-            provider: "openai",
-            model: "text-embedding-3-small",
-            requestedProvider: "openai",
-          }),
-        },
-      };
-    },
-  };
-});
-
-import { createMemoryGetTool, createMemorySearchTool } from "./memory-tool.js";
-
-describe("memory tools", () => {
-  it("does not throw when memory_search fails (e.g. embeddings 429)", async () => {
-    const cfg = { agents: { list: [{ id: "main", default: true }] } };
-    const tool = createMemorySearchTool({ config: cfg });
-    expect(tool).not.toBeNull();
-    if (!tool) {
-      throw new Error("tool missing");
-    }
-
-    const result = await tool.execute("call_1", { query: "hello" });
-    expect(result.details).toEqual({
-      results: [],
-      disabled: true,
-      error: "openai embeddings failed: 429 insufficient_quota",
-    });
-  });
-
-  it("does not throw when memory_get fails", async () => {
-    const cfg = { agents: { list: [{ id: "main", default: true }] } };
-    const tool = createMemoryGetTool({ config: cfg });
-    expect(tool).not.toBeNull();
-    if (!tool) {
-      throw new Error("tool missing");
-    }
-
-    const result = await tool.execute("call_2", { path: "memory/NOPE.md" });
-    expect(result.details).toEqual({
-      path: "memory/NOPE.md",
-      text: "",
-      disabled: true,
-      error: "path required",
-    });
-  });
-});
diff --git a/src/agents/tools/memory-tool.citations.e2e.test.ts b/src/agents/tools/memory-tool.e2e.test.ts
similarity index 69%
rename from src/agents/tools/memory-tool.citations.e2e.test.ts
rename to src/agents/tools/memory-tool.e2e.test.ts
index 8e4d5c1b7fd..38e2caab24d 100644
--- a/src/agents/tools/memory-tool.citations.e2e.test.ts
+++ b/src/agents/tools/memory-tool.e2e.test.ts
@@ -1,18 +1,21 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 let backend: "builtin" | "qmd" = "builtin";
+let searchImpl: () => Promise<unknown[]> = async () => [
+  {
+    path: "MEMORY.md",
+    startLine: 5,
+    endLine: 7,
+    score: 0.9,
+    snippet: "@@ -5,3 @@\nAssistant: noted",
+    source: "memory" as const,
+  },
+];
+let readFileImpl: () => Promise<string> = async () => "";
+
 const stubManager = {
-  search: vi.fn(async () => [
-    {
-      path: "MEMORY.md",
-      startLine: 5,
-      endLine: 7,
-      score: 0.9,
-      snippet: "@@ -5,3 @@\nAssistant: noted",
-      source: "memory" as const,
-    },
-  ]),
-  readFile: vi.fn(),
+  search: vi.fn(async () => await searchImpl()),
+  readFile: vi.fn(async () => await readFileImpl()),
   status: () => ({
     backend,
     files: 1,
@@ -37,9 +40,21 @@ vi.mock("../../memory/index.js", () => {
   };
 });
 
-import { createMemorySearchTool } from "./memory-tool.js";
+import { createMemoryGetTool, createMemorySearchTool } from "./memory-tool.js";
 
 beforeEach(() => {
+  backend = "builtin";
+  searchImpl = async () => [
+    {
+      path: "MEMORY.md",
+      startLine: 5,
+      endLine: 7,
+      score: 0.9,
+      snippet: "@@ -5,3 @@\nAssistant: noted",
+      source: "memory" as const,
+    },
+  ];
+  readFileImpl = async () => "";
   vi.clearAllMocks();
 });
 
@@ -121,3 +136,46 @@ describe("memory search citations", () => {
     expect(details.results[0]?.snippet).not.toMatch(/Source:/);
   });
 });
+
+describe("memory tools", () => {
+  it("does not throw when memory_search fails (e.g. embeddings 429)", async () => {
+    searchImpl = async () => {
+      throw new Error("openai embeddings failed: 429 insufficient_quota");
+    };
+
+    const cfg = { agents: { list: [{ id: "main", default: true }] } };
+    const tool = createMemorySearchTool({ config: cfg });
+    expect(tool).not.toBeNull();
+    if (!tool) {
+      throw new Error("tool missing");
+    }
+
+    const result = await tool.execute("call_1", { query: "hello" });
+    expect(result.details).toEqual({
+      results: [],
+      disabled: true,
+      error: "openai embeddings failed: 429 insufficient_quota",
+    });
+  });
+
+  it("does not throw when memory_get fails", async () => {
+    readFileImpl = async () => {
+      throw new Error("path required");
+    };
+
+    const cfg = { agents: { list: [{ id: "main", default: true }] } };
+    const tool = createMemoryGetTool({ config: cfg });
+    expect(tool).not.toBeNull();
+    if (!tool) {
+      throw new Error("tool missing");
+    }
+
+    const result = await tool.execute("call_2", { path: "memory/NOPE.md" });
+    expect(result.details).toEqual({
+      path: "memory/NOPE.md",
+      text: "",
+      disabled: true,
+      error: "path required",
+    });
+  });
+});
diff --git a/src/agents/tools/memory-tool.ts b/src/agents/tools/memory-tool.ts
index 953a0582115..e0cb82d6d41 100644
--- a/src/agents/tools/memory-tool.ts
+++ b/src/agents/tools/memory-tool.ts
@@ -22,10 +22,7 @@ const MemoryGetSchema = Type.Object({
   lines: Type.Optional(Type.Number()),
 });
 
-export function createMemorySearchTool(options: {
-  config?: OpenClawConfig;
-  agentSessionKey?: string;
-}): AnyAgentTool | null {
+function resolveMemoryToolContext(options: { config?: OpenClawConfig; agentSessionKey?: string }) {
   const cfg = options.config;
   if (!cfg) {
     return null;
@@ -37,6 +34,18 @@ export function createMemorySearchTool(options: {
   if (!resolveMemorySearchConfig(cfg, agentId)) {
     return null;
   }
+  return { cfg, agentId };
+}
+
+export function createMemorySearchTool(options: {
+  config?: OpenClawConfig;
+  agentSessionKey?: string;
+}): AnyAgentTool | null {
+  const ctx = resolveMemoryToolContext(options);
+  if (!ctx) {
+    return null;
+  }
+  const { cfg, agentId } = ctx;
   return {
     label: "Memory Search",
     name: "memory_search",
@@ -91,17 +100,11 @@ export function createMemoryGetTool(options: {
   config?: OpenClawConfig;
   agentSessionKey?: string;
 }): AnyAgentTool | null {
-  const cfg = options.config;
-  if (!cfg) {
-    return null;
-  }
-  const agentId = resolveSessionAgentId({
-    sessionKey: options.agentSessionKey,
-    config: cfg,
-  });
-  if (!resolveMemorySearchConfig(cfg, agentId)) {
+  const ctx = resolveMemoryToolContext(options);
+  if (!ctx) {
     return null;
   }
+  const { cfg, agentId } = ctx;
   return {
     label: "Memory Get",
     name: "memory_get",
diff --git a/src/agents/tools/message-tool.e2e.test.ts b/src/agents/tools/message-tool.e2e.test.ts
index 5c974e001c7..6a7d2eed24b 100644
--- a/src/agents/tools/message-tool.e2e.test.ts
+++ b/src/agents/tools/message-tool.e2e.test.ts
@@ -44,7 +44,7 @@ describe("message tool agent routing", () => {
 
     const call = mocks.runMessageAction.mock.calls[0]?.[0];
     expect(call?.agentId).toBe("alpha");
-    expect(call?.sessionKey).toBeUndefined();
+    expect(call?.sessionKey).toBe("agent:alpha:main");
   });
 });
 
diff --git a/src/agents/tools/message-tool.ts b/src/agents/tools/message-tool.ts
index c30b89d4894..e894f71cf0d 100644
--- a/src/agents/tools/message-tool.ts
+++ b/src/agents/tools/message-tool.ts
@@ -47,6 +47,98 @@ function buildRoutingSchema() {
   };
 }
 
+const discordComponentEmojiSchema = Type.Object({
+  name: Type.String(),
+  id: Type.Optional(Type.String()),
+  animated: Type.Optional(Type.Boolean()),
+});
+
+const discordComponentOptionSchema = Type.Object({
+  label: Type.String(),
+  value: Type.String(),
+  description: Type.Optional(Type.String()),
+  emoji: Type.Optional(discordComponentEmojiSchema),
+  default: Type.Optional(Type.Boolean()),
+});
+
+const discordComponentButtonSchema = Type.Object({
+  label: Type.String(),
+  style: Type.Optional(stringEnum(["primary", "secondary", "success", "danger", "link"])),
+  url: Type.Optional(Type.String()),
+  emoji: Type.Optional(discordComponentEmojiSchema),
+  disabled: Type.Optional(Type.Boolean()),
+});
+
+const discordComponentSelectSchema = Type.Object({
+  type: Type.Optional(stringEnum(["string", "user", "role", "mentionable", "channel"])),
+  placeholder: Type.Optional(Type.String()),
+  minValues: Type.Optional(Type.Number()),
+  maxValues: Type.Optional(Type.Number()),
+  options: Type.Optional(Type.Array(discordComponentOptionSchema)),
+});
+
+const discordComponentBlockSchema = Type.Object({
+  type: Type.String(),
+  text: Type.Optional(Type.String()),
+  texts: Type.Optional(Type.Array(Type.String())),
+  accessory: Type.Optional(
+    Type.Object({
+      type: Type.String(),
+      url: Type.Optional(Type.String()),
+      button: Type.Optional(discordComponentButtonSchema),
+    }),
+  ),
+  spacing: Type.Optional(stringEnum(["small", "large"])),
+  divider: Type.Optional(Type.Boolean()),
+  buttons: Type.Optional(Type.Array(discordComponentButtonSchema)),
+  select: Type.Optional(discordComponentSelectSchema),
+  items: Type.Optional(
+    Type.Array(
+      Type.Object({
+        url: Type.String(),
+        description: Type.Optional(Type.String()),
+        spoiler: Type.Optional(Type.Boolean()),
+      }),
+    ),
+  ),
+  file: Type.Optional(Type.String()),
+  spoiler: Type.Optional(Type.Boolean()),
+});
+
+const discordComponentModalFieldSchema = Type.Object({
+  type: Type.String(),
+  name: Type.Optional(Type.String()),
+  label: Type.String(),
+  description: Type.Optional(Type.String()),
+  placeholder: Type.Optional(Type.String()),
+  required: Type.Optional(Type.Boolean()),
+  options: Type.Optional(Type.Array(discordComponentOptionSchema)),
+  minValues: Type.Optional(Type.Number()),
+  maxValues: Type.Optional(Type.Number()),
+  minLength: Type.Optional(Type.Number()),
+  maxLength: Type.Optional(Type.Number()),
+  style: Type.Optional(stringEnum(["short", "paragraph"])),
+});
+
+const discordComponentModalSchema = Type.Object({
+  title: Type.String(),
+  triggerLabel: Type.Optional(Type.String()),
+  triggerStyle: Type.Optional(stringEnum(["primary", "secondary", "success", "danger", "link"])),
+  fields: Type.Array(discordComponentModalFieldSchema),
+});
+
+const discordComponentMessageSchema = Type.Object({
+  text: Type.Optional(Type.String()),
+  container: Type.Optional(
+    Type.Object({
+      accentColor: Type.Optional(Type.String()),
+      spoiler: Type.Optional(Type.Boolean()),
+    }),
+  ),
+  blocks: Type.Optional(Type.Array(discordComponentBlockSchema)),
+  modal: Type.Optional(discordComponentModalSchema),
+});
+
 function buildSendSchema(options: { includeButtons: boolean; includeCards: boolean }) {
   const props: Record<string, unknown> = {
     message: Type.Optional(Type.String()),
@@ -105,6 +197,7 @@ function buildSendSchema(options: { includeButtons: boolean; includeCards: boole
         },
       ),
     ),
+    components: Type.Optional(discordComponentMessageSchema),
   };
   if (!options.includeButtons) {
     delete props.buttons;
@@ -481,6 +574,7 @@ export function createMessageTool(options?: MessageToolOptions): AnyAgentTool {
         defaultAccountId: accountId ?? undefined,
         gateway,
         toolContext,
+        sessionKey: options?.agentSessionKey,
         agentId: options?.agentSessionKey
           ? resolveSessionAgentId({ sessionKey: options.agentSessionKey, config: cfg })
           : undefined,
diff --git a/src/agents/tools/sessions-access.test.ts b/src/agents/tools/sessions-access.test.ts
new file mode 100644
index 00000000000..0f18191b5b9
--- /dev/null
+++ b/src/agents/tools/sessions-access.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import {
+  createAgentToAgentPolicy,
+  createSessionVisibilityGuard,
+  resolveEffectiveSessionToolsVisibility,
+  resolveSandboxSessionToolsVisibility,
+  resolveSandboxedSessionToolContext,
+  resolveSessionToolsVisibility,
+} from "./sessions-access.js";
+
+describe("resolveSessionToolsVisibility", () => {
+  it("defaults to tree when unset or invalid", () => {
+    expect(resolveSessionToolsVisibility({} as OpenClawConfig)).toBe("tree");
+    expect(
+      resolveSessionToolsVisibility({
+        tools: { sessions: { visibility: "invalid" } },
+      } as OpenClawConfig),
+    ).toBe("tree");
+  });
+
+  it("accepts known visibility values case-insensitively", () => {
+    expect(
+      resolveSessionToolsVisibility({
+        tools: { sessions: { visibility: "ALL" } },
+      } as OpenClawConfig),
+    ).toBe("all");
+  });
+});
+
+describe("resolveEffectiveSessionToolsVisibility", () => {
+  it("clamps to tree in sandbox when sandbox visibility is spawned", () => {
+    const cfg = {
+      tools: { sessions: { visibility: "all" } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "spawned" } } },
+    } as OpenClawConfig;
+    expect(resolveEffectiveSessionToolsVisibility({ cfg, sandboxed: true })).toBe("tree");
+  });
+
+  it("preserves visibility when sandbox clamp is all", () => {
+    const cfg = {
+      tools: { sessions: { visibility: "all" } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "all" } } },
+    } as OpenClawConfig;
+    expect(resolveEffectiveSessionToolsVisibility({ cfg, sandboxed: true })).toBe("all");
+  });
+});
+
+describe("sandbox session-tools context", () => {
+  it("defaults sandbox visibility clamp to spawned", () => {
+    expect(resolveSandboxSessionToolsVisibility({} as OpenClawConfig)).toBe("spawned");
+  });
+
+  it("restricts non-subagent sandboxed sessions to spawned visibility", () => {
+    const cfg = {
+      tools: { sessions: { visibility: "all" } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "spawned" } } },
+    } as OpenClawConfig;
+    const context = resolveSandboxedSessionToolContext({
+      cfg,
+      agentSessionKey: "agent:main:main",
+      sandboxed: true,
+    });
+
+    expect(context.restrictToSpawned).toBe(true);
+    expect(context.requesterInternalKey).toBe("agent:main:main");
+    expect(context.effectiveRequesterKey).toBe("agent:main:main");
+  });
+
+  it("does not restrict subagent sessions in sandboxed mode", () => {
+    const cfg = {
+      tools: { sessions: { visibility: "all" } },
+      agents: { defaults: { sandbox: { sessionToolsVisibility: "spawned" } } },
+    } as OpenClawConfig;
+    const context = resolveSandboxedSessionToolContext({
+      cfg,
+      agentSessionKey: "agent:main:subagent:abc",
+      sandboxed: true,
+    });
+
+    expect(context.restrictToSpawned).toBe(false);
+    expect(context.requesterInternalKey).toBe("agent:main:subagent:abc");
+  });
+});
+
+describe("createAgentToAgentPolicy", () => {
+  it("denies cross-agent access when disabled", () => {
+    const policy = createAgentToAgentPolicy({} as OpenClawConfig);
+    expect(policy.enabled).toBe(false);
+    expect(policy.isAllowed("main", "main")).toBe(true);
+    expect(policy.isAllowed("main", "ops")).toBe(false);
+  });
+
+  it("honors allow patterns when enabled", () => {
+    const policy = createAgentToAgentPolicy({
+      tools: {
+        agentToAgent: {
+          enabled: true,
+          allow: ["ops-*", "main"],
+        },
+      },
+    } as OpenClawConfig);
+
+    expect(policy.isAllowed("ops-a", "ops-b")).toBe(true);
+    expect(policy.isAllowed("main", "ops-a")).toBe(true);
+    expect(policy.isAllowed("guest", "ops-a")).toBe(false);
+  });
+});
+
+describe("createSessionVisibilityGuard", () => {
+  it("blocks cross-agent send when agent-to-agent is disabled", async () => {
+    const guard = await createSessionVisibilityGuard({
+      action: "send",
+      requesterSessionKey: "agent:main:main",
+      visibility: "all",
+      a2aPolicy: createAgentToAgentPolicy({} as OpenClawConfig),
+    });
+
+    expect(guard.check("agent:ops:main")).toEqual({
+      allowed: false,
+      status: "forbidden",
+      error:
+        "Agent-to-agent messaging is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent sends.",
+    });
+  });
+
+  it("enforces self visibility for same-agent sessions", async () => {
+    const guard = await createSessionVisibilityGuard({
+      action: "history",
+      requesterSessionKey: "agent:main:main",
+      visibility: "self",
+      a2aPolicy: createAgentToAgentPolicy({} as OpenClawConfig),
+    });
+
+    expect(guard.check("agent:main:main")).toEqual({ allowed: true });
+    expect(guard.check("agent:main:telegram:group:1")).toEqual({
+      allowed: false,
+      status: "forbidden",
+      error:
+        "Session history visibility is restricted to the current session (tools.sessions.visibility=self).",
+    });
+  });
+});
diff --git a/src/agents/tools/sessions-access.ts b/src/agents/tools/sessions-access.ts
new file mode 100644
index 00000000000..6574c2296cf
--- /dev/null
+++ b/src/agents/tools/sessions-access.ts
@@ -0,0 +1,240 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import { isSubagentSessionKey, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+import {
+  listSpawnedSessionKeys,
+  resolveInternalSessionKey,
+  resolveMainSessionAlias,
+} from "./sessions-resolution.js";
+
+export type SessionToolsVisibility = "self" | "tree" | "agent" | "all";
+
+export type AgentToAgentPolicy = {
+  enabled: boolean;
+  matchesAllow: (agentId: string) => boolean;
+  isAllowed: (requesterAgentId: string, targetAgentId: string) => boolean;
+};
+
+export type SessionAccessAction = "history" | "send" | "list";
+
+export type SessionAccessResult =
+  | { allowed: true }
+  | { allowed: false; error: string; status: "forbidden" };
+
+export function resolveSessionToolsVisibility(cfg: OpenClawConfig): SessionToolsVisibility {
+  const raw = (cfg.tools as { sessions?: { visibility?: unknown } } | undefined)?.sessions
+    ?.visibility;
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (value === "self" || value === "tree" || value === "agent" || value === "all") {
+    return value;
+  }
+  return "tree";
+}
+
+export function resolveEffectiveSessionToolsVisibility(params: {
+  cfg: OpenClawConfig;
+  sandboxed: boolean;
+}): SessionToolsVisibility {
+  const visibility = resolveSessionToolsVisibility(params.cfg);
+  if (!params.sandboxed) {
+    return visibility;
+  }
+  const sandboxClamp = params.cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
+  if (sandboxClamp === "spawned" && visibility !== "tree") {
+    return "tree";
+  }
+  return visibility;
+}
+
+export function resolveSandboxSessionToolsVisibility(cfg: OpenClawConfig): "spawned" | "all" {
+  return cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
+}
+
+export function resolveSandboxedSessionToolContext(params: {
+  cfg: OpenClawConfig;
+  agentSessionKey?: string;
+  sandboxed?: boolean;
+}): {
+  mainKey: string;
+  alias: string;
+  visibility: "spawned" | "all";
+  requesterInternalKey: string | undefined;
+  effectiveRequesterKey: string;
+  restrictToSpawned: boolean;
+} {
+  const { mainKey, alias } = resolveMainSessionAlias(params.cfg);
+  const visibility = resolveSandboxSessionToolsVisibility(params.cfg);
+  const requesterInternalKey =
+    typeof params.agentSessionKey === "string" && params.agentSessionKey.trim()
+      ? resolveInternalSessionKey({
+          key: params.agentSessionKey,
+          alias,
+          mainKey,
+        })
+      : undefined;
+  const effectiveRequesterKey = requesterInternalKey ?? alias;
+  const restrictToSpawned =
+    params.sandboxed === true &&
+    visibility === "spawned" &&
+    !!requesterInternalKey &&
+    !isSubagentSessionKey(requesterInternalKey);
+  return {
+    mainKey,
+    alias,
+    visibility,
+    requesterInternalKey,
+    effectiveRequesterKey,
+    restrictToSpawned,
+  };
+}
+
+export function createAgentToAgentPolicy(cfg: OpenClawConfig): AgentToAgentPolicy {
+  const routingA2A = cfg.tools?.agentToAgent;
+  const enabled = routingA2A?.enabled === true;
+  const allowPatterns = Array.isArray(routingA2A?.allow) ? routingA2A.allow : [];
+  const matchesAllow = (agentId: string) => {
+    if (allowPatterns.length === 0) {
+      return true;
+    }
+    return allowPatterns.some((pattern) => {
+      const raw = String(pattern ?? "").trim();
+      if (!raw) {
+        return false;
+      }
+      if (raw === "*") {
+        return true;
+      }
+      if (!raw.includes("*")) {
+        return raw === agentId;
+      }
+      const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`^${escaped.replaceAll("\\*", ".*")}$`, "i");
+      return re.test(agentId);
+    });
+  };
+  const isAllowed = (requesterAgentId: string, targetAgentId: string) => {
+    if (requesterAgentId === targetAgentId) {
+      return true;
+    }
+    if (!enabled) {
+      return false;
+    }
+    return matchesAllow(requesterAgentId) && matchesAllow(targetAgentId);
+  };
+  return { enabled, matchesAllow, isAllowed };
+}
+
+function actionPrefix(action: SessionAccessAction): string {
+  if (action === "history") {
+    return "Session history";
+  }
+  if (action === "send") {
+    return "Session send";
+  }
+  return "Session list";
+}
+
+function a2aDisabledMessage(action: SessionAccessAction): string {
+  if (action === "history") {
+    return "Agent-to-agent history is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent access.";
+  }
+  if (action === "send") {
+    return "Agent-to-agent messaging is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent sends.";
+  }
+  return "Agent-to-agent listing is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent visibility.";
+}
+
+function a2aDeniedMessage(action: SessionAccessAction): string {
+  if (action === "history") {
+    return "Agent-to-agent history denied by tools.agentToAgent.allow.";
+  }
+  if (action === "send") {
+    return "Agent-to-agent messaging denied by tools.agentToAgent.allow.";
+  }
+  return "Agent-to-agent listing denied by tools.agentToAgent.allow.";
+}
+
+function crossVisibilityMessage(action: SessionAccessAction): string {
+  if (action === "history") {
+    return "Session history visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+  }
+  if (action === "send") {
+    return "Session send visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+  }
+  return "Session list visibility is restricted. Set tools.sessions.visibility=all to allow cross-agent access.";
+}
+
+function selfVisibilityMessage(action: SessionAccessAction): string {
+  return `${actionPrefix(action)} visibility is restricted to the current session (tools.sessions.visibility=self).`;
+}
+
+function treeVisibilityMessage(action: SessionAccessAction): string {
+  return `${actionPrefix(action)} visibility is restricted to the current session tree (tools.sessions.visibility=tree).`;
+}
+
+export async function createSessionVisibilityGuard(params: {
+  action: SessionAccessAction;
+  requesterSessionKey: string;
+  visibility: SessionToolsVisibility;
+  a2aPolicy: AgentToAgentPolicy;
+}): Promise<{
+  check: (targetSessionKey: string) => SessionAccessResult;
+}> {
+  const requesterAgentId = resolveAgentIdFromSessionKey(params.requesterSessionKey);
+  const spawnedKeys =
+    params.visibility === "tree"
+      ? await listSpawnedSessionKeys({ requesterSessionKey: params.requesterSessionKey })
+      : null;
+
+  const check = (targetSessionKey: string): SessionAccessResult => {
+    const targetAgentId = resolveAgentIdFromSessionKey(targetSessionKey);
+    const isCrossAgent = targetAgentId !== requesterAgentId;
+    if (isCrossAgent) {
+      if (params.visibility !== "all") {
+        return {
+          allowed: false,
+          status: "forbidden",
+          error: crossVisibilityMessage(params.action),
+        };
+      }
+      if (!params.a2aPolicy.enabled) {
+        return {
+          allowed: false,
+          status: "forbidden",
+          error: a2aDisabledMessage(params.action),
+        };
+      }
+      if (!params.a2aPolicy.isAllowed(requesterAgentId, targetAgentId)) {
+        return {
+          allowed: false,
+          status: "forbidden",
+          error: a2aDeniedMessage(params.action),
+        };
+      }
+      return { allowed: true };
+    }
+
+    if (params.visibility === "self" && targetSessionKey !== params.requesterSessionKey) {
+      return {
+        allowed: false,
+        status: "forbidden",
+        error: selfVisibilityMessage(params.action),
+      };
+    }
+
+    if (
+      params.visibility === "tree" &&
+      targetSessionKey !== params.requesterSessionKey &&
+      !spawnedKeys?.has(targetSessionKey)
+    ) {
+      return {
+        allowed: false,
+        status: "forbidden",
+        error: treeVisibilityMessage(params.action),
+      };
+    }
+
+    return { allowed: true };
+  };
+
+  return { check };
+}
diff --git a/src/agents/tools/sessions-announce-target.e2e.test.ts b/src/agents/tools/sessions-announce-target.e2e.test.ts
deleted file mode 100644
index fe28be7dff9..00000000000
--- a/src/agents/tools/sessions-announce-target.e2e.test.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { createTestRegistry } from "../../test-utils/channel-plugins.js";
-
-const callGatewayMock = vi.fn();
-vi.mock("../../gateway/call.js", () => ({
-  callGateway: (opts: unknown) => callGatewayMock(opts),
-}));
-
-const loadResolveAnnounceTarget = async () => await import("./sessions-announce-target.js");
-
-const installRegistry = async () => {
-  const { setActivePluginRegistry } = await import("../../plugins/runtime.js");
-  setActivePluginRegistry(
-    createTestRegistry([
-      {
-        pluginId: "discord",
-        source: "test",
-        plugin: {
-          id: "discord",
-          meta: {
-            id: "discord",
-            label: "Discord",
-            selectionLabel: "Discord",
-            docsPath: "/channels/discord",
-            blurb: "Discord test stub.",
-          },
-          capabilities: { chatTypes: ["direct", "channel", "thread"] },
-          config: {
-            listAccountIds: () => ["default"],
-            resolveAccount: () => ({}),
-          },
-        },
-      },
-      {
-        pluginId: "whatsapp",
-        source: "test",
-        plugin: {
-          id: "whatsapp",
-          meta: {
-            id: "whatsapp",
-            label: "WhatsApp",
-            selectionLabel: "WhatsApp",
-            docsPath: "/channels/whatsapp",
-            blurb: "WhatsApp test stub.",
-            preferSessionLookupForAnnounceTarget: true,
-          },
-          capabilities: { chatTypes: ["direct", "group"] },
-          config: {
-            listAccountIds: () => ["default"],
-            resolveAccount: () => ({}),
-          },
-        },
-      },
-    ]),
-  );
-};
-
-describe("resolveAnnounceTarget", () => {
-  beforeEach(async () => {
-    callGatewayMock.mockReset();
-    await installRegistry();
-  });
-
-  it("derives non-WhatsApp announce targets from the session key", async () => {
-    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
-    const target = await resolveAnnounceTarget({
-      sessionKey: "agent:main:discord:group:dev",
-      displayKey: "agent:main:discord:group:dev",
-    });
-    expect(target).toEqual({ channel: "discord", to: "channel:dev" });
-    expect(callGatewayMock).not.toHaveBeenCalled();
-  });
-
-  it("hydrates WhatsApp accountId from sessions.list when available", async () => {
-    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
-    callGatewayMock.mockResolvedValueOnce({
-      sessions: [
-        {
-          key: "agent:main:whatsapp:group:123@g.us",
-          deliveryContext: {
-            channel: "whatsapp",
-            to: "123@g.us",
-            accountId: "work",
-          },
-        },
-      ],
-    });
-
-    const target = await resolveAnnounceTarget({
-      sessionKey: "agent:main:whatsapp:group:123@g.us",
-      displayKey: "agent:main:whatsapp:group:123@g.us",
-    });
-    expect(target).toEqual({
-      channel: "whatsapp",
-      to: "123@g.us",
-      accountId: "work",
-    });
-    expect(callGatewayMock).toHaveBeenCalledTimes(1);
-    const first = callGatewayMock.mock.calls[0]?.[0] as { method?: string } | undefined;
-    expect(first).toBeDefined();
-    expect(first?.method).toBe("sessions.list");
-  });
-});
diff --git a/src/agents/tools/sessions-helpers.e2e.test.ts b/src/agents/tools/sessions-helpers.e2e.test.ts
deleted file mode 100644
index 887cc1f4670..00000000000
--- a/src/agents/tools/sessions-helpers.e2e.test.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { extractAssistantText, sanitizeTextContent } from "./sessions-helpers.js";
-
-describe("sanitizeTextContent", () => {
-  it("strips minimax tool call XML and downgraded markers", () => {
-    const input =
-      'Hello <invoke name="tool">payload</invoke></minimax:tool_call> ' +
-      "[Tool Call: foo (ID: 1)] world";
-    const result = sanitizeTextContent(input).trim();
-    expect(result).toBe("Hello  world");
-    expect(result).not.toContain("invoke");
-    expect(result).not.toContain("Tool Call");
-  });
-
-  it("strips thinking tags", () => {
-    const input = "Before <think>secret</think> after";
-    const result = sanitizeTextContent(input).trim();
-    expect(result).toBe("Before  after");
-  });
-});
-
-describe("extractAssistantText", () => {
-  it("sanitizes blocks without injecting newlines", () => {
-    const message = {
-      role: "assistant",
-      content: [
-        { type: "text", text: "Hi " },
-        { type: "text", text: "<think>secret</think>there" },
-      ],
-    };
-    expect(extractAssistantText(message)).toBe("Hi there");
-  });
-
-  it("rewrites error-ish assistant text only when the transcript marks it as an error", () => {
-    const message = {
-      role: "assistant",
-      stopReason: "error",
-      errorMessage: "500 Internal Server Error",
-      content: [{ type: "text", text: "500 Internal Server Error" }],
-    };
-    expect(extractAssistantText(message)).toBe("HTTP 500: Internal Server Error");
-  });
-
-  it("keeps normal status text that mentions billing", () => {
-    const message = {
-      role: "assistant",
-      content: [
-        {
-          type: "text",
-          text: "Firebase downgraded us to the free Spark plan. Check whether billing should be re-enabled.",
-        },
-      ],
-    };
-    expect(extractAssistantText(message)).toBe(
-      "Firebase downgraded us to the free Spark plan. Check whether billing should be re-enabled.",
-    );
-  });
-});
diff --git a/src/agents/tools/sessions-helpers.ts b/src/agents/tools/sessions-helpers.ts
index 1b399de5a80..09c21e69998 100644
--- a/src/agents/tools/sessions-helpers.ts
+++ b/src/agents/tools/sessions-helpers.ts
@@ -1,10 +1,29 @@
-import type { OpenClawConfig } from "../../config/config.js";
-import { callGateway } from "../../gateway/call.js";
-import {
-  isAcpSessionKey,
-  isSubagentSessionKey,
-  normalizeMainKey,
-} from "../../routing/session-key.js";
+export type {
+  AgentToAgentPolicy,
+  SessionAccessAction,
+  SessionAccessResult,
+  SessionToolsVisibility,
+} from "./sessions-access.js";
+export {
+  createAgentToAgentPolicy,
+  createSessionVisibilityGuard,
+  resolveEffectiveSessionToolsVisibility,
+  resolveSandboxSessionToolsVisibility,
+  resolveSandboxedSessionToolContext,
+  resolveSessionToolsVisibility,
+} from "./sessions-access.js";
+export type { SessionReferenceResolution } from "./sessions-resolution.js";
+export {
+  isRequesterSpawnedSessionVisible,
+  listSpawnedSessionKeys,
+  looksLikeSessionId,
+  looksLikeSessionKey,
+  resolveDisplaySessionKey,
+  resolveInternalSessionKey,
+  resolveMainSessionAlias,
+  resolveSessionReference,
+  shouldResolveSessionIdInput,
+} from "./sessions-resolution.js";
 import { sanitizeUserFacingText } from "../pi-embedded-helpers.js";
 import {
   stripDowngradedToolCallText,
@@ -49,282 +68,6 @@ function normalizeKey(value?: string) {
   return trimmed ? trimmed : undefined;
 }
 
-export function resolveMainSessionAlias(cfg: OpenClawConfig) {
-  const mainKey = normalizeMainKey(cfg.session?.mainKey);
-  const scope = cfg.session?.scope ?? "per-sender";
-  const alias = scope === "global" ? "global" : mainKey;
-  return { mainKey, alias, scope };
-}
-
-export function resolveDisplaySessionKey(params: { key: string; alias: string; mainKey: string }) {
-  if (params.key === params.alias) {
-    return "main";
-  }
-  if (params.key === params.mainKey) {
-    return "main";
-  }
-  return params.key;
-}
-
-export function resolveInternalSessionKey(params: { key: string; alias: string; mainKey: string }) {
-  if (params.key === "main") {
-    return params.alias;
-  }
-  return params.key;
-}
-
-export function resolveSandboxSessionToolsVisibility(cfg: OpenClawConfig): "spawned" | "all" {
-  return cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
-}
-
-export function resolveSandboxedSessionToolContext(params: {
-  cfg: OpenClawConfig;
-  agentSessionKey?: string;
-  sandboxed?: boolean;
-}): {
-  mainKey: string;
-  alias: string;
-  visibility: "spawned" | "all";
-  requesterInternalKey: string | undefined;
-  restrictToSpawned: boolean;
-} {
-  const { mainKey, alias } = resolveMainSessionAlias(params.cfg);
-  const visibility = resolveSandboxSessionToolsVisibility(params.cfg);
-  const requesterInternalKey =
-    typeof params.agentSessionKey === "string" && params.agentSessionKey.trim()
-      ? resolveInternalSessionKey({
-          key: params.agentSessionKey,
-          alias,
-          mainKey,
-        })
-      : undefined;
-  const restrictToSpawned =
-    params.sandboxed === true &&
-    visibility === "spawned" &&
-    !!requesterInternalKey &&
-    !isSubagentSessionKey(requesterInternalKey);
-  return { mainKey, alias, visibility, requesterInternalKey, restrictToSpawned };
-}
-
-export type AgentToAgentPolicy = {
-  enabled: boolean;
-  matchesAllow: (agentId: string) => boolean;
-  isAllowed: (requesterAgentId: string, targetAgentId: string) => boolean;
-};
-
-export function createAgentToAgentPolicy(cfg: OpenClawConfig): AgentToAgentPolicy {
-  const routingA2A = cfg.tools?.agentToAgent;
-  const enabled = routingA2A?.enabled === true;
-  const allowPatterns = Array.isArray(routingA2A?.allow) ? routingA2A.allow : [];
-  const matchesAllow = (agentId: string) => {
-    if (allowPatterns.length === 0) {
-      return true;
-    }
-    return allowPatterns.some((pattern) => {
-      const raw = String(pattern ?? "").trim();
-      if (!raw) {
-        return false;
-      }
-      if (raw === "*") {
-        return true;
-      }
-      if (!raw.includes("*")) {
-        return raw === agentId;
-      }
-      const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const re = new RegExp(`^${escaped.replaceAll("\\*", ".*")}$`, "i");
-      return re.test(agentId);
-    });
-  };
-  const isAllowed = (requesterAgentId: string, targetAgentId: string) => {
-    if (requesterAgentId === targetAgentId) {
-      return true;
-    }
-    if (!enabled) {
-      return false;
-    }
-    return matchesAllow(requesterAgentId) && matchesAllow(targetAgentId);
-  };
-  return { enabled, matchesAllow, isAllowed };
-}
-
-const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export function looksLikeSessionId(value: string): boolean {
-  return SESSION_ID_RE.test(value.trim());
-}
-
-export function looksLikeSessionKey(value: string): boolean {
-  const raw = value.trim();
-  if (!raw) {
-    return false;
-  }
-  // These are canonical key shapes that should never be treated as sessionIds.
-  if (raw === "main" || raw === "global" || raw === "unknown") {
-    return true;
-  }
-  if (isAcpSessionKey(raw)) {
-    return true;
-  }
-  if (raw.startsWith("agent:")) {
-    return true;
-  }
-  if (raw.startsWith("cron:") || raw.startsWith("hook:")) {
-    return true;
-  }
-  if (raw.startsWith("node-") || raw.startsWith("node:")) {
-    return true;
-  }
-  if (raw.includes(":group:") || raw.includes(":channel:")) {
-    return true;
-  }
-  return false;
-}
-
-export function shouldResolveSessionIdInput(value: string): boolean {
-  // Treat anything that doesn't look like a well-formed key as a sessionId candidate.
-  return looksLikeSessionId(value) || !looksLikeSessionKey(value);
-}
-
-export type SessionReferenceResolution =
-  | {
-      ok: true;
-      key: string;
-      displayKey: string;
-      resolvedViaSessionId: boolean;
-    }
-  | { ok: false; status: "error" | "forbidden"; error: string };
-
-async function resolveSessionKeyFromSessionId(params: {
-  sessionId: string;
-  alias: string;
-  mainKey: string;
-  requesterInternalKey?: string;
-  restrictToSpawned: boolean;
-}): Promise<SessionReferenceResolution> {
-  try {
-    // Resolve via gateway so we respect store routing and visibility rules.
-    const result = await callGateway<{ key?: string }>({
-      method: "sessions.resolve",
-      params: {
-        sessionId: params.sessionId,
-        spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
-        includeGlobal: !params.restrictToSpawned,
-        includeUnknown: !params.restrictToSpawned,
-      },
-    });
-    const key = typeof result?.key === "string" ? result.key.trim() : "";
-    if (!key) {
-      throw new Error(
-        `Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`,
-      );
-    }
-    return {
-      ok: true,
-      key,
-      displayKey: resolveDisplaySessionKey({
-        key,
-        alias: params.alias,
-        mainKey: params.mainKey,
-      }),
-      resolvedViaSessionId: true,
-    };
-  } catch (err) {
-    if (params.restrictToSpawned) {
-      return {
-        ok: false,
-        status: "forbidden",
-        error: `Session not visible from this sandboxed agent session: ${params.sessionId}`,
-      };
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      ok: false,
-      status: "error",
-      error:
-        message ||
-        `Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`,
-    };
-  }
-}
-
-async function resolveSessionKeyFromKey(params: {
-  key: string;
-  alias: string;
-  mainKey: string;
-  requesterInternalKey?: string;
-  restrictToSpawned: boolean;
-}): Promise<SessionReferenceResolution | null> {
-  try {
-    // Try key-based resolution first so non-standard keys keep working.
-    const result = await callGateway<{ key?: string }>({
-      method: "sessions.resolve",
-      params: {
-        key: params.key,
-        spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
-      },
-    });
-    const key = typeof result?.key === "string" ? result.key.trim() : "";
-    if (!key) {
-      return null;
-    }
-    return {
-      ok: true,
-      key,
-      displayKey: resolveDisplaySessionKey({
-        key,
-        alias: params.alias,
-        mainKey: params.mainKey,
-      }),
-      resolvedViaSessionId: false,
-    };
-  } catch {
-    return null;
-  }
-}
-
-export async function resolveSessionReference(params: {
-  sessionKey: string;
-  alias: string;
-  mainKey: string;
-  requesterInternalKey?: string;
-  restrictToSpawned: boolean;
-}): Promise<SessionReferenceResolution> {
-  const raw = params.sessionKey.trim();
-  if (shouldResolveSessionIdInput(raw)) {
-    // Prefer key resolution to avoid misclassifying custom keys as sessionIds.
-    const resolvedByKey = await resolveSessionKeyFromKey({
-      key: raw,
-      alias: params.alias,
-      mainKey: params.mainKey,
-      requesterInternalKey: params.requesterInternalKey,
-      restrictToSpawned: params.restrictToSpawned,
-    });
-    if (resolvedByKey) {
-      return resolvedByKey;
-    }
-    return await resolveSessionKeyFromSessionId({
-      sessionId: raw,
-      alias: params.alias,
-      mainKey: params.mainKey,
-      requesterInternalKey: params.requesterInternalKey,
-      restrictToSpawned: params.restrictToSpawned,
-    });
-  }
-
-  const resolvedKey = resolveInternalSessionKey({
-    key: raw,
-    alias: params.alias,
-    mainKey: params.mainKey,
-  });
-  const displayKey = resolveDisplaySessionKey({
-    key: resolvedKey,
-    alias: params.alias,
-    mainKey: params.mainKey,
-  });
-  return { ok: true, key: resolvedKey, displayKey, resolvedViaSessionId: false };
-}
-
 export function classifySessionKind(params: {
   key: string;
   gatewayKind?: string | null;
diff --git a/src/agents/tools/sessions-history-tool.ts b/src/agents/tools/sessions-history-tool.ts
index a2b9741d639..dae466b7230 100644
--- a/src/agents/tools/sessions-history-tool.ts
+++ b/src/agents/tools/sessions-history-tool.ts
@@ -3,13 +3,14 @@ import type { AnyAgentTool } from "./common.js";
 import { loadConfig } from "../../config/config.js";
 import { callGateway } from "../../gateway/call.js";
 import { capArrayByJsonBytes } from "../../gateway/session-utils.fs.js";
-import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
 import { truncateUtf16Safe } from "../../utils.js";
 import { jsonResult, readStringParam } from "./common.js";
 import {
+  createSessionVisibilityGuard,
   createAgentToAgentPolicy,
+  isRequesterSpawnedSessionVisible,
+  resolveEffectiveSessionToolsVisibility,
   resolveSessionReference,
-  SessionListRow,
   resolveSandboxedSessionToolContext,
   stripToolMessages,
 } from "./sessions-helpers.js";
@@ -147,27 +148,6 @@ function enforceSessionsHistoryHardCap(params: {
   return { items: placeholder, bytes: jsonUtf8Bytes(placeholder), hardCapped: true };
 }
 
-async function isSpawnedSessionAllowed(params: {
-  requesterSessionKey: string;
-  targetSessionKey: string;
-}): Promise<boolean> {
-  try {
-    const list = await callGateway<{ sessions: Array<SessionListRow> }>({
-      method: "sessions.list",
-      params: {
-        includeGlobal: false,
-        includeUnknown: false,
-        limit: 500,
-        spawnedBy: params.requesterSessionKey,
-      },
-    });
-    const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
-    return sessions.some((entry) => entry?.key === params.targetSessionKey);
-  } catch {
-    return false;
-  }
-}
-
 export function createSessionsHistoryTool(opts?: {
   agentSessionKey?: string;
   sandboxed?: boolean;
@@ -183,7 +163,7 @@ export function createSessionsHistoryTool(opts?: {
         required: true,
       });
       const cfg = loadConfig();
-      const { mainKey, alias, requesterInternalKey, restrictToSpawned } =
+      const { mainKey, alias, effectiveRequesterKey, restrictToSpawned } =
         resolveSandboxedSessionToolContext({
           cfg,
           agentSessionKey: opts?.agentSessionKey,
@@ -193,7 +173,7 @@ export function createSessionsHistoryTool(opts?: {
         sessionKey: sessionKeyParam,
         alias,
         mainKey,
-        requesterInternalKey,
+        requesterInternalKey: effectiveRequesterKey,
         restrictToSpawned,
       });
       if (!resolvedSession.ok) {
@@ -203,9 +183,9 @@ export function createSessionsHistoryTool(opts?: {
       const resolvedKey = resolvedSession.key;
       const displayKey = resolvedSession.displayKey;
       const resolvedViaSessionId = resolvedSession.resolvedViaSessionId;
-      if (restrictToSpawned && requesterInternalKey && !resolvedViaSessionId) {
-        const ok = await isSpawnedSessionAllowed({
-          requesterSessionKey: requesterInternalKey,
+      if (restrictToSpawned && !resolvedViaSessionId && resolvedKey !== effectiveRequesterKey) {
+        const ok = await isRequesterSpawnedSessionVisible({
+          requesterSessionKey: effectiveRequesterKey,
           targetSessionKey: resolvedKey,
         });
         if (!ok) {
@@ -217,23 +197,22 @@ export function createSessionsHistoryTool(opts?: {
       }
 
       const a2aPolicy = createAgentToAgentPolicy(cfg);
-      const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
-      const targetAgentId = resolveAgentIdFromSessionKey(resolvedKey);
-      const isCrossAgent = requesterAgentId !== targetAgentId;
-      if (isCrossAgent) {
-        if (!a2aPolicy.enabled) {
-          return jsonResult({
-            status: "forbidden",
-            error:
-              "Agent-to-agent history is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent access.",
-          });
-        }
-        if (!a2aPolicy.isAllowed(requesterAgentId, targetAgentId)) {
-          return jsonResult({
-            status: "forbidden",
-            error: "Agent-to-agent history denied by tools.agentToAgent.allow.",
-          });
-        }
+      const visibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
+      const visibilityGuard = await createSessionVisibilityGuard({
+        action: "history",
+        requesterSessionKey: effectiveRequesterKey,
+        visibility,
+        a2aPolicy,
+      });
+      const access = visibilityGuard.check(resolvedKey);
+      if (!access.allowed) {
+        return jsonResult({
+          status: access.status,
+          error: access.error,
+        });
       }
 
       const limit =
diff --git a/src/agents/tools/sessions-list-tool.gating.e2e.test.ts b/src/agents/tools/sessions-list-tool.gating.e2e.test.ts
deleted file mode 100644
index 636c2c5a1c3..00000000000
--- a/src/agents/tools/sessions-list-tool.gating.e2e.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const callGatewayMock = vi.fn();
-vi.mock("../../gateway/call.js", () => ({
-  callGateway: (opts: unknown) => callGatewayMock(opts),
-}));
-
-vi.mock("../../config/config.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../config/config.js")>();
-  return {
-    ...actual,
-    loadConfig: () =>
-      ({
-        session: { scope: "per-sender", mainKey: "main" },
-        tools: { agentToAgent: { enabled: false } },
-      }) as never,
-  };
-});
-
-import { createSessionsListTool } from "./sessions-list-tool.js";
-
-describe("sessions_list gating", () => {
-  beforeEach(() => {
-    callGatewayMock.mockReset();
-    callGatewayMock.mockResolvedValue({
-      path: "/tmp/sessions.json",
-      sessions: [
-        { key: "agent:main:main", kind: "direct" },
-        { key: "agent:other:main", kind: "direct" },
-      ],
-    });
-  });
-
-  it("filters out other agents when tools.agentToAgent.enabled is false", async () => {
-    const tool = createSessionsListTool({ agentSessionKey: "agent:main:main" });
-    const result = await tool.execute("call1", {});
-    expect(result.details).toMatchObject({
-      count: 1,
-      sessions: [{ key: "agent:main:main" }],
-    });
-  });
-});
diff --git a/src/agents/tools/sessions-list-tool.ts b/src/agents/tools/sessions-list-tool.ts
index abbb6b4958d..277b95f3c27 100644
--- a/src/agents/tools/sessions-list-tool.ts
+++ b/src/agents/tools/sessions-list-tool.ts
@@ -7,10 +7,12 @@ import { callGateway } from "../../gateway/call.js";
 import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
 import { jsonResult, readStringArrayParam } from "./common.js";
 import {
+  createSessionVisibilityGuard,
   createAgentToAgentPolicy,
   classifySessionKind,
   deriveChannel,
   resolveDisplaySessionKey,
+  resolveEffectiveSessionToolsVisibility,
   resolveInternalSessionKey,
   resolveSandboxedSessionToolContext,
   type SessionListRow,
@@ -42,6 +44,11 @@ export function createSessionsListTool(opts?: {
           agentSessionKey: opts?.agentSessionKey,
           sandboxed: opts?.sandboxed,
         });
+      const effectiveRequesterKey = requesterInternalKey ?? alias;
+      const visibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
 
       const kindsRaw = readStringArrayParam(params, "kinds")?.map((value) =>
         value.trim().toLowerCase(),
@@ -72,15 +79,21 @@ export function createSessionsListTool(opts?: {
           activeMinutes,
           includeGlobal: !restrictToSpawned,
           includeUnknown: !restrictToSpawned,
-          spawnedBy: restrictToSpawned ? requesterInternalKey : undefined,
+          spawnedBy: restrictToSpawned ? effectiveRequesterKey : undefined,
         },
       });
 
       const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
       const storePath = typeof list?.path === "string" ? list.path : undefined;
       const a2aPolicy = createAgentToAgentPolicy(cfg);
-      const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
+      const visibilityGuard = await createSessionVisibilityGuard({
+        action: "list",
+        requesterSessionKey: effectiveRequesterKey,
+        visibility,
+        a2aPolicy,
+      });
       const rows: SessionListRow[] = [];
+      const historyTargets: Array<{ row: SessionListRow; resolvedKey: string }> = [];
 
       for (const entry of sessions) {
         if (!entry || typeof entry !== "object") {
@@ -90,10 +103,8 @@ export function createSessionsListTool(opts?: {
         if (!key) {
           continue;
         }
-
-        const entryAgentId = resolveAgentIdFromSessionKey(key);
-        const crossAgent = entryAgentId !== requesterAgentId;
-        if (crossAgent && !a2aPolicy.isAllowed(requesterAgentId, entryAgentId)) {
+        const access = visibilityGuard.check(key);
+        if (!access.allowed) {
           continue;
         }
 
@@ -188,25 +199,41 @@ export function createSessionsListTool(opts?: {
           lastAccountId,
           transcriptPath,
         };
-
         if (messageLimit > 0) {
           const resolvedKey = resolveInternalSessionKey({
             key: displayKey,
             alias,
             mainKey,
           });
-          const history = await callGateway<{ messages: Array<unknown> }>({
-            method: "chat.history",
-            params: { sessionKey: resolvedKey, limit: messageLimit },
-          });
-          const rawMessages = Array.isArray(history?.messages) ? history.messages : [];
-          const filtered = stripToolMessages(rawMessages);
-          row.messages = filtered.length > messageLimit ? filtered.slice(-messageLimit) : filtered;
+          historyTargets.push({ row, resolvedKey });
         }
-
         rows.push(row);
       }
 
+      if (messageLimit > 0 && historyTargets.length > 0) {
+        const maxConcurrent = Math.min(4, historyTargets.length);
+        let index = 0;
+        const worker = async () => {
+          while (true) {
+            const next = index;
+            index += 1;
+            if (next >= historyTargets.length) {
+              return;
+            }
+            const target = historyTargets[next];
+            const history = await callGateway<{ messages: Array<unknown> }>({
+              method: "chat.history",
+              params: { sessionKey: target.resolvedKey, limit: messageLimit },
+            });
+            const rawMessages = Array.isArray(history?.messages) ? history.messages : [];
+            const filtered = stripToolMessages(rawMessages);
+            target.row.messages =
+              filtered.length > messageLimit ? filtered.slice(-messageLimit) : filtered;
+          }
+        };
+        await Promise.all(Array.from({ length: maxConcurrent }, () => worker()));
+      }
+
       return jsonResult({
         count: rows.length,
         sessions: rows,
diff --git a/src/agents/tools/sessions-resolution.test.ts b/src/agents/tools/sessions-resolution.test.ts
new file mode 100644
index 00000000000..a71bd4a6b7a
--- /dev/null
+++ b/src/agents/tools/sessions-resolution.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import {
+  looksLikeSessionId,
+  looksLikeSessionKey,
+  resolveDisplaySessionKey,
+  resolveInternalSessionKey,
+  resolveMainSessionAlias,
+  shouldResolveSessionIdInput,
+} from "./sessions-resolution.js";
+
+describe("resolveMainSessionAlias", () => {
+  it("uses normalized main key and global alias for global scope", () => {
+    const cfg = {
+      session: { mainKey: " Primary ", scope: "global" },
+    } as OpenClawConfig;
+
+    expect(resolveMainSessionAlias(cfg)).toEqual({
+      mainKey: "primary",
+      alias: "global",
+      scope: "global",
+    });
+  });
+
+  it("falls back to per-sender defaults", () => {
+    expect(resolveMainSessionAlias({} as OpenClawConfig)).toEqual({
+      mainKey: "main",
+      alias: "main",
+      scope: "per-sender",
+    });
+  });
+});
+
+describe("session key display/internal mapping", () => {
+  it("maps alias and main key to display main", () => {
+    expect(resolveDisplaySessionKey({ key: "global", alias: "global", mainKey: "main" })).toBe(
+      "main",
+    );
+    expect(resolveDisplaySessionKey({ key: "main", alias: "global", mainKey: "main" })).toBe(
+      "main",
+    );
+    expect(
+      resolveDisplaySessionKey({ key: "agent:ops:main", alias: "global", mainKey: "main" }),
+    ).toBe("agent:ops:main");
+  });
+
+  it("maps input main to alias for internal routing", () => {
+    expect(resolveInternalSessionKey({ key: "main", alias: "global", mainKey: "main" })).toBe(
+      "global",
+    );
+    expect(
+      resolveInternalSessionKey({ key: "agent:ops:main", alias: "global", mainKey: "main" }),
+    ).toBe("agent:ops:main");
+  });
+});
+
+describe("session reference shape detection", () => {
+  it("detects session ids", () => {
+    expect(looksLikeSessionId("d4f5a5a1-9f75-42cf-83a6-8d170e6a1538")).toBe(true);
+    expect(looksLikeSessionId("not-a-uuid")).toBe(false);
+  });
+
+  it("detects canonical session key families", () => {
+    expect(looksLikeSessionKey("main")).toBe(true);
+    expect(looksLikeSessionKey("agent:main:main")).toBe(true);
+    expect(looksLikeSessionKey("cron:daily-report")).toBe(true);
+    expect(looksLikeSessionKey("node:macbook")).toBe(true);
+    expect(looksLikeSessionKey("telegram:group:123")).toBe(true);
+    expect(looksLikeSessionKey("random-slug")).toBe(false);
+  });
+
+  it("treats non-keys as session-id candidates", () => {
+    expect(shouldResolveSessionIdInput("agent:main:main")).toBe(false);
+    expect(shouldResolveSessionIdInput("d4f5a5a1-9f75-42cf-83a6-8d170e6a1538")).toBe(true);
+    expect(shouldResolveSessionIdInput("random-slug")).toBe(true);
+  });
+});
diff --git a/src/agents/tools/sessions-resolution.ts b/src/agents/tools/sessions-resolution.ts
new file mode 100644
index 00000000000..b3539d08d8f
--- /dev/null
+++ b/src/agents/tools/sessions-resolution.ts
@@ -0,0 +1,257 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import { callGateway } from "../../gateway/call.js";
+import { isAcpSessionKey, normalizeMainKey } from "../../routing/session-key.js";
+
+function normalizeKey(value?: string) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveMainSessionAlias(cfg: OpenClawConfig) {
+  const mainKey = normalizeMainKey(cfg.session?.mainKey);
+  const scope = cfg.session?.scope ?? "per-sender";
+  const alias = scope === "global" ? "global" : mainKey;
+  return { mainKey, alias, scope };
+}
+
+export function resolveDisplaySessionKey(params: { key: string; alias: string; mainKey: string }) {
+  if (params.key === params.alias) {
+    return "main";
+  }
+  if (params.key === params.mainKey) {
+    return "main";
+  }
+  return params.key;
+}
+
+export function resolveInternalSessionKey(params: { key: string; alias: string; mainKey: string }) {
+  if (params.key === "main") {
+    return params.alias;
+  }
+  return params.key;
+}
+
+export async function listSpawnedSessionKeys(params: {
+  requesterSessionKey: string;
+  limit?: number;
+}): Promise<Set<string>> {
+  const limit =
+    typeof params.limit === "number" && Number.isFinite(params.limit)
+      ? Math.max(1, Math.floor(params.limit))
+      : 500;
+  try {
+    const list = await callGateway<{ sessions: Array<{ key?: unknown }> }>({
+      method: "sessions.list",
+      params: {
+        includeGlobal: false,
+        includeUnknown: false,
+        limit,
+        spawnedBy: params.requesterSessionKey,
+      },
+    });
+    const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+    const keys = sessions
+      .map((entry) => (typeof entry?.key === "string" ? entry.key : ""))
+      .map((value) => value.trim())
+      .filter(Boolean);
+    return new Set(keys);
+  } catch {
+    return new Set();
+  }
+}
+
+export async function isRequesterSpawnedSessionVisible(params: {
+  requesterSessionKey: string;
+  targetSessionKey: string;
+  limit?: number;
+}): Promise<boolean> {
+  if (params.requesterSessionKey === params.targetSessionKey) {
+    return true;
+  }
+  const keys = await listSpawnedSessionKeys({
+    requesterSessionKey: params.requesterSessionKey,
+    limit: params.limit,
+  });
+  return keys.has(params.targetSessionKey);
+}
+
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function looksLikeSessionId(value: string): boolean {
+  return SESSION_ID_RE.test(value.trim());
+}
+
+export function looksLikeSessionKey(value: string): boolean {
+  const raw = value.trim();
+  if (!raw) {
+    return false;
+  }
+  // These are canonical key shapes that should never be treated as sessionIds.
+  if (raw === "main" || raw === "global" || raw === "unknown") {
+    return true;
+  }
+  if (isAcpSessionKey(raw)) {
+    return true;
+  }
+  if (raw.startsWith("agent:")) {
+    return true;
+  }
+  if (raw.startsWith("cron:") || raw.startsWith("hook:")) {
+    return true;
+  }
+  if (raw.startsWith("node-") || raw.startsWith("node:")) {
+    return true;
+  }
+  if (raw.includes(":group:") || raw.includes(":channel:")) {
+    return true;
+  }
+  return false;
+}
+
+export function shouldResolveSessionIdInput(value: string): boolean {
+  // Treat anything that doesn't look like a well-formed key as a sessionId candidate.
+  return looksLikeSessionId(value) || !looksLikeSessionKey(value);
+}
+
+export type SessionReferenceResolution =
+  | {
+      ok: true;
+      key: string;
+      displayKey: string;
+      resolvedViaSessionId: boolean;
+    }
+  | { ok: false; status: "error" | "forbidden"; error: string };
+
+async function resolveSessionKeyFromSessionId(params: {
+  sessionId: string;
+  alias: string;
+  mainKey: string;
+  requesterInternalKey?: string;
+  restrictToSpawned: boolean;
+}): Promise<SessionReferenceResolution> {
+  try {
+    // Resolve via gateway so we respect store routing and visibility rules.
+    const result = await callGateway<{ key?: string }>({
+      method: "sessions.resolve",
+      params: {
+        sessionId: params.sessionId,
+        spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
+        includeGlobal: !params.restrictToSpawned,
+        includeUnknown: !params.restrictToSpawned,
+      },
+    });
+    const key = typeof result?.key === "string" ? result.key.trim() : "";
+    if (!key) {
+      throw new Error(
+        `Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`,
+      );
+    }
+    return {
+      ok: true,
+      key,
+      displayKey: resolveDisplaySessionKey({
+        key,
+        alias: params.alias,
+        mainKey: params.mainKey,
+      }),
+      resolvedViaSessionId: true,
+    };
+  } catch (err) {
+    if (params.restrictToSpawned) {
+      return {
+        ok: false,
+        status: "forbidden",
+        error: `Session not visible from this sandboxed agent session: ${params.sessionId}`,
+      };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: "error",
+      error:
+        message ||
+        `Session not found: ${params.sessionId} (use the full sessionKey from sessions_list)`,
+    };
+  }
+}
+
+async function resolveSessionKeyFromKey(params: {
+  key: string;
+  alias: string;
+  mainKey: string;
+  requesterInternalKey?: string;
+  restrictToSpawned: boolean;
+}): Promise<SessionReferenceResolution | null> {
+  try {
+    // Try key-based resolution first so non-standard keys keep working.
+    const result = await callGateway<{ key?: string }>({
+      method: "sessions.resolve",
+      params: {
+        key: params.key,
+        spawnedBy: params.restrictToSpawned ? params.requesterInternalKey : undefined,
+      },
+    });
+    const key = typeof result?.key === "string" ? result.key.trim() : "";
+    if (!key) {
+      return null;
+    }
+    return {
+      ok: true,
+      key,
+      displayKey: resolveDisplaySessionKey({
+        key,
+        alias: params.alias,
+        mainKey: params.mainKey,
+      }),
+      resolvedViaSessionId: false,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveSessionReference(params: {
+  sessionKey: string;
+  alias: string;
+  mainKey: string;
+  requesterInternalKey?: string;
+  restrictToSpawned: boolean;
+}): Promise<SessionReferenceResolution> {
+  const raw = params.sessionKey.trim();
+  if (shouldResolveSessionIdInput(raw)) {
+    // Prefer key resolution to avoid misclassifying custom keys as sessionIds.
+    const resolvedByKey = await resolveSessionKeyFromKey({
+      key: raw,
+      alias: params.alias,
+      mainKey: params.mainKey,
+      requesterInternalKey: params.requesterInternalKey,
+      restrictToSpawned: params.restrictToSpawned,
+    });
+    if (resolvedByKey) {
+      return resolvedByKey;
+    }
+    return await resolveSessionKeyFromSessionId({
+      sessionId: raw,
+      alias: params.alias,
+      mainKey: params.mainKey,
+      requesterInternalKey: params.requesterInternalKey,
+      restrictToSpawned: params.restrictToSpawned,
+    });
+  }
+
+  const resolvedKey = resolveInternalSessionKey({
+    key: raw,
+    alias: params.alias,
+    mainKey: params.mainKey,
+  });
+  const displayKey = resolveDisplaySessionKey({
+    key: resolvedKey,
+    alias: params.alias,
+    mainKey: params.mainKey,
+  });
+  return { ok: true, key: resolvedKey, displayKey, resolvedViaSessionId: false };
+}
+
+export function normalizeOptionalKey(value?: string) {
+  return normalizeKey(value);
+}
diff --git a/src/agents/tools/sessions-send-tool.gating.e2e.test.ts b/src/agents/tools/sessions-send-tool.gating.e2e.test.ts
deleted file mode 100644
index 76a242c9898..00000000000
--- a/src/agents/tools/sessions-send-tool.gating.e2e.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const callGatewayMock = vi.fn();
-vi.mock("../../gateway/call.js", () => ({
-  callGateway: (opts: unknown) => callGatewayMock(opts),
-}));
-
-vi.mock("../../config/config.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../config/config.js")>();
-  return {
-    ...actual,
-    loadConfig: () =>
-      ({
-        session: { scope: "per-sender", mainKey: "main" },
-        tools: { agentToAgent: { enabled: false } },
-      }) as never,
-  };
-});
-
-import { createSessionsSendTool } from "./sessions-send-tool.js";
-
-describe("sessions_send gating", () => {
-  beforeEach(() => {
-    callGatewayMock.mockReset();
-  });
-
-  it("blocks cross-agent sends when tools.agentToAgent.enabled is false", async () => {
-    const tool = createSessionsSendTool({
-      agentSessionKey: "agent:main:main",
-      agentChannel: "whatsapp",
-    });
-
-    const result = await tool.execute("call1", {
-      sessionKey: "agent:other:main",
-      message: "hi",
-      timeoutSeconds: 0,
-    });
-
-    expect(callGatewayMock).not.toHaveBeenCalled();
-    expect(result.details).toMatchObject({ status: "forbidden" });
-  });
-});
diff --git a/src/agents/tools/sessions-send-tool.ts b/src/agents/tools/sessions-send-tool.ts
index e871847fb65..505201cadb4 100644
--- a/src/agents/tools/sessions-send-tool.ts
+++ b/src/agents/tools/sessions-send-tool.ts
@@ -3,11 +3,7 @@ import crypto from "node:crypto";
 import type { AnyAgentTool } from "./common.js";
 import { loadConfig } from "../../config/config.js";
 import { callGateway } from "../../gateway/call.js";
-import {
-  isSubagentSessionKey,
-  normalizeAgentId,
-  resolveAgentIdFromSessionKey,
-} from "../../routing/session-key.js";
+import { normalizeAgentId, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
 import { SESSION_LABEL_MAX_LENGTH } from "../../sessions/session-label.js";
 import {
   type GatewayMessageChannel,
@@ -16,11 +12,13 @@ import {
 import { AGENT_LANE_NESTED } from "../lanes.js";
 import { jsonResult, readStringParam } from "./common.js";
 import {
+  createSessionVisibilityGuard,
   createAgentToAgentPolicy,
   extractAssistantText,
-  resolveInternalSessionKey,
-  resolveMainSessionAlias,
+  isRequesterSpawnedSessionVisible,
+  resolveEffectiveSessionToolsVisibility,
   resolveSessionReference,
+  resolveSandboxedSessionToolContext,
   stripToolMessages,
 } from "./sessions-helpers.js";
 import { buildAgentToAgentMessageContext, resolvePingPongTurns } from "./sessions-send-helpers.js";
@@ -49,23 +47,18 @@ export function createSessionsSendTool(opts?: {
       const params = args as Record<string, unknown>;
       const message = readStringParam(params, "message", { required: true });
       const cfg = loadConfig();
-      const { mainKey, alias } = resolveMainSessionAlias(cfg);
-      const visibility = cfg.agents?.defaults?.sandbox?.sessionToolsVisibility ?? "spawned";
-      const requesterInternalKey =
-        typeof opts?.agentSessionKey === "string" && opts.agentSessionKey.trim()
-          ? resolveInternalSessionKey({
-              key: opts.agentSessionKey,
-              alias,
-              mainKey,
-            })
-          : undefined;
-      const restrictToSpawned =
-        opts?.sandboxed === true &&
-        visibility === "spawned" &&
-        !!requesterInternalKey &&
-        !isSubagentSessionKey(requesterInternalKey);
+      const { mainKey, alias, effectiveRequesterKey, restrictToSpawned } =
+        resolveSandboxedSessionToolContext({
+          cfg,
+          agentSessionKey: opts?.agentSessionKey,
+          sandboxed: opts?.sandboxed,
+        });
 
       const a2aPolicy = createAgentToAgentPolicy(cfg);
+      const sessionVisibility = resolveEffectiveSessionToolsVisibility({
+        cfg,
+        sandboxed: opts?.sandboxed === true,
+      });
 
       const sessionKeyParam = readStringParam(params, "sessionKey");
       const labelParam = readStringParam(params, "label")?.trim() || undefined;
@@ -78,30 +71,14 @@ export function createSessionsSendTool(opts?: {
         });
       }
 
-      const listSessions = async (listParams: Record<string, unknown>) => {
-        const result = await callGateway<{ sessions: Array<{ key: string }> }>({
-          method: "sessions.list",
-          params: listParams,
-          timeoutMs: 10_000,
-        });
-        return Array.isArray(result?.sessions) ? result.sessions : [];
-      };
-
       let sessionKey = sessionKeyParam;
       if (!sessionKey && labelParam) {
-        const requesterAgentId = requesterInternalKey
-          ? resolveAgentIdFromSessionKey(requesterInternalKey)
-          : undefined;
+        const requesterAgentId = resolveAgentIdFromSessionKey(effectiveRequesterKey);
         const requestedAgentId = labelAgentIdParam
           ? normalizeAgentId(labelAgentIdParam)
           : undefined;
 
-        if (
-          restrictToSpawned &&
-          requestedAgentId &&
-          requesterAgentId &&
-          requestedAgentId !== requesterAgentId
-        ) {
+        if (restrictToSpawned && requestedAgentId && requestedAgentId !== requesterAgentId) {
           return jsonResult({
             runId: crypto.randomUUID(),
             status: "forbidden",
@@ -130,7 +107,7 @@ export function createSessionsSendTool(opts?: {
         const resolveParams: Record<string, unknown> = {
           label: labelParam,
           ...(requestedAgentId ? { agentId: requestedAgentId } : {}),
-          ...(restrictToSpawned ? { spawnedBy: requesterInternalKey } : {}),
+          ...(restrictToSpawned ? { spawnedBy: effectiveRequesterKey } : {}),
         };
         let resolvedKey = "";
         try {
@@ -184,7 +161,7 @@ export function createSessionsSendTool(opts?: {
         sessionKey,
         alias,
         mainKey,
-        requesterInternalKey,
+        requesterInternalKey: effectiveRequesterKey,
         restrictToSpawned,
       });
       if (!resolvedSession.ok) {
@@ -199,14 +176,11 @@ export function createSessionsSendTool(opts?: {
       const displayKey = resolvedSession.displayKey;
       const resolvedViaSessionId = resolvedSession.resolvedViaSessionId;
 
-      if (restrictToSpawned && !resolvedViaSessionId) {
-        const sessions = await listSessions({
-          includeGlobal: false,
-          includeUnknown: false,
-          limit: 500,
-          spawnedBy: requesterInternalKey,
+      if (restrictToSpawned && !resolvedViaSessionId && resolvedKey !== effectiveRequesterKey) {
+        const ok = await isRequesterSpawnedSessionVisible({
+          requesterSessionKey: effectiveRequesterKey,
+          targetSessionKey: resolvedKey,
         });
-        const ok = sessions.some((entry) => entry?.key === resolvedKey);
         if (!ok) {
           return jsonResult({
             runId: crypto.randomUUID(),
@@ -224,27 +198,20 @@ export function createSessionsSendTool(opts?: {
       const announceTimeoutMs = timeoutSeconds === 0 ? 30_000 : timeoutMs;
       const idempotencyKey = crypto.randomUUID();
       let runId: string = idempotencyKey;
-      const requesterAgentId = resolveAgentIdFromSessionKey(requesterInternalKey);
-      const targetAgentId = resolveAgentIdFromSessionKey(resolvedKey);
-      const isCrossAgent = requesterAgentId !== targetAgentId;
-      if (isCrossAgent) {
-        if (!a2aPolicy.enabled) {
-          return jsonResult({
-            runId: crypto.randomUUID(),
-            status: "forbidden",
-            error:
-              "Agent-to-agent messaging is disabled. Set tools.agentToAgent.enabled=true to allow cross-agent sends.",
-            sessionKey: displayKey,
-          });
-        }
-        if (!a2aPolicy.isAllowed(requesterAgentId, targetAgentId)) {
-          return jsonResult({
-            runId: crypto.randomUUID(),
-            status: "forbidden",
-            error: "Agent-to-agent messaging denied by tools.agentToAgent.allow.",
-            sessionKey: displayKey,
-          });
-        }
+      const visibilityGuard = await createSessionVisibilityGuard({
+        action: "send",
+        requesterSessionKey: effectiveRequesterKey,
+        visibility: sessionVisibility,
+        a2aPolicy,
+      });
+      const access = visibilityGuard.check(resolvedKey);
+      if (!access.allowed) {
+        return jsonResult({
+          runId: crypto.randomUUID(),
+          status: access.status,
+          error: access.error,
+          sessionKey: displayKey,
+        });
       }
 
       const agentMessageContext = buildAgentToAgentMessageContext({
diff --git a/src/agents/tools/sessions-spawn-tool.ts b/src/agents/tools/sessions-spawn-tool.ts
index 11486c025e3..867aa85c9d9 100644
--- a/src/agents/tools/sessions-spawn-tool.ts
+++ b/src/agents/tools/sessions-spawn-tool.ts
@@ -28,6 +28,8 @@ const SessionsSpawnToolSchema = Type.Object({
   model: Type.Optional(Type.String()),
   thinking: Type.Optional(Type.String()),
   runTimeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
+  // Back-compat: older callers used timeoutSeconds for this tool.
+  timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
   cleanup: optionalStringEnum(["delete", "keep"] as const),
 });
 
@@ -97,9 +99,15 @@ export function createSessionsSpawnTool(opts?: {
       });
       // Default to 0 (no timeout) when omitted. Sub-agent runs are long-lived
       // by default and should not inherit the main agent 600s timeout.
+      const timeoutSecondsCandidate =
+        typeof params.runTimeoutSeconds === "number"
+          ? params.runTimeoutSeconds
+          : typeof params.timeoutSeconds === "number"
+            ? params.timeoutSeconds
+            : undefined;
       const runTimeoutSeconds =
-        typeof params.runTimeoutSeconds === "number" && Number.isFinite(params.runTimeoutSeconds)
-          ? Math.max(0, Math.floor(params.runTimeoutSeconds))
+        typeof timeoutSecondsCandidate === "number" && Number.isFinite(timeoutSecondsCandidate)
+          ? Math.max(0, Math.floor(timeoutSecondsCandidate))
           : 0;
       let modelWarning: string | undefined;
       let modelApplied = false;
diff --git a/src/agents/tools/sessions.e2e.test.ts b/src/agents/tools/sessions.e2e.test.ts
new file mode 100644
index 00000000000..4e3d6a55652
--- /dev/null
+++ b/src/agents/tools/sessions.e2e.test.ts
@@ -0,0 +1,220 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
+import { extractAssistantText, sanitizeTextContent } from "./sessions-helpers.js";
+
+const callGatewayMock = vi.fn();
+vi.mock("../../gateway/call.js", () => ({
+  callGateway: (opts: unknown) => callGatewayMock(opts),
+}));
+
+vi.mock("../../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () =>
+      ({
+        session: { scope: "per-sender", mainKey: "main" },
+        tools: { agentToAgent: { enabled: false } },
+      }) as never,
+  };
+});
+
+import { createSessionsListTool } from "./sessions-list-tool.js";
+import { createSessionsSendTool } from "./sessions-send-tool.js";
+
+const loadResolveAnnounceTarget = async () => await import("./sessions-announce-target.js");
+
+const installRegistry = async () => {
+  const { setActivePluginRegistry } = await import("../../plugins/runtime.js");
+  setActivePluginRegistry(
+    createTestRegistry([
+      {
+        pluginId: "discord",
+        source: "test",
+        plugin: {
+          id: "discord",
+          meta: {
+            id: "discord",
+            label: "Discord",
+            selectionLabel: "Discord",
+            docsPath: "/channels/discord",
+            blurb: "Discord test stub.",
+          },
+          capabilities: { chatTypes: ["direct", "channel", "thread"] },
+          config: {
+            listAccountIds: () => ["default"],
+            resolveAccount: () => ({}),
+          },
+        },
+      },
+      {
+        pluginId: "whatsapp",
+        source: "test",
+        plugin: {
+          id: "whatsapp",
+          meta: {
+            id: "whatsapp",
+            label: "WhatsApp",
+            selectionLabel: "WhatsApp",
+            docsPath: "/channels/whatsapp",
+            blurb: "WhatsApp test stub.",
+            preferSessionLookupForAnnounceTarget: true,
+          },
+          capabilities: { chatTypes: ["direct", "group"] },
+          config: {
+            listAccountIds: () => ["default"],
+            resolveAccount: () => ({}),
+          },
+        },
+      },
+    ]),
+  );
+};
+
+describe("sanitizeTextContent", () => {
+  it("strips minimax tool call XML and downgraded markers", () => {
+    const input =
+      'Hello <invoke name="tool">payload</invoke></minimax:tool_call> ' +
+      "[Tool Call: foo (ID: 1)] world";
+    const result = sanitizeTextContent(input).trim();
+    expect(result).toBe("Hello  world");
+    expect(result).not.toContain("invoke");
+    expect(result).not.toContain("Tool Call");
+  });
+
+  it("strips thinking tags", () => {
+    const input = "Before <think>secret</think> after";
+    const result = sanitizeTextContent(input).trim();
+    expect(result).toBe("Before  after");
+  });
+});
+
+describe("extractAssistantText", () => {
+  it("sanitizes blocks without injecting newlines", () => {
+    const message = {
+      role: "assistant",
+      content: [
+        { type: "text", text: "Hi " },
+        { type: "text", text: "<think>secret</think>there" },
+      ],
+    };
+    expect(extractAssistantText(message)).toBe("Hi there");
+  });
+
+  it("rewrites error-ish assistant text only when the transcript marks it as an error", () => {
+    const message = {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "500 Internal Server Error",
+      content: [{ type: "text", text: "500 Internal Server Error" }],
+    };
+    expect(extractAssistantText(message)).toBe("HTTP 500: Internal Server Error");
+  });
+
+  it("keeps normal status text that mentions billing", () => {
+    const message = {
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: "Firebase downgraded us to the free Spark plan. Check whether billing should be re-enabled.",
+        },
+      ],
+    };
+    expect(extractAssistantText(message)).toBe(
+      "Firebase downgraded us to the free Spark plan. Check whether billing should be re-enabled.",
+    );
+  });
+});
+
+describe("resolveAnnounceTarget", () => {
+  beforeEach(async () => {
+    callGatewayMock.mockReset();
+    await installRegistry();
+  });
+
+  it("derives non-WhatsApp announce targets from the session key", async () => {
+    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
+    const target = await resolveAnnounceTarget({
+      sessionKey: "agent:main:discord:group:dev",
+      displayKey: "agent:main:discord:group:dev",
+    });
+    expect(target).toEqual({ channel: "discord", to: "channel:dev" });
+    expect(callGatewayMock).not.toHaveBeenCalled();
+  });
+
+  it("hydrates WhatsApp accountId from sessions.list when available", async () => {
+    const { resolveAnnounceTarget } = await loadResolveAnnounceTarget();
+    callGatewayMock.mockResolvedValueOnce({
+      sessions: [
+        {
+          key: "agent:main:whatsapp:group:123@g.us",
+          deliveryContext: {
+            channel: "whatsapp",
+            to: "123@g.us",
+            accountId: "work",
+          },
+        },
+      ],
+    });
+
+    const target = await resolveAnnounceTarget({
+      sessionKey: "agent:main:whatsapp:group:123@g.us",
+      displayKey: "agent:main:whatsapp:group:123@g.us",
+    });
+    expect(target).toEqual({
+      channel: "whatsapp",
+      to: "123@g.us",
+      accountId: "work",
+    });
+    expect(callGatewayMock).toHaveBeenCalledTimes(1);
+    const first = callGatewayMock.mock.calls[0]?.[0] as { method?: string } | undefined;
+    expect(first).toBeDefined();
+    expect(first?.method).toBe("sessions.list");
+  });
+});
+
+describe("sessions_list gating", () => {
+  beforeEach(() => {
+    callGatewayMock.mockReset();
+    callGatewayMock.mockResolvedValue({
+      path: "/tmp/sessions.json",
+      sessions: [
+        { key: "agent:main:main", kind: "direct" },
+        { key: "agent:other:main", kind: "direct" },
+      ],
+    });
+  });
+
+  it("filters out other agents when tools.agentToAgent.enabled is false", async () => {
+    const tool = createSessionsListTool({ agentSessionKey: "agent:main:main" });
+    const result = await tool.execute("call1", {});
+    expect(result.details).toMatchObject({
+      count: 1,
+      sessions: [{ key: "agent:main:main" }],
+    });
+  });
+});
+
+describe("sessions_send gating", () => {
+  beforeEach(() => {
+    callGatewayMock.mockReset();
+  });
+
+  it("blocks cross-agent sends when tools.agentToAgent.enabled is false", async () => {
+    const tool = createSessionsSendTool({
+      agentSessionKey: "agent:main:main",
+      agentChannel: "whatsapp",
+    });
+
+    const result = await tool.execute("call1", {
+      sessionKey: "agent:other:main",
+      message: "hi",
+      timeoutSeconds: 0,
+    });
+
+    expect(callGatewayMock).toHaveBeenCalledTimes(1);
+    expect(callGatewayMock.mock.calls[0]?.[0]).toMatchObject({ method: "sessions.list" });
+    expect(result.details).toMatchObject({ status: "forbidden" });
+  });
+});
diff --git a/src/agents/tools/subagents-tool.ts b/src/agents/tools/subagents-tool.ts
index 1eafeeb7971..803b80631cb 100644
--- a/src/agents/tools/subagents-tool.ts
+++ b/src/agents/tools/subagents-tool.ts
@@ -413,71 +413,43 @@ export function createSubagentsTool(opts?: { agentSessionKey?: string }): AnyAge
         const cache = new Map<string, Record<string, SessionEntry>>();
 
         let index = 1;
+        const buildListEntry = (entry: SubagentRunRecord, runtimeMs: number) => {
+          const sessionEntry = resolveSessionEntryForKey({
+            cfg,
+            key: entry.childSessionKey,
+            cache,
+          }).entry;
+          const totalTokens = resolveTotalTokens(sessionEntry);
+          const usageText = formatTokenUsageDisplay(sessionEntry);
+          const status = resolveRunStatus(entry);
+          const runtime = formatDurationCompact(runtimeMs);
+          const label = truncateLine(resolveRunLabel(entry), 48);
+          const task = truncateLine(entry.task.trim(), 72);
+          const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
+          const baseView = {
+            index,
+            runId: entry.runId,
+            sessionKey: entry.childSessionKey,
+            label,
+            task,
+            status,
+            runtime,
+            runtimeMs,
+            model: resolveModelRef(sessionEntry) || entry.model,
+            totalTokens,
+            startedAt: entry.startedAt,
+          };
+          index += 1;
+          return { line, view: entry.endedAt ? { ...baseView, endedAt: entry.endedAt } : baseView };
+        };
         const active = runs
           .filter((entry) => !entry.endedAt)
-          .map((entry) => {
-            const sessionEntry = resolveSessionEntryForKey({
-              cfg,
-              key: entry.childSessionKey,
-              cache,
-            }).entry;
-            const totalTokens = resolveTotalTokens(sessionEntry);
-            const usageText = formatTokenUsageDisplay(sessionEntry);
-            const status = resolveRunStatus(entry);
-            const runtime = formatDurationCompact(now - (entry.startedAt ?? entry.createdAt));
-            const label = truncateLine(resolveRunLabel(entry), 48);
-            const task = truncateLine(entry.task.trim(), 72);
-            const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
-            const view = {
-              index,
-              runId: entry.runId,
-              sessionKey: entry.childSessionKey,
-              label,
-              task,
-              status,
-              runtime,
-              runtimeMs: now - (entry.startedAt ?? entry.createdAt),
-              model: resolveModelRef(sessionEntry) || entry.model,
-              totalTokens,
-              startedAt: entry.startedAt,
-            };
-            index += 1;
-            return { line, view };
-          });
+          .map((entry) => buildListEntry(entry, now - (entry.startedAt ?? entry.createdAt)));
         const recent = runs
           .filter((entry) => !!entry.endedAt && (entry.endedAt ?? 0) >= recentCutoff)
-          .map((entry) => {
-            const sessionEntry = resolveSessionEntryForKey({
-              cfg,
-              key: entry.childSessionKey,
-              cache,
-            }).entry;
-            const totalTokens = resolveTotalTokens(sessionEntry);
-            const usageText = formatTokenUsageDisplay(sessionEntry);
-            const status = resolveRunStatus(entry);
-            const runtime = formatDurationCompact(
-              (entry.endedAt ?? now) - (entry.startedAt ?? entry.createdAt),
-            );
-            const label = truncateLine(resolveRunLabel(entry), 48);
-            const task = truncateLine(entry.task.trim(), 72);
-            const line = `${index}. ${label} (${resolveModelDisplay(sessionEntry, entry.model)}, ${runtime}${usageText ? `, ${usageText}` : ""}) ${status}${task.toLowerCase() !== label.toLowerCase() ? ` - ${task}` : ""}`;
-            const view = {
-              index,
-              runId: entry.runId,
-              sessionKey: entry.childSessionKey,
-              label,
-              task,
-              status,
-              runtime,
-              runtimeMs: (entry.endedAt ?? now) - (entry.startedAt ?? entry.createdAt),
-              model: resolveModelRef(sessionEntry) || entry.model,
-              totalTokens,
-              startedAt: entry.startedAt,
-              endedAt: entry.endedAt,
-            };
-            index += 1;
-            return { line, view };
-          });
+          .map((entry) =>
+            buildListEntry(entry, (entry.endedAt ?? now) - (entry.startedAt ?? entry.createdAt)),
+          );
 
         const text = buildListText({ active, recent, recentMinutes });
         return jsonResult({
diff --git a/src/agents/tools/web-fetch-utils.ts b/src/agents/tools/web-fetch-utils.ts
index 09716e2cd46..a9ef9d5ba45 100644
--- a/src/agents/tools/web-fetch-utils.ts
+++ b/src/agents/tools/web-fetch-utils.ts
@@ -1,5 +1,8 @@
 export type ExtractMode = "markdown" | "text";
 
+const READABILITY_MAX_HTML_CHARS = 1_000_000;
+const READABILITY_MAX_ESTIMATED_NESTING_DEPTH = 3_000;
+
 let readabilityDepsPromise:
   | Promise<{
       Readability: typeof import("@mozilla/readability").Readability;
@@ -107,6 +110,100 @@ export function truncateText(
   return { text: value.slice(0, maxChars), truncated: true };
 }
 
+function exceedsEstimatedHtmlNestingDepth(html: string, maxDepth: number): boolean {
+  // Cheap heuristic to skip Readability+DOM parsing on pathological HTML (deep nesting => stack/memory blowups).
+  // Not an HTML parser; tuned to catch attacker-controlled "<div><div>..." cases.
+  const voidTags = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+  ]);
+
+  let depth = 0;
+  const len = html.length;
+  for (let i = 0; i < len; i++) {
+    if (html.charCodeAt(i) !== 60) {
+      continue; // '<'
+    }
+    const next = html.charCodeAt(i + 1);
+    if (next === 33 || next === 63) {
+      continue; // <! ...> or <? ...>
+    }
+
+    let j = i + 1;
+    let closing = false;
+    if (html.charCodeAt(j) === 47) {
+      closing = true;
+      j += 1;
+    }
+
+    while (j < len && html.charCodeAt(j) <= 32) {
+      j += 1;
+    }
+
+    const nameStart = j;
+    while (j < len) {
+      const c = html.charCodeAt(j);
+      const isNameChar =
+        (c >= 65 && c <= 90) || // A-Z
+        (c >= 97 && c <= 122) || // a-z
+        (c >= 48 && c <= 57) || // 0-9
+        c === 58 || // :
+        c === 45; // -
+      if (!isNameChar) {
+        break;
+      }
+      j += 1;
+    }
+
+    const tagName = html.slice(nameStart, j).toLowerCase();
+    if (!tagName) {
+      continue;
+    }
+
+    if (closing) {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    if (voidTags.has(tagName)) {
+      continue;
+    }
+
+    // Best-effort self-closing detection: scan a short window for "/>".
+    let selfClosing = false;
+    for (let k = j; k < len && k < j + 200; k++) {
+      const c = html.charCodeAt(k);
+      if (c === 62) {
+        if (html.charCodeAt(k - 1) === 47) {
+          selfClosing = true;
+        }
+        break;
+      }
+    }
+    if (selfClosing) {
+      continue;
+    }
+
+    depth += 1;
+    if (depth > maxDepth) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export async function extractReadableContent(params: {
   html: string;
   url: string;
@@ -120,6 +217,12 @@ export async function extractReadableContent(params: {
     }
     return rendered;
   };
+  if (
+    params.html.length > READABILITY_MAX_HTML_CHARS ||
+    exceedsEstimatedHtmlNestingDepth(params.html, READABILITY_MAX_ESTIMATED_NESTING_DEPTH)
+  ) {
+    return fallback();
+  }
   try {
     const { Readability, parseHTML } = await loadReadabilityDeps();
     const { document } = parseHTML(params.html);
diff --git a/src/agents/tools/web-fetch.response-limit.test.ts b/src/agents/tools/web-fetch.response-limit.test.ts
new file mode 100644
index 00000000000..2755fd0b1c7
--- /dev/null
+++ b/src/agents/tools/web-fetch.response-limit.test.ts
@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as ssrf from "../../infra/net/ssrf.js";
+import { createWebFetchTool } from "./web-tools.js";
+
+// Avoid dynamic-importing heavy readability deps in this unit test suite.
+vi.mock("./web-fetch-utils.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("./web-fetch-utils.js")>("./web-fetch-utils.js");
+  return {
+    ...actual,
+    extractReadableContent: vi.fn().mockResolvedValue({
+      title: "HTML Page",
+      text: "HTML Page\n\nContent here.",
+    }),
+  };
+});
+
+const lookupMock = vi.fn();
+const resolvePinnedHostname = ssrf.resolvePinnedHostname;
+const baseToolConfig = {
+  config: {
+    tools: {
+      web: { fetch: { cacheTtlMinutes: 0, firecrawl: { enabled: false }, maxResponseBytes: 1024 } },
+    },
+  },
+} as const;
+
+describe("web_fetch response size limits", () => {
+  const priorFetch = global.fetch;
+
+  beforeEach(() => {
+    lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }]);
+    vi.spyOn(ssrf, "resolvePinnedHostname").mockImplementation((hostname) =>
+      resolvePinnedHostname(hostname, lookupMock),
+    );
+  });
+
+  afterEach(() => {
+    // @ts-expect-error restore
+    global.fetch = priorFetch;
+    lookupMock.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  it("caps response bytes and does not hang on endless streams", async () => {
+    const chunk = new TextEncoder().encode("<html><body><div>hi</div></body></html>");
+    const stream = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        controller.enqueue(chunk);
+      },
+    });
+    const response = new Response(stream, {
+      status: 200,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+
+    const fetchSpy = vi.fn().mockResolvedValue(response);
+    // @ts-expect-error mock fetch
+    global.fetch = fetchSpy;
+
+    const tool = createWebFetchTool(baseToolConfig);
+    const result = await tool?.execute?.("call", { url: "https://example.com/stream" });
+
+    expect(result?.details?.warning).toContain("Response body truncated");
+  });
+});
diff --git a/src/agents/tools/web-fetch.ts b/src/agents/tools/web-fetch.ts
index a703aa54f3a..fdb5ade5172 100644
--- a/src/agents/tools/web-fetch.ts
+++ b/src/agents/tools/web-fetch.ts
@@ -33,8 +33,12 @@ export { extractReadableContent } from "./web-fetch-utils.js";
 const EXTRACT_MODES = ["markdown", "text"] as const;
 
 const DEFAULT_FETCH_MAX_CHARS = 50_000;
+const DEFAULT_FETCH_MAX_RESPONSE_BYTES = 2_000_000;
+const FETCH_MAX_RESPONSE_BYTES_MIN = 32_000;
+const FETCH_MAX_RESPONSE_BYTES_MAX = 10_000_000;
 const DEFAULT_FETCH_MAX_REDIRECTS = 3;
 const DEFAULT_ERROR_MAX_CHARS = 4_000;
+const DEFAULT_ERROR_MAX_BYTES = 64_000;
 const DEFAULT_FIRECRAWL_BASE_URL = "https://api.firecrawl.dev";
 const DEFAULT_FIRECRAWL_MAX_AGE_MS = 172_800_000;
 const DEFAULT_FETCH_USER_AGENT =
@@ -108,6 +112,18 @@ function resolveFetchMaxCharsCap(fetch?: WebFetchConfig): number {
   return Math.max(100, Math.floor(raw));
 }
 
+function resolveFetchMaxResponseBytes(fetch?: WebFetchConfig): number {
+  const raw =
+    fetch && "maxResponseBytes" in fetch && typeof fetch.maxResponseBytes === "number"
+      ? fetch.maxResponseBytes
+      : undefined;
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+    return DEFAULT_FETCH_MAX_RESPONSE_BYTES;
+  }
+  const value = Math.floor(raw);
+  return Math.min(FETCH_MAX_RESPONSE_BYTES_MAX, Math.max(FETCH_MAX_RESPONSE_BYTES_MIN, value));
+}
+
 function resolveFirecrawlConfig(fetch?: WebFetchConfig): FirecrawlFetchConfig {
   if (!fetch || typeof fetch !== "object") {
     return undefined;
@@ -409,15 +425,7 @@ export async function fetchFirecrawlContent(params: {
   };
 }
 
-async function runWebFetch(params: {
-  url: string;
-  extractMode: ExtractMode;
-  maxChars: number;
-  maxRedirects: number;
-  timeoutSeconds: number;
-  cacheTtlMs: number;
-  userAgent: string;
-  readabilityEnabled: boolean;
+type FirecrawlRuntimeParams = {
   firecrawlEnabled: boolean;
   firecrawlApiKey?: string;
   firecrawlBaseUrl: string;
@@ -426,7 +434,72 @@ async function runWebFetch(params: {
   firecrawlProxy: "auto" | "basic" | "stealth";
   firecrawlStoreInCache: boolean;
   firecrawlTimeoutSeconds: number;
-}): Promise<Record<string, unknown>> {
+};
+
+type WebFetchRuntimeParams = FirecrawlRuntimeParams & {
+  url: string;
+  extractMode: ExtractMode;
+  maxChars: number;
+  maxResponseBytes: number;
+  maxRedirects: number;
+  timeoutSeconds: number;
+  cacheTtlMs: number;
+  userAgent: string;
+  readabilityEnabled: boolean;
+};
+
+function toFirecrawlContentParams(
+  params: FirecrawlRuntimeParams & { url: string; extractMode: ExtractMode },
+): Parameters<typeof fetchFirecrawlContent>[0] | null {
+  if (!params.firecrawlEnabled || !params.firecrawlApiKey) {
+    return null;
+  }
+  return {
+    url: params.url,
+    extractMode: params.extractMode,
+    apiKey: params.firecrawlApiKey,
+    baseUrl: params.firecrawlBaseUrl,
+    onlyMainContent: params.firecrawlOnlyMainContent,
+    maxAgeMs: params.firecrawlMaxAgeMs,
+    proxy: params.firecrawlProxy,
+    storeInCache: params.firecrawlStoreInCache,
+    timeoutSeconds: params.firecrawlTimeoutSeconds,
+  };
+}
+
+async function maybeFetchFirecrawlWebFetchPayload(
+  params: WebFetchRuntimeParams & {
+    urlToFetch: string;
+    finalUrlFallback: string;
+    statusFallback: number;
+    cacheKey: string;
+    tookMs: number;
+  },
+): Promise<Record<string, unknown> | null> {
+  const firecrawlParams = toFirecrawlContentParams({
+    ...params,
+    url: params.urlToFetch,
+    extractMode: params.extractMode,
+  });
+  if (!firecrawlParams) {
+    return null;
+  }
+
+  const firecrawl = await fetchFirecrawlContent(firecrawlParams);
+  const payload = buildFirecrawlWebFetchPayload({
+    firecrawl,
+    rawUrl: params.url,
+    finalUrlFallback: params.finalUrlFallback,
+    statusFallback: params.statusFallback,
+    extractMode: params.extractMode,
+    maxChars: params.maxChars,
+    tookMs: params.tookMs,
+  });
+  writeCache(FETCH_CACHE, params.cacheKey, payload, params.cacheTtlMs);
+  return payload;
+}
+
+async function runWebFetch(params: WebFetchRuntimeParams): Promise<Record<string, unknown>> {
   const cacheKey = normalizeCacheKey(
     `fetch:${params.url}:${params.extractMode}:${params.maxChars}`,
   );
@@ -477,28 +550,15 @@ async function runWebFetch(params: {
     if (error instanceof SsrFBlockedError) {
       throw error;
     }
-    if (params.firecrawlEnabled && params.firecrawlApiKey) {
-      const firecrawl = await fetchFirecrawlContent({
-        url: finalUrl,
-        extractMode: params.extractMode,
-        apiKey: params.firecrawlApiKey,
-        baseUrl: params.firecrawlBaseUrl,
-        onlyMainContent: params.firecrawlOnlyMainContent,
-        maxAgeMs: params.firecrawlMaxAgeMs,
-        proxy: params.firecrawlProxy,
-        storeInCache: params.firecrawlStoreInCache,
-        timeoutSeconds: params.firecrawlTimeoutSeconds,
-      });
-      const payload = buildFirecrawlWebFetchPayload({
-        firecrawl,
-        rawUrl: params.url,
-        finalUrlFallback: finalUrl,
-        statusFallback: 200,
-        extractMode: params.extractMode,
-        maxChars: params.maxChars,
-        tookMs: Date.now() - start,
-      });
-      writeCache(FETCH_CACHE, cacheKey, payload, params.cacheTtlMs);
+    const payload = await maybeFetchFirecrawlWebFetchPayload({
+      ...params,
+      urlToFetch: finalUrl,
+      finalUrlFallback: finalUrl,
+      statusFallback: 200,
+      cacheKey,
+      tookMs: Date.now() - start,
+    });
+    if (payload) {
       return payload;
     }
     throw error;
@@ -506,31 +566,19 @@ async function runWebFetch(params: {
 
   try {
     if (!res.ok) {
-      if (params.firecrawlEnabled && params.firecrawlApiKey) {
-        const firecrawl = await fetchFirecrawlContent({
-          url: params.url,
-          extractMode: params.extractMode,
-          apiKey: params.firecrawlApiKey,
-          baseUrl: params.firecrawlBaseUrl,
-          onlyMainContent: params.firecrawlOnlyMainContent,
-          maxAgeMs: params.firecrawlMaxAgeMs,
-          proxy: params.firecrawlProxy,
-          storeInCache: params.firecrawlStoreInCache,
-          timeoutSeconds: params.firecrawlTimeoutSeconds,
-        });
-        const payload = buildFirecrawlWebFetchPayload({
-          firecrawl,
-          rawUrl: params.url,
-          finalUrlFallback: finalUrl,
-          statusFallback: res.status,
-          extractMode: params.extractMode,
-          maxChars: params.maxChars,
-          tookMs: Date.now() - start,
-        });
-        writeCache(FETCH_CACHE, cacheKey, payload, params.cacheTtlMs);
+      const payload = await maybeFetchFirecrawlWebFetchPayload({
+        ...params,
+        urlToFetch: params.url,
+        finalUrlFallback: finalUrl,
+        statusFallback: res.status,
+        cacheKey,
+        tookMs: Date.now() - start,
+      });
+      if (payload) {
         return payload;
       }
-      const rawDetail = await readResponseText(res);
+      const rawDetailResult = await readResponseText(res, { maxBytes: DEFAULT_ERROR_MAX_BYTES });
+      const rawDetail = rawDetailResult.text;
       const detail = formatWebFetchErrorDetail({
         detail: rawDetail,
         contentType: res.headers.get("content-type"),
@@ -542,7 +590,11 @@ async function runWebFetch(params: {
 
     const contentType = res.headers.get("content-type") ?? "application/octet-stream";
     const normalizedContentType = normalizeContentType(contentType) ?? "application/octet-stream";
-    const body = await readResponseText(res);
+    const bodyResult = await readResponseText(res, { maxBytes: params.maxResponseBytes });
+    const body = bodyResult.text;
+    const responseTruncatedWarning = bodyResult.truncated
+      ? `Response body truncated after ${params.maxResponseBytes} bytes.`
+      : undefined;
 
     let title: string | undefined;
     let extractor = "raw";
@@ -593,6 +645,7 @@ async function runWebFetch(params: {
 
     const wrapped = wrapWebFetchContent(text, params.maxChars);
     const wrappedTitle = title ? wrapWebFetchField(title) : undefined;
+    const wrappedWarning = wrapWebFetchField(responseTruncatedWarning);
     const payload = {
       url: params.url, // Keep raw for tool chaining
       finalUrl, // Keep raw
@@ -613,6 +666,7 @@ async function runWebFetch(params: {
       fetchedAt: new Date().toISOString(),
       tookMs: Date.now() - start,
       text: wrapped.text,
+      warning: wrappedWarning,
     };
     writeCache(FETCH_CACHE, cacheKey, payload, params.cacheTtlMs);
     return payload;
@@ -623,33 +677,15 @@ async function runWebFetch(params: {
   }
 }
 
-async function tryFirecrawlFallback(params: {
-  url: string;
-  extractMode: ExtractMode;
-  firecrawlEnabled: boolean;
-  firecrawlApiKey?: string;
-  firecrawlBaseUrl: string;
-  firecrawlOnlyMainContent: boolean;
-  firecrawlMaxAgeMs: number;
-  firecrawlProxy: "auto" | "basic" | "stealth";
-  firecrawlStoreInCache: boolean;
-  firecrawlTimeoutSeconds: number;
-}): Promise<{ text: string; title?: string } | null> {
-  if (!params.firecrawlEnabled || !params.firecrawlApiKey) {
+async function tryFirecrawlFallback(
+  params: FirecrawlRuntimeParams & { url: string; extractMode: ExtractMode },
+): Promise<{ text: string; title?: string } | null> {
+  const firecrawlParams = toFirecrawlContentParams(params);
+  if (!firecrawlParams) {
     return null;
   }
   try {
-    const firecrawl = await fetchFirecrawlContent({
-      url: params.url,
-      extractMode: params.extractMode,
-      apiKey: params.firecrawlApiKey,
-      baseUrl: params.firecrawlBaseUrl,
-      onlyMainContent: params.firecrawlOnlyMainContent,
-      maxAgeMs: params.firecrawlMaxAgeMs,
-      proxy: params.firecrawlProxy,
-      storeInCache: params.firecrawlStoreInCache,
-      timeoutSeconds: params.firecrawlTimeoutSeconds,
-    });
+    const firecrawl = await fetchFirecrawlContent(firecrawlParams);
     return { text: firecrawl.text, title: firecrawl.title };
   } catch {
     return null;
@@ -695,6 +731,7 @@ export function createWebFetchTool(options?: {
   const userAgent =
     (fetch && "userAgent" in fetch && typeof fetch.userAgent === "string" && fetch.userAgent) ||
     DEFAULT_FETCH_USER_AGENT;
+  const maxResponseBytes = resolveFetchMaxResponseBytes(fetch);
   return {
     label: "Web Fetch",
     name: "web_fetch",
@@ -715,6 +752,7 @@ export function createWebFetchTool(options?: {
           DEFAULT_FETCH_MAX_CHARS,
           maxCharsCap,
         ),
+        maxResponseBytes,
         maxRedirects: resolveMaxRedirects(fetch?.maxRedirects, DEFAULT_FETCH_MAX_REDIRECTS),
         timeoutSeconds: resolveTimeoutSeconds(fetch?.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS),
         cacheTtlMs: resolveCacheTtlMs(fetch?.cacheTtlMinutes, DEFAULT_CACHE_TTL_MINUTES),
diff --git a/src/agents/tools/web-search.e2e.test.ts b/src/agents/tools/web-search.e2e.test.ts
index e8896f908b4..975f92be877 100644
--- a/src/agents/tools/web-search.e2e.test.ts
+++ b/src/agents/tools/web-search.e2e.test.ts
@@ -1,30 +1,7 @@
 import { describe, expect, it } from "vitest";
+import { withEnv } from "../../test-utils/env.js";
 import { __testing } from "./web-search.js";
 
-function withEnv<T>(env: Record<string, string | undefined>, fn: () => T): T {
-  const prev: Record<string, string | undefined> = {};
-  for (const [key, value] of Object.entries(env)) {
-    prev[key] = process.env[key];
-    if (value === undefined) {
-      // Make tests hermetic even on machines with real keys set.
-      delete process.env[key];
-    } else {
-      process.env[key] = value;
-    }
-  }
-  try {
-    return fn();
-  } finally {
-    for (const [key, value] of Object.entries(prev)) {
-      if (value === undefined) {
-        delete process.env[key];
-      } else {
-        process.env[key] = value;
-      }
-    }
-  }
-}
-
 const {
   inferPerplexityBaseUrlFromApiKey,
   resolvePerplexityBaseUrl,
diff --git a/src/agents/tools/web-search.ts b/src/agents/tools/web-search.ts
index f2e059f439c..be174b951d3 100644
--- a/src/agents/tools/web-search.ts
+++ b/src/agents/tools/web-search.ts
@@ -486,7 +486,8 @@ async function runPerplexitySearch(params: {
   });
 
   if (!res.ok) {
-    const detail = await readResponseText(res);
+    const detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    const detail = detailResult.text;
     throw new Error(`Perplexity API error (${res.status}): ${detail || res.statusText}`);
   }
 
@@ -535,7 +536,8 @@ async function runGrokSearch(params: {
   });
 
   if (!res.ok) {
-    const detail = await readResponseText(res);
+    const detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    const detail = detailResult.text;
     throw new Error(`xAI API error (${res.status}): ${detail || res.statusText}`);
   }
 
@@ -665,7 +667,8 @@ async function runWebSearch(params: {
   });
 
   if (!res.ok) {
-    const detail = await readResponseText(res);
+    const detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    const detail = detailResult.text;
     throw new Error(`Brave Search API error (${res.status}): ${detail || res.statusText}`);
   }
 
diff --git a/src/agents/tools/web-shared.ts b/src/agents/tools/web-shared.ts
index 2a7353796e2..da0fbb38beb 100644
--- a/src/agents/tools/web-shared.ts
+++ b/src/agents/tools/web-shared.ts
@@ -86,10 +86,85 @@ export function withTimeout(signal: AbortSignal | undefined, timeoutMs: number):
   return controller.signal;
 }
 
-export async function readResponseText(res: Response): Promise<string> {
+export type ReadResponseTextResult = {
+  text: string;
+  truncated: boolean;
+  bytesRead: number;
+};
+
+export async function readResponseText(
+  res: Response,
+  options?: { maxBytes?: number },
+): Promise<ReadResponseTextResult> {
+  const maxBytesRaw = options?.maxBytes;
+  const maxBytes =
+    typeof maxBytesRaw === "number" && Number.isFinite(maxBytesRaw) && maxBytesRaw > 0
+      ? Math.floor(maxBytesRaw)
+      : undefined;
+
+  const body = (res as unknown as { body?: unknown }).body;
+  if (
+    maxBytes &&
+    body &&
+    typeof body === "object" &&
+    "getReader" in body &&
+    typeof (body as { getReader: () => unknown }).getReader === "function"
+  ) {
+    const reader = (body as ReadableStream<Uint8Array>).getReader();
+    const decoder = new TextDecoder();
+    let bytesRead = 0;
+    let truncated = false;
+    const parts: string[] = [];
+
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+          break;
+        }
+        if (!value || value.byteLength === 0) {
+          continue;
+        }
+
+        let chunk = value;
+        if (bytesRead + chunk.byteLength > maxBytes) {
+          const remaining = Math.max(0, maxBytes - bytesRead);
+          if (remaining <= 0) {
+            truncated = true;
+            break;
+          }
+          chunk = chunk.subarray(0, remaining);
+          truncated = true;
+        }
+
+        bytesRead += chunk.byteLength;
+        parts.push(decoder.decode(chunk, { stream: true }));
+
+        if (truncated || bytesRead >= maxBytes) {
+          truncated = true;
+          break;
+        }
+      }
+    } catch {
+      // Best-effort: return whatever we decoded so far.
+    } finally {
+      if (truncated) {
+        try {
+          await reader.cancel();
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    parts.push(decoder.decode());
+    return { text: parts.join(""), truncated, bytesRead };
+  }
+
   try {
-    return await res.text();
+    const text = await res.text();
+    return { text, truncated: false, bytesRead: text.length };
   } catch {
-    return "";
+    return { text: "", truncated: false, bytesRead: 0 };
   }
 }
diff --git a/src/agents/transcript-policy.e2e.test.ts b/src/agents/transcript-policy.e2e.test.ts
index 669f69384e8..58f23e21ccc 100644
--- a/src/agents/transcript-policy.e2e.test.ts
+++ b/src/agents/transcript-policy.e2e.test.ts
@@ -2,15 +2,15 @@ import { describe, expect, it } from "vitest";
 import { resolveTranscriptPolicy } from "./transcript-policy.js";
 
 describe("resolveTranscriptPolicy e2e smoke", () => {
-  it("uses strict tool-call sanitization for OpenAI models", () => {
+  it("uses images-only sanitization without tool-call id rewriting for OpenAI models", () => {
     const policy = resolveTranscriptPolicy({
       provider: "openai",
       modelId: "gpt-4o",
       modelApi: "openai",
     });
     expect(policy.sanitizeMode).toBe("images-only");
-    expect(policy.sanitizeToolCallIds).toBe(true);
-    expect(policy.toolCallIdMode).toBe("strict");
+    expect(policy.sanitizeToolCallIds).toBe(false);
+    expect(policy.toolCallIdMode).toBeUndefined();
   });
 
   it("uses strict9 tool-call sanitization for Mistral-family models", () => {
diff --git a/src/agents/transcript-policy.test.ts b/src/agents/transcript-policy.test.ts
index 6ae7883db17..56c1230b65a 100644
--- a/src/agents/transcript-policy.test.ts
+++ b/src/agents/transcript-policy.test.ts
@@ -30,13 +30,13 @@ describe("resolveTranscriptPolicy", () => {
     expect(policy.toolCallIdMode).toBe("strict9");
   });
 
-  it("enables sanitizeToolCallIds for OpenAI provider", () => {
+  it("disables sanitizeToolCallIds for OpenAI provider", () => {
     const policy = resolveTranscriptPolicy({
       provider: "openai",
       modelId: "gpt-4o",
       modelApi: "openai",
     });
-    expect(policy.sanitizeToolCallIds).toBe(true);
-    expect(policy.toolCallIdMode).toBe("strict");
+    expect(policy.sanitizeToolCallIds).toBe(false);
+    expect(policy.toolCallIdMode).toBeUndefined();
   });
 });
diff --git a/src/agents/transcript-policy.ts b/src/agents/transcript-policy.ts
index e25ea55458c..22e173320b5 100644
--- a/src/agents/transcript-policy.ts
+++ b/src/agents/transcript-policy.ts
@@ -95,7 +95,7 @@ export function resolveTranscriptPolicy(params: {
 
   const needsNonImageSanitize = isGoogle || isAnthropic || isMistral || isOpenRouterGemini;
 
-  const sanitizeToolCallIds = isGoogle || isMistral || isAnthropic || isOpenAi;
+  const sanitizeToolCallIds = isGoogle || isMistral || isAnthropic;
   const toolCallIdMode: ToolCallIdMode | undefined = isMistral
     ? "strict9"
     : sanitizeToolCallIds
@@ -109,7 +109,7 @@ export function resolveTranscriptPolicy(params: {
 
   return {
     sanitizeMode: isOpenAi ? "images-only" : needsNonImageSanitize ? "full" : "images-only",
-    sanitizeToolCallIds,
+    sanitizeToolCallIds: !isOpenAi && sanitizeToolCallIds,
     toolCallIdMode,
     repairToolUseResultPairing: !isOpenAi && repairToolUseResultPairing,
     preserveSignatures: isAntigravityClaudeModel,
diff --git a/src/agents/workspace-run.ts b/src/agents/workspace-run.ts
index 1061a0344ed..8ba281c485d 100644
--- a/src/agents/workspace-run.ts
+++ b/src/agents/workspace-run.ts
@@ -1,4 +1,5 @@
 import type { OpenClawConfig } from "../config/config.js";
+import { logWarn } from "../logger.js";
 import { redactIdentifier } from "../logging/redact-identifier.js";
 import {
   classifySessionKeyShape,
@@ -8,6 +9,7 @@ import {
 } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { sanitizeForPromptLiteral } from "./sanitize-for-prompt.js";
 
 export type WorkspaceFallbackReason = "missing" | "blank" | "invalid_type";
 type AgentIdSource = "explicit" | "session_key" | "default";
@@ -84,8 +86,12 @@ export function resolveRunWorkspaceDir(params: {
   if (typeof requested === "string") {
     const trimmed = requested.trim();
     if (trimmed) {
+      const sanitized = sanitizeForPromptLiteral(trimmed);
+      if (sanitized !== trimmed) {
+        logWarn("Control/format characters stripped from workspaceDir (OC-19 hardening).");
+      }
       return {
-        workspaceDir: resolveUserPath(trimmed),
+        workspaceDir: resolveUserPath(sanitized),
         usedFallback: false,
         agentId,
         agentIdSource,
@@ -96,8 +102,12 @@ export function resolveRunWorkspaceDir(params: {
   const fallbackReason: WorkspaceFallbackReason =
     requested == null ? "missing" : typeof requested === "string" ? "blank" : "invalid_type";
   const fallbackWorkspace = resolveAgentWorkspaceDir(params.config ?? {}, agentId);
+  const sanitizedFallback = sanitizeForPromptLiteral(fallbackWorkspace);
+  if (sanitizedFallback !== fallbackWorkspace) {
+    logWarn("Control/format characters stripped from fallback workspaceDir (OC-19 hardening).");
+  }
   return {
-    workspaceDir: resolveUserPath(fallbackWorkspace),
+    workspaceDir: resolveUserPath(sanitizedFallback),
     usedFallback: true,
     fallbackReason,
     agentId,
diff --git a/src/agents/workspace.load-extra-bootstrap-files.test.ts b/src/agents/workspace.load-extra-bootstrap-files.test.ts
index 32586029c02..0a478524aef 100644
--- a/src/agents/workspace.load-extra-bootstrap-files.test.ts
+++ b/src/agents/workspace.load-extra-bootstrap-files.test.ts
@@ -1,12 +1,31 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { makeTempWorkspace } from "../test-helpers/workspace.js";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { loadExtraBootstrapFiles } from "./workspace.js";
 
 describe("loadExtraBootstrapFiles", () => {
+  let fixtureRoot = "";
+  let fixtureCount = 0;
+
+  const createWorkspaceDir = async (prefix: string) => {
+    const dir = path.join(fixtureRoot, `${prefix}-${fixtureCount++}`);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+  };
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-extra-bootstrap-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
   it("loads recognized bootstrap files from glob patterns", async () => {
-    const workspaceDir = await makeTempWorkspace("openclaw-extra-bootstrap-glob-");
+    const workspaceDir = await createWorkspaceDir("glob");
     const packageDir = path.join(workspaceDir, "packages", "core");
     await fs.mkdir(packageDir, { recursive: true });
     await fs.writeFile(path.join(packageDir, "TOOLS.md"), "tools", "utf-8");
@@ -20,7 +39,7 @@ describe("loadExtraBootstrapFiles", () => {
   });
 
   it("keeps path-traversal attempts outside workspace excluded", async () => {
-    const rootDir = await makeTempWorkspace("openclaw-extra-bootstrap-root-");
+    const rootDir = await createWorkspaceDir("root");
     const workspaceDir = path.join(rootDir, "workspace");
     const outsideDir = path.join(rootDir, "outside");
     await fs.mkdir(workspaceDir, { recursive: true });
@@ -37,7 +56,7 @@ describe("loadExtraBootstrapFiles", () => {
       return;
     }
 
-    const rootDir = await makeTempWorkspace("openclaw-extra-bootstrap-symlink-");
+    const rootDir = await createWorkspaceDir("symlink");
     const realWorkspace = path.join(rootDir, "real-workspace");
     const linkedWorkspace = path.join(rootDir, "linked-workspace");
     await fs.mkdir(realWorkspace, { recursive: true });
diff --git a/src/agents/workspace.ts b/src/agents/workspace.ts
index bf5f33992a0..9e1c081c7ec 100644
--- a/src/agents/workspace.ts
+++ b/src/agents/workspace.ts
@@ -184,6 +184,18 @@ async function readWorkspaceOnboardingState(statePath: string): Promise<Workspac
   }
 }
 
+async function readWorkspaceOnboardingStateForDir(dir: string): Promise<WorkspaceOnboardingState> {
+  const statePath = resolveWorkspaceStatePath(resolveUserPath(dir));
+  return await readWorkspaceOnboardingState(statePath);
+}
+
+export async function isWorkspaceOnboardingCompleted(dir: string): Promise<boolean> {
+  const state = await readWorkspaceOnboardingStateForDir(dir);
+  return (
+    typeof state.onboardingCompletedAt === "string" && state.onboardingCompletedAt.trim().length > 0
+  );
+}
+
 async function writeWorkspaceOnboardingState(
   statePath: string,
   state: WorkspaceOnboardingState,
diff --git a/src/auto-reply/chunk.ts b/src/auto-reply/chunk.ts
index 204f88ad397..e91b9e86833 100644
--- a/src/auto-reply/chunk.ts
+++ b/src/auto-reply/chunk.ts
@@ -298,7 +298,7 @@ function splitByNewline(
   return lines;
 }
 
-export function chunkText(text: string, limit: number): string[] {
+function resolveChunkEarlyReturn(text: string, limit: number): string[] | undefined {
   if (!text) {
     return [];
   }
@@ -308,6 +308,14 @@ export function chunkText(text: string, limit: number): string[] {
   if (text.length <= limit) {
     return [text];
   }
+  return undefined;
+}
+
+export function chunkText(text: string, limit: number): string[] {
+  const early = resolveChunkEarlyReturn(text, limit);
+  if (early) {
+    return early;
+  }
 
   const chunks: string[] = [];
   let remaining = text;
@@ -346,14 +354,9 @@ export function chunkText(text: string, limit: number): string[] {
 }
 
 export function chunkMarkdownText(text: string, limit: number): string[] {
-  if (!text) {
-    return [];
-  }
-  if (limit <= 0) {
-    return [text];
-  }
-  if (text.length <= limit) {
-    return [text];
+  const early = resolveChunkEarlyReturn(text, limit);
+  if (early) {
+    return early;
   }
 
   const chunks: string[] = [];
diff --git a/src/auto-reply/reply.triggers.group-intro-prompts.e2e.test.ts b/src/auto-reply/reply.triggers.group-intro-prompts.e2e.test.ts
index 5ac5281acb6..6322d7c9a8d 100644
--- a/src/auto-reply/reply.triggers.group-intro-prompts.e2e.test.ts
+++ b/src/auto-reply/reply.triggers.group-intro-prompts.e2e.test.ts
@@ -127,7 +127,10 @@ describe("group intro prompts", () => {
         vi.mocked(runEmbeddedPiAgent).mock.calls.at(-1)?.[0]?.extraSystemPrompt ?? "";
       expect(extraSystemPrompt).toContain('"channel": "discord"');
       expect(extraSystemPrompt).toContain(
-        `You are replying inside a Discord group chat. Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). ${groupParticipationNote} Address the specific sender noted in the message context.`,
+        `You are in the Discord group chat "Release Squad". Participants: Alice, Bob.`,
+      );
+      expect(extraSystemPrompt).toContain(
+        `Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). ${groupParticipationNote} Address the specific sender noted in the message context.`,
       );
     });
   });
@@ -158,8 +161,12 @@ describe("group intro prompts", () => {
       const extraSystemPrompt =
         vi.mocked(runEmbeddedPiAgent).mock.calls.at(-1)?.[0]?.extraSystemPrompt ?? "";
       expect(extraSystemPrompt).toContain('"channel": "whatsapp"');
+      expect(extraSystemPrompt).toContain(`You are in the WhatsApp group chat "Ops".`);
       expect(extraSystemPrompt).toContain(
-        `You are replying inside a WhatsApp group chat. Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). WhatsApp IDs: SenderId is the participant JID (group participant id). ${groupParticipationNote} Address the specific sender noted in the message context.`,
+        `WhatsApp IDs: SenderId is the participant JID (group participant id).`,
+      );
+      expect(extraSystemPrompt).toContain(
+        `Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). WhatsApp IDs: SenderId is the participant JID (group participant id). ${groupParticipationNote} Address the specific sender noted in the message context.`,
       );
     });
   });
@@ -190,8 +197,9 @@ describe("group intro prompts", () => {
       const extraSystemPrompt =
         vi.mocked(runEmbeddedPiAgent).mock.calls.at(-1)?.[0]?.extraSystemPrompt ?? "";
       expect(extraSystemPrompt).toContain('"channel": "telegram"');
+      expect(extraSystemPrompt).toContain(`You are in the Telegram group chat "Dev Chat".`);
       expect(extraSystemPrompt).toContain(
-        `You are replying inside a Telegram group chat. Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). ${groupParticipationNote} Address the specific sender noted in the message context.`,
+        `Activation: trigger-only (you are invoked only when explicitly mentioned; recent context may be included). ${groupParticipationNote} Address the specific sender noted in the message context.`,
       );
     });
   });
diff --git a/src/auto-reply/reply/abort.test.ts b/src/auto-reply/reply/abort.test.ts
index 76b0889e8c4..7f4172f1d2f 100644
--- a/src/auto-reply/reply/abort.test.ts
+++ b/src/auto-reply/reply/abort.test.ts
@@ -6,6 +6,7 @@ import type { OpenClawConfig } from "../../config/config.js";
 import {
   getAbortMemory,
   getAbortMemorySizeForTest,
+  isAbortRequestText,
   isAbortTrigger,
   resetAbortMemoryForTest,
   setAbortMemory,
@@ -75,6 +76,17 @@ describe("abort detection", () => {
     expect(isAbortTrigger("/stop")).toBe(false);
   });
 
+  it("isAbortRequestText aligns abort command semantics", () => {
+    expect(isAbortRequestText("/stop")).toBe(true);
+    expect(isAbortRequestText("stop")).toBe(true);
+    expect(isAbortRequestText("/stop@openclaw_bot", { botUsername: "openclaw_bot" })).toBe(true);
+
+    expect(isAbortRequestText("/status")).toBe(false);
+    expect(isAbortRequestText("stop please")).toBe(false);
+    expect(isAbortRequestText("/abort")).toBe(false);
+    expect(isAbortRequestText("/abort now")).toBe(false);
+  });
+
   it("removes abort memory entry when flag is reset", () => {
     setAbortMemory("session-1", true);
     expect(getAbortMemory("session-1")).toBe(true);
diff --git a/src/auto-reply/reply/abort.ts b/src/auto-reply/reply/abort.ts
index f2b4e8bc709..3b55c08bb45 100644
--- a/src/auto-reply/reply/abort.ts
+++ b/src/auto-reply/reply/abort.ts
@@ -19,7 +19,7 @@ import {
 import { logVerbose } from "../../globals.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
 import { resolveCommandAuthorization } from "../command-auth.js";
-import { normalizeCommandBody } from "../commands-registry.js";
+import { normalizeCommandBody, type CommandNormalizeOptions } from "../commands-registry.js";
 import { stripMentions, stripStructuralPrefixes } from "./mentions.js";
 import { clearSessionQueues } from "./queue.js";
 
@@ -35,6 +35,17 @@ export function isAbortTrigger(text?: string): boolean {
   return ABORT_TRIGGERS.has(normalized);
 }
 
+export function isAbortRequestText(text?: string, options?: CommandNormalizeOptions): boolean {
+  if (!text) {
+    return false;
+  }
+  const normalized = normalizeCommandBody(text, options).trim();
+  if (!normalized) {
+    return false;
+  }
+  return normalized.toLowerCase() === "/stop" || isAbortTrigger(normalized);
+}
+
 export function getAbortMemory(key: string): boolean | undefined {
   const normalized = key.trim();
   if (!normalized) {
@@ -202,8 +213,7 @@ export async function tryFastAbortFromMessage(params: {
   const raw = stripStructuralPrefixes(ctx.CommandBody ?? ctx.RawBody ?? ctx.Body ?? "");
   const isGroup = ctx.ChatType?.trim().toLowerCase() === "group";
   const stripped = isGroup ? stripMentions(raw, ctx, cfg, agentId) : raw;
-  const normalized = normalizeCommandBody(stripped);
-  const abortRequested = normalized === "/stop" || isAbortTrigger(stripped);
+  const abortRequested = isAbortRequestText(stripped);
   if (!abortRequested) {
     return { handled: false, aborted: false };
   }
diff --git a/src/auto-reply/reply/agent-runner-memory.ts b/src/auto-reply/reply/agent-runner-memory.ts
index 22c489c5354..de81ffec664 100644
--- a/src/auto-reply/reply/agent-runner-memory.ts
+++ b/src/auto-reply/reply/agent-runner-memory.ts
@@ -19,6 +19,7 @@ import { registerAgentRunContext } from "../../infra/agent-events.js";
 import { buildThreadingToolContext, resolveEnforceFinalTag } from "./agent-runner-utils.js";
 import {
   resolveMemoryFlushContextWindowTokens,
+  resolveMemoryFlushPromptForRun,
   resolveMemoryFlushSettings,
   shouldRunMemoryFlush,
 } from "./memory-flush.js";
@@ -133,7 +134,10 @@ export async function runMemoryFlushIfNeeded(params: {
           agentDir: params.followupRun.run.agentDir,
           config: params.followupRun.run.config,
           skillsSnapshot: params.followupRun.run.skillsSnapshot,
-          prompt: memoryFlushSettings.prompt,
+          prompt: resolveMemoryFlushPromptForRun({
+            prompt: memoryFlushSettings.prompt,
+            cfg: params.cfg,
+          }),
           extraSystemPrompt: flushSystemPrompt,
           ownerNumbers: params.followupRun.run.ownerNumbers,
           enforceFinalTag: resolveEnforceFinalTag(params.followupRun.run, provider),
diff --git a/src/auto-reply/reply/agent-runner-utils.test.ts b/src/auto-reply/reply/agent-runner-utils.test.ts
deleted file mode 100644
index 145b93bd61d..00000000000
--- a/src/auto-reply/reply/agent-runner-utils.test.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import type { TemplateContext } from "../templating.js";
-import { buildThreadingToolContext } from "./agent-runner-utils.js";
-
-describe("buildThreadingToolContext", () => {
-  const cfg = {} as OpenClawConfig;
-
-  it("uses conversation id for WhatsApp", () => {
-    const sessionCtx = {
-      Provider: "whatsapp",
-      From: "123@g.us",
-      To: "+15550001",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: cfg,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("123@g.us");
-  });
-
-  it("falls back to To for WhatsApp when From is missing", () => {
-    const sessionCtx = {
-      Provider: "whatsapp",
-      To: "+15550001",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: cfg,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("+15550001");
-  });
-
-  it("uses the recipient id for other channels", () => {
-    const sessionCtx = {
-      Provider: "telegram",
-      From: "user:42",
-      To: "chat:99",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: cfg,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("chat:99");
-  });
-
-  it("uses the sender handle for iMessage direct chats", () => {
-    const sessionCtx = {
-      Provider: "imessage",
-      ChatType: "direct",
-      From: "imessage:+15550001",
-      To: "chat_id:12",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: cfg,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("imessage:+15550001");
-  });
-
-  it("uses chat_id for iMessage groups", () => {
-    const sessionCtx = {
-      Provider: "imessage",
-      ChatType: "group",
-      From: "imessage:group:7",
-      To: "chat_id:7",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: cfg,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("chat_id:7");
-  });
-
-  it("prefers MessageThreadId for Slack tool threading", () => {
-    const sessionCtx = {
-      Provider: "slack",
-      To: "channel:C1",
-      MessageThreadId: "123.456",
-    } as TemplateContext;
-
-    const result = buildThreadingToolContext({
-      sessionCtx,
-      config: { channels: { slack: { replyToMode: "all" } } } as OpenClawConfig,
-      hasRepliedRef: undefined,
-    });
-
-    expect(result.currentChannelId).toBe("C1");
-    expect(result.currentThreadTs).toBe("123.456");
-  });
-});
diff --git a/src/auto-reply/reply/agent-runner.heartbeat-typing.runreplyagent-typing-heartbeat.test.ts b/src/auto-reply/reply/agent-runner.heartbeat-typing.runreplyagent-typing-heartbeat.test.ts
deleted file mode 100644
index 9c14f82c77f..00000000000
--- a/src/auto-reply/reply/agent-runner.heartbeat-typing.runreplyagent-typing-heartbeat.test.ts
+++ /dev/null
@@ -1,583 +0,0 @@
-import fs from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import * as sessions from "../../config/sessions.js";
-import {
-  createMinimalRun,
-  getRunEmbeddedPiAgentMock,
-  installRunReplyAgentTypingHeartbeatTestHooks,
-} from "./agent-runner.heartbeat-typing.test-harness.js";
-
-type AgentRunParams = {
-  onPartialReply?: (payload: { text?: string }) => Promise<void> | void;
-  onAssistantMessageStart?: () => Promise<void> | void;
-  onReasoningStream?: (payload: { text?: string }) => Promise<void> | void;
-  onBlockReply?: (payload: { text?: string; mediaUrls?: string[] }) => Promise<void> | void;
-  onToolResult?: (payload: { text?: string; mediaUrls?: string[] }) => Promise<void> | void;
-  onAgentEvent?: (evt: { stream: string; data: Record<string, unknown> }) => void;
-};
-
-const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-
-let fixtureRoot = "";
-let caseId = 0;
-
-type StateEnvSnapshot = {
-  OPENCLAW_STATE_DIR: string | undefined;
-};
-
-function snapshotStateEnv(): StateEnvSnapshot {
-  return { OPENCLAW_STATE_DIR: process.env.OPENCLAW_STATE_DIR };
-}
-
-function restoreStateEnv(snapshot: StateEnvSnapshot) {
-  if (snapshot.OPENCLAW_STATE_DIR === undefined) {
-    delete process.env.OPENCLAW_STATE_DIR;
-  } else {
-    process.env.OPENCLAW_STATE_DIR = snapshot.OPENCLAW_STATE_DIR;
-  }
-}
-
-async function withTempStateDir<T>(fn: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = path.join(fixtureRoot, `case-${++caseId}`);
-  await fs.mkdir(stateDir, { recursive: true });
-  const envSnapshot = snapshotStateEnv();
-  process.env.OPENCLAW_STATE_DIR = stateDir;
-  try {
-    return await fn(stateDir);
-  } finally {
-    restoreStateEnv(envSnapshot);
-  }
-}
-
-async function writeCorruptGeminiSessionFixture(params: {
-  stateDir: string;
-  sessionId: string;
-  persistStore: boolean;
-}) {
-  const storePath = path.join(params.stateDir, "sessions", "sessions.json");
-  const sessionEntry = { sessionId: params.sessionId, updatedAt: Date.now() };
-  const sessionStore = { main: sessionEntry };
-
-  await fs.mkdir(path.dirname(storePath), { recursive: true });
-  if (params.persistStore) {
-    await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
-  }
-
-  const transcriptPath = sessions.resolveSessionTranscriptPath(params.sessionId);
-  await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-  await fs.writeFile(transcriptPath, "bad", "utf-8");
-
-  return { storePath, sessionEntry, sessionStore, transcriptPath };
-}
-
-describe("runReplyAgent typing (heartbeat)", () => {
-  installRunReplyAgentTypingHeartbeatTestHooks();
-
-  beforeAll(async () => {
-    fixtureRoot = await fs.mkdtemp(path.join(tmpdir(), "openclaw-typing-heartbeat-"));
-  });
-
-  afterAll(async () => {
-    if (fixtureRoot) {
-      await fs.rm(fixtureRoot, { recursive: true, force: true });
-    }
-  });
-
-  beforeEach(() => {
-    vi.stubEnv("OPENCLAW_TEST_FAST", "1");
-  });
-
-  it("signals typing for normal runs", async () => {
-    const onPartialReply = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onPartialReply?.({ text: "hi" });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      opts: { isHeartbeat: false, onPartialReply },
-    });
-    await run();
-
-    expect(onPartialReply).toHaveBeenCalled();
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("hi");
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-  });
-
-  it("signals typing even without consumer partial handler", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onPartialReply?.({ text: "hi" });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "message",
-    });
-    await run();
-
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("hi");
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("never signals typing for heartbeat runs", async () => {
-    const onPartialReply = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onPartialReply?.({ text: "hi" });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      opts: { isHeartbeat: true, onPartialReply },
-    });
-    await run();
-
-    expect(onPartialReply).toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("suppresses partial streaming for NO_REPLY", async () => {
-    const onPartialReply = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onPartialReply?.({ text: "NO_REPLY" });
-      return { payloads: [{ text: "NO_REPLY" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      opts: { isHeartbeat: false, onPartialReply },
-      typingMode: "message",
-    });
-    await run();
-
-    expect(onPartialReply).not.toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("does not start typing on assistant message start without prior text in message mode", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onAssistantMessageStart?.();
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "message",
-    });
-    await run();
-
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-  });
-
-  it("starts typing from reasoning stream in thinking mode", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onReasoningStream?.({ text: "Reasoning:\n_step_" });
-      await params.onPartialReply?.({ text: "hi" });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "thinking",
-    });
-    await run();
-
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-  });
-
-  it("suppresses typing in never mode", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onPartialReply?.({ text: "hi" });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "never",
-    });
-    await run();
-
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("signals typing on normalized block replies", async () => {
-    const onBlockReply = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onBlockReply?.({ text: "\n\nchunk", mediaUrls: [] });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "message",
-      blockStreamingEnabled: true,
-      opts: { onBlockReply },
-    });
-    await run();
-
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("chunk");
-    expect(onBlockReply).toHaveBeenCalled();
-    const [blockPayload, blockOpts] = onBlockReply.mock.calls[0] ?? [];
-    expect(blockPayload).toMatchObject({ text: "chunk", audioAsVoice: false });
-    expect(blockOpts).toMatchObject({
-      abortSignal: expect.any(AbortSignal),
-      timeoutMs: expect.any(Number),
-    });
-  });
-
-  it("signals typing on tool results", async () => {
-    const onToolResult = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onToolResult?.({ text: "tooling", mediaUrls: [] });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "message",
-      opts: { onToolResult },
-    });
-    await run();
-
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("tooling");
-    expect(onToolResult).toHaveBeenCalledWith({
-      text: "tooling",
-      mediaUrls: [],
-    });
-  });
-
-  it("skips typing for silent tool results", async () => {
-    const onToolResult = vi.fn();
-    runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-      await params.onToolResult?.({ text: "NO_REPLY", mediaUrls: [] });
-      return { payloads: [{ text: "final" }], meta: {} };
-    });
-
-    const { run, typing } = createMinimalRun({
-      typingMode: "message",
-      opts: { onToolResult },
-    });
-    await run();
-
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-    expect(onToolResult).not.toHaveBeenCalled();
-  });
-
-  it("announces auto-compaction in verbose mode and tracks count", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const storePath = path.join(stateDir, "sessions", "sessions.json");
-      const sessionEntry = { sessionId: "session", updatedAt: Date.now() };
-      const sessionStore = { main: sessionEntry };
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
-        params.onAgentEvent?.({
-          stream: "compaction",
-          data: { phase: "end", willRetry: false },
-        });
-        return { payloads: [{ text: "final" }], meta: {} };
-      });
-
-      const { run } = createMinimalRun({
-        resolvedVerboseLevel: "on",
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-      expect(Array.isArray(res)).toBe(true);
-      const payloads = res as { text?: string }[];
-      expect(payloads[0]?.text).toContain("Auto-compaction complete");
-      expect(payloads[0]?.text).toContain("count 1");
-      expect(sessionStore.main.compactionCount).toBe(1);
-    });
-  });
-
-  it("retries after compaction failure by resetting the session", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const sessionId = "session";
-      const storePath = path.join(stateDir, "sessions", "sessions.json");
-      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
-      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
-      const sessionStore = { main: sessionEntry };
-
-      await fs.mkdir(path.dirname(storePath), { recursive: true });
-      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
-      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-      await fs.writeFile(transcriptPath, "ok", "utf-8");
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-        throw new Error(
-          'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
-        );
-      });
-
-      const { run } = createMinimalRun({
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-
-      expect(runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
-      const payload = Array.isArray(res) ? res[0] : res;
-      expect(payload).toMatchObject({
-        text: expect.stringContaining("Context limit exceeded during compaction"),
-      });
-      expect(payload.text?.toLowerCase()).toContain("reset");
-      expect(sessionStore.main.sessionId).not.toBe(sessionId);
-
-      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
-    });
-  });
-
-  it("retries after context overflow payload by resetting the session", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const sessionId = "session";
-      const storePath = path.join(stateDir, "sessions", "sessions.json");
-      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
-      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
-      const sessionStore = { main: sessionEntry };
-
-      await fs.mkdir(path.dirname(storePath), { recursive: true });
-      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
-      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-      await fs.writeFile(transcriptPath, "ok", "utf-8");
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
-        payloads: [{ text: "Context overflow: prompt too large", isError: true }],
-        meta: {
-          durationMs: 1,
-          error: {
-            kind: "context_overflow",
-            message: 'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
-          },
-        },
-      }));
-
-      const { run } = createMinimalRun({
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-
-      expect(runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
-      const payload = Array.isArray(res) ? res[0] : res;
-      expect(payload).toMatchObject({
-        text: expect.stringContaining("Context limit exceeded"),
-      });
-      expect(payload.text?.toLowerCase()).toContain("reset");
-      expect(sessionStore.main.sessionId).not.toBe(sessionId);
-
-      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
-    });
-  });
-
-  it("resets the session after role ordering payloads", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const sessionId = "session";
-      const storePath = path.join(stateDir, "sessions", "sessions.json");
-      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
-      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
-      const sessionStore = { main: sessionEntry };
-
-      await fs.mkdir(path.dirname(storePath), { recursive: true });
-      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
-      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-      await fs.writeFile(transcriptPath, "ok", "utf-8");
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
-        payloads: [{ text: "Message ordering conflict - please try again.", isError: true }],
-        meta: {
-          durationMs: 1,
-          error: {
-            kind: "role_ordering",
-            message: 'messages: roles must alternate between "user" and "assistant"',
-          },
-        },
-      }));
-
-      const { run } = createMinimalRun({
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-
-      const payload = Array.isArray(res) ? res[0] : res;
-      expect(payload).toMatchObject({
-        text: expect.stringContaining("Message ordering conflict"),
-      });
-      expect(payload.text?.toLowerCase()).toContain("reset");
-      expect(sessionStore.main.sessionId).not.toBe(sessionId);
-      await expect(fs.access(transcriptPath)).rejects.toBeDefined();
-
-      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
-    });
-  });
-
-  it("resets corrupted Gemini sessions and deletes transcripts", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const { storePath, sessionEntry, sessionStore, transcriptPath } =
-        await writeCorruptGeminiSessionFixture({
-          stateDir,
-          sessionId: "session-corrupt",
-          persistStore: true,
-        });
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-        throw new Error(
-          "function call turn comes immediately after a user turn or after a function response turn",
-        );
-      });
-
-      const { run } = createMinimalRun({
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-
-      expect(res).toMatchObject({
-        text: expect.stringContaining("Session history was corrupted"),
-      });
-      expect(sessionStore.main).toBeUndefined();
-      await expect(fs.access(transcriptPath)).rejects.toThrow();
-
-      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(persisted.main).toBeUndefined();
-    });
-  });
-
-  it("keeps sessions intact on other errors", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const sessionId = "session-ok";
-      const storePath = path.join(stateDir, "sessions", "sessions.json");
-      const sessionEntry = { sessionId, updatedAt: Date.now() };
-      const sessionStore = { main: sessionEntry };
-
-      await fs.mkdir(path.dirname(storePath), { recursive: true });
-      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
-
-      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
-      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-      await fs.writeFile(transcriptPath, "ok", "utf-8");
-
-      runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-        throw new Error("INVALID_ARGUMENT: some other failure");
-      });
-
-      const { run } = createMinimalRun({
-        sessionEntry,
-        sessionStore,
-        sessionKey: "main",
-        storePath,
-      });
-      const res = await run();
-
-      expect(res).toMatchObject({
-        text: expect.stringContaining("Agent failed before reply"),
-      });
-      expect(sessionStore.main).toBeDefined();
-      await expect(fs.access(transcriptPath)).resolves.toBeUndefined();
-
-      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(persisted.main).toBeDefined();
-    });
-  });
-
-  it("still replies even if session reset fails to persist", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const saveSpy = vi
-        .spyOn(sessions, "saveSessionStore")
-        .mockRejectedValueOnce(new Error("boom"));
-      try {
-        const { storePath, sessionEntry, sessionStore, transcriptPath } =
-          await writeCorruptGeminiSessionFixture({
-            stateDir,
-            sessionId: "session-corrupt",
-            persistStore: false,
-          });
-
-        runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-          throw new Error(
-            "function call turn comes immediately after a user turn or after a function response turn",
-          );
-        });
-
-        const { run } = createMinimalRun({
-          sessionEntry,
-          sessionStore,
-          sessionKey: "main",
-          storePath,
-        });
-        const res = await run();
-
-        expect(res).toMatchObject({
-          text: expect.stringContaining("Session history was corrupted"),
-        });
-        expect(sessionStore.main).toBeUndefined();
-        await expect(fs.access(transcriptPath)).rejects.toThrow();
-      } finally {
-        saveSpy.mockRestore();
-      }
-    });
-  });
-
-  it("returns friendly message for role ordering errors thrown as exceptions", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-      throw new Error("400 Incorrect role information");
-    });
-
-    const { run } = createMinimalRun({});
-    const res = await run();
-
-    expect(res).toMatchObject({
-      text: expect.stringContaining("Message ordering conflict"),
-    });
-    expect(res).toMatchObject({
-      text: expect.not.stringContaining("400"),
-    });
-  });
-
-  it("returns friendly message for 'roles must alternate' errors thrown as exceptions", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
-      throw new Error('messages: roles must alternate between "user" and "assistant"');
-    });
-
-    const { run } = createMinimalRun({});
-    const res = await run();
-
-    expect(res).toMatchObject({
-      text: expect.stringContaining("Message ordering conflict"),
-    });
-  });
-
-  it("rewrites Bun socket errors into friendly text", async () => {
-    runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
-      payloads: [
-        {
-          text: "TypeError: The socket connection was closed unexpectedly. For more information, pass `verbose: true` in the second argument to fetch()",
-          isError: true,
-        },
-      ],
-      meta: {},
-    }));
-
-    const { run } = createMinimalRun();
-    const res = await run();
-    const payloads = Array.isArray(res) ? res : res ? [res] : [];
-    expect(payloads.length).toBe(1);
-    expect(payloads[0]?.text).toContain("LLM connection failed");
-    expect(payloads[0]?.text).toContain("socket connection was closed unexpectedly");
-    expect(payloads[0]?.text).toContain("```");
-  });
-});
diff --git a/src/auto-reply/reply/agent-runner.heartbeat-typing.test-harness.ts b/src/auto-reply/reply/agent-runner.heartbeat-typing.test-harness.ts
deleted file mode 100644
index d1c176d494f..00000000000
--- a/src/auto-reply/reply/agent-runner.heartbeat-typing.test-harness.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import { beforeAll, beforeEach, vi } from "vitest";
-import type { SessionEntry } from "../../config/sessions.js";
-import type { TypingMode } from "../../config/types.js";
-import type { TemplateContext } from "../templating.js";
-import type { GetReplyOptions } from "../types.js";
-import type { FollowupRun, QueueSettings } from "./queue.js";
-import { createMockTypingController } from "./test-helpers.js";
-
-// Avoid exporting vitest mock types (TS2742 under pnpm + d.ts emit).
-// oxlint-disable-next-line typescript/no-explicit-any
-type AnyMock = any;
-
-const state = vi.hoisted(() => ({
-  runEmbeddedPiAgentMock: vi.fn(),
-}));
-
-let runReplyAgentPromise:
-  | Promise<(typeof import("./agent-runner.js"))["runReplyAgent"]>
-  | undefined;
-
-async function getRunReplyAgent() {
-  if (!runReplyAgentPromise) {
-    runReplyAgentPromise = import("./agent-runner.js").then((m) => m.runReplyAgent);
-  }
-  return await runReplyAgentPromise;
-}
-
-export function getRunEmbeddedPiAgentMock(): AnyMock {
-  return state.runEmbeddedPiAgentMock;
-}
-
-export function installRunReplyAgentTypingHeartbeatTestHooks() {
-  beforeAll(async () => {
-    // Avoid attributing the initial agent-runner import cost to the first test case.
-    await getRunReplyAgent();
-  });
-  beforeEach(() => {
-    state.runEmbeddedPiAgentMock.mockReset();
-  });
-}
-
-vi.mock("../../agents/model-fallback.js", async () => {
-  const { modelFallbackMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return modelFallbackMockFactory();
-});
-
-vi.mock("../../agents/pi-embedded.js", async () => {
-  const { embeddedPiMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return embeddedPiMockFactory(state);
-});
-
-vi.mock("./queue.js", async () => {
-  const { queueMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return await queueMockFactory();
-});
-
-export function createMinimalRun(params?: {
-  opts?: GetReplyOptions;
-  resolvedVerboseLevel?: "off" | "on";
-  sessionStore?: Record<string, SessionEntry>;
-  sessionEntry?: SessionEntry;
-  sessionKey?: string;
-  storePath?: string;
-  typingMode?: TypingMode;
-  blockStreamingEnabled?: boolean;
-}) {
-  const typing = createMockTypingController();
-  const opts = params?.opts;
-  const sessionCtx = {
-    Provider: "whatsapp",
-    MessageSid: "msg",
-  } as unknown as TemplateContext;
-  const resolvedQueue = { mode: "interrupt" } as unknown as QueueSettings;
-  const sessionKey = params?.sessionKey ?? "main";
-  const followupRun = {
-    prompt: "hello",
-    summaryLine: "hello",
-    enqueuedAt: Date.now(),
-    run: {
-      sessionId: "session",
-      sessionKey,
-      messageProvider: "whatsapp",
-      sessionFile: "/tmp/session.jsonl",
-      workspaceDir: "/tmp",
-      config: {},
-      skillsSnapshot: {},
-      provider: "anthropic",
-      model: "claude",
-      thinkLevel: "low",
-      verboseLevel: params?.resolvedVerboseLevel ?? "off",
-      elevatedLevel: "off",
-      bashElevated: {
-        enabled: false,
-        allowed: false,
-        defaultLevel: "off",
-      },
-      timeoutMs: 1_000,
-      blockReplyBreak: "message_end",
-    },
-  } as unknown as FollowupRun;
-
-  return {
-    typing,
-    opts,
-    run: async () => {
-      const runReplyAgent = await getRunReplyAgent();
-      return runReplyAgent({
-        commandBody: "hello",
-        followupRun,
-        queueKey: "main",
-        resolvedQueue,
-        shouldSteer: false,
-        shouldFollowup: false,
-        isActive: false,
-        isStreaming: false,
-        opts,
-        typing,
-        sessionEntry: params?.sessionEntry,
-        sessionStore: params?.sessionStore,
-        sessionKey,
-        storePath: params?.storePath,
-        sessionCtx,
-        defaultModel: "anthropic/claude-opus-4-5",
-        resolvedVerboseLevel: params?.resolvedVerboseLevel ?? "off",
-        isNewSession: false,
-        blockStreamingEnabled: params?.blockStreamingEnabled ?? false,
-        resolvedBlockStreamingBreak: "message_end",
-        shouldInjectGroupIntro: false,
-        typingMode: params?.typingMode ?? "instant",
-      });
-    },
-  };
-}
diff --git a/src/auto-reply/reply/agent-runner.memory-flush.runreplyagent-memory-flush.test.ts b/src/auto-reply/reply/agent-runner.memory-flush.runreplyagent-memory-flush.test.ts
deleted file mode 100644
index e13de88c54d..00000000000
--- a/src/auto-reply/reply/agent-runner.memory-flush.runreplyagent-memory-flush.test.ts
+++ /dev/null
@@ -1,423 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  createBaseRun,
-  getRunCliAgentMock,
-  getRunEmbeddedPiAgentMock,
-  seedSessionStore,
-  type EmbeddedRunParams,
-} from "./agent-runner.memory-flush.test-harness.js";
-import { DEFAULT_MEMORY_FLUSH_PROMPT } from "./memory-flush.js";
-
-let runReplyAgent: typeof import("./agent-runner.js").runReplyAgent;
-
-let fixtureRoot = "";
-let caseId = 0;
-
-async function withTempStore<T>(fn: (storePath: string) => Promise<T>): Promise<T> {
-  const dir = path.join(fixtureRoot, `case-${++caseId}`);
-  await fs.mkdir(dir, { recursive: true });
-  return await fn(path.join(dir, "sessions.json"));
-}
-
-async function runReplyAgentWithBase(params: {
-  baseRun: ReturnType<typeof createBaseRun>;
-  storePath: string;
-  sessionKey: string;
-  sessionEntry: Record<string, unknown>;
-  commandBody: string;
-  typingMode?: "instant";
-}): Promise<void> {
-  const { typing, sessionCtx, resolvedQueue, followupRun } = params.baseRun;
-  await runReplyAgent({
-    commandBody: params.commandBody,
-    followupRun,
-    queueKey: params.sessionKey,
-    resolvedQueue,
-    shouldSteer: false,
-    shouldFollowup: false,
-    isActive: false,
-    isStreaming: false,
-    typing,
-    sessionCtx,
-    sessionEntry: params.sessionEntry,
-    sessionStore: { [params.sessionKey]: params.sessionEntry },
-    sessionKey: params.sessionKey,
-    storePath: params.storePath,
-    defaultModel: "anthropic/claude-opus-4-5",
-    agentCfgContextTokens: 100_000,
-    resolvedVerboseLevel: "off",
-    isNewSession: false,
-    blockStreamingEnabled: false,
-    resolvedBlockStreamingBreak: "message_end",
-    shouldInjectGroupIntro: false,
-    typingMode: params.typingMode ?? "instant",
-  });
-}
-
-async function expectMemoryFlushSkippedWithWorkspaceAccess(
-  workspaceAccess: "ro" | "none",
-): Promise<void> {
-  const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-  runEmbeddedPiAgentMock.mockReset();
-
-  await withTempStore(async (storePath) => {
-    const sessionKey = "main";
-    const sessionEntry = {
-      sessionId: "session",
-      updatedAt: Date.now(),
-      totalTokens: 80_000,
-      compactionCount: 1,
-    };
-
-    await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-    const calls: Array<{ prompt?: string }> = [];
-    runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
-      calls.push({ prompt: params.prompt });
-      return {
-        payloads: [{ text: "ok" }],
-        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-      };
-    });
-
-    const baseRun = createBaseRun({
-      storePath,
-      sessionEntry,
-      config: {
-        agents: {
-          defaults: {
-            sandbox: { mode: "all", workspaceAccess },
-          },
-        },
-      },
-    });
-
-    await runReplyAgentWithBase({
-      baseRun,
-      storePath,
-      sessionKey,
-      sessionEntry,
-      commandBody: "hello",
-    });
-
-    expect(calls.map((call) => call.prompt)).toEqual(["hello"]);
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].memoryFlushAt).toBeUndefined();
-  });
-}
-
-beforeAll(async () => {
-  fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-memory-flush-"));
-  ({ runReplyAgent } = await import("./agent-runner.js"));
-});
-
-afterAll(async () => {
-  if (fixtureRoot) {
-    await fs.rm(fixtureRoot, { recursive: true, force: true });
-  }
-});
-
-describe("runReplyAgent memory flush", () => {
-  it("skips memory flush for CLI providers", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    const runCliAgentMock = getRunCliAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-    runCliAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 1,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      runEmbeddedPiAgentMock.mockImplementation(async () => ({
-        payloads: [{ text: "ok" }],
-        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-      }));
-      runCliAgentMock.mockResolvedValue({
-        payloads: [{ text: "ok" }],
-        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-      });
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-        runOverrides: { provider: "codex-cli" },
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      expect(runCliAgentMock).toHaveBeenCalledTimes(1);
-      const call = runCliAgentMock.mock.calls[0]?.[0] as { prompt?: string } | undefined;
-      expect(call?.prompt).toBe("hello");
-      expect(runEmbeddedPiAgentMock).not.toHaveBeenCalled();
-    });
-  });
-
-  it("uses configured prompts for memory flush runs", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 1,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      const calls: Array<EmbeddedRunParams> = [];
-      runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
-        calls.push(params);
-        if (params.prompt === DEFAULT_MEMORY_FLUSH_PROMPT) {
-          return { payloads: [], meta: {} };
-        }
-        return {
-          payloads: [{ text: "ok" }],
-          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-        };
-      });
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-        config: {
-          agents: {
-            defaults: {
-              compaction: {
-                memoryFlush: {
-                  prompt: "Write notes.",
-                  systemPrompt: "Flush memory now.",
-                },
-              },
-            },
-          },
-        },
-        runOverrides: { extraSystemPrompt: "extra system" },
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      const flushCall = calls[0];
-      expect(flushCall?.prompt).toContain("Write notes.");
-      expect(flushCall?.prompt).toContain("NO_REPLY");
-      expect(flushCall?.extraSystemPrompt).toContain("extra system");
-      expect(flushCall?.extraSystemPrompt).toContain("Flush memory now.");
-      expect(flushCall?.extraSystemPrompt).toContain("NO_REPLY");
-      expect(calls[1]?.prompt).toBe("hello");
-    });
-  });
-
-  it("runs a memory flush turn and updates session metadata", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 1,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      const calls: Array<{ prompt?: string }> = [];
-      runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
-        calls.push({ prompt: params.prompt });
-        if (params.prompt === DEFAULT_MEMORY_FLUSH_PROMPT) {
-          return { payloads: [], meta: {} };
-        }
-        return {
-          payloads: [{ text: "ok" }],
-          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-        };
-      });
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      expect(calls.map((call) => call.prompt)).toEqual([DEFAULT_MEMORY_FLUSH_PROMPT, "hello"]);
-
-      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(stored[sessionKey].memoryFlushAt).toBeTypeOf("number");
-      expect(stored[sessionKey].memoryFlushCompactionCount).toBe(1);
-    });
-  });
-
-  it("skips memory flush when disabled in config", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 1,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      runEmbeddedPiAgentMock.mockImplementation(async () => ({
-        payloads: [{ text: "ok" }],
-        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-      }));
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-        config: { agents: { defaults: { compaction: { memoryFlush: { enabled: false } } } } },
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      expect(runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
-      const call = runEmbeddedPiAgentMock.mock.calls[0]?.[0] as { prompt?: string } | undefined;
-      expect(call?.prompt).toBe("hello");
-
-      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(stored[sessionKey].memoryFlushAt).toBeUndefined();
-    });
-  });
-
-  it("skips memory flush after a prior flush in the same compaction cycle", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 2,
-        memoryFlushCompactionCount: 2,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      const calls: Array<{ prompt?: string }> = [];
-      runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
-        calls.push({ prompt: params.prompt });
-        return {
-          payloads: [{ text: "ok" }],
-          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-        };
-      });
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      expect(calls.map((call) => call.prompt)).toEqual(["hello"]);
-    });
-  });
-
-  it("skips memory flush when the sandbox workspace is read-only", async () => {
-    await expectMemoryFlushSkippedWithWorkspaceAccess("ro");
-  });
-
-  it("skips memory flush when the sandbox workspace is none", async () => {
-    await expectMemoryFlushSkippedWithWorkspaceAccess("none");
-  });
-
-  it("increments compaction count when flush compaction completes", async () => {
-    const runEmbeddedPiAgentMock = getRunEmbeddedPiAgentMock();
-    runEmbeddedPiAgentMock.mockReset();
-
-    await withTempStore(async (storePath) => {
-      const sessionKey = "main";
-      const sessionEntry = {
-        sessionId: "session",
-        updatedAt: Date.now(),
-        totalTokens: 80_000,
-        compactionCount: 1,
-      };
-
-      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
-
-      runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
-        if (params.prompt === DEFAULT_MEMORY_FLUSH_PROMPT) {
-          params.onAgentEvent?.({
-            stream: "compaction",
-            data: { phase: "end", willRetry: false },
-          });
-          return { payloads: [], meta: {} };
-        }
-        return {
-          payloads: [{ text: "ok" }],
-          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
-        };
-      });
-
-      const baseRun = createBaseRun({
-        storePath,
-        sessionEntry,
-      });
-
-      await runReplyAgentWithBase({
-        baseRun,
-        storePath,
-        sessionKey,
-        sessionEntry,
-        commandBody: "hello",
-      });
-
-      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-      expect(stored[sessionKey].compactionCount).toBe(2);
-      expect(stored[sessionKey].memoryFlushCompactionCount).toBe(2);
-    });
-  });
-});
diff --git a/src/auto-reply/reply/agent-runner.memory-flush.test-harness.ts b/src/auto-reply/reply/agent-runner.memory-flush.test-harness.ts
deleted file mode 100644
index 131da7c5240..00000000000
--- a/src/auto-reply/reply/agent-runner.memory-flush.test-harness.ts
+++ /dev/null
@@ -1,119 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { vi } from "vitest";
-import type { TemplateContext } from "../templating.js";
-import type { FollowupRun, QueueSettings } from "./queue.js";
-import { createMockTypingController } from "./test-helpers.js";
-
-// Avoid exporting vitest mock types (TS2742 under pnpm + d.ts emit).
-// oxlint-disable-next-line typescript/no-explicit-any
-type AnyMock = any;
-
-type EmbeddedRunParams = {
-  prompt?: string;
-  extraSystemPrompt?: string;
-  onAgentEvent?: (evt: { stream?: string; data?: { phase?: string; willRetry?: boolean } }) => void;
-};
-
-const state = vi.hoisted(() => ({
-  runEmbeddedPiAgentMock: vi.fn(),
-  runCliAgentMock: vi.fn(),
-}));
-
-export function getRunEmbeddedPiAgentMock(): AnyMock {
-  return state.runEmbeddedPiAgentMock;
-}
-
-export function getRunCliAgentMock(): AnyMock {
-  return state.runCliAgentMock;
-}
-
-export type { EmbeddedRunParams };
-
-vi.mock("../../agents/model-fallback.js", async () => {
-  const { modelFallbackMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return modelFallbackMockFactory();
-});
-
-vi.mock("../../agents/cli-runner.js", () => ({
-  runCliAgent: (params: unknown) => state.runCliAgentMock(params),
-}));
-
-vi.mock("../../agents/pi-embedded.js", async () => {
-  const { embeddedPiMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return embeddedPiMockFactory(state);
-});
-
-vi.mock("./queue.js", async () => {
-  const { queueMockFactory } = await import("./agent-runner.test-harness.mocks.js");
-  return await queueMockFactory();
-});
-
-export async function seedSessionStore(params: {
-  storePath: string;
-  sessionKey: string;
-  entry: Record<string, unknown>;
-}) {
-  await fs.mkdir(path.dirname(params.storePath), { recursive: true });
-  await fs.writeFile(
-    params.storePath,
-    JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
-    "utf-8",
-  );
-}
-
-export function createBaseRun(params: {
-  storePath: string;
-  sessionEntry: Record<string, unknown>;
-  config?: Record<string, unknown>;
-  runOverrides?: Partial<FollowupRun["run"]>;
-}) {
-  const typing = createMockTypingController();
-  const sessionCtx = {
-    Provider: "whatsapp",
-    OriginatingTo: "+15550001111",
-    AccountId: "primary",
-    MessageSid: "msg",
-  } as unknown as TemplateContext;
-  const resolvedQueue = { mode: "interrupt" } as unknown as QueueSettings;
-  const followupRun = {
-    prompt: "hello",
-    summaryLine: "hello",
-    enqueuedAt: Date.now(),
-    run: {
-      agentId: "main",
-      agentDir: "/tmp/agent",
-      sessionId: "session",
-      sessionKey: "main",
-      messageProvider: "whatsapp",
-      sessionFile: "/tmp/session.jsonl",
-      workspaceDir: "/tmp",
-      config: params.config ?? {},
-      skillsSnapshot: {},
-      provider: "anthropic",
-      model: "claude",
-      thinkLevel: "low",
-      verboseLevel: "off",
-      elevatedLevel: "off",
-      bashElevated: {
-        enabled: false,
-        allowed: false,
-        defaultLevel: "off",
-      },
-      timeoutMs: 1_000,
-      blockReplyBreak: "message_end",
-    },
-  } as unknown as FollowupRun;
-  const run = {
-    ...followupRun.run,
-    ...params.runOverrides,
-    config: params.config ?? followupRun.run.config,
-  };
-
-  return {
-    typing,
-    sessionCtx,
-    resolvedQueue,
-    followupRun: { ...followupRun, run },
-  };
-}
diff --git a/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts b/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
index d602b0a73f6..99ec07a6245 100644
--- a/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
+++ b/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
@@ -8,7 +8,6 @@ import type { TemplateContext } from "../templating.js";
 import type { FollowupRun, QueueSettings } from "./queue.js";
 import { loadSessionStore, saveSessionStore } from "../../config/sessions.js";
 import { onAgentEvent } from "../../infra/agent-events.js";
-import { DEFAULT_MEMORY_FLUSH_PROMPT } from "./memory-flush.js";
 import { createMockTypingController } from "./test-helpers.js";
 
 const runEmbeddedPiAgentMock = vi.fn();
@@ -948,7 +947,7 @@ describe("runReplyAgent fallback reasoning tags", () => {
 
   it("enforces <final> during memory flush on fallback providers", async () => {
     runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedPiAgentParams) => {
-      if (params.prompt === DEFAULT_MEMORY_FLUSH_PROMPT) {
+      if (params.prompt?.includes("Pre-compaction memory flush.")) {
         return { payloads: [], meta: {} };
       }
       return { payloads: [{ text: "ok" }], meta: {} };
@@ -968,9 +967,10 @@ describe("runReplyAgent fallback reasoning tags", () => {
       },
     });
 
-    const flushCall = runEmbeddedPiAgentMock.mock.calls.find(
-      ([params]) =>
-        (params as EmbeddedPiAgentParams | undefined)?.prompt === DEFAULT_MEMORY_FLUSH_PROMPT,
+    const flushCall = runEmbeddedPiAgentMock.mock.calls.find(([params]) =>
+      (params as EmbeddedPiAgentParams | undefined)?.prompt?.includes(
+        "Pre-compaction memory flush.",
+      ),
     )?.[0] as EmbeddedPiAgentParams | undefined;
 
     expect(flushCall?.enforceFinalTag).toBe(true);
diff --git a/src/auto-reply/reply/agent-runner.runreplyagent.test.ts b/src/auto-reply/reply/agent-runner.runreplyagent.test.ts
new file mode 100644
index 00000000000..29d1be5b80a
--- /dev/null
+++ b/src/auto-reply/reply/agent-runner.runreplyagent.test.ts
@@ -0,0 +1,1032 @@
+import fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionEntry } from "../../config/sessions.js";
+import type { TypingMode } from "../../config/types.js";
+import type { TemplateContext } from "../templating.js";
+import type { GetReplyOptions } from "../types.js";
+import type { FollowupRun, QueueSettings } from "./queue.js";
+import * as sessions from "../../config/sessions.js";
+import { createMockTypingController } from "./test-helpers.js";
+
+type AgentRunParams = {
+  onPartialReply?: (payload: { text?: string }) => Promise<void> | void;
+  onAssistantMessageStart?: () => Promise<void> | void;
+  onReasoningStream?: (payload: { text?: string }) => Promise<void> | void;
+  onBlockReply?: (payload: { text?: string; mediaUrls?: string[] }) => Promise<void> | void;
+  onToolResult?: (payload: { text?: string; mediaUrls?: string[] }) => Promise<void> | void;
+  onAgentEvent?: (evt: { stream: string; data: Record<string, unknown> }) => void;
+};
+
+type EmbeddedRunParams = {
+  prompt?: string;
+  extraSystemPrompt?: string;
+  onAgentEvent?: (evt: { stream?: string; data?: { phase?: string; willRetry?: boolean } }) => void;
+};
+
+const state = vi.hoisted(() => ({
+  runEmbeddedPiAgentMock: vi.fn(),
+  runCliAgentMock: vi.fn(),
+}));
+
+let runReplyAgentPromise:
+  | Promise<(typeof import("./agent-runner.js"))["runReplyAgent"]>
+  | undefined;
+
+async function getRunReplyAgent() {
+  if (!runReplyAgentPromise) {
+    runReplyAgentPromise = import("./agent-runner.js").then((m) => m.runReplyAgent);
+  }
+  return await runReplyAgentPromise;
+}
+
+vi.mock("../../agents/model-fallback.js", () => ({
+  runWithModelFallback: async ({
+    provider,
+    model,
+    run,
+  }: {
+    provider: string;
+    model: string;
+    run: (provider: string, model: string) => Promise<unknown>;
+  }) => ({
+    result: await run(provider, model),
+    provider,
+    model,
+  }),
+}));
+
+vi.mock("../../agents/pi-embedded.js", () => ({
+  queueEmbeddedPiMessage: vi.fn().mockReturnValue(false),
+  runEmbeddedPiAgent: (params: unknown) => state.runEmbeddedPiAgentMock(params),
+}));
+
+vi.mock("../../agents/cli-runner.js", () => ({
+  runCliAgent: (params: unknown) => state.runCliAgentMock(params),
+}));
+
+vi.mock("./queue.js", () => ({
+  enqueueFollowupRun: vi.fn(),
+  scheduleFollowupDrain: vi.fn(),
+}));
+
+beforeAll(async () => {
+  // Avoid attributing the initial agent-runner import cost to the first test case.
+  await getRunReplyAgent();
+});
+
+beforeEach(() => {
+  state.runEmbeddedPiAgentMock.mockReset();
+  state.runCliAgentMock.mockReset();
+  vi.stubEnv("OPENCLAW_TEST_FAST", "1");
+});
+
+function createMinimalRun(params?: {
+  opts?: GetReplyOptions;
+  resolvedVerboseLevel?: "off" | "on";
+  sessionStore?: Record<string, SessionEntry>;
+  sessionEntry?: SessionEntry;
+  sessionKey?: string;
+  storePath?: string;
+  typingMode?: TypingMode;
+  blockStreamingEnabled?: boolean;
+}) {
+  const typing = createMockTypingController();
+  const opts = params?.opts;
+  const sessionCtx = {
+    Provider: "whatsapp",
+    MessageSid: "msg",
+  } as unknown as TemplateContext;
+  const resolvedQueue = { mode: "interrupt" } as unknown as QueueSettings;
+  const sessionKey = params?.sessionKey ?? "main";
+  const followupRun = {
+    prompt: "hello",
+    summaryLine: "hello",
+    enqueuedAt: Date.now(),
+    run: {
+      sessionId: "session",
+      sessionKey,
+      messageProvider: "whatsapp",
+      sessionFile: "/tmp/session.jsonl",
+      workspaceDir: "/tmp",
+      config: {},
+      skillsSnapshot: {},
+      provider: "anthropic",
+      model: "claude",
+      thinkLevel: "low",
+      verboseLevel: params?.resolvedVerboseLevel ?? "off",
+      elevatedLevel: "off",
+      bashElevated: {
+        enabled: false,
+        allowed: false,
+        defaultLevel: "off",
+      },
+      timeoutMs: 1_000,
+      blockReplyBreak: "message_end",
+    },
+  } as unknown as FollowupRun;
+
+  return {
+    typing,
+    opts,
+    run: async () => {
+      const runReplyAgent = await getRunReplyAgent();
+      return runReplyAgent({
+        commandBody: "hello",
+        followupRun,
+        queueKey: "main",
+        resolvedQueue,
+        shouldSteer: false,
+        shouldFollowup: false,
+        isActive: false,
+        isStreaming: false,
+        opts,
+        typing,
+        sessionEntry: params?.sessionEntry,
+        sessionStore: params?.sessionStore,
+        sessionKey,
+        storePath: params?.storePath,
+        sessionCtx,
+        defaultModel: "anthropic/claude-opus-4-5",
+        resolvedVerboseLevel: params?.resolvedVerboseLevel ?? "off",
+        isNewSession: false,
+        blockStreamingEnabled: params?.blockStreamingEnabled ?? false,
+        resolvedBlockStreamingBreak: "message_end",
+        shouldInjectGroupIntro: false,
+        typingMode: params?.typingMode ?? "instant",
+      });
+    },
+  };
+}
+
+async function seedSessionStore(params: {
+  storePath: string;
+  sessionKey: string;
+  entry: Record<string, unknown>;
+}) {
+  await fs.mkdir(path.dirname(params.storePath), { recursive: true });
+  await fs.writeFile(
+    params.storePath,
+    JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
+    "utf-8",
+  );
+}
+
+function createBaseRun(params: {
+  storePath: string;
+  sessionEntry: Record<string, unknown>;
+  config?: Record<string, unknown>;
+  runOverrides?: Partial<FollowupRun["run"]>;
+}) {
+  const typing = createMockTypingController();
+  const sessionCtx = {
+    Provider: "whatsapp",
+    OriginatingTo: "+15550001111",
+    AccountId: "primary",
+    MessageSid: "msg",
+  } as unknown as TemplateContext;
+  const resolvedQueue = { mode: "interrupt" } as unknown as QueueSettings;
+  const followupRun = {
+    prompt: "hello",
+    summaryLine: "hello",
+    enqueuedAt: Date.now(),
+    run: {
+      agentId: "main",
+      agentDir: "/tmp/agent",
+      sessionId: "session",
+      sessionKey: "main",
+      messageProvider: "whatsapp",
+      sessionFile: "/tmp/session.jsonl",
+      workspaceDir: "/tmp",
+      config: params.config ?? {},
+      skillsSnapshot: {},
+      provider: "anthropic",
+      model: "claude",
+      thinkLevel: "low",
+      verboseLevel: "off",
+      elevatedLevel: "off",
+      bashElevated: {
+        enabled: false,
+        allowed: false,
+        defaultLevel: "off",
+      },
+      timeoutMs: 1_000,
+      blockReplyBreak: "message_end",
+    },
+  } as unknown as FollowupRun;
+  const run = {
+    ...followupRun.run,
+    ...params.runOverrides,
+    config: params.config ?? followupRun.run.config,
+  };
+
+  return {
+    typing,
+    sessionCtx,
+    resolvedQueue,
+    followupRun: { ...followupRun, run },
+  };
+}
+
+async function runReplyAgentWithBase(params: {
+  baseRun: ReturnType<typeof createBaseRun>;
+  storePath: string;
+  sessionKey: string;
+  sessionEntry: Record<string, unknown>;
+  commandBody: string;
+  typingMode?: "instant";
+}): Promise<void> {
+  const runReplyAgent = await getRunReplyAgent();
+  const { typing, sessionCtx, resolvedQueue, followupRun } = params.baseRun;
+  await runReplyAgent({
+    commandBody: params.commandBody,
+    followupRun,
+    queueKey: params.sessionKey,
+    resolvedQueue,
+    shouldSteer: false,
+    shouldFollowup: false,
+    isActive: false,
+    isStreaming: false,
+    typing,
+    sessionCtx,
+    sessionEntry: params.sessionEntry,
+    sessionStore: { [params.sessionKey]: params.sessionEntry } as Record<string, SessionEntry>,
+    sessionKey: params.sessionKey,
+    storePath: params.storePath,
+    defaultModel: "anthropic/claude-opus-4-5",
+    agentCfgContextTokens: 100_000,
+    resolvedVerboseLevel: "off",
+    isNewSession: false,
+    blockStreamingEnabled: false,
+    resolvedBlockStreamingBreak: "message_end",
+    shouldInjectGroupIntro: false,
+    typingMode: params.typingMode ?? "instant",
+  });
+}
+
+describe("runReplyAgent typing (heartbeat)", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
+
+  type StateEnvSnapshot = {
+    OPENCLAW_STATE_DIR: string | undefined;
+  };
+
+  function snapshotStateEnv(): StateEnvSnapshot {
+    return { OPENCLAW_STATE_DIR: process.env.OPENCLAW_STATE_DIR };
+  }
+
+  function restoreStateEnv(snapshot: StateEnvSnapshot) {
+    if (snapshot.OPENCLAW_STATE_DIR === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = snapshot.OPENCLAW_STATE_DIR;
+    }
+  }
+
+  async function withTempStateDir<T>(fn: (stateDir: string) => Promise<T>): Promise<T> {
+    const stateDir = path.join(fixtureRoot, `case-${++caseId}`);
+    await fs.mkdir(stateDir, { recursive: true });
+    const envSnapshot = snapshotStateEnv();
+    process.env.OPENCLAW_STATE_DIR = stateDir;
+    try {
+      return await fn(stateDir);
+    } finally {
+      restoreStateEnv(envSnapshot);
+    }
+  }
+
+  async function writeCorruptGeminiSessionFixture(params: {
+    stateDir: string;
+    sessionId: string;
+    persistStore: boolean;
+  }) {
+    const storePath = path.join(params.stateDir, "sessions", "sessions.json");
+    const sessionEntry = { sessionId: params.sessionId, updatedAt: Date.now() };
+    const sessionStore = { main: sessionEntry };
+
+    await fs.mkdir(path.dirname(storePath), { recursive: true });
+    if (params.persistStore) {
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+    }
+
+    const transcriptPath = sessions.resolveSessionTranscriptPath(params.sessionId);
+    await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+    await fs.writeFile(transcriptPath, "bad", "utf-8");
+
+    return { storePath, sessionEntry, sessionStore, transcriptPath };
+  }
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(tmpdir(), "openclaw-typing-heartbeat-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("signals typing for normal runs", async () => {
+    const onPartialReply = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onPartialReply?.({ text: "hi" });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      opts: { isHeartbeat: false, onPartialReply },
+    });
+    await run();
+
+    expect(onPartialReply).toHaveBeenCalled();
+    expect(typing.startTypingOnText).toHaveBeenCalledWith("hi");
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+  });
+
+  it("never signals typing for heartbeat runs", async () => {
+    const onPartialReply = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onPartialReply?.({ text: "hi" });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      opts: { isHeartbeat: true, onPartialReply },
+    });
+    await run();
+
+    expect(onPartialReply).toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+  });
+
+  it("suppresses partial streaming for NO_REPLY", async () => {
+    const onPartialReply = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onPartialReply?.({ text: "NO_REPLY" });
+      return { payloads: [{ text: "NO_REPLY" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      opts: { isHeartbeat: false, onPartialReply },
+      typingMode: "message",
+    });
+    await run();
+
+    expect(onPartialReply).not.toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+  });
+
+  it("does not start typing on assistant message start without prior text in message mode", async () => {
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onAssistantMessageStart?.();
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "message",
+    });
+    await run();
+
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+  });
+
+  it("starts typing from reasoning stream in thinking mode", async () => {
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onReasoningStream?.({ text: "Reasoning:\n_step_" });
+      await params.onPartialReply?.({ text: "hi" });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "thinking",
+    });
+    await run();
+
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+  });
+
+  it("suppresses typing in never mode", async () => {
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onPartialReply?.({ text: "hi" });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "never",
+    });
+    await run();
+
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+  });
+
+  it("signals typing on normalized block replies", async () => {
+    const onBlockReply = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onBlockReply?.({ text: "\n\nchunk", mediaUrls: [] });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "message",
+      blockStreamingEnabled: true,
+      opts: { onBlockReply },
+    });
+    await run();
+
+    expect(typing.startTypingOnText).toHaveBeenCalledWith("chunk");
+    expect(onBlockReply).toHaveBeenCalled();
+    const [blockPayload, blockOpts] = onBlockReply.mock.calls[0] ?? [];
+    expect(blockPayload).toMatchObject({ text: "chunk", audioAsVoice: false });
+    expect(blockOpts).toMatchObject({
+      abortSignal: expect.any(AbortSignal),
+      timeoutMs: expect.any(Number),
+    });
+  });
+
+  it("signals typing on tool results", async () => {
+    const onToolResult = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onToolResult?.({ text: "tooling", mediaUrls: [] });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "message",
+      opts: { onToolResult },
+    });
+    await run();
+
+    expect(typing.startTypingOnText).toHaveBeenCalledWith("tooling");
+    expect(onToolResult).toHaveBeenCalledWith({
+      text: "tooling",
+      mediaUrls: [],
+    });
+  });
+
+  it("skips typing for silent tool results", async () => {
+    const onToolResult = vi.fn();
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+      await params.onToolResult?.({ text: "NO_REPLY", mediaUrls: [] });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const { run, typing } = createMinimalRun({
+      typingMode: "message",
+      opts: { onToolResult },
+    });
+    await run();
+
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+    expect(onToolResult).not.toHaveBeenCalled();
+  });
+
+  it("announces auto-compaction in verbose mode and tracks count", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const sessionEntry = { sessionId: "session", updatedAt: Date.now() };
+      const sessionStore = { main: sessionEntry };
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async (params: AgentRunParams) => {
+        params.onAgentEvent?.({
+          stream: "compaction",
+          data: { phase: "end", willRetry: false },
+        });
+        return { payloads: [{ text: "final" }], meta: {} };
+      });
+
+      const { run } = createMinimalRun({
+        resolvedVerboseLevel: "on",
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+      expect(Array.isArray(res)).toBe(true);
+      const payloads = res as { text?: string }[];
+      expect(payloads[0]?.text).toContain("Auto-compaction complete");
+      expect(payloads[0]?.text).toContain("count 1");
+      expect(sessionStore.main.compactionCount).toBe(1);
+    });
+  });
+
+  it("retries after compaction failure by resetting the session", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const sessionId = "session";
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
+      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
+      const sessionStore = { main: sessionEntry };
+
+      await fs.mkdir(path.dirname(storePath), { recursive: true });
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, "ok", "utf-8");
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+        throw new Error(
+          'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
+        );
+      });
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+
+      expect(state.runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
+      const payload = Array.isArray(res) ? res[0] : res;
+      expect(payload).toMatchObject({
+        text: expect.stringContaining("Context limit exceeded during compaction"),
+      });
+      expect(payload.text?.toLowerCase()).toContain("reset");
+      expect(sessionStore.main.sessionId).not.toBe(sessionId);
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
+    });
+  });
+
+  it("retries after context overflow payload by resetting the session", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const sessionId = "session";
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
+      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
+      const sessionStore = { main: sessionEntry };
+
+      await fs.mkdir(path.dirname(storePath), { recursive: true });
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, "ok", "utf-8");
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
+        payloads: [{ text: "Context overflow: prompt too large", isError: true }],
+        meta: {
+          durationMs: 1,
+          error: {
+            kind: "context_overflow",
+            message: 'Context overflow: Summarization failed: 400 {"message":"prompt is too long"}',
+          },
+        },
+      }));
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+
+      expect(state.runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
+      const payload = Array.isArray(res) ? res[0] : res;
+      expect(payload).toMatchObject({
+        text: expect.stringContaining("Context limit exceeded"),
+      });
+      expect(payload.text?.toLowerCase()).toContain("reset");
+      expect(sessionStore.main.sessionId).not.toBe(sessionId);
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
+    });
+  });
+
+  it("resets the session after role ordering payloads", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const sessionId = "session";
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
+      const sessionEntry = { sessionId, updatedAt: Date.now(), sessionFile: transcriptPath };
+      const sessionStore = { main: sessionEntry };
+
+      await fs.mkdir(path.dirname(storePath), { recursive: true });
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, "ok", "utf-8");
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
+        payloads: [{ text: "Message ordering conflict - please try again.", isError: true }],
+        meta: {
+          durationMs: 1,
+          error: {
+            kind: "role_ordering",
+            message: 'messages: roles must alternate between "user" and "assistant"',
+          },
+        },
+      }));
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+
+      const payload = Array.isArray(res) ? res[0] : res;
+      expect(payload).toMatchObject({
+        text: expect.stringContaining("Message ordering conflict"),
+      });
+      expect(payload.text?.toLowerCase()).toContain("reset");
+      expect(sessionStore.main.sessionId).not.toBe(sessionId);
+      await expect(fs.access(transcriptPath)).rejects.toBeDefined();
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main.sessionId).toBe(sessionStore.main.sessionId);
+    });
+  });
+
+  it("resets corrupted Gemini sessions and deletes transcripts", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const { storePath, sessionEntry, sessionStore, transcriptPath } =
+        await writeCorruptGeminiSessionFixture({
+          stateDir,
+          sessionId: "session-corrupt",
+          persistStore: true,
+        });
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+        throw new Error(
+          "function call turn comes immediately after a user turn or after a function response turn",
+        );
+      });
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+
+      expect(res).toMatchObject({
+        text: expect.stringContaining("Session history was corrupted"),
+      });
+      expect(sessionStore.main).toBeUndefined();
+      await expect(fs.access(transcriptPath)).rejects.toThrow();
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main).toBeUndefined();
+    });
+  });
+
+  it("keeps sessions intact on other errors", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const sessionId = "session-ok";
+      const storePath = path.join(stateDir, "sessions", "sessions.json");
+      const sessionEntry = { sessionId, updatedAt: Date.now() };
+      const sessionStore = { main: sessionEntry };
+
+      await fs.mkdir(path.dirname(storePath), { recursive: true });
+      await fs.writeFile(storePath, JSON.stringify(sessionStore), "utf-8");
+
+      const transcriptPath = sessions.resolveSessionTranscriptPath(sessionId);
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, "ok", "utf-8");
+
+      state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+        throw new Error("INVALID_ARGUMENT: some other failure");
+      });
+
+      const { run } = createMinimalRun({
+        sessionEntry,
+        sessionStore,
+        sessionKey: "main",
+        storePath,
+      });
+      const res = await run();
+
+      expect(res).toMatchObject({
+        text: expect.stringContaining("Agent failed before reply"),
+      });
+      expect(sessionStore.main).toBeDefined();
+      await expect(fs.access(transcriptPath)).resolves.toBeUndefined();
+
+      const persisted = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(persisted.main).toBeDefined();
+    });
+  });
+
+  it("still replies even if session reset fails to persist", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const saveSpy = vi
+        .spyOn(sessions, "saveSessionStore")
+        .mockRejectedValueOnce(new Error("boom"));
+      try {
+        const { storePath, sessionEntry, sessionStore, transcriptPath } =
+          await writeCorruptGeminiSessionFixture({
+            stateDir,
+            sessionId: "session-corrupt",
+            persistStore: false,
+          });
+
+        state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+          throw new Error(
+            "function call turn comes immediately after a user turn or after a function response turn",
+          );
+        });
+
+        const { run } = createMinimalRun({
+          sessionEntry,
+          sessionStore,
+          sessionKey: "main",
+          storePath,
+        });
+        const res = await run();
+
+        expect(res).toMatchObject({
+          text: expect.stringContaining("Session history was corrupted"),
+        });
+        expect(sessionStore.main).toBeUndefined();
+        await expect(fs.access(transcriptPath)).rejects.toThrow();
+      } finally {
+        saveSpy.mockRestore();
+      }
+    });
+  });
+
+  it("returns friendly message for role ordering errors thrown as exceptions", async () => {
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => {
+      throw new Error("400 Incorrect role information");
+    });
+
+    const { run } = createMinimalRun({});
+    const res = await run();
+
+    expect(res).toMatchObject({
+      text: expect.stringContaining("Message ordering conflict"),
+    });
+    expect(res).toMatchObject({
+      text: expect.not.stringContaining("400"),
+    });
+  });
+
+  it("rewrites Bun socket errors into friendly text", async () => {
+    state.runEmbeddedPiAgentMock.mockImplementationOnce(async () => ({
+      payloads: [
+        {
+          text: "TypeError: The socket connection was closed unexpectedly. For more information, pass `verbose: true` in the second argument to fetch()",
+          isError: true,
+        },
+      ],
+      meta: {},
+    }));
+
+    const { run } = createMinimalRun();
+    const res = await run();
+    const payloads = Array.isArray(res) ? res : res ? [res] : [];
+    expect(payloads.length).toBe(1);
+    expect(payloads[0]?.text).toContain("LLM connection failed");
+    expect(payloads[0]?.text).toContain("socket connection was closed unexpectedly");
+    expect(payloads[0]?.text).toContain("```");
+  });
+});
+
+describe("runReplyAgent memory flush", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
+
+  async function withTempStore<T>(fn: (storePath: string) => Promise<T>): Promise<T> {
+    const dir = path.join(fixtureRoot, `case-${++caseId}`);
+    await fs.mkdir(dir, { recursive: true });
+    return await fn(path.join(dir, "sessions.json"));
+  }
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(tmpdir(), "openclaw-memory-flush-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("skips memory flush for CLI providers", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "main";
+      const sessionEntry = {
+        sessionId: "session",
+        updatedAt: Date.now(),
+        totalTokens: 80_000,
+        compactionCount: 1,
+      };
+
+      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
+
+      state.runEmbeddedPiAgentMock.mockImplementation(async () => ({
+        payloads: [{ text: "ok" }],
+        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+      }));
+      state.runCliAgentMock.mockResolvedValue({
+        payloads: [{ text: "ok" }],
+        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+      });
+
+      const baseRun = createBaseRun({
+        storePath,
+        sessionEntry,
+        runOverrides: { provider: "codex-cli" },
+      });
+
+      await runReplyAgentWithBase({
+        baseRun,
+        storePath,
+        sessionKey,
+        sessionEntry,
+        commandBody: "hello",
+      });
+
+      expect(state.runCliAgentMock).toHaveBeenCalledTimes(1);
+      const call = state.runCliAgentMock.mock.calls[0]?.[0] as { prompt?: string } | undefined;
+      expect(call?.prompt).toBe("hello");
+      expect(state.runEmbeddedPiAgentMock).not.toHaveBeenCalled();
+    });
+  });
+
+  it("runs a memory flush turn and updates session metadata", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "main";
+      const sessionEntry = {
+        sessionId: "session",
+        updatedAt: Date.now(),
+        totalTokens: 80_000,
+        compactionCount: 1,
+      };
+
+      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
+
+      const calls: Array<{ prompt?: string }> = [];
+      state.runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
+        calls.push({ prompt: params.prompt });
+        if (params.prompt?.includes("Pre-compaction memory flush.")) {
+          return { payloads: [], meta: {} };
+        }
+        return {
+          payloads: [{ text: "ok" }],
+          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+        };
+      });
+
+      const baseRun = createBaseRun({
+        storePath,
+        sessionEntry,
+      });
+
+      await runReplyAgentWithBase({
+        baseRun,
+        storePath,
+        sessionKey,
+        sessionEntry,
+        commandBody: "hello",
+      });
+
+      expect(calls).toHaveLength(2);
+      expect(calls[0]?.prompt).toContain("Pre-compaction memory flush.");
+      expect(calls[0]?.prompt).toContain("Current time:");
+      expect(calls[0]?.prompt).toMatch(/memory\/\d{4}-\d{2}-\d{2}\.md/);
+      expect(calls[1]?.prompt).toBe("hello");
+
+      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(stored[sessionKey].memoryFlushAt).toBeTypeOf("number");
+      expect(stored[sessionKey].memoryFlushCompactionCount).toBe(1);
+    });
+  });
+
+  it("skips memory flush when disabled in config", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "main";
+      const sessionEntry = {
+        sessionId: "session",
+        updatedAt: Date.now(),
+        totalTokens: 80_000,
+        compactionCount: 1,
+      };
+
+      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
+
+      state.runEmbeddedPiAgentMock.mockImplementation(async () => ({
+        payloads: [{ text: "ok" }],
+        meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+      }));
+
+      const baseRun = createBaseRun({
+        storePath,
+        sessionEntry,
+        config: { agents: { defaults: { compaction: { memoryFlush: { enabled: false } } } } },
+      });
+
+      await runReplyAgentWithBase({
+        baseRun,
+        storePath,
+        sessionKey,
+        sessionEntry,
+        commandBody: "hello",
+      });
+
+      expect(state.runEmbeddedPiAgentMock).toHaveBeenCalledTimes(1);
+      const call = state.runEmbeddedPiAgentMock.mock.calls[0]?.[0] as
+        | { prompt?: string }
+        | undefined;
+      expect(call?.prompt).toBe("hello");
+
+      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(stored[sessionKey].memoryFlushAt).toBeUndefined();
+    });
+  });
+
+  it("skips memory flush after a prior flush in the same compaction cycle", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "main";
+      const sessionEntry = {
+        sessionId: "session",
+        updatedAt: Date.now(),
+        totalTokens: 80_000,
+        compactionCount: 2,
+        memoryFlushCompactionCount: 2,
+      };
+
+      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
+
+      const calls: Array<{ prompt?: string }> = [];
+      state.runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
+        calls.push({ prompt: params.prompt });
+        return {
+          payloads: [{ text: "ok" }],
+          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+        };
+      });
+
+      const baseRun = createBaseRun({
+        storePath,
+        sessionEntry,
+      });
+
+      await runReplyAgentWithBase({
+        baseRun,
+        storePath,
+        sessionKey,
+        sessionEntry,
+        commandBody: "hello",
+      });
+
+      expect(calls.map((call) => call.prompt)).toEqual(["hello"]);
+    });
+  });
+
+  it("increments compaction count when flush compaction completes", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "main";
+      const sessionEntry = {
+        sessionId: "session",
+        updatedAt: Date.now(),
+        totalTokens: 80_000,
+        compactionCount: 1,
+      };
+
+      await seedSessionStore({ storePath, sessionKey, entry: sessionEntry });
+
+      state.runEmbeddedPiAgentMock.mockImplementation(async (params: EmbeddedRunParams) => {
+        if (params.prompt?.includes("Pre-compaction memory flush.")) {
+          params.onAgentEvent?.({
+            stream: "compaction",
+            data: { phase: "end", willRetry: false },
+          });
+          return { payloads: [], meta: {} };
+        }
+        return {
+          payloads: [{ text: "ok" }],
+          meta: { agentMeta: { usage: { input: 1, output: 1 } } },
+        };
+      });
+
+      const baseRun = createBaseRun({
+        storePath,
+        sessionEntry,
+      });
+
+      await runReplyAgentWithBase({
+        baseRun,
+        storePath,
+        sessionKey,
+        sessionEntry,
+        commandBody: "hello",
+      });
+
+      const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+      expect(stored[sessionKey].compactionCount).toBe(2);
+      expect(stored[sessionKey].memoryFlushCompactionCount).toBe(2);
+    });
+  });
+});
diff --git a/src/auto-reply/reply/agent-runner.test-harness.mocks.ts b/src/auto-reply/reply/agent-runner.test-harness.mocks.ts
deleted file mode 100644
index 01888f761de..00000000000
--- a/src/auto-reply/reply/agent-runner.test-harness.mocks.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { vi } from "vitest";
-
-export function modelFallbackMockFactory(): Record<string, unknown> {
-  return {
-    runWithModelFallback: async ({
-      provider,
-      model,
-      run,
-    }: {
-      provider: string;
-      model: string;
-      run: (provider: string, model: string) => Promise<unknown>;
-    }) => ({
-      result: await run(provider, model),
-      provider,
-      model,
-    }),
-  };
-}
-
-export function embeddedPiMockFactory(state: {
-  runEmbeddedPiAgentMock: (params: unknown) => unknown;
-}): Record<string, unknown> {
-  return {
-    queueEmbeddedPiMessage: vi.fn().mockReturnValue(false),
-    runEmbeddedPiAgent: (params: unknown) => state.runEmbeddedPiAgentMock(params),
-  };
-}
-
-export async function queueMockFactory(): Promise<Record<string, unknown>> {
-  const actual = await vi.importActual<typeof import("./queue.js")>("./queue.js");
-  return {
-    ...actual,
-    enqueueFollowupRun: vi.fn(),
-    scheduleFollowupDrain: vi.fn(),
-  };
-}
diff --git a/src/auto-reply/reply/agent-runner.ts b/src/auto-reply/reply/agent-runner.ts
index 73a380e705c..c8f8eba129a 100644
--- a/src/auto-reply/reply/agent-runner.ts
+++ b/src/auto-reply/reply/agent-runner.ts
@@ -157,22 +157,26 @@ export async function runReplyAgent(params: {
           buffer: createAudioAsVoiceBuffer({ isAudioPayload }),
         })
       : null;
+  const touchActiveSessionEntry = async () => {
+    if (!activeSessionEntry || !activeSessionStore || !sessionKey) {
+      return;
+    }
+    const updatedAt = Date.now();
+    activeSessionEntry.updatedAt = updatedAt;
+    activeSessionStore[sessionKey] = activeSessionEntry;
+    if (storePath) {
+      await updateSessionStoreEntry({
+        storePath,
+        sessionKey,
+        update: async () => ({ updatedAt }),
+      });
+    }
+  };
 
   if (shouldSteer && isStreaming) {
     const steered = queueEmbeddedPiMessage(followupRun.run.sessionId, followupRun.prompt);
     if (steered && !shouldFollowup) {
-      if (activeSessionEntry && activeSessionStore && sessionKey) {
-        const updatedAt = Date.now();
-        activeSessionEntry.updatedAt = updatedAt;
-        activeSessionStore[sessionKey] = activeSessionEntry;
-        if (storePath) {
-          await updateSessionStoreEntry({
-            storePath,
-            sessionKey,
-            update: async () => ({ updatedAt }),
-          });
-        }
-      }
+      await touchActiveSessionEntry();
       typing.cleanup();
       return undefined;
     }
@@ -180,18 +184,7 @@ export async function runReplyAgent(params: {
 
   if (isActive && (shouldFollowup || resolvedQueue.mode === "steer")) {
     enqueueFollowupRun(queueKey, followupRun, resolvedQueue);
-    if (activeSessionEntry && activeSessionStore && sessionKey) {
-      const updatedAt = Date.now();
-      activeSessionEntry.updatedAt = updatedAt;
-      activeSessionStore[sessionKey] = activeSessionEntry;
-      if (storePath) {
-        await updateSessionStoreEntry({
-          storePath,
-          sessionKey,
-          update: async () => ({ updatedAt }),
-        });
-      }
-    }
+    await touchActiveSessionEntry();
     typing.cleanup();
     return undefined;
   }
@@ -457,6 +450,7 @@ export async function runReplyAgent(params: {
           promptTokens,
           total: totalTokens,
         },
+        lastCallUsage: runResult.meta.agentMeta?.lastCallUsage,
         context: {
           limit: contextTokensUsed,
           used: totalTokens,
diff --git a/src/auto-reply/reply/commands-approve.test.ts b/src/auto-reply/reply/commands-approve.test.ts
deleted file mode 100644
index cfb1f3cb7f0..00000000000
--- a/src/auto-reply/reply/commands-approve.test.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { callGateway } from "../../gateway/call.js";
-import { handleCommands } from "./commands.js";
-import { buildCommandTestParams } from "./commands.test-harness.js";
-
-vi.mock("../../gateway/call.js", () => ({
-  callGateway: vi.fn(),
-}));
-
-describe("/approve command", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("rejects invalid usage", async () => {
-    const cfg = {
-      commands: { text: true },
-      channels: { whatsapp: { allowFrom: ["*"] } },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/approve", cfg);
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Usage: /approve");
-  });
-
-  it("submits approval", async () => {
-    const cfg = {
-      commands: { text: true },
-      channels: { whatsapp: { allowFrom: ["*"] } },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/approve abc allow-once", cfg, { SenderId: "123" });
-
-    const mockCallGateway = vi.mocked(callGateway);
-    mockCallGateway.mockResolvedValueOnce({ ok: true });
-
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
-    expect(mockCallGateway).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "exec.approval.resolve",
-        params: { id: "abc", decision: "allow-once" },
-      }),
-    );
-  });
-
-  it("rejects gateway clients without approvals scope", async () => {
-    const cfg = {
-      commands: { text: true },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/approve abc allow-once", cfg, {
-      Provider: "webchat",
-      Surface: "webchat",
-      GatewayClientScopes: ["operator.write"],
-    });
-
-    const mockCallGateway = vi.mocked(callGateway);
-    mockCallGateway.mockResolvedValueOnce({ ok: true });
-
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("requires operator.approvals");
-    expect(mockCallGateway).not.toHaveBeenCalled();
-  });
-
-  it("allows gateway clients with approvals scope", async () => {
-    const cfg = {
-      commands: { text: true },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/approve abc allow-once", cfg, {
-      Provider: "webchat",
-      Surface: "webchat",
-      GatewayClientScopes: ["operator.approvals"],
-    });
-
-    const mockCallGateway = vi.mocked(callGateway);
-    mockCallGateway.mockResolvedValueOnce({ ok: true });
-
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
-    expect(mockCallGateway).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "exec.approval.resolve",
-        params: { id: "abc", decision: "allow-once" },
-      }),
-    );
-  });
-
-  it("allows gateway clients with admin scope", async () => {
-    const cfg = {
-      commands: { text: true },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/approve abc allow-once", cfg, {
-      Provider: "webchat",
-      Surface: "webchat",
-      GatewayClientScopes: ["operator.admin"],
-    });
-
-    const mockCallGateway = vi.mocked(callGateway);
-    mockCallGateway.mockResolvedValueOnce({ ok: true });
-
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
-    expect(mockCallGateway).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "exec.approval.resolve",
-        params: { id: "abc", decision: "allow-once" },
-      }),
-    );
-  });
-});
diff --git a/src/auto-reply/reply/commands-compact.test.ts b/src/auto-reply/reply/commands-compact.test.ts
deleted file mode 100644
index 7c418ac239a..00000000000
--- a/src/auto-reply/reply/commands-compact.test.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { compactEmbeddedPiSession } from "../../agents/pi-embedded.js";
-import { handleCompactCommand } from "./commands-compact.js";
-import { buildCommandTestParams } from "./commands.test-harness.js";
-
-vi.mock("../../agents/pi-embedded.js", () => ({
-  abortEmbeddedPiRun: vi.fn(),
-  compactEmbeddedPiSession: vi.fn(),
-  isEmbeddedPiRunActive: vi.fn().mockReturnValue(false),
-  waitForEmbeddedPiRunEnd: vi.fn().mockResolvedValue(undefined),
-}));
-
-vi.mock("../../infra/system-events.js", () => ({
-  enqueueSystemEvent: vi.fn(),
-}));
-
-vi.mock("./session-updates.js", () => ({
-  incrementCompactionCount: vi.fn(),
-}));
-
-describe("/compact command", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("returns null when command is not /compact", async () => {
-    const cfg = {
-      commands: { text: true },
-      channels: { whatsapp: { allowFrom: ["*"] } },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/status", cfg);
-
-    const result = await handleCompactCommand(
-      {
-        ...params,
-      },
-      true,
-    );
-
-    expect(result).toBeNull();
-    expect(vi.mocked(compactEmbeddedPiSession)).not.toHaveBeenCalled();
-  });
-
-  it("rejects unauthorized /compact commands", async () => {
-    const cfg = {
-      commands: { text: true },
-      channels: { whatsapp: { allowFrom: ["*"] } },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/compact", cfg);
-
-    const result = await handleCompactCommand(
-      {
-        ...params,
-        command: {
-          ...params.command,
-          isAuthorizedSender: false,
-          senderId: "unauthorized",
-        },
-      },
-      true,
-    );
-
-    expect(result).toEqual({ shouldContinue: false });
-    expect(vi.mocked(compactEmbeddedPiSession)).not.toHaveBeenCalled();
-  });
-
-  it("routes manual compaction with explicit trigger and context metadata", async () => {
-    const cfg = {
-      commands: { text: true },
-      channels: { whatsapp: { allowFrom: ["*"] } },
-      session: { store: "/tmp/openclaw-session-store.json" },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams("/compact: focus on decisions", cfg, {
-      From: "+15550001",
-      To: "+15550002",
-    });
-    vi.mocked(compactEmbeddedPiSession).mockResolvedValueOnce({
-      ok: true,
-      compacted: false,
-    });
-
-    const result = await handleCompactCommand(
-      {
-        ...params,
-        sessionEntry: {
-          sessionId: "session-1",
-          groupId: "group-1",
-          groupChannel: "#general",
-          space: "workspace-1",
-          spawnedBy: "agent:main:parent",
-          totalTokens: 12345,
-        },
-      },
-      true,
-    );
-
-    expect(result?.shouldContinue).toBe(false);
-    expect(vi.mocked(compactEmbeddedPiSession)).toHaveBeenCalledOnce();
-    expect(vi.mocked(compactEmbeddedPiSession)).toHaveBeenCalledWith(
-      expect.objectContaining({
-        sessionId: "session-1",
-        sessionKey: "agent:main:main",
-        trigger: "manual",
-        customInstructions: "focus on decisions",
-        messageChannel: "whatsapp",
-        groupId: "group-1",
-        groupChannel: "#general",
-        groupSpace: "workspace-1",
-        spawnedBy: "agent:main:parent",
-      }),
-    );
-  });
-});
diff --git a/src/auto-reply/reply/commands-info.test.ts b/src/auto-reply/reply/commands-info.test.ts
deleted file mode 100644
index 9751c39cca5..00000000000
--- a/src/auto-reply/reply/commands-info.test.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildCommandsPaginationKeyboard } from "./commands-info.js";
-
-describe("buildCommandsPaginationKeyboard", () => {
-  it("adds agent id to callback data when provided", () => {
-    const keyboard = buildCommandsPaginationKeyboard(2, 3, "agent-main");
-    expect(keyboard[0]).toEqual([
-      { text: "◀ Prev", callback_data: "commands_page_1:agent-main" },
-      { text: "2/3", callback_data: "commands_page_noop:agent-main" },
-      { text: "Next ▶", callback_data: "commands_page_3:agent-main" },
-    ]);
-  });
-});
diff --git a/src/auto-reply/reply/commands-parsing.test.ts b/src/auto-reply/reply/commands-parsing.test.ts
deleted file mode 100644
index 47309f93217..00000000000
--- a/src/auto-reply/reply/commands-parsing.test.ts
+++ /dev/null
@@ -1,85 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { extractMessageText } from "./commands-subagents.js";
-import { handleCommands } from "./commands.js";
-import { buildCommandTestParams } from "./commands.test-harness.js";
-import { parseConfigCommand } from "./config-commands.js";
-import { parseDebugCommand } from "./debug-commands.js";
-
-describe("parseConfigCommand", () => {
-  it("parses show/unset", () => {
-    expect(parseConfigCommand("/config")).toEqual({ action: "show" });
-    expect(parseConfigCommand("/config show")).toEqual({
-      action: "show",
-      path: undefined,
-    });
-    expect(parseConfigCommand("/config show foo.bar")).toEqual({
-      action: "show",
-      path: "foo.bar",
-    });
-    expect(parseConfigCommand("/config get foo.bar")).toEqual({
-      action: "show",
-      path: "foo.bar",
-    });
-    expect(parseConfigCommand("/config unset foo.bar")).toEqual({
-      action: "unset",
-      path: "foo.bar",
-    });
-  });
-
-  it("parses set with JSON", () => {
-    const cmd = parseConfigCommand('/config set foo={"a":1}');
-    expect(cmd).toEqual({ action: "set", path: "foo", value: { a: 1 } });
-  });
-});
-
-describe("parseDebugCommand", () => {
-  it("parses show/reset", () => {
-    expect(parseDebugCommand("/debug")).toEqual({ action: "show" });
-    expect(parseDebugCommand("/debug show")).toEqual({ action: "show" });
-    expect(parseDebugCommand("/debug reset")).toEqual({ action: "reset" });
-  });
-
-  it("parses set with JSON", () => {
-    const cmd = parseDebugCommand('/debug set foo={"a":1}');
-    expect(cmd).toEqual({ action: "set", path: "foo", value: { a: 1 } });
-  });
-
-  it("parses unset", () => {
-    const cmd = parseDebugCommand("/debug unset foo.bar");
-    expect(cmd).toEqual({ action: "unset", path: "foo.bar" });
-  });
-});
-
-describe("extractMessageText", () => {
-  it("preserves user text that looks like tool call markers", () => {
-    const message = {
-      role: "user",
-      content: "Here [Tool Call: foo (ID: 1)] ok",
-    };
-    const result = extractMessageText(message);
-    expect(result?.text).toContain("[Tool Call: foo (ID: 1)]");
-  });
-
-  it("sanitizes assistant tool call markers", () => {
-    const message = {
-      role: "assistant",
-      content: "Here [Tool Call: foo (ID: 1)] ok",
-    };
-    const result = extractMessageText(message);
-    expect(result?.text).toBe("Here ok");
-  });
-});
-
-describe("handleCommands /config configWrites gating", () => {
-  it("blocks /config set when channel config writes are disabled", async () => {
-    const cfg = {
-      commands: { config: true, text: true },
-      channels: { whatsapp: { allowFrom: ["*"], configWrites: false } },
-    } as OpenClawConfig;
-    const params = buildCommandTestParams('/config set messages.ackReaction=":)"', cfg);
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Config writes are disabled");
-  });
-});
diff --git a/src/auto-reply/reply/commands-policy.test.ts b/src/auto-reply/reply/commands-policy.test.ts
deleted file mode 100644
index c93b818e25f..00000000000
--- a/src/auto-reply/reply/commands-policy.test.ts
+++ /dev/null
@@ -1,335 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import type { MsgContext } from "../templating.js";
-import { buildCommandContext, handleCommands } from "./commands.js";
-import { parseInlineDirectives } from "./directive-handling.js";
-
-const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn());
-const validateConfigObjectWithPluginsMock = vi.hoisted(() => vi.fn());
-const writeConfigFileMock = vi.hoisted(() => vi.fn());
-
-vi.mock("../../config/config.js", async () => {
-  const actual =
-    await vi.importActual<typeof import("../../config/config.js")>("../../config/config.js");
-  return {
-    ...actual,
-    readConfigFileSnapshot: readConfigFileSnapshotMock,
-    validateConfigObjectWithPlugins: validateConfigObjectWithPluginsMock,
-    writeConfigFile: writeConfigFileMock,
-  };
-});
-
-const readChannelAllowFromStoreMock = vi.hoisted(() => vi.fn());
-const addChannelAllowFromStoreEntryMock = vi.hoisted(() => vi.fn());
-const removeChannelAllowFromStoreEntryMock = vi.hoisted(() => vi.fn());
-
-vi.mock("../../pairing/pairing-store.js", async () => {
-  const actual = await vi.importActual<typeof import("../../pairing/pairing-store.js")>(
-    "../../pairing/pairing-store.js",
-  );
-  return {
-    ...actual,
-    readChannelAllowFromStore: readChannelAllowFromStoreMock,
-    addChannelAllowFromStoreEntry: addChannelAllowFromStoreEntryMock,
-    removeChannelAllowFromStoreEntry: removeChannelAllowFromStoreEntryMock,
-  };
-});
-
-vi.mock("../../channels/plugins/pairing.js", async () => {
-  const actual = await vi.importActual<typeof import("../../channels/plugins/pairing.js")>(
-    "../../channels/plugins/pairing.js",
-  );
-  return {
-    ...actual,
-    listPairingChannels: () => ["telegram"],
-  };
-});
-
-vi.mock("../../agents/model-catalog.js", () => ({
-  loadModelCatalog: vi.fn(async () => [
-    { provider: "anthropic", id: "claude-opus-4-5", name: "Claude Opus" },
-    { provider: "anthropic", id: "claude-sonnet-4-5", name: "Claude Sonnet" },
-    { provider: "openai", id: "gpt-4.1", name: "GPT-4.1" },
-    { provider: "openai", id: "gpt-4.1-mini", name: "GPT-4.1 Mini" },
-    { provider: "google", id: "gemini-2.0-flash", name: "Gemini Flash" },
-  ]),
-}));
-
-function buildParams(commandBody: string, cfg: OpenClawConfig, ctxOverrides?: Partial<MsgContext>) {
-  const ctx = {
-    Body: commandBody,
-    CommandBody: commandBody,
-    CommandSource: "text",
-    CommandAuthorized: true,
-    Provider: "telegram",
-    Surface: "telegram",
-    ...ctxOverrides,
-  } as MsgContext;
-
-  const command = buildCommandContext({
-    ctx,
-    cfg,
-    isGroup: false,
-    triggerBodyNormalized: commandBody.trim().toLowerCase(),
-    commandAuthorized: true,
-  });
-
-  return {
-    ctx,
-    cfg,
-    command,
-    directives: parseInlineDirectives(commandBody),
-    elevated: { enabled: true, allowed: true, failures: [] },
-    sessionKey: "agent:main:main",
-    workspaceDir: "/tmp",
-    defaultGroupActivation: () => "mention",
-    resolvedVerboseLevel: "off" as const,
-    resolvedReasoningLevel: "off" as const,
-    resolveDefaultThinkingLevel: async () => undefined,
-    provider: "telegram",
-    model: "test-model",
-    contextTokens: 0,
-    isGroup: false,
-  };
-}
-
-describe("handleCommands /allowlist", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("lists config + store allowFrom entries", async () => {
-    readChannelAllowFromStoreMock.mockResolvedValueOnce(["456"]);
-
-    const cfg = {
-      commands: { text: true },
-      channels: { telegram: { allowFrom: ["123", "@Alice"] } },
-    } as OpenClawConfig;
-    const params = buildParams("/allowlist list dm", cfg);
-    const result = await handleCommands(params);
-
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Channel: telegram");
-    expect(result.reply?.text).toContain("DM allowFrom (config): 123, @alice");
-    expect(result.reply?.text).toContain("Paired allowFrom (store): 456");
-  });
-
-  it("adds entries to config and pairing store", async () => {
-    readConfigFileSnapshotMock.mockResolvedValueOnce({
-      valid: true,
-      parsed: {
-        channels: { telegram: { allowFrom: ["123"] } },
-      },
-    });
-    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
-      ok: true,
-      config,
-    }));
-    addChannelAllowFromStoreEntryMock.mockResolvedValueOnce({
-      changed: true,
-      allowFrom: ["123", "789"],
-    });
-
-    const cfg = {
-      commands: { text: true, config: true },
-      channels: { telegram: { allowFrom: ["123"] } },
-    } as OpenClawConfig;
-    const params = buildParams("/allowlist add dm 789", cfg);
-    const result = await handleCommands(params);
-
-    expect(result.shouldContinue).toBe(false);
-    expect(writeConfigFileMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        channels: { telegram: { allowFrom: ["123", "789"] } },
-      }),
-    );
-    expect(addChannelAllowFromStoreEntryMock).toHaveBeenCalledWith({
-      channel: "telegram",
-      entry: "789",
-    });
-    expect(result.reply?.text).toContain("DM allowlist added");
-  });
-
-  it("removes Slack DM allowlist entries from canonical allowFrom and deletes legacy dm.allowFrom", async () => {
-    readConfigFileSnapshotMock.mockResolvedValueOnce({
-      valid: true,
-      parsed: {
-        channels: {
-          slack: {
-            allowFrom: ["U111", "U222"],
-            dm: { allowFrom: ["U111", "U222"] },
-            configWrites: true,
-          },
-        },
-      },
-    });
-    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
-      ok: true,
-      config,
-    }));
-
-    const cfg = {
-      commands: { text: true, config: true },
-      channels: {
-        slack: {
-          allowFrom: ["U111", "U222"],
-          dm: { allowFrom: ["U111", "U222"] },
-          configWrites: true,
-        },
-      },
-    } as OpenClawConfig;
-
-    const params = buildParams("/allowlist remove dm U111", cfg, {
-      Provider: "slack",
-      Surface: "slack",
-    });
-    const result = await handleCommands(params);
-
-    expect(result.shouldContinue).toBe(false);
-    expect(writeConfigFileMock).toHaveBeenCalledTimes(1);
-    const written = writeConfigFileMock.mock.calls[0]?.[0] as OpenClawConfig;
-    expect(written.channels?.slack?.allowFrom).toEqual(["U222"]);
-    expect(written.channels?.slack?.dm?.allowFrom).toBeUndefined();
-    expect(result.reply?.text).toContain("channels.slack.allowFrom");
-  });
-
-  it("removes Discord DM allowlist entries from canonical allowFrom and deletes legacy dm.allowFrom", async () => {
-    readConfigFileSnapshotMock.mockResolvedValueOnce({
-      valid: true,
-      parsed: {
-        channels: {
-          discord: {
-            allowFrom: ["111", "222"],
-            dm: { allowFrom: ["111", "222"] },
-            configWrites: true,
-          },
-        },
-      },
-    });
-    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
-      ok: true,
-      config,
-    }));
-
-    const cfg = {
-      commands: { text: true, config: true },
-      channels: {
-        discord: {
-          allowFrom: ["111", "222"],
-          dm: { allowFrom: ["111", "222"] },
-          configWrites: true,
-        },
-      },
-    } as OpenClawConfig;
-
-    const params = buildParams("/allowlist remove dm 111", cfg, {
-      Provider: "discord",
-      Surface: "discord",
-    });
-    const result = await handleCommands(params);
-
-    expect(result.shouldContinue).toBe(false);
-    expect(writeConfigFileMock).toHaveBeenCalledTimes(1);
-    const written = writeConfigFileMock.mock.calls[0]?.[0] as OpenClawConfig;
-    expect(written.channels?.discord?.allowFrom).toEqual(["222"]);
-    expect(written.channels?.discord?.dm?.allowFrom).toBeUndefined();
-    expect(result.reply?.text).toContain("channels.discord.allowFrom");
-  });
-});
-
-describe("/models command", () => {
-  const cfg = {
-    commands: { text: true },
-    agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
-  } as unknown as OpenClawConfig;
-
-  it.each(["discord", "whatsapp"])("lists providers on %s (text)", async (surface) => {
-    const params = buildParams("/models", cfg, { Provider: surface, Surface: surface });
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Providers:");
-    expect(result.reply?.text).toContain("anthropic");
-    expect(result.reply?.text).toContain("Use: /models <provider>");
-  });
-
-  it("lists providers on telegram (buttons)", async () => {
-    const params = buildParams("/models", cfg, { Provider: "telegram", Surface: "telegram" });
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toBe("Select a provider:");
-    const buttons = (result.reply?.channelData as { telegram?: { buttons?: unknown[][] } })
-      ?.telegram?.buttons;
-    expect(buttons).toBeDefined();
-    expect(buttons?.length).toBeGreaterThan(0);
-  });
-
-  it("lists provider models with pagination hints", async () => {
-    // Use discord surface for text-based output tests
-    const params = buildParams("/models anthropic", cfg, { Surface: "discord" });
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Models (anthropic)");
-    expect(result.reply?.text).toContain("page 1/");
-    expect(result.reply?.text).toContain("anthropic/claude-opus-4-5");
-    expect(result.reply?.text).toContain("Switch: /model <provider/model>");
-    expect(result.reply?.text).toContain("All: /models anthropic all");
-  });
-
-  it("ignores page argument when all flag is present", async () => {
-    // Use discord surface for text-based output tests
-    const params = buildParams("/models anthropic 3 all", cfg, { Surface: "discord" });
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Models (anthropic)");
-    expect(result.reply?.text).toContain("page 1/1");
-    expect(result.reply?.text).toContain("anthropic/claude-opus-4-5");
-    expect(result.reply?.text).not.toContain("Page out of range");
-  });
-
-  it("errors on out-of-range pages", async () => {
-    // Use discord surface for text-based output tests
-    const params = buildParams("/models anthropic 4", cfg, { Surface: "discord" });
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Page out of range");
-    expect(result.reply?.text).toContain("valid: 1-");
-  });
-
-  it("handles unknown providers", async () => {
-    const params = buildParams("/models not-a-provider", cfg);
-    const result = await handleCommands(params);
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Unknown provider");
-    expect(result.reply?.text).toContain("Available providers");
-  });
-
-  it("lists configured models outside the curated catalog", async () => {
-    const customCfg = {
-      commands: { text: true },
-      agents: {
-        defaults: {
-          model: {
-            primary: "localai/ultra-chat",
-            fallbacks: ["anthropic/claude-opus-4-5"],
-          },
-          imageModel: "visionpro/studio-v1",
-        },
-      },
-    } as unknown as OpenClawConfig;
-
-    // Use discord surface for text-based output tests
-    const providerList = await handleCommands(
-      buildParams("/models", customCfg, { Surface: "discord" }),
-    );
-    expect(providerList.reply?.text).toContain("localai");
-    expect(providerList.reply?.text).toContain("visionpro");
-
-    const result = await handleCommands(
-      buildParams("/models localai", customCfg, { Surface: "discord" }),
-    );
-    expect(result.shouldContinue).toBe(false);
-    expect(result.reply?.text).toContain("Models (localai)");
-    expect(result.reply?.text).toContain("localai/ultra-chat");
-    expect(result.reply?.text).not.toContain("Unknown provider");
-  });
-});
diff --git a/src/auto-reply/reply/commands-session.ts b/src/auto-reply/reply/commands-session.ts
index 20091a5ce98..205c6b38764 100644
--- a/src/auto-reply/reply/commands-session.ts
+++ b/src/auto-reply/reply/commands-session.ts
@@ -53,6 +53,30 @@ function resolveAbortTarget(params: {
   return { entry: undefined, key: targetSessionKey, sessionId: undefined };
 }
 
+async function applyAbortTarget(params: {
+  abortTarget: ReturnType<typeof resolveAbortTarget>;
+  sessionStore?: Record<string, SessionEntry>;
+  storePath?: string;
+  abortKey?: string;
+}) {
+  const { abortTarget } = params;
+  if (abortTarget.sessionId) {
+    abortEmbeddedPiRun(abortTarget.sessionId);
+  }
+  if (abortTarget.entry && params.sessionStore && abortTarget.key) {
+    abortTarget.entry.abortedLastRun = true;
+    abortTarget.entry.updatedAt = Date.now();
+    params.sessionStore[abortTarget.key] = abortTarget.entry;
+    if (params.storePath) {
+      await updateSessionStore(params.storePath, (store) => {
+        store[abortTarget.key] = abortTarget.entry;
+      });
+    }
+  } else if (params.abortKey) {
+    setAbortMemory(params.abortKey, true);
+  }
+}
+
 export const handleActivationCommand: CommandHandler = async (params, allowTextCommands) => {
   if (!allowTextCommands) {
     return null;
@@ -304,27 +328,18 @@ export const handleStopCommand: CommandHandler = async (params, allowTextCommand
     sessionEntry: params.sessionEntry,
     sessionStore: params.sessionStore,
   });
-  if (abortTarget.sessionId) {
-    abortEmbeddedPiRun(abortTarget.sessionId);
-  }
   const cleared = clearSessionQueues([abortTarget.key, abortTarget.sessionId]);
   if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
     logVerbose(
       `stop: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
     );
   }
-  if (abortTarget.entry && params.sessionStore && abortTarget.key) {
-    abortTarget.entry.abortedLastRun = true;
-    abortTarget.entry.updatedAt = Date.now();
-    params.sessionStore[abortTarget.key] = abortTarget.entry;
-    if (params.storePath) {
-      await updateSessionStore(params.storePath, (store) => {
-        store[abortTarget.key] = abortTarget.entry;
-      });
-    }
-  } else if (params.command.abortKey) {
-    setAbortMemory(params.command.abortKey, true);
-  }
+  await applyAbortTarget({
+    abortTarget,
+    sessionStore: params.sessionStore,
+    storePath: params.storePath,
+    abortKey: params.command.abortKey,
+  });
 
   // Trigger internal hook for stop command
   const hookEvent = createInternalHookEvent(
@@ -361,20 +376,11 @@ export const handleAbortTrigger: CommandHandler = async (params, allowTextComman
     sessionEntry: params.sessionEntry,
     sessionStore: params.sessionStore,
   });
-  if (abortTarget.sessionId) {
-    abortEmbeddedPiRun(abortTarget.sessionId);
-  }
-  if (abortTarget.entry && params.sessionStore && abortTarget.key) {
-    abortTarget.entry.abortedLastRun = true;
-    abortTarget.entry.updatedAt = Date.now();
-    params.sessionStore[abortTarget.key] = abortTarget.entry;
-    if (params.storePath) {
-      await updateSessionStore(params.storePath, (store) => {
-        store[abortTarget.key] = abortTarget.entry;
-      });
-    }
-  } else if (params.command.abortKey) {
-    setAbortMemory(params.command.abortKey, true);
-  }
+  await applyAbortTarget({
+    abortTarget,
+    sessionStore: params.sessionStore,
+    storePath: params.storePath,
+    abortKey: params.command.abortKey,
+  });
   return { shouldContinue: false, reply: { text: "⚙️ Agent was aborted." } };
 };
diff --git a/src/auto-reply/reply/commands-setunset.ts b/src/auto-reply/reply/commands-setunset.ts
new file mode 100644
index 00000000000..137973a5e69
--- /dev/null
+++ b/src/auto-reply/reply/commands-setunset.ts
@@ -0,0 +1,38 @@
+import { parseConfigValue } from "./config-value.js";
+
+export type SetUnsetParseResult =
+  | { kind: "set"; path: string; value: unknown }
+  | { kind: "unset"; path: string }
+  | { kind: "error"; message: string };
+
+export function parseSetUnsetCommand(params: {
+  slash: string;
+  action: "set" | "unset";
+  args: string;
+}): SetUnsetParseResult {
+  const action = params.action;
+  const args = params.args.trim();
+  if (action === "unset") {
+    if (!args) {
+      return { kind: "error", message: `Usage: ${params.slash} unset path` };
+    }
+    return { kind: "unset", path: args };
+  }
+  if (!args) {
+    return { kind: "error", message: `Usage: ${params.slash} set path=value` };
+  }
+  const eqIndex = args.indexOf("=");
+  if (eqIndex <= 0) {
+    return { kind: "error", message: `Usage: ${params.slash} set path=value` };
+  }
+  const path = args.slice(0, eqIndex).trim();
+  const rawValue = args.slice(eqIndex + 1);
+  if (!path) {
+    return { kind: "error", message: `Usage: ${params.slash} set path=value` };
+  }
+  const parsed = parseConfigValue(rawValue);
+  if (parsed.error) {
+    return { kind: "error", message: parsed.error };
+  }
+  return { kind: "set", path, value: parsed.value };
+}
diff --git a/src/auto-reply/reply/commands-slash-parse.ts b/src/auto-reply/reply/commands-slash-parse.ts
new file mode 100644
index 00000000000..8cf5541e31b
--- /dev/null
+++ b/src/auto-reply/reply/commands-slash-parse.ts
@@ -0,0 +1,46 @@
+export type SlashCommandParseResult =
+  | { kind: "no-match" }
+  | { kind: "empty" }
+  | { kind: "invalid" }
+  | { kind: "parsed"; action: string; args: string };
+
+export type ParsedSlashCommand =
+  | { ok: true; action: string; args: string }
+  | { ok: false; message: string };
+
+export function parseSlashCommandActionArgs(raw: string, slash: string): SlashCommandParseResult {
+  const trimmed = raw.trim();
+  const slashLower = slash.toLowerCase();
+  if (!trimmed.toLowerCase().startsWith(slashLower)) {
+    return { kind: "no-match" };
+  }
+  const rest = trimmed.slice(slash.length).trim();
+  if (!rest) {
+    return { kind: "empty" };
+  }
+  const match = rest.match(/^(\S+)(?:\s+([\s\S]+))?$/);
+  if (!match) {
+    return { kind: "invalid" };
+  }
+  const action = match[1]?.toLowerCase() ?? "";
+  const args = (match[2] ?? "").trim();
+  return { kind: "parsed", action, args };
+}
+
+export function parseSlashCommandOrNull(
+  raw: string,
+  slash: string,
+  opts: { invalidMessage: string; defaultAction?: string },
+): ParsedSlashCommand | null {
+  const parsed = parseSlashCommandActionArgs(raw, slash);
+  if (parsed.kind === "no-match") {
+    return null;
+  }
+  if (parsed.kind === "invalid") {
+    return { ok: false, message: opts.invalidMessage };
+  }
+  if (parsed.kind === "empty") {
+    return { ok: true, action: opts.defaultAction ?? "show", args: "" };
+  }
+  return { ok: true, action: parsed.action, args: parsed.args };
+}
diff --git a/src/auto-reply/reply/commands-subagents.ts b/src/auto-reply/reply/commands-subagents.ts
index 35e3556d394..b4d201e9479 100644
--- a/src/auto-reply/reply/commands-subagents.ts
+++ b/src/auto-reply/reply/commands-subagents.ts
@@ -27,6 +27,7 @@ import { callGateway } from "../../gateway/call.js";
 import { logVerbose } from "../../globals.js";
 import { formatTimeAgo } from "../../infra/format-time/format-relative.ts";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
+import { extractTextFromChatContent } from "../../shared/chat-content.js";
 import {
   formatDurationCompact,
   formatTokenUsageDisplay,
@@ -202,45 +203,15 @@ function buildSubagentsHelp() {
 type ChatMessage = {
   role?: unknown;
   content?: unknown;
-  name?: unknown;
-  toolName?: unknown;
 };
 
-function normalizeMessageText(text: string) {
-  return text.replace(/\s+/g, " ").trim();
-}
-
 export function extractMessageText(message: ChatMessage): { role: string; text: string } | null {
   const role = typeof message.role === "string" ? message.role : "";
   const shouldSanitize = role === "assistant";
-  const content = message.content;
-  if (typeof content === "string") {
-    const normalized = normalizeMessageText(
-      shouldSanitize ? sanitizeTextContent(content) : content,
-    );
-    return normalized ? { role, text: normalized } : null;
-  }
-  if (!Array.isArray(content)) {
-    return null;
-  }
-  const chunks: string[] = [];
-  for (const block of content) {
-    if (!block || typeof block !== "object") {
-      continue;
-    }
-    if ((block as { type?: unknown }).type !== "text") {
-      continue;
-    }
-    const text = (block as { text?: unknown }).text;
-    if (typeof text === "string") {
-      const value = shouldSanitize ? sanitizeTextContent(text) : text;
-      if (value.trim()) {
-        chunks.push(value);
-      }
-    }
-  }
-  const joined = normalizeMessageText(chunks.join(" "));
-  return joined ? { role, text: joined } : null;
+  const text = extractTextFromChatContent(message.content, {
+    sanitizeText: shouldSanitize ? sanitizeTextContent : undefined,
+  });
+  return text ? { role, text } : null;
 }
 
 function formatLogLines(messages: ChatMessage[]) {
diff --git a/src/auto-reply/reply/commands.test.ts b/src/auto-reply/reply/commands.test.ts
index 431755561dc..1351296a2a1 100644
--- a/src/auto-reply/reply/commands.test.ts
+++ b/src/auto-reply/reply/commands.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { MsgContext } from "../templating.js";
 import {
@@ -13,14 +13,96 @@ import { updateSessionStore } from "../../config/sessions.js";
 import * as internalHooks from "../../hooks/internal-hooks.js";
 import { clearPluginCommands, registerPluginCommand } from "../../plugins/commands.js";
 import { resetBashChatCommandForTests } from "./bash-command.js";
+import { handleCompactCommand } from "./commands-compact.js";
+import { buildCommandsPaginationKeyboard } from "./commands-info.js";
+import { extractMessageText } from "./commands-subagents.js";
 import { buildCommandTestParams } from "./commands.test-harness.js";
+import { parseConfigCommand } from "./config-commands.js";
+import { parseDebugCommand } from "./debug-commands.js";
+import { parseInlineDirectives } from "./directive-handling.js";
+
+const readConfigFileSnapshotMock = vi.hoisted(() => vi.fn());
+const validateConfigObjectWithPluginsMock = vi.hoisted(() => vi.fn());
+const writeConfigFileMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../../config/config.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("../../config/config.js")>("../../config/config.js");
+  return {
+    ...actual,
+    readConfigFileSnapshot: readConfigFileSnapshotMock,
+    validateConfigObjectWithPlugins: validateConfigObjectWithPluginsMock,
+    writeConfigFile: writeConfigFileMock,
+  };
+});
+
+const readChannelAllowFromStoreMock = vi.hoisted(() => vi.fn());
+const addChannelAllowFromStoreEntryMock = vi.hoisted(() => vi.fn());
+const removeChannelAllowFromStoreEntryMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../../pairing/pairing-store.js", async () => {
+  const actual = await vi.importActual<typeof import("../../pairing/pairing-store.js")>(
+    "../../pairing/pairing-store.js",
+  );
+  return {
+    ...actual,
+    readChannelAllowFromStore: readChannelAllowFromStoreMock,
+    addChannelAllowFromStoreEntry: addChannelAllowFromStoreEntryMock,
+    removeChannelAllowFromStoreEntry: removeChannelAllowFromStoreEntryMock,
+  };
+});
+
+vi.mock("../../channels/plugins/pairing.js", async () => {
+  const actual = await vi.importActual<typeof import("../../channels/plugins/pairing.js")>(
+    "../../channels/plugins/pairing.js",
+  );
+  return {
+    ...actual,
+    listPairingChannels: () => ["telegram"],
+  };
+});
+
+vi.mock("../../agents/model-catalog.js", () => ({
+  loadModelCatalog: vi.fn(async () => [
+    { provider: "anthropic", id: "claude-opus-4-5", name: "Claude Opus" },
+    { provider: "anthropic", id: "claude-sonnet-4-5", name: "Claude Sonnet" },
+    { provider: "openai", id: "gpt-4.1", name: "GPT-4.1" },
+    { provider: "openai", id: "gpt-4.1-mini", name: "GPT-4.1 Mini" },
+    { provider: "google", id: "gemini-2.0-flash", name: "Gemini Flash" },
+  ]),
+}));
+
+vi.mock("../../agents/pi-embedded.js", () => {
+  const resolveEmbeddedSessionLane = (key: string) => {
+    const cleaned = key.trim() || "main";
+    return cleaned.startsWith("session:") ? cleaned : `session:${cleaned}`;
+  };
+  return {
+    abortEmbeddedPiRun: vi.fn(),
+    compactEmbeddedPiSession: vi.fn(),
+    isEmbeddedPiRunActive: vi.fn().mockReturnValue(false),
+    isEmbeddedPiRunStreaming: vi.fn().mockReturnValue(false),
+    queueEmbeddedPiMessage: vi.fn().mockReturnValue(false),
+    resolveEmbeddedSessionLane,
+    runEmbeddedPiAgent: vi.fn(),
+    waitForEmbeddedPiRunEnd: vi.fn().mockResolvedValue(undefined),
+  };
+});
+
+vi.mock("../../infra/system-events.js", () => ({
+  enqueueSystemEvent: vi.fn(),
+}));
+
+vi.mock("./session-updates.js", () => ({
+  incrementCompactionCount: vi.fn(),
+}));
 
 const callGatewayMock = vi.fn();
 vi.mock("../../gateway/call.js", () => ({
   callGateway: (opts: unknown) => callGatewayMock(opts),
 }));
 
-import { handleCommands } from "./commands.js";
+import { buildCommandContext, handleCommands } from "./commands.js";
 
 // Avoid expensive workspace scans during /context tests.
 vi.mock("./commands-context-report.js", () => ({
@@ -104,6 +186,293 @@ describe("handleCommands gating", () => {
   });
 });
 
+describe("/approve command", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("rejects invalid usage", async () => {
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as OpenClawConfig;
+    const params = buildParams("/approve", cfg);
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Usage: /approve");
+  });
+
+  it("submits approval", async () => {
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as OpenClawConfig;
+    const params = buildParams("/approve abc allow-once", cfg, { SenderId: "123" });
+
+    callGatewayMock.mockResolvedValueOnce({ ok: true });
+
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
+    expect(callGatewayMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "exec.approval.resolve",
+        params: { id: "abc", decision: "allow-once" },
+      }),
+    );
+  });
+
+  it("rejects gateway clients without approvals scope", async () => {
+    const cfg = {
+      commands: { text: true },
+    } as OpenClawConfig;
+    const params = buildParams("/approve abc allow-once", cfg, {
+      Provider: "webchat",
+      Surface: "webchat",
+      GatewayClientScopes: ["operator.write"],
+    });
+
+    callGatewayMock.mockResolvedValueOnce({ ok: true });
+
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("requires operator.approvals");
+    expect(callGatewayMock).not.toHaveBeenCalled();
+  });
+
+  it("allows gateway clients with approvals scope", async () => {
+    const cfg = {
+      commands: { text: true },
+    } as OpenClawConfig;
+    const params = buildParams("/approve abc allow-once", cfg, {
+      Provider: "webchat",
+      Surface: "webchat",
+      GatewayClientScopes: ["operator.approvals"],
+    });
+
+    callGatewayMock.mockResolvedValueOnce({ ok: true });
+
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
+    expect(callGatewayMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "exec.approval.resolve",
+        params: { id: "abc", decision: "allow-once" },
+      }),
+    );
+  });
+
+  it("allows gateway clients with admin scope", async () => {
+    const cfg = {
+      commands: { text: true },
+    } as OpenClawConfig;
+    const params = buildParams("/approve abc allow-once", cfg, {
+      Provider: "webchat",
+      Surface: "webchat",
+      GatewayClientScopes: ["operator.admin"],
+    });
+
+    callGatewayMock.mockResolvedValueOnce({ ok: true });
+
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
+    expect(callGatewayMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "exec.approval.resolve",
+        params: { id: "abc", decision: "allow-once" },
+      }),
+    );
+  });
+});
+
+describe("/compact command", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns null when command is not /compact", async () => {
+    const { compactEmbeddedPiSession } = await import("../../agents/pi-embedded.js");
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as OpenClawConfig;
+    const params = buildParams("/status", cfg);
+
+    const result = await handleCompactCommand(
+      {
+        ...params,
+      },
+      true,
+    );
+
+    expect(result).toBeNull();
+    expect(vi.mocked(compactEmbeddedPiSession)).not.toHaveBeenCalled();
+  });
+
+  it("rejects unauthorized /compact commands", async () => {
+    const { compactEmbeddedPiSession } = await import("../../agents/pi-embedded.js");
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as OpenClawConfig;
+    const params = buildParams("/compact", cfg);
+
+    const result = await handleCompactCommand(
+      {
+        ...params,
+        command: {
+          ...params.command,
+          isAuthorizedSender: false,
+          senderId: "unauthorized",
+        },
+      },
+      true,
+    );
+
+    expect(result).toEqual({ shouldContinue: false });
+    expect(vi.mocked(compactEmbeddedPiSession)).not.toHaveBeenCalled();
+  });
+
+  it("routes manual compaction with explicit trigger and context metadata", async () => {
+    const { compactEmbeddedPiSession } = await import("../../agents/pi-embedded.js");
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+      session: { store: "/tmp/openclaw-session-store.json" },
+    } as OpenClawConfig;
+    const params = buildParams("/compact: focus on decisions", cfg, {
+      From: "+15550001",
+      To: "+15550002",
+    });
+    vi.mocked(compactEmbeddedPiSession).mockResolvedValueOnce({
+      ok: true,
+      compacted: false,
+    });
+
+    const result = await handleCompactCommand(
+      {
+        ...params,
+        sessionEntry: {
+          sessionId: "session-1",
+          groupId: "group-1",
+          groupChannel: "#general",
+          space: "workspace-1",
+          spawnedBy: "agent:main:parent",
+          totalTokens: 12345,
+        },
+      },
+      true,
+    );
+
+    expect(result?.shouldContinue).toBe(false);
+    expect(vi.mocked(compactEmbeddedPiSession)).toHaveBeenCalledOnce();
+    expect(vi.mocked(compactEmbeddedPiSession)).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: "session-1",
+        sessionKey: "agent:main:main",
+        trigger: "manual",
+        customInstructions: "focus on decisions",
+        messageChannel: "whatsapp",
+        groupId: "group-1",
+        groupChannel: "#general",
+        groupSpace: "workspace-1",
+        spawnedBy: "agent:main:parent",
+      }),
+    );
+  });
+});
+
+describe("buildCommandsPaginationKeyboard", () => {
+  it("adds agent id to callback data when provided", () => {
+    const keyboard = buildCommandsPaginationKeyboard(2, 3, "agent-main");
+    expect(keyboard[0]).toEqual([
+      { text: "◀ Prev", callback_data: "commands_page_1:agent-main" },
+      { text: "2/3", callback_data: "commands_page_noop:agent-main" },
+      { text: "Next ▶", callback_data: "commands_page_3:agent-main" },
+    ]);
+  });
+});
+
+describe("parseConfigCommand", () => {
+  it("parses show/unset", () => {
+    expect(parseConfigCommand("/config")).toEqual({ action: "show" });
+    expect(parseConfigCommand("/config show")).toEqual({
+      action: "show",
+      path: undefined,
+    });
+    expect(parseConfigCommand("/config show foo.bar")).toEqual({
+      action: "show",
+      path: "foo.bar",
+    });
+    expect(parseConfigCommand("/config get foo.bar")).toEqual({
+      action: "show",
+      path: "foo.bar",
+    });
+    expect(parseConfigCommand("/config unset foo.bar")).toEqual({
+      action: "unset",
+      path: "foo.bar",
+    });
+  });
+
+  it("parses set with JSON", () => {
+    const cmd = parseConfigCommand('/config set foo={"a":1}');
+    expect(cmd).toEqual({ action: "set", path: "foo", value: { a: 1 } });
+  });
+});
+
+describe("parseDebugCommand", () => {
+  it("parses show/reset", () => {
+    expect(parseDebugCommand("/debug")).toEqual({ action: "show" });
+    expect(parseDebugCommand("/debug show")).toEqual({ action: "show" });
+    expect(parseDebugCommand("/debug reset")).toEqual({ action: "reset" });
+  });
+
+  it("parses set with JSON", () => {
+    const cmd = parseDebugCommand('/debug set foo={"a":1}');
+    expect(cmd).toEqual({ action: "set", path: "foo", value: { a: 1 } });
+  });
+
+  it("parses unset", () => {
+    const cmd = parseDebugCommand("/debug unset foo.bar");
+    expect(cmd).toEqual({ action: "unset", path: "foo.bar" });
+  });
+});
+
+describe("extractMessageText", () => {
+  it("preserves user text that looks like tool call markers", () => {
+    const message = {
+      role: "user",
+      content: "Here [Tool Call: foo (ID: 1)] ok",
+    };
+    const result = extractMessageText(message);
+    expect(result?.text).toContain("[Tool Call: foo (ID: 1)]");
+  });
+
+  it("sanitizes assistant tool call markers", () => {
+    const message = {
+      role: "assistant",
+      content: "Here [Tool Call: foo (ID: 1)] ok",
+    };
+    const result = extractMessageText(message);
+    expect(result?.text).toBe("Here ok");
+  });
+});
+
+describe("handleCommands /config configWrites gating", () => {
+  it("blocks /config set when channel config writes are disabled", async () => {
+    const cfg = {
+      commands: { config: true, text: true },
+      channels: { whatsapp: { allowFrom: ["*"], configWrites: false } },
+    } as OpenClawConfig;
+    const params = buildParams('/config set messages.ackReaction=":)"', cfg);
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Config writes are disabled");
+  });
+});
+
 describe("handleCommands bash alias", () => {
   it("routes !poll through the /bash handler", async () => {
     resetBashChatCommandForTests();
@@ -130,6 +499,289 @@ describe("handleCommands bash alias", () => {
   });
 });
 
+function buildPolicyParams(
+  commandBody: string,
+  cfg: OpenClawConfig,
+  ctxOverrides?: Partial<MsgContext>,
+) {
+  const ctx = {
+    Body: commandBody,
+    CommandBody: commandBody,
+    CommandSource: "text",
+    CommandAuthorized: true,
+    Provider: "telegram",
+    Surface: "telegram",
+    ...ctxOverrides,
+  } as MsgContext;
+
+  const command = buildCommandContext({
+    ctx,
+    cfg,
+    isGroup: false,
+    triggerBodyNormalized: commandBody.trim().toLowerCase(),
+    commandAuthorized: true,
+  });
+
+  return {
+    ctx,
+    cfg,
+    command,
+    directives: parseInlineDirectives(commandBody),
+    elevated: { enabled: true, allowed: true, failures: [] },
+    sessionKey: "agent:main:main",
+    workspaceDir: "/tmp",
+    defaultGroupActivation: () => "mention",
+    resolvedVerboseLevel: "off" as const,
+    resolvedReasoningLevel: "off" as const,
+    resolveDefaultThinkingLevel: async () => undefined,
+    provider: "telegram",
+    model: "test-model",
+    contextTokens: 0,
+    isGroup: false,
+  };
+}
+
+describe("handleCommands /allowlist", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("lists config + store allowFrom entries", async () => {
+    readChannelAllowFromStoreMock.mockResolvedValueOnce(["456"]);
+
+    const cfg = {
+      commands: { text: true },
+      channels: { telegram: { allowFrom: ["123", "@Alice"] } },
+    } as OpenClawConfig;
+    const params = buildPolicyParams("/allowlist list dm", cfg);
+    const result = await handleCommands(params);
+
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Channel: telegram");
+    expect(result.reply?.text).toContain("DM allowFrom (config): 123, @alice");
+    expect(result.reply?.text).toContain("Paired allowFrom (store): 456");
+  });
+
+  it("adds entries to config and pairing store", async () => {
+    readConfigFileSnapshotMock.mockResolvedValueOnce({
+      valid: true,
+      parsed: {
+        channels: { telegram: { allowFrom: ["123"] } },
+      },
+    });
+    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
+      ok: true,
+      config,
+    }));
+    addChannelAllowFromStoreEntryMock.mockResolvedValueOnce({
+      changed: true,
+      allowFrom: ["123", "789"],
+    });
+
+    const cfg = {
+      commands: { text: true, config: true },
+      channels: { telegram: { allowFrom: ["123"] } },
+    } as OpenClawConfig;
+    const params = buildPolicyParams("/allowlist add dm 789", cfg);
+    const result = await handleCommands(params);
+
+    expect(result.shouldContinue).toBe(false);
+    expect(writeConfigFileMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channels: { telegram: { allowFrom: ["123", "789"] } },
+      }),
+    );
+    expect(addChannelAllowFromStoreEntryMock).toHaveBeenCalledWith({
+      channel: "telegram",
+      entry: "789",
+    });
+    expect(result.reply?.text).toContain("DM allowlist added");
+  });
+
+  it("removes Slack DM allowlist entries from canonical allowFrom and deletes legacy dm.allowFrom", async () => {
+    readConfigFileSnapshotMock.mockResolvedValueOnce({
+      valid: true,
+      parsed: {
+        channels: {
+          slack: {
+            allowFrom: ["U111", "U222"],
+            dm: { allowFrom: ["U111", "U222"] },
+            configWrites: true,
+          },
+        },
+      },
+    });
+    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
+      ok: true,
+      config,
+    }));
+
+    const cfg = {
+      commands: { text: true, config: true },
+      channels: {
+        slack: {
+          allowFrom: ["U111", "U222"],
+          dm: { allowFrom: ["U111", "U222"] },
+          configWrites: true,
+        },
+      },
+    } as OpenClawConfig;
+
+    const params = buildPolicyParams("/allowlist remove dm U111", cfg, {
+      Provider: "slack",
+      Surface: "slack",
+    });
+    const result = await handleCommands(params);
+
+    expect(result.shouldContinue).toBe(false);
+    expect(writeConfigFileMock).toHaveBeenCalledTimes(1);
+    const written = writeConfigFileMock.mock.calls[0]?.[0] as OpenClawConfig;
+    expect(written.channels?.slack?.allowFrom).toEqual(["U222"]);
+    expect(written.channels?.slack?.dm?.allowFrom).toBeUndefined();
+    expect(result.reply?.text).toContain("channels.slack.allowFrom");
+  });
+
+  it("removes Discord DM allowlist entries from canonical allowFrom and deletes legacy dm.allowFrom", async () => {
+    readConfigFileSnapshotMock.mockResolvedValueOnce({
+      valid: true,
+      parsed: {
+        channels: {
+          discord: {
+            allowFrom: ["111", "222"],
+            dm: { allowFrom: ["111", "222"] },
+            configWrites: true,
+          },
+        },
+      },
+    });
+    validateConfigObjectWithPluginsMock.mockImplementation((config: unknown) => ({
+      ok: true,
+      config,
+    }));
+
+    const cfg = {
+      commands: { text: true, config: true },
+      channels: {
+        discord: {
+          allowFrom: ["111", "222"],
+          dm: { allowFrom: ["111", "222"] },
+          configWrites: true,
+        },
+      },
+    } as OpenClawConfig;
+
+    const params = buildPolicyParams("/allowlist remove dm 111", cfg, {
+      Provider: "discord",
+      Surface: "discord",
+    });
+    const result = await handleCommands(params);
+
+    expect(result.shouldContinue).toBe(false);
+    expect(writeConfigFileMock).toHaveBeenCalledTimes(1);
+    const written = writeConfigFileMock.mock.calls[0]?.[0] as OpenClawConfig;
+    expect(written.channels?.discord?.allowFrom).toEqual(["222"]);
+    expect(written.channels?.discord?.dm?.allowFrom).toBeUndefined();
+    expect(result.reply?.text).toContain("channels.discord.allowFrom");
+  });
+});
+
+describe("/models command", () => {
+  const cfg = {
+    commands: { text: true },
+    agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
+  } as unknown as OpenClawConfig;
+
+  it.each(["discord", "whatsapp"])("lists providers on %s (text)", async (surface) => {
+    const params = buildPolicyParams("/models", cfg, { Provider: surface, Surface: surface });
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Providers:");
+    expect(result.reply?.text).toContain("anthropic");
+    expect(result.reply?.text).toContain("Use: /models <provider>");
+  });
+
+  it("lists providers on telegram (buttons)", async () => {
+    const params = buildPolicyParams("/models", cfg, { Provider: "telegram", Surface: "telegram" });
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toBe("Select a provider:");
+    const buttons = (result.reply?.channelData as { telegram?: { buttons?: unknown[][] } })
+      ?.telegram?.buttons;
+    expect(buttons).toBeDefined();
+    expect(buttons?.length).toBeGreaterThan(0);
+  });
+
+  it("lists provider models with pagination hints", async () => {
+    // Use discord surface for text-based output tests
+    const params = buildPolicyParams("/models anthropic", cfg, { Surface: "discord" });
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Models (anthropic)");
+    expect(result.reply?.text).toContain("page 1/");
+    expect(result.reply?.text).toContain("anthropic/claude-opus-4-5");
+    expect(result.reply?.text).toContain("Switch: /model <provider/model>");
+    expect(result.reply?.text).toContain("All: /models anthropic all");
+  });
+
+  it("ignores page argument when all flag is present", async () => {
+    // Use discord surface for text-based output tests
+    const params = buildPolicyParams("/models anthropic 3 all", cfg, { Surface: "discord" });
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Models (anthropic)");
+    expect(result.reply?.text).toContain("page 1/1");
+    expect(result.reply?.text).toContain("anthropic/claude-opus-4-5");
+    expect(result.reply?.text).not.toContain("Page out of range");
+  });
+
+  it("errors on out-of-range pages", async () => {
+    // Use discord surface for text-based output tests
+    const params = buildPolicyParams("/models anthropic 4", cfg, { Surface: "discord" });
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Page out of range");
+    expect(result.reply?.text).toContain("valid: 1-");
+  });
+
+  it("handles unknown providers", async () => {
+    const params = buildPolicyParams("/models not-a-provider", cfg);
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Unknown provider");
+    expect(result.reply?.text).toContain("Available providers");
+  });
+
+  it("lists configured models outside the curated catalog", async () => {
+    const customCfg = {
+      commands: { text: true },
+      agents: {
+        defaults: {
+          model: {
+            primary: "localai/ultra-chat",
+            fallbacks: ["anthropic/claude-opus-4-5"],
+          },
+          imageModel: "visionpro/studio-v1",
+        },
+      },
+    } as unknown as OpenClawConfig;
+
+    // Use discord surface for text-based output tests
+    const providerList = await handleCommands(
+      buildPolicyParams("/models", customCfg, { Surface: "discord" }),
+    );
+    expect(providerList.reply?.text).toContain("localai");
+    expect(providerList.reply?.text).toContain("visionpro");
+
+    const result = await handleCommands(
+      buildPolicyParams("/models localai", customCfg, { Surface: "discord" }),
+    );
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Models (localai)");
+    expect(result.reply?.text).toContain("localai/ultra-chat");
+    expect(result.reply?.text).not.toContain("Unknown provider");
+  });
+});
+
 describe("handleCommands plugin commands", () => {
   it("dispatches registered plugin commands", async () => {
     clearPluginCommands();
diff --git a/src/auto-reply/reply/config-commands.ts b/src/auto-reply/reply/config-commands.ts
index b78baa45905..fc924985c58 100644
--- a/src/auto-reply/reply/config-commands.ts
+++ b/src/auto-reply/reply/config-commands.ts
@@ -1,4 +1,5 @@
-import { parseConfigValue } from "./config-value.js";
+import { parseSetUnsetCommand } from "./commands-setunset.js";
+import { parseSlashCommandOrNull } from "./commands-slash-parse.js";
 
 export type ConfigCommand =
   | { action: "show"; path?: string }
@@ -7,60 +8,31 @@ export type ConfigCommand =
   | { action: "error"; message: string };
 
 export function parseConfigCommand(raw: string): ConfigCommand | null {
-  const trimmed = raw.trim();
-  if (!trimmed.toLowerCase().startsWith("/config")) {
+  const parsed = parseSlashCommandOrNull(raw, "/config", {
+    invalidMessage: "Invalid /config syntax.",
+  });
+  if (!parsed) {
     return null;
   }
-  const rest = trimmed.slice("/config".length).trim();
-  if (!rest) {
-    return { action: "show" };
+  if (!parsed.ok) {
+    return { action: "error", message: parsed.message };
   }
-
-  const match = rest.match(/^(\S+)(?:\s+([\s\S]+))?$/);
-  if (!match) {
-    return { action: "error", message: "Invalid /config syntax." };
-  }
-  const action = match[1].toLowerCase();
-  const args = (match[2] ?? "").trim();
+  const { action, args } = parsed;
 
   switch (action) {
     case "show":
       return { action: "show", path: args || undefined };
     case "get":
       return { action: "show", path: args || undefined };
-    case "unset": {
-      if (!args) {
-        return { action: "error", message: "Usage: /config unset path" };
-      }
-      return { action: "unset", path: args };
-    }
+    case "unset":
     case "set": {
-      if (!args) {
-        return {
-          action: "error",
-          message: "Usage: /config set path=value",
-        };
+      const parsed = parseSetUnsetCommand({ slash: "/config", action, args });
+      if (parsed.kind === "error") {
+        return { action: "error", message: parsed.message };
       }
-      const eqIndex = args.indexOf("=");
-      if (eqIndex <= 0) {
-        return {
-          action: "error",
-          message: "Usage: /config set path=value",
-        };
-      }
-      const path = args.slice(0, eqIndex).trim();
-      const rawValue = args.slice(eqIndex + 1);
-      if (!path) {
-        return {
-          action: "error",
-          message: "Usage: /config set path=value",
-        };
-      }
-      const parsed = parseConfigValue(rawValue);
-      if (parsed.error) {
-        return { action: "error", message: parsed.error };
-      }
-      return { action: "set", path, value: parsed.value };
+      return parsed.kind === "set"
+        ? { action: "set", path: parsed.path, value: parsed.value }
+        : { action: "unset", path: parsed.path };
     }
     default:
       return {
diff --git a/src/auto-reply/reply/debug-commands.ts b/src/auto-reply/reply/debug-commands.ts
index 5f9f8c9fd0e..089caf2a5e5 100644
--- a/src/auto-reply/reply/debug-commands.ts
+++ b/src/auto-reply/reply/debug-commands.ts
@@ -1,4 +1,5 @@
-import { parseConfigValue } from "./config-value.js";
+import { parseSetUnsetCommand } from "./commands-setunset.js";
+import { parseSlashCommandOrNull } from "./commands-slash-parse.js";
 
 export type DebugCommand =
   | { action: "show" }
@@ -8,60 +9,31 @@ export type DebugCommand =
   | { action: "error"; message: string };
 
 export function parseDebugCommand(raw: string): DebugCommand | null {
-  const trimmed = raw.trim();
-  if (!trimmed.toLowerCase().startsWith("/debug")) {
+  const parsed = parseSlashCommandOrNull(raw, "/debug", {
+    invalidMessage: "Invalid /debug syntax.",
+  });
+  if (!parsed) {
     return null;
   }
-  const rest = trimmed.slice("/debug".length).trim();
-  if (!rest) {
-    return { action: "show" };
+  if (!parsed.ok) {
+    return { action: "error", message: parsed.message };
   }
-
-  const match = rest.match(/^(\S+)(?:\s+([\s\S]+))?$/);
-  if (!match) {
-    return { action: "error", message: "Invalid /debug syntax." };
-  }
-  const action = match[1].toLowerCase();
-  const args = (match[2] ?? "").trim();
+  const { action, args } = parsed;
 
   switch (action) {
     case "show":
       return { action: "show" };
     case "reset":
       return { action: "reset" };
-    case "unset": {
-      if (!args) {
-        return { action: "error", message: "Usage: /debug unset path" };
-      }
-      return { action: "unset", path: args };
-    }
+    case "unset":
     case "set": {
-      if (!args) {
-        return {
-          action: "error",
-          message: "Usage: /debug set path=value",
-        };
+      const parsed = parseSetUnsetCommand({ slash: "/debug", action, args });
+      if (parsed.kind === "error") {
+        return { action: "error", message: parsed.message };
       }
-      const eqIndex = args.indexOf("=");
-      if (eqIndex <= 0) {
-        return {
-          action: "error",
-          message: "Usage: /debug set path=value",
-        };
-      }
-      const path = args.slice(0, eqIndex).trim();
-      const rawValue = args.slice(eqIndex + 1);
-      if (!path) {
-        return {
-          action: "error",
-          message: "Usage: /debug set path=value",
-        };
-      }
-      const parsed = parseConfigValue(rawValue);
-      if (parsed.error) {
-        return { action: "error", message: parsed.error };
-      }
-      return { action: "set", path, value: parsed.value };
+      return parsed.kind === "set"
+        ? { action: "set", path: parsed.path, value: parsed.value }
+        : { action: "unset", path: parsed.path };
     }
     default:
       return {
diff --git a/src/auto-reply/reply/directive-handling.fast-lane.ts b/src/auto-reply/reply/directive-handling.fast-lane.ts
index e83aa889dfc..fdea7c75e01 100644
--- a/src/auto-reply/reply/directive-handling.fast-lane.ts
+++ b/src/auto-reply/reply/directive-handling.fast-lane.ts
@@ -1,7 +1,7 @@
 import type { ReplyPayload } from "../types.js";
 import type { ApplyInlineDirectivesFastLaneParams } from "./directive-handling.params.js";
-import type { ElevatedLevel, ReasoningLevel, ThinkLevel, VerboseLevel } from "./directives.js";
 import { handleDirectiveOnly } from "./directive-handling.impl.js";
+import { resolveCurrentDirectiveLevels } from "./directive-handling.levels.js";
 import { isDirectiveOnly } from "./directive-handling.parse.js";
 
 export async function applyInlineDirectivesFastLane(
@@ -48,19 +48,12 @@ export async function applyInlineDirectivesFastLane(
   }
 
   const agentCfg = params.agentCfg;
-  const resolvedDefaultThinkLevel =
-    (sessionEntry?.thinkingLevel as ThinkLevel | undefined) ??
-    (agentCfg?.thinkingDefault as ThinkLevel | undefined) ??
-    (await modelState.resolveDefaultThinkingLevel());
-  const currentThinkLevel = resolvedDefaultThinkLevel;
-  const currentVerboseLevel =
-    (sessionEntry?.verboseLevel as VerboseLevel | undefined) ??
-    (agentCfg?.verboseDefault as VerboseLevel | undefined);
-  const currentReasoningLevel =
-    (sessionEntry?.reasoningLevel as ReasoningLevel | undefined) ?? "off";
-  const currentElevatedLevel =
-    (sessionEntry?.elevatedLevel as ElevatedLevel | undefined) ??
-    (agentCfg?.elevatedDefault as ElevatedLevel | undefined);
+  const { currentThinkLevel, currentVerboseLevel, currentReasoningLevel, currentElevatedLevel } =
+    await resolveCurrentDirectiveLevels({
+      sessionEntry,
+      agentCfg,
+      resolveDefaultThinkingLevel: () => modelState.resolveDefaultThinkingLevel(),
+    });
 
   const directiveAck = await handleDirectiveOnly({
     cfg,
diff --git a/src/auto-reply/reply/directive-handling.impl.ts b/src/auto-reply/reply/directive-handling.impl.ts
index cc8b5aef608..838d7aeee70 100644
--- a/src/auto-reply/reply/directive-handling.impl.ts
+++ b/src/auto-reply/reply/directive-handling.impl.ts
@@ -21,10 +21,9 @@ import {
 import { maybeHandleQueueDirective } from "./directive-handling.queue-validation.js";
 import {
   formatDirectiveAck,
-  formatElevatedEvent,
   formatElevatedRuntimeHint,
   formatElevatedUnavailableText,
-  formatReasoningEvent,
+  enqueueModeSwitchEvents,
   withOptions,
 } from "./directive-handling.shared.js";
 
@@ -363,20 +362,13 @@ export async function handleDirectiveOnly(
       });
     }
   }
-  if (elevatedChanged) {
-    const nextElevated = (sessionEntry.elevatedLevel ?? "off") as ElevatedLevel;
-    enqueueSystemEvent(formatElevatedEvent(nextElevated), {
-      sessionKey,
-      contextKey: "mode:elevated",
-    });
-  }
-  if (reasoningChanged) {
-    const nextReasoning = (sessionEntry.reasoningLevel ?? "off") as ReasoningLevel;
-    enqueueSystemEvent(formatReasoningEvent(nextReasoning), {
-      sessionKey,
-      contextKey: "mode:reasoning",
-    });
-  }
+  enqueueModeSwitchEvents({
+    enqueueSystemEvent,
+    sessionEntry,
+    sessionKey,
+    elevatedChanged,
+    reasoningChanged,
+  });
 
   const parts: string[] = [];
   if (directives.hasThinkDirective && directives.thinkLevel) {
diff --git a/src/auto-reply/reply/directive-handling.levels.ts b/src/auto-reply/reply/directive-handling.levels.ts
new file mode 100644
index 00000000000..61f9aef1c79
--- /dev/null
+++ b/src/auto-reply/reply/directive-handling.levels.ts
@@ -0,0 +1,41 @@
+import type { ElevatedLevel, ReasoningLevel, ThinkLevel, VerboseLevel } from "../thinking.js";
+
+export async function resolveCurrentDirectiveLevels(params: {
+  sessionEntry?: {
+    thinkingLevel?: unknown;
+    verboseLevel?: unknown;
+    reasoningLevel?: unknown;
+    elevatedLevel?: unknown;
+  };
+  agentCfg?: {
+    thinkingDefault?: unknown;
+    verboseDefault?: unknown;
+    elevatedDefault?: unknown;
+  };
+  resolveDefaultThinkingLevel: () => Promise<ThinkLevel | undefined>;
+}): Promise<{
+  currentThinkLevel: ThinkLevel | undefined;
+  currentVerboseLevel: VerboseLevel | undefined;
+  currentReasoningLevel: ReasoningLevel;
+  currentElevatedLevel: ElevatedLevel | undefined;
+}> {
+  const resolvedDefaultThinkLevel =
+    (params.sessionEntry?.thinkingLevel as ThinkLevel | undefined) ??
+    (params.agentCfg?.thinkingDefault as ThinkLevel | undefined) ??
+    (await params.resolveDefaultThinkingLevel());
+  const currentThinkLevel = resolvedDefaultThinkLevel;
+  const currentVerboseLevel =
+    (params.sessionEntry?.verboseLevel as VerboseLevel | undefined) ??
+    (params.agentCfg?.verboseDefault as VerboseLevel | undefined);
+  const currentReasoningLevel =
+    (params.sessionEntry?.reasoningLevel as ReasoningLevel | undefined) ?? "off";
+  const currentElevatedLevel =
+    (params.sessionEntry?.elevatedLevel as ElevatedLevel | undefined) ??
+    (params.agentCfg?.elevatedDefault as ElevatedLevel | undefined);
+  return {
+    currentThinkLevel,
+    currentVerboseLevel,
+    currentReasoningLevel,
+    currentElevatedLevel,
+  };
+}
diff --git a/src/auto-reply/reply/directive-handling.persist.ts b/src/auto-reply/reply/directive-handling.persist.ts
index 225cae08145..a7c97ad4486 100644
--- a/src/auto-reply/reply/directive-handling.persist.ts
+++ b/src/auto-reply/reply/directive-handling.persist.ts
@@ -20,7 +20,7 @@ import { enqueueSystemEvent } from "../../infra/system-events.js";
 import { applyVerboseOverride } from "../../sessions/level-overrides.js";
 import { applyModelOverrideToSessionEntry } from "../../sessions/model-overrides.js";
 import { resolveProfileOverride } from "./directive-handling.auth.js";
-import { formatElevatedEvent, formatReasoningEvent } from "./directive-handling.shared.js";
+import { enqueueModeSwitchEvents } from "./directive-handling.shared.js";
 
 export async function persistInlineDirectives(params: {
   directives: InlineDirectives;
@@ -199,20 +199,13 @@ export async function persistInlineDirectives(params: {
           store[sessionKey] = sessionEntry;
         });
       }
-      if (elevatedChanged) {
-        const nextElevated = (sessionEntry.elevatedLevel ?? "off") as ElevatedLevel;
-        enqueueSystemEvent(formatElevatedEvent(nextElevated), {
-          sessionKey,
-          contextKey: "mode:elevated",
-        });
-      }
-      if (reasoningChanged) {
-        const nextReasoning = (sessionEntry.reasoningLevel ?? "off") as ReasoningLevel;
-        enqueueSystemEvent(formatReasoningEvent(nextReasoning), {
-          sessionKey,
-          contextKey: "mode:reasoning",
-        });
-      }
+      enqueueModeSwitchEvents({
+        enqueueSystemEvent,
+        sessionEntry,
+        sessionKey,
+        elevatedChanged,
+        reasoningChanged,
+      });
     }
   }
 
diff --git a/src/auto-reply/reply/directive-handling.shared.ts b/src/auto-reply/reply/directive-handling.shared.ts
index 04d7ad0f64b..01a61b773a3 100644
--- a/src/auto-reply/reply/directive-handling.shared.ts
+++ b/src/auto-reply/reply/directive-handling.shared.ts
@@ -40,6 +40,29 @@ export const formatReasoningEvent = (level: ReasoningLevel) => {
   return "Reasoning OFF — hide <think>.";
 };
 
+export function enqueueModeSwitchEvents(params: {
+  enqueueSystemEvent: (text: string, meta: { sessionKey: string; contextKey: string }) => void;
+  sessionEntry: { elevatedLevel?: string | null; reasoningLevel?: string | null };
+  sessionKey: string;
+  elevatedChanged?: boolean;
+  reasoningChanged?: boolean;
+}): void {
+  if (params.elevatedChanged) {
+    const nextElevated = (params.sessionEntry.elevatedLevel ?? "off") as ElevatedLevel;
+    params.enqueueSystemEvent(formatElevatedEvent(nextElevated), {
+      sessionKey: params.sessionKey,
+      contextKey: "mode:elevated",
+    });
+  }
+  if (params.reasoningChanged) {
+    const nextReasoning = (params.sessionEntry.reasoningLevel ?? "off") as ReasoningLevel;
+    params.enqueueSystemEvent(formatReasoningEvent(nextReasoning), {
+      sessionKey: params.sessionKey,
+      contextKey: "mode:reasoning",
+    });
+  }
+}
+
 export function formatElevatedUnavailableText(params: {
   runtimeSandboxed: boolean;
   failures?: Array<{ gate: string; key: string }>;
diff --git a/src/auto-reply/reply/formatting.test.ts b/src/auto-reply/reply/formatting.test.ts
deleted file mode 100644
index e6fb0689881..00000000000
--- a/src/auto-reply/reply/formatting.test.ts
+++ /dev/null
@@ -1,280 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { parseAudioTag } from "./audio-tags.js";
-import { createBlockReplyCoalescer } from "./block-reply-coalescer.js";
-import { createReplyReferencePlanner } from "./reply-reference.js";
-import { createStreamingDirectiveAccumulator } from "./streaming-directives.js";
-
-describe("parseAudioTag", () => {
-  it("detects audio_as_voice and strips the tag", () => {
-    const result = parseAudioTag("Hello [[audio_as_voice]] world");
-    expect(result.audioAsVoice).toBe(true);
-    expect(result.hadTag).toBe(true);
-    expect(result.text).toBe("Hello world");
-  });
-
-  it("returns empty output for missing text", () => {
-    const result = parseAudioTag(undefined);
-    expect(result.audioAsVoice).toBe(false);
-    expect(result.hadTag).toBe(false);
-    expect(result.text).toBe("");
-  });
-
-  it("removes tag-only messages", () => {
-    const result = parseAudioTag("[[audio_as_voice]]");
-    expect(result.audioAsVoice).toBe(true);
-    expect(result.text).toBe("");
-  });
-});
-
-describe("block reply coalescer", () => {
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("coalesces chunks within the idle window", async () => {
-    vi.useFakeTimers();
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 1, maxChars: 200, idleMs: 100, joiner: " " },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    coalescer.enqueue({ text: "Hello" });
-    coalescer.enqueue({ text: "world" });
-
-    await vi.advanceTimersByTimeAsync(100);
-    expect(flushes).toEqual(["Hello world"]);
-    coalescer.stop();
-  });
-
-  it("waits until minChars before idle flush", async () => {
-    vi.useFakeTimers();
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 10, maxChars: 200, idleMs: 50, joiner: " " },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    coalescer.enqueue({ text: "short" });
-    await vi.advanceTimersByTimeAsync(50);
-    expect(flushes).toEqual([]);
-
-    coalescer.enqueue({ text: "message" });
-    await vi.advanceTimersByTimeAsync(50);
-    expect(flushes).toEqual(["short message"]);
-    coalescer.stop();
-  });
-
-  it("flushes each enqueued payload separately when flushOnEnqueue is set", async () => {
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 1, maxChars: 200, idleMs: 100, joiner: "\n\n", flushOnEnqueue: true },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    coalescer.enqueue({ text: "First paragraph" });
-    coalescer.enqueue({ text: "Second paragraph" });
-    coalescer.enqueue({ text: "Third paragraph" });
-
-    await Promise.resolve();
-    expect(flushes).toEqual(["First paragraph", "Second paragraph", "Third paragraph"]);
-    coalescer.stop();
-  });
-
-  it("still accumulates when flushOnEnqueue is not set (default)", async () => {
-    vi.useFakeTimers();
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 1, maxChars: 2000, idleMs: 100, joiner: "\n\n" },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    coalescer.enqueue({ text: "First paragraph" });
-    coalescer.enqueue({ text: "Second paragraph" });
-
-    await vi.advanceTimersByTimeAsync(100);
-    expect(flushes).toEqual(["First paragraph\n\nSecond paragraph"]);
-    coalescer.stop();
-  });
-
-  it("flushes short payloads immediately when flushOnEnqueue is set", async () => {
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 10, maxChars: 200, idleMs: 50, joiner: "\n\n", flushOnEnqueue: true },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    coalescer.enqueue({ text: "Hi" });
-    await Promise.resolve();
-    expect(flushes).toEqual(["Hi"]);
-    coalescer.stop();
-  });
-
-  it("resets char budget per paragraph with flushOnEnqueue", async () => {
-    const flushes: string[] = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 1, maxChars: 30, idleMs: 100, joiner: "\n\n", flushOnEnqueue: true },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push(payload.text ?? "");
-      },
-    });
-
-    // Each 20-char payload fits within maxChars=30 individually
-    coalescer.enqueue({ text: "12345678901234567890" });
-    coalescer.enqueue({ text: "abcdefghijklmnopqrst" });
-
-    await Promise.resolve();
-    // Without flushOnEnqueue, these would be joined to 40+ chars and trigger maxChars split.
-    // With flushOnEnqueue, each is sent independently within budget.
-    expect(flushes).toEqual(["12345678901234567890", "abcdefghijklmnopqrst"]);
-    coalescer.stop();
-  });
-
-  it("flushes buffered text before media payloads", () => {
-    const flushes: Array<{ text?: string; mediaUrls?: string[] }> = [];
-    const coalescer = createBlockReplyCoalescer({
-      config: { minChars: 1, maxChars: 200, idleMs: 0, joiner: " " },
-      shouldAbort: () => false,
-      onFlush: (payload) => {
-        flushes.push({
-          text: payload.text,
-          mediaUrls: payload.mediaUrls,
-        });
-      },
-    });
-
-    coalescer.enqueue({ text: "Hello" });
-    coalescer.enqueue({ text: "world" });
-    coalescer.enqueue({ mediaUrls: ["https://example.com/a.png"] });
-    void coalescer.flush({ force: true });
-
-    expect(flushes[0].text).toBe("Hello world");
-    expect(flushes[1].mediaUrls).toEqual(["https://example.com/a.png"]);
-    coalescer.stop();
-  });
-});
-
-describe("createReplyReferencePlanner", () => {
-  it("disables references when mode is off", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "off",
-      startId: "parent",
-    });
-    expect(planner.use()).toBeUndefined();
-    expect(planner.hasReplied()).toBe(false);
-  });
-
-  it("uses startId once when mode is first", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "first",
-      startId: "parent",
-    });
-    expect(planner.use()).toBe("parent");
-    expect(planner.hasReplied()).toBe(true);
-    planner.markSent();
-    expect(planner.use()).toBeUndefined();
-  });
-
-  it("returns startId for every call when mode is all", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "all",
-      startId: "parent",
-    });
-    expect(planner.use()).toBe("parent");
-    expect(planner.use()).toBe("parent");
-  });
-
-  it("respects replyToMode off even with existingId", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "off",
-      existingId: "thread-1",
-      startId: "parent",
-    });
-    expect(planner.use()).toBeUndefined();
-    expect(planner.hasReplied()).toBe(false);
-  });
-
-  it("uses existingId once when mode is first", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "first",
-      existingId: "thread-1",
-      startId: "parent",
-    });
-    expect(planner.use()).toBe("thread-1");
-    expect(planner.hasReplied()).toBe(true);
-    expect(planner.use()).toBeUndefined();
-  });
-
-  it("uses existingId on every call when mode is all", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "all",
-      existingId: "thread-1",
-      startId: "parent",
-    });
-    expect(planner.use()).toBe("thread-1");
-    expect(planner.use()).toBe("thread-1");
-  });
-
-  it("honors allowReference=false", () => {
-    const planner = createReplyReferencePlanner({
-      replyToMode: "all",
-      startId: "parent",
-      allowReference: false,
-    });
-    expect(planner.use()).toBeUndefined();
-    expect(planner.hasReplied()).toBe(false);
-    planner.markSent();
-    expect(planner.hasReplied()).toBe(true);
-  });
-});
-
-describe("createStreamingDirectiveAccumulator", () => {
-  it("stashes reply_to_current until a renderable chunk arrives", () => {
-    const accumulator = createStreamingDirectiveAccumulator();
-
-    expect(accumulator.consume("[[reply_to_current]]")).toBeNull();
-
-    const result = accumulator.consume("Hello");
-    expect(result?.text).toBe("Hello");
-    expect(result?.replyToCurrent).toBe(true);
-    expect(result?.replyToTag).toBe(true);
-  });
-
-  it("handles reply tags split across chunks", () => {
-    const accumulator = createStreamingDirectiveAccumulator();
-
-    expect(accumulator.consume("[[reply_to_")).toBeNull();
-
-    const result = accumulator.consume("current]] Yo");
-    expect(result?.text).toBe("Yo");
-    expect(result?.replyToCurrent).toBe(true);
-    expect(result?.replyToTag).toBe(true);
-  });
-
-  it("propagates explicit reply ids across chunks", () => {
-    const accumulator = createStreamingDirectiveAccumulator();
-
-    expect(accumulator.consume("[[reply_to: abc-123]]")).toBeNull();
-
-    const result = accumulator.consume("Hi");
-    expect(result?.text).toBe("Hi");
-    expect(result?.replyToId).toBe("abc-123");
-    expect(result?.replyToTag).toBe(true);
-  });
-});
diff --git a/src/auto-reply/reply/get-reply-directives-apply.ts b/src/auto-reply/reply/get-reply-directives-apply.ts
index 0068aed5415..b6ecc4c8300 100644
--- a/src/auto-reply/reply/get-reply-directives-apply.ts
+++ b/src/auto-reply/reply/get-reply-directives-apply.ts
@@ -1,7 +1,7 @@
 import type { OpenClawConfig } from "../../config/config.js";
 import type { SessionEntry } from "../../config/sessions.js";
 import type { MsgContext } from "../templating.js";
-import type { ElevatedLevel, ReasoningLevel, ThinkLevel, VerboseLevel } from "../thinking.js";
+import type { ElevatedLevel } from "../thinking.js";
 import type { ReplyPayload } from "../types.js";
 import type { createModelSelectionState } from "./model-selection.js";
 import type { TypingController } from "./typing.js";
@@ -13,6 +13,7 @@ import {
   isDirectiveOnly,
   persistInlineDirectives,
 } from "./directive-handling.js";
+import { resolveCurrentDirectiveLevels } from "./directive-handling.levels.js";
 import { clearInlineDirectives } from "./get-reply-directives-utils.js";
 
 type AgentDefaults = NonNullable<OpenClawConfig["agents"]>["defaults"];
@@ -122,19 +123,17 @@ export async function applyInlineDirectiveOverrides(params: {
       typing.cleanup();
       return { kind: "reply", reply: undefined };
     }
-    const resolvedDefaultThinkLevel =
-      (sessionEntry?.thinkingLevel as ThinkLevel | undefined) ??
-      (agentCfg?.thinkingDefault as ThinkLevel | undefined) ??
-      (await modelState.resolveDefaultThinkingLevel());
+    const {
+      currentThinkLevel: resolvedDefaultThinkLevel,
+      currentVerboseLevel,
+      currentReasoningLevel,
+      currentElevatedLevel,
+    } = await resolveCurrentDirectiveLevels({
+      sessionEntry,
+      agentCfg,
+      resolveDefaultThinkingLevel: () => modelState.resolveDefaultThinkingLevel(),
+    });
     const currentThinkLevel = resolvedDefaultThinkLevel;
-    const currentVerboseLevel =
-      (sessionEntry?.verboseLevel as VerboseLevel | undefined) ??
-      (agentCfg?.verboseDefault as VerboseLevel | undefined);
-    const currentReasoningLevel =
-      (sessionEntry?.reasoningLevel as ReasoningLevel | undefined) ?? "off";
-    const currentElevatedLevel =
-      (sessionEntry?.elevatedLevel as ElevatedLevel | undefined) ??
-      (agentCfg?.elevatedDefault as ElevatedLevel | undefined);
     const directiveReply = await handleDirectiveOnly({
       cfg,
       directives,
diff --git a/src/auto-reply/reply/get-reply-directives-utils.ts b/src/auto-reply/reply/get-reply-directives-utils.ts
index c6b926ee6dc..02c60a31fac 100644
--- a/src/auto-reply/reply/get-reply-directives-utils.ts
+++ b/src/auto-reply/reply/get-reply-directives-utils.ts
@@ -1,5 +1,22 @@
 import type { InlineDirectives } from "./directive-handling.js";
 
+const CLEARED_EXEC_FIELDS = {
+  hasExecDirective: false,
+  execHost: undefined,
+  execSecurity: undefined,
+  execAsk: undefined,
+  execNode: undefined,
+  rawExecHost: undefined,
+  rawExecSecurity: undefined,
+  rawExecAsk: undefined,
+  rawExecNode: undefined,
+  hasExecOptions: false,
+  invalidExecHost: false,
+  invalidExecSecurity: false,
+  invalidExecAsk: false,
+  invalidExecNode: false,
+} satisfies Partial<InlineDirectives>;
+
 export function clearInlineDirectives(cleaned: string): InlineDirectives {
   return {
     cleaned,
@@ -15,20 +32,7 @@ export function clearInlineDirectives(cleaned: string): InlineDirectives {
     hasElevatedDirective: false,
     elevatedLevel: undefined,
     rawElevatedLevel: undefined,
-    hasExecDirective: false,
-    execHost: undefined,
-    execSecurity: undefined,
-    execAsk: undefined,
-    execNode: undefined,
-    rawExecHost: undefined,
-    rawExecSecurity: undefined,
-    rawExecAsk: undefined,
-    rawExecNode: undefined,
-    hasExecOptions: false,
-    invalidExecHost: false,
-    invalidExecSecurity: false,
-    invalidExecAsk: false,
-    invalidExecNode: false,
+    ...CLEARED_EXEC_FIELDS,
     hasStatusDirective: false,
     hasModelDirective: false,
     rawModelDirective: undefined,
@@ -45,3 +49,10 @@ export function clearInlineDirectives(cleaned: string): InlineDirectives {
     hasQueueOptions: false,
   };
 }
+
+export function clearExecInlineDirectives(directives: InlineDirectives): InlineDirectives {
+  return {
+    ...directives,
+    ...CLEARED_EXEC_FIELDS,
+  };
+}
diff --git a/src/auto-reply/reply/get-reply-directives.ts b/src/auto-reply/reply/get-reply-directives.ts
index 683011ae13c..417bdf6541e 100644
--- a/src/auto-reply/reply/get-reply-directives.ts
+++ b/src/auto-reply/reply/get-reply-directives.ts
@@ -14,7 +14,7 @@ import { resolveBlockStreamingChunking } from "./block-streaming.js";
 import { buildCommandContext } from "./commands.js";
 import { type InlineDirectives, parseInlineDirectives } from "./directive-handling.js";
 import { applyInlineDirectiveOverrides } from "./get-reply-directives-apply.js";
-import { clearInlineDirectives } from "./get-reply-directives-utils.js";
+import { clearExecInlineDirectives, clearInlineDirectives } from "./get-reply-directives-utils.js";
 import { defaultGroupActivation, resolveGroupRequireMention } from "./groups.js";
 import { CURRENT_MESSAGE_MARKER, stripMentions, stripStructuralPrefixes } from "./mentions.js";
 import { createModelSelectionState, resolveContextTokens } from "./model-selection.js";
@@ -169,27 +169,34 @@ export async function resolveReplyDirectives(params: {
     surface: command.surface,
     commandSource: ctx.CommandSource,
   });
-  const shouldResolveSkillCommands =
-    allowTextCommands && command.commandBodyNormalized.includes("/");
-  const skillCommands = shouldResolveSkillCommands
-    ? listSkillCommandsForWorkspace({
-        workspaceDir,
-        cfg,
-        skillFilter,
-      })
-    : [];
   const reservedCommands = new Set(
     listChatCommands().flatMap((cmd) =>
       cmd.textAliases.map((a) => a.replace(/^\//, "").toLowerCase()),
     ),
   );
-  for (const command of skillCommands) {
-    reservedCommands.add(command.name.toLowerCase());
-  }
-  const configuredAliases = Object.values(cfg.agents?.defaults?.models ?? {})
+
+  const rawAliases = Object.values(cfg.agents?.defaults?.models ?? {})
     .map((entry) => entry.alias?.trim())
     .filter((alias): alias is string => Boolean(alias))
     .filter((alias) => !reservedCommands.has(alias.toLowerCase()));
+
+  // Only load workspace skill commands when we actually need them to filter aliases.
+  // This avoids scanning skills for messages that only use inline directives like /think:/verbose:.
+  const skillCommands =
+    allowTextCommands && rawAliases.length > 0
+      ? listSkillCommandsForWorkspace({
+          workspaceDir,
+          cfg,
+          skillFilter,
+        })
+      : [];
+  for (const command of skillCommands) {
+    reservedCommands.add(command.name.toLowerCase());
+  }
+
+  const configuredAliases = rawAliases.filter(
+    (alias) => !reservedCommands.has(alias.toLowerCase()),
+  );
   const allowStatusDirective = allowTextCommands && command.isAuthorizedSender;
   let parsedDirectives = parseInlineDirectives(commandText, {
     modelAliases: configuredAliases,
@@ -215,23 +222,7 @@ export async function resolveReplyDirectives(params: {
   }
   if (isGroup && ctx.WasMentioned !== true && parsedDirectives.hasExecDirective) {
     if (parsedDirectives.execSecurity !== "deny") {
-      parsedDirectives = {
-        ...parsedDirectives,
-        hasExecDirective: false,
-        execHost: undefined,
-        execSecurity: undefined,
-        execAsk: undefined,
-        execNode: undefined,
-        rawExecHost: undefined,
-        rawExecSecurity: undefined,
-        rawExecAsk: undefined,
-        rawExecNode: undefined,
-        hasExecOptions: false,
-        invalidExecHost: false,
-        invalidExecSecurity: false,
-        invalidExecAsk: false,
-        invalidExecNode: false,
-      };
+      parsedDirectives = clearExecInlineDirectives(parsedDirectives);
     }
   }
   const hasInlineDirective =
diff --git a/src/auto-reply/reply/get-reply-inline-actions.ts b/src/auto-reply/reply/get-reply-inline-actions.ts
index 3d6c9296ee0..a2d153e1134 100644
--- a/src/auto-reply/reply/get-reply-inline-actions.ts
+++ b/src/auto-reply/reply/get-reply-inline-actions.ts
@@ -11,12 +11,52 @@ import { createOpenClawTools } from "../../agents/openclaw-tools.js";
 import { getChannelDock } from "../../channels/dock.js";
 import { logVerbose } from "../../globals.js";
 import { resolveGatewayMessageChannel } from "../../utils/message-channel.js";
+import { listChatCommands } from "../commands-registry.js";
 import { listSkillCommandsForWorkspace, resolveSkillCommandInvocation } from "../skill-commands.js";
 import { getAbortMemory } from "./abort.js";
 import { buildStatusReply, handleCommands } from "./commands.js";
 import { isDirectiveOnly } from "./directive-handling.js";
 import { extractInlineSimpleCommand } from "./reply-inline.js";
 
+const builtinSlashCommands = (() => {
+  const reserved = new Set<string>();
+  for (const command of listChatCommands()) {
+    if (command.nativeName) {
+      reserved.add(command.nativeName.toLowerCase());
+    }
+    for (const alias of command.textAliases) {
+      const trimmed = alias.trim();
+      if (!trimmed.startsWith("/")) {
+        continue;
+      }
+      reserved.add(trimmed.slice(1).toLowerCase());
+    }
+  }
+  for (const name of [
+    "think",
+    "verbose",
+    "reasoning",
+    "elevated",
+    "exec",
+    "model",
+    "status",
+    "queue",
+  ]) {
+    reserved.add(name);
+  }
+  return reserved;
+})();
+
+function resolveSlashCommandName(commandBodyNormalized: string): string | null {
+  const trimmed = commandBodyNormalized.trim();
+  if (!trimmed.startsWith("/")) {
+    return null;
+  }
+  const match = trimmed.match(/^\/([^\s:]+)(?::|\s|$)/);
+  const name = match?.[1]?.trim().toLowerCase() ?? "";
+  return name ? name : null;
+}
+
 export type InlineActionResult =
   | { kind: "reply"; reply: ReplyPayload | ReplyPayload[] | undefined }
   | {
@@ -135,7 +175,12 @@ export async function handleInlineActions(params: {
   let directives = initialDirectives;
   let cleanedBody = initialCleanedBody;
 
-  const shouldLoadSkillCommands = command.commandBodyNormalized.startsWith("/");
+  const slashCommandName = resolveSlashCommandName(command.commandBodyNormalized);
+  const shouldLoadSkillCommands =
+    allowTextCommands &&
+    slashCommandName !== null &&
+    // `/skill …` needs the full skill command list.
+    (slashCommandName === "skill" || !builtinSlashCommands.has(slashCommandName));
   const skillCommands =
     shouldLoadSkillCommands && params.skillCommands
       ? params.skillCommands
diff --git a/src/auto-reply/reply/history.test.ts b/src/auto-reply/reply/history.test.ts
deleted file mode 100644
index 7991731daf6..00000000000
--- a/src/auto-reply/reply/history.test.ts
+++ /dev/null
@@ -1,152 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  appendHistoryEntry,
-  buildHistoryContext,
-  buildHistoryContextFromEntries,
-  buildHistoryContextFromMap,
-  buildPendingHistoryContextFromMap,
-  clearHistoryEntriesIfEnabled,
-  HISTORY_CONTEXT_MARKER,
-  recordPendingHistoryEntryIfEnabled,
-} from "./history.js";
-import { CURRENT_MESSAGE_MARKER } from "./mentions.js";
-
-describe("history helpers", () => {
-  it("returns current message when history is empty", () => {
-    const result = buildHistoryContext({
-      historyText: "  ",
-      currentMessage: "hello",
-    });
-    expect(result).toBe("hello");
-  });
-
-  it("wraps history entries and excludes current by default", () => {
-    const result = buildHistoryContextFromEntries({
-      entries: [
-        { sender: "A", body: "one" },
-        { sender: "B", body: "two" },
-      ],
-      currentMessage: "current",
-      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
-    });
-
-    expect(result).toContain(HISTORY_CONTEXT_MARKER);
-    expect(result).toContain("A: one");
-    expect(result).not.toContain("B: two");
-    expect(result).toContain(CURRENT_MESSAGE_MARKER);
-    expect(result).toContain("current");
-  });
-
-  it("trims history to configured limit", () => {
-    const historyMap = new Map<string, { sender: string; body: string }[]>();
-
-    appendHistoryEntry({
-      historyMap,
-      historyKey: "group",
-      limit: 2,
-      entry: { sender: "A", body: "one" },
-    });
-    appendHistoryEntry({
-      historyMap,
-      historyKey: "group",
-      limit: 2,
-      entry: { sender: "B", body: "two" },
-    });
-    appendHistoryEntry({
-      historyMap,
-      historyKey: "group",
-      limit: 2,
-      entry: { sender: "C", body: "three" },
-    });
-
-    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["two", "three"]);
-  });
-
-  it("builds context from map and appends entry", () => {
-    const historyMap = new Map<string, { sender: string; body: string }[]>();
-    historyMap.set("group", [
-      { sender: "A", body: "one" },
-      { sender: "B", body: "two" },
-    ]);
-
-    const result = buildHistoryContextFromMap({
-      historyMap,
-      historyKey: "group",
-      limit: 3,
-      entry: { sender: "C", body: "three" },
-      currentMessage: "current",
-      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
-    });
-
-    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two", "three"]);
-    expect(result).toContain(HISTORY_CONTEXT_MARKER);
-    expect(result).toContain("A: one");
-    expect(result).toContain("B: two");
-    expect(result).not.toContain("C: three");
-  });
-
-  it("builds context from pending map without appending", () => {
-    const historyMap = new Map<string, { sender: string; body: string }[]>();
-    historyMap.set("group", [
-      { sender: "A", body: "one" },
-      { sender: "B", body: "two" },
-    ]);
-
-    const result = buildPendingHistoryContextFromMap({
-      historyMap,
-      historyKey: "group",
-      limit: 3,
-      currentMessage: "current",
-      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
-    });
-
-    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two"]);
-    expect(result).toContain(HISTORY_CONTEXT_MARKER);
-    expect(result).toContain("A: one");
-    expect(result).toContain("B: two");
-    expect(result).toContain(CURRENT_MESSAGE_MARKER);
-    expect(result).toContain("current");
-  });
-
-  it("records pending entries only when enabled", () => {
-    const historyMap = new Map<string, { sender: string; body: string }[]>();
-
-    recordPendingHistoryEntryIfEnabled({
-      historyMap,
-      historyKey: "group",
-      limit: 0,
-      entry: { sender: "A", body: "one" },
-    });
-    expect(historyMap.get("group")).toEqual(undefined);
-
-    recordPendingHistoryEntryIfEnabled({
-      historyMap,
-      historyKey: "group",
-      limit: 2,
-      entry: null,
-    });
-    expect(historyMap.get("group")).toEqual(undefined);
-
-    recordPendingHistoryEntryIfEnabled({
-      historyMap,
-      historyKey: "group",
-      limit: 2,
-      entry: { sender: "B", body: "two" },
-    });
-    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["two"]);
-  });
-
-  it("clears history entries only when enabled", () => {
-    const historyMap = new Map<string, { sender: string; body: string }[]>();
-    historyMap.set("group", [
-      { sender: "A", body: "one" },
-      { sender: "B", body: "two" },
-    ]);
-
-    clearHistoryEntriesIfEnabled({ historyMap, historyKey: "group", limit: 0 });
-    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two"]);
-
-    clearHistoryEntriesIfEnabled({ historyMap, historyKey: "group", limit: 2 });
-    expect(historyMap.get("group")).toEqual([]);
-  });
-});
diff --git a/src/auto-reply/reply/inbound-context.providers-contract.test.ts b/src/auto-reply/reply/inbound-context.providers-contract.test.ts
deleted file mode 100644
index a75b2996c30..00000000000
--- a/src/auto-reply/reply/inbound-context.providers-contract.test.ts
+++ /dev/null
@@ -1,161 +0,0 @@
-import { describe, it } from "vitest";
-import type { MsgContext } from "../templating.js";
-import { expectInboundContextContract } from "../../../test/helpers/inbound-contract.js";
-import { finalizeInboundContext } from "./inbound-context.js";
-
-describe("inbound context contract (providers + extensions)", () => {
-  const cases: Array<{ name: string; ctx: MsgContext }> = [
-    {
-      name: "whatsapp group",
-      ctx: {
-        Provider: "whatsapp",
-        Surface: "whatsapp",
-        ChatType: "group",
-        From: "123@g.us",
-        To: "+15550001111",
-        Body: "[WhatsApp 123@g.us] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "telegram group",
-      ctx: {
-        Provider: "telegram",
-        Surface: "telegram",
-        ChatType: "group",
-        From: "group:123",
-        To: "telegram:123",
-        Body: "[Telegram group:123] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "Telegram Group",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "slack channel",
-      ctx: {
-        Provider: "slack",
-        Surface: "slack",
-        ChatType: "channel",
-        From: "slack:channel:C123",
-        To: "channel:C123",
-        Body: "[Slack #general] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "#general",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "discord channel",
-      ctx: {
-        Provider: "discord",
-        Surface: "discord",
-        ChatType: "channel",
-        From: "group:123",
-        To: "channel:123",
-        Body: "[Discord #general] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "#general",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "signal dm",
-      ctx: {
-        Provider: "signal",
-        Surface: "signal",
-        ChatType: "direct",
-        From: "signal:+15550001111",
-        To: "signal:+15550002222",
-        Body: "[Signal] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-      },
-    },
-    {
-      name: "imessage group",
-      ctx: {
-        Provider: "imessage",
-        Surface: "imessage",
-        ChatType: "group",
-        From: "group:chat_id:123",
-        To: "chat_id:123",
-        Body: "[iMessage Group] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "iMessage Group",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "matrix channel",
-      ctx: {
-        Provider: "matrix",
-        Surface: "matrix",
-        ChatType: "channel",
-        From: "matrix:channel:!room:example.org",
-        To: "room:!room:example.org",
-        Body: "[Matrix] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "#general",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "msteams channel",
-      ctx: {
-        Provider: "msteams",
-        Surface: "msteams",
-        ChatType: "channel",
-        From: "msteams:channel:19:abc@thread.tacv2",
-        To: "msteams:channel:19:abc@thread.tacv2",
-        Body: "[Teams] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "Teams Channel",
-        SenderName: "Alice",
-      },
-    },
-    {
-      name: "zalo dm",
-      ctx: {
-        Provider: "zalo",
-        Surface: "zalo",
-        ChatType: "direct",
-        From: "zalo:123",
-        To: "zalo:123",
-        Body: "[Zalo] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-      },
-    },
-    {
-      name: "zalouser group",
-      ctx: {
-        Provider: "zalouser",
-        Surface: "zalouser",
-        ChatType: "group",
-        From: "group:123",
-        To: "zalouser:123",
-        Body: "[Zalo Personal] hi",
-        RawBody: "hi",
-        CommandBody: "hi",
-        GroupSubject: "Zalouser Group",
-        SenderName: "Alice",
-      },
-    },
-  ];
-
-  for (const entry of cases) {
-    it(entry.name, () => {
-      const ctx = finalizeInboundContext({ ...entry.ctx });
-      expectInboundContextContract(ctx);
-    });
-  }
-});
diff --git a/src/auto-reply/reply/inbound-meta.test.ts b/src/auto-reply/reply/inbound-meta.test.ts
index f358aebc794..a1daa577d08 100644
--- a/src/auto-reply/reply/inbound-meta.test.ts
+++ b/src/auto-reply/reply/inbound-meta.test.ts
@@ -1,6 +1,53 @@
 import { describe, expect, it } from "vitest";
 import type { TemplateContext } from "../templating.js";
-import { buildInboundUserContextPrefix } from "./inbound-meta.js";
+import { buildInboundMetaSystemPrompt, buildInboundUserContextPrefix } from "./inbound-meta.js";
+
+function parseInboundMetaPayload(text: string): Record<string, unknown> {
+  const match = text.match(/```json\n([\s\S]*?)\n```/);
+  if (!match?.[1]) {
+    throw new Error("missing inbound meta json block");
+  }
+  return JSON.parse(match[1]) as Record<string, unknown>;
+}
+
+describe("buildInboundMetaSystemPrompt", () => {
+  it("includes trusted message and routing ids for tool actions", () => {
+    const prompt = buildInboundMetaSystemPrompt({
+      MessageSid: "123",
+      MessageSidFull: "123",
+      ReplyToId: "99",
+      OriginatingTo: "telegram:5494292670",
+      OriginatingChannel: "telegram",
+      Provider: "telegram",
+      Surface: "telegram",
+      ChatType: "direct",
+    } as TemplateContext);
+
+    const payload = parseInboundMetaPayload(prompt);
+    expect(payload["schema"]).toBe("openclaw.inbound_meta.v1");
+    expect(payload["message_id"]).toBe("123");
+    expect(payload["message_id_full"]).toBeUndefined();
+    expect(payload["reply_to_id"]).toBe("99");
+    expect(payload["chat_id"]).toBe("telegram:5494292670");
+    expect(payload["channel"]).toBe("telegram");
+  });
+
+  it("keeps message_id_full only when it differs from message_id", () => {
+    const prompt = buildInboundMetaSystemPrompt({
+      MessageSid: "short-id",
+      MessageSidFull: "full-provider-message-id",
+      OriginatingTo: "channel:C1",
+      OriginatingChannel: "slack",
+      Provider: "slack",
+      Surface: "slack",
+      ChatType: "group",
+    } as TemplateContext);
+
+    const payload = parseInboundMetaPayload(prompt);
+    expect(payload["message_id"]).toBe("short-id");
+    expect(payload["message_id_full"]).toBe("full-provider-message-id");
+  });
+});
 
 describe("buildInboundUserContextPrefix", () => {
   it("omits conversation label block for direct chats", () => {
diff --git a/src/auto-reply/reply/inbound-meta.ts b/src/auto-reply/reply/inbound-meta.ts
index 83676810238..03c06b7e2b0 100644
--- a/src/auto-reply/reply/inbound-meta.ts
+++ b/src/auto-reply/reply/inbound-meta.ts
@@ -13,11 +13,19 @@ function safeTrim(value: unknown): string | undefined {
 export function buildInboundMetaSystemPrompt(ctx: TemplateContext): string {
   const chatType = normalizeChatType(ctx.ChatType);
   const isDirect = !chatType || chatType === "direct";
+  const messageId = safeTrim(ctx.MessageSid);
+  const messageIdFull = safeTrim(ctx.MessageSidFull);
+  const replyToId = safeTrim(ctx.ReplyToId);
+  const chatId = safeTrim(ctx.OriginatingTo);
 
   // Keep system metadata strictly free of attacker-controlled strings (sender names, group subjects, etc.).
   // Those belong in the user-role "untrusted context" blocks.
   const payload = {
     schema: "openclaw.inbound_meta.v1",
+    message_id: messageId,
+    message_id_full: messageIdFull && messageIdFull !== messageId ? messageIdFull : undefined,
+    chat_id: chatId,
+    reply_to_id: replyToId,
     channel: safeTrim(ctx.OriginatingChannel) ?? safeTrim(ctx.Surface) ?? safeTrim(ctx.Provider),
     provider: safeTrim(ctx.Provider),
     surface: safeTrim(ctx.Surface),
diff --git a/src/auto-reply/reply/inbound-text.test.ts b/src/auto-reply/reply/inbound-text.test.ts
deleted file mode 100644
index 2b54a71299a..00000000000
--- a/src/auto-reply/reply/inbound-text.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeInboundTextNewlines } from "./inbound-text.js";
-
-describe("normalizeInboundTextNewlines", () => {
-  it("converts CRLF to LF", () => {
-    expect(normalizeInboundTextNewlines("hello\r\nworld")).toBe("hello\nworld");
-  });
-
-  it("converts CR to LF", () => {
-    expect(normalizeInboundTextNewlines("hello\rworld")).toBe("hello\nworld");
-  });
-
-  it("preserves literal backslash-n sequences in Windows paths", () => {
-    // Windows paths like C:\Work\nxxx should NOT have \n converted to newlines
-    const windowsPath = "C:\\Work\\nxxx\\README.md";
-    expect(normalizeInboundTextNewlines(windowsPath)).toBe("C:\\Work\\nxxx\\README.md");
-  });
-
-  it("preserves backslash-n in messages containing Windows paths", () => {
-    const message = "Please read the file at C:\\Work\\nxxx\\README.md";
-    expect(normalizeInboundTextNewlines(message)).toBe(
-      "Please read the file at C:\\Work\\nxxx\\README.md",
-    );
-  });
-
-  it("preserves multiple backslash-n sequences", () => {
-    const message = "C:\\new\\notes\\nested";
-    expect(normalizeInboundTextNewlines(message)).toBe("C:\\new\\notes\\nested");
-  });
-
-  it("still normalizes actual CRLF while preserving backslash-n", () => {
-    const message = "Line 1\r\nC:\\Work\\nxxx";
-    expect(normalizeInboundTextNewlines(message)).toBe("Line 1\nC:\\Work\\nxxx");
-  });
-});
diff --git a/src/auto-reply/reply/line-directives.test.ts b/src/auto-reply/reply/line-directives.test.ts
deleted file mode 100644
index bf60232b854..00000000000
--- a/src/auto-reply/reply/line-directives.test.ts
+++ /dev/null
@@ -1,377 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseLineDirectives, hasLineDirectives } from "./line-directives.js";
-
-const getLineData = (result: ReturnType<typeof parseLineDirectives>) =>
-  (result.channelData?.line as Record<string, unknown> | undefined) ?? {};
-
-describe("hasLineDirectives", () => {
-  it("detects quick_replies directive", () => {
-    expect(hasLineDirectives("Here are options [[quick_replies: A, B, C]]")).toBe(true);
-  });
-
-  it("detects location directive", () => {
-    expect(hasLineDirectives("[[location: Place | Address | 35.6 | 139.7]]")).toBe(true);
-  });
-
-  it("detects confirm directive", () => {
-    expect(hasLineDirectives("[[confirm: Continue? | Yes | No]]")).toBe(true);
-  });
-
-  it("detects buttons directive", () => {
-    expect(hasLineDirectives("[[buttons: Menu | Choose | Opt1:data1, Opt2:data2]]")).toBe(true);
-  });
-
-  it("returns false for regular text", () => {
-    expect(hasLineDirectives("Just regular text")).toBe(false);
-  });
-
-  it("returns false for similar but invalid patterns", () => {
-    expect(hasLineDirectives("[[not_a_directive: something]]")).toBe(false);
-  });
-
-  it("detects media_player directive", () => {
-    expect(hasLineDirectives("[[media_player: Song | Artist | Speaker]]")).toBe(true);
-  });
-
-  it("detects event directive", () => {
-    expect(hasLineDirectives("[[event: Meeting | Jan 24 | 2pm]]")).toBe(true);
-  });
-
-  it("detects agenda directive", () => {
-    expect(hasLineDirectives("[[agenda: Today | Meeting:9am, Lunch:12pm]]")).toBe(true);
-  });
-
-  it("detects device directive", () => {
-    expect(hasLineDirectives("[[device: TV | Room]]")).toBe(true);
-  });
-
-  it("detects appletv_remote directive", () => {
-    expect(hasLineDirectives("[[appletv_remote: Apple TV | Playing]]")).toBe(true);
-  });
-});
-
-describe("parseLineDirectives", () => {
-  describe("quick_replies", () => {
-    it("parses quick_replies and removes from text", () => {
-      const result = parseLineDirectives({
-        text: "Choose one:\n[[quick_replies: Option A, Option B, Option C]]",
-      });
-
-      expect(getLineData(result).quickReplies).toEqual(["Option A", "Option B", "Option C"]);
-      expect(result.text).toBe("Choose one:");
-    });
-
-    it("handles quick_replies in middle of text", () => {
-      const result = parseLineDirectives({
-        text: "Before [[quick_replies: A, B]] After",
-      });
-
-      expect(getLineData(result).quickReplies).toEqual(["A", "B"]);
-      expect(result.text).toBe("Before  After");
-    });
-
-    it("merges with existing quickReplies", () => {
-      const result = parseLineDirectives({
-        text: "Text [[quick_replies: C, D]]",
-        channelData: { line: { quickReplies: ["A", "B"] } },
-      });
-
-      expect(getLineData(result).quickReplies).toEqual(["A", "B", "C", "D"]);
-    });
-  });
-
-  describe("location", () => {
-    it("parses location with all fields", () => {
-      const result = parseLineDirectives({
-        text: "Here's the location:\n[[location: Tokyo Station | Tokyo, Japan | 35.6812 | 139.7671]]",
-      });
-
-      expect(getLineData(result).location).toEqual({
-        title: "Tokyo Station",
-        address: "Tokyo, Japan",
-        latitude: 35.6812,
-        longitude: 139.7671,
-      });
-      expect(result.text).toBe("Here's the location:");
-    });
-
-    it("ignores invalid coordinates", () => {
-      const result = parseLineDirectives({
-        text: "[[location: Place | Address | invalid | 139.7]]",
-      });
-
-      expect(getLineData(result).location).toBeUndefined();
-    });
-
-    it("does not override existing location", () => {
-      const existing = { title: "Existing", address: "Addr", latitude: 1, longitude: 2 };
-      const result = parseLineDirectives({
-        text: "[[location: New | New Addr | 35.6 | 139.7]]",
-        channelData: { line: { location: existing } },
-      });
-
-      expect(getLineData(result).location).toEqual(existing);
-    });
-  });
-
-  describe("confirm", () => {
-    it("parses simple confirm", () => {
-      const result = parseLineDirectives({
-        text: "[[confirm: Delete this item? | Yes | No]]",
-      });
-
-      expect(getLineData(result).templateMessage).toEqual({
-        type: "confirm",
-        text: "Delete this item?",
-        confirmLabel: "Yes",
-        confirmData: "yes",
-        cancelLabel: "No",
-        cancelData: "no",
-        altText: "Delete this item?",
-      });
-      // Text is undefined when directive consumes entire text
-      expect(result.text).toBeUndefined();
-    });
-
-    it("parses confirm with custom data", () => {
-      const result = parseLineDirectives({
-        text: "[[confirm: Proceed? | OK:action=confirm | Cancel:action=cancel]]",
-      });
-
-      expect(getLineData(result).templateMessage).toEqual({
-        type: "confirm",
-        text: "Proceed?",
-        confirmLabel: "OK",
-        confirmData: "action=confirm",
-        cancelLabel: "Cancel",
-        cancelData: "action=cancel",
-        altText: "Proceed?",
-      });
-    });
-  });
-
-  describe("buttons", () => {
-    it("parses buttons with message actions", () => {
-      const result = parseLineDirectives({
-        text: "[[buttons: Menu | Select an option | Help:/help, Status:/status]]",
-      });
-
-      expect(getLineData(result).templateMessage).toEqual({
-        type: "buttons",
-        title: "Menu",
-        text: "Select an option",
-        actions: [
-          { type: "message", label: "Help", data: "/help" },
-          { type: "message", label: "Status", data: "/status" },
-        ],
-        altText: "Menu: Select an option",
-      });
-    });
-
-    it("parses buttons with uri actions", () => {
-      const result = parseLineDirectives({
-        text: "[[buttons: Links | Visit us | Site:https://example.com]]",
-      });
-
-      const templateMessage = getLineData(result).templateMessage as {
-        type?: string;
-        actions?: Array<Record<string, unknown>>;
-      };
-      expect(templateMessage?.type).toBe("buttons");
-      if (templateMessage?.type === "buttons") {
-        expect(templateMessage.actions?.[0]).toEqual({
-          type: "uri",
-          label: "Site",
-          uri: "https://example.com",
-        });
-      }
-    });
-
-    it("parses buttons with postback actions", () => {
-      const result = parseLineDirectives({
-        text: "[[buttons: Actions | Choose | Select:action=select&id=1]]",
-      });
-
-      const templateMessage = getLineData(result).templateMessage as {
-        type?: string;
-        actions?: Array<Record<string, unknown>>;
-      };
-      expect(templateMessage?.type).toBe("buttons");
-      if (templateMessage?.type === "buttons") {
-        expect(templateMessage.actions?.[0]).toEqual({
-          type: "postback",
-          label: "Select",
-          data: "action=select&id=1",
-        });
-      }
-    });
-
-    it("limits to 4 actions", () => {
-      const result = parseLineDirectives({
-        text: "[[buttons: Menu | Text | A:a, B:b, C:c, D:d, E:e, F:f]]",
-      });
-
-      const templateMessage = getLineData(result).templateMessage as {
-        type?: string;
-        actions?: Array<Record<string, unknown>>;
-      };
-      expect(templateMessage?.type).toBe("buttons");
-      if (templateMessage?.type === "buttons") {
-        expect(templateMessage.actions?.length).toBe(4);
-      }
-    });
-  });
-
-  describe("media_player", () => {
-    it("parses media_player with all fields", () => {
-      const result = parseLineDirectives({
-        text: "Now playing:\n[[media_player: Bohemian Rhapsody | Queen | Speaker | https://example.com/album.jpg | playing]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as {
-        altText?: string;
-        contents?: { footer?: { contents?: unknown[] } };
-      };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("🎵 Bohemian Rhapsody - Queen");
-      const contents = flexMessage?.contents as { footer?: { contents?: unknown[] } };
-      expect(contents.footer?.contents?.length).toBeGreaterThan(0);
-      expect(result.text).toBe("Now playing:");
-    });
-
-    it("parses media_player with minimal fields", () => {
-      const result = parseLineDirectives({
-        text: "[[media_player: Unknown Track]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("🎵 Unknown Track");
-    });
-
-    it("handles paused status", () => {
-      const result = parseLineDirectives({
-        text: "[[media_player: Song | Artist | Player | | paused]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as {
-        contents?: { body: { contents: unknown[] } };
-      };
-      expect(flexMessage).toBeDefined();
-      const contents = flexMessage?.contents as { body: { contents: unknown[] } };
-      expect(contents).toBeDefined();
-    });
-  });
-
-  describe("event", () => {
-    it("parses event with all fields", () => {
-      const result = parseLineDirectives({
-        text: "[[event: Team Meeting | January 24, 2026 | 2:00 PM - 3:00 PM | Conference Room A | Discuss Q1 roadmap]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📅 Team Meeting - January 24, 2026 2:00 PM - 3:00 PM");
-    });
-
-    it("parses event with minimal fields", () => {
-      const result = parseLineDirectives({
-        text: "[[event: Birthday Party | March 15]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📅 Birthday Party - March 15");
-    });
-  });
-
-  describe("agenda", () => {
-    it("parses agenda with multiple events", () => {
-      const result = parseLineDirectives({
-        text: "[[agenda: Today's Schedule | Team Meeting:9:00 AM, Lunch:12:00 PM, Review:3:00 PM]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📋 Today's Schedule (3 events)");
-    });
-
-    it("parses agenda with events without times", () => {
-      const result = parseLineDirectives({
-        text: "[[agenda: Tasks | Buy groceries, Call mom, Workout]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📋 Tasks (3 events)");
-    });
-  });
-
-  describe("device", () => {
-    it("parses device with controls", () => {
-      const result = parseLineDirectives({
-        text: "[[device: TV | Streaming Box | Playing | Play/Pause:toggle, Menu:menu]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📱 TV: Playing");
-    });
-
-    it("parses device with minimal fields", () => {
-      const result = parseLineDirectives({
-        text: "[[device: Speaker]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toBe("📱 Speaker");
-    });
-  });
-
-  describe("appletv_remote", () => {
-    it("parses appletv_remote with status", () => {
-      const result = parseLineDirectives({
-        text: "[[appletv_remote: Apple TV | Playing]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-      expect(flexMessage?.altText).toContain("Apple TV");
-    });
-
-    it("parses appletv_remote with minimal fields", () => {
-      const result = parseLineDirectives({
-        text: "[[appletv_remote: Apple TV]]",
-      });
-
-      const flexMessage = getLineData(result).flexMessage as { altText?: string };
-      expect(flexMessage).toBeDefined();
-    });
-  });
-
-  describe("combined directives", () => {
-    it("handles text with no directives", () => {
-      const result = parseLineDirectives({
-        text: "Just plain text here",
-      });
-
-      expect(result.text).toBe("Just plain text here");
-      expect(getLineData(result).quickReplies).toBeUndefined();
-      expect(getLineData(result).location).toBeUndefined();
-      expect(getLineData(result).templateMessage).toBeUndefined();
-    });
-
-    it("preserves other payload fields", () => {
-      const result = parseLineDirectives({
-        text: "Hello [[quick_replies: A, B]]",
-        mediaUrl: "https://example.com/image.jpg",
-        replyToId: "msg123",
-      });
-
-      expect(result.mediaUrl).toBe("https://example.com/image.jpg");
-      expect(result.replyToId).toBe("msg123");
-      expect(getLineData(result).quickReplies).toEqual(["A", "B"]);
-    });
-  });
-});
diff --git a/src/auto-reply/reply/memory-flush.test.ts b/src/auto-reply/reply/memory-flush.test.ts
index e3dcc124e18..362b1b10a2c 100644
--- a/src/auto-reply/reply/memory-flush.test.ts
+++ b/src/auto-reply/reply/memory-flush.test.ts
@@ -1,133 +1,36 @@
 import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
-  resolveMemoryFlushContextWindowTokens,
-  resolveMemoryFlushSettings,
-  shouldRunMemoryFlush,
-} from "./memory-flush.js";
+import { resolveMemoryFlushPromptForRun } from "./memory-flush.js";
 
-describe("memory flush settings", () => {
-  it("defaults to enabled with fallback prompt and system prompt", () => {
-    const settings = resolveMemoryFlushSettings();
-    expect(settings).not.toBeNull();
-    expect(settings?.enabled).toBe(true);
-    expect(settings?.prompt.length).toBeGreaterThan(0);
-    expect(settings?.systemPrompt.length).toBeGreaterThan(0);
-  });
-
-  it("respects disable flag", () => {
-    expect(
-      resolveMemoryFlushSettings({
-        agents: {
-          defaults: { compaction: { memoryFlush: { enabled: false } } },
-        },
-      }),
-    ).toBeNull();
-  });
-
-  it("appends NO_REPLY hint when missing", () => {
-    const settings = resolveMemoryFlushSettings({
-      agents: {
-        defaults: {
-          compaction: {
-            memoryFlush: {
-              prompt: "Write memories now.",
-              systemPrompt: "Flush memory.",
-            },
-          },
-        },
+describe("resolveMemoryFlushPromptForRun", () => {
+  const cfg = {
+    agents: {
+      defaults: {
+        userTimezone: "America/New_York",
+        timeFormat: "12",
       },
+    },
+  };
+
+  it("replaces YYYY-MM-DD using user timezone and appends current time", () => {
+    const prompt = resolveMemoryFlushPromptForRun({
+      prompt: "Store durable notes in memory/YYYY-MM-DD.md",
+      cfg,
+      nowMs: Date.UTC(2026, 1, 16, 15, 0, 0),
     });
-    expect(settings?.prompt).toContain("NO_REPLY");
-    expect(settings?.systemPrompt).toContain("NO_REPLY");
-  });
-});
-
-describe("shouldRunMemoryFlush", () => {
-  it("requires totalTokens and threshold", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: { totalTokens: 0 },
-        contextWindowTokens: 16_000,
-        reserveTokensFloor: 20_000,
-        softThresholdTokens: DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
-      }),
-    ).toBe(false);
-  });
-
-  it("skips when entry is missing", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: undefined,
-        contextWindowTokens: 16_000,
-        reserveTokensFloor: 1_000,
-        softThresholdTokens: DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
-      }),
-    ).toBe(false);
-  });
-
-  it("skips when under threshold", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: { totalTokens: 10_000 },
-        contextWindowTokens: 100_000,
-        reserveTokensFloor: 20_000,
-        softThresholdTokens: 10_000,
-      }),
-    ).toBe(false);
-  });
-
-  it("triggers at the threshold boundary", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: { totalTokens: 85 },
-        contextWindowTokens: 100,
-        reserveTokensFloor: 10,
-        softThresholdTokens: 5,
-      }),
-    ).toBe(true);
-  });
-
-  it("skips when already flushed for current compaction count", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: {
-          totalTokens: 90_000,
-          compactionCount: 2,
-          memoryFlushCompactionCount: 2,
-        },
-        contextWindowTokens: 100_000,
-        reserveTokensFloor: 5_000,
-        softThresholdTokens: 2_000,
-      }),
-    ).toBe(false);
-  });
-
-  it("runs when above threshold and not flushed", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: { totalTokens: 96_000, compactionCount: 1 },
-        contextWindowTokens: 100_000,
-        reserveTokensFloor: 5_000,
-        softThresholdTokens: 2_000,
-      }),
-    ).toBe(true);
-  });
-
-  it("ignores stale cached totals", () => {
-    expect(
-      shouldRunMemoryFlush({
-        entry: { totalTokens: 96_000, totalTokensFresh: false, compactionCount: 1 },
-        contextWindowTokens: 100_000,
-        reserveTokensFloor: 5_000,
-        softThresholdTokens: 2_000,
-      }),
-    ).toBe(false);
-  });
-});
-
-describe("resolveMemoryFlushContextWindowTokens", () => {
-  it("falls back to agent config or default tokens", () => {
-    expect(resolveMemoryFlushContextWindowTokens({ agentCfgContextTokens: 42_000 })).toBe(42_000);
+
+    expect(prompt).toContain("memory/2026-02-16.md");
+    expect(prompt).toContain("Current time:");
+    expect(prompt).toContain("(America/New_York)");
+  });
+
+  it("does not append a duplicate current time line", () => {
+    const prompt = resolveMemoryFlushPromptForRun({
+      prompt: "Store notes.\nCurrent time: already present",
+      cfg,
+      nowMs: Date.UTC(2026, 1, 16, 15, 0, 0),
+    });
+
+    expect(prompt).toContain("Current time: already present");
+    expect((prompt.match(/Current time:/g) ?? []).length).toBe(1);
   });
 });
diff --git a/src/auto-reply/reply/memory-flush.ts b/src/auto-reply/reply/memory-flush.ts
index 8ff6f1b1b6f..a3b50ae3444 100644
--- a/src/auto-reply/reply/memory-flush.ts
+++ b/src/auto-reply/reply/memory-flush.ts
@@ -1,5 +1,6 @@
 import type { OpenClawConfig } from "../../config/config.js";
 import { lookupContextTokens } from "../../agents/context.js";
+import { resolveCronStyleNow } from "../../agents/current-time.js";
 import { DEFAULT_CONTEXT_TOKENS } from "../../agents/defaults.js";
 import { DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR } from "../../agents/pi-settings.js";
 import { resolveFreshSessionTotalTokens, type SessionEntry } from "../../config/sessions.js";
@@ -20,6 +21,40 @@ export const DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT = [
   `You may reply, but usually ${SILENT_REPLY_TOKEN} is correct.`,
 ].join(" ");
 
+function formatDateStampInTimezone(nowMs: number, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(nowMs));
+  const year = parts.find((part) => part.type === "year")?.value;
+  const month = parts.find((part) => part.type === "month")?.value;
+  const day = parts.find((part) => part.type === "day")?.value;
+  if (year && month && day) {
+    return `${year}-${month}-${day}`;
+  }
+  return new Date(nowMs).toISOString().slice(0, 10);
+}
+
+export function resolveMemoryFlushPromptForRun(params: {
+  prompt: string;
+  cfg?: OpenClawConfig;
+  nowMs?: number;
+}): string {
+  const nowMs = Number.isFinite(params.nowMs) ? (params.nowMs as number) : Date.now();
+  const { userTimezone, timeLine } = resolveCronStyleNow(params.cfg ?? {}, nowMs);
+  const dateStamp = formatDateStampInTimezone(nowMs, userTimezone);
+  const withDate = params.prompt.replaceAll("YYYY-MM-DD", dateStamp).trimEnd();
+  if (!withDate) {
+    return timeLine;
+  }
+  if (withDate.includes("Current time:")) {
+    return withDate;
+  }
+  return `${withDate}\n${timeLine}`;
+}
+
 export type MemoryFlushSettings = {
   enabled: boolean;
   softThresholdTokens: number;
diff --git a/src/auto-reply/reply/mentions.test.ts b/src/auto-reply/reply/mentions.test.ts
deleted file mode 100644
index 8b700d23b1f..00000000000
--- a/src/auto-reply/reply/mentions.test.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { matchesMentionWithExplicit } from "./mentions.js";
-
-describe("matchesMentionWithExplicit", () => {
-  const mentionRegexes = [/\bopenclaw\b/i];
-
-  it("checks mentionPatterns even when explicit mention is available", () => {
-    const result = matchesMentionWithExplicit({
-      text: "@openclaw hello",
-      mentionRegexes,
-      explicit: {
-        hasAnyMention: true,
-        isExplicitlyMentioned: false,
-        canResolveExplicit: true,
-      },
-    });
-    expect(result).toBe(true);
-  });
-
-  it("returns false when explicit is false and no regex match", () => {
-    const result = matchesMentionWithExplicit({
-      text: "<@999999> hello",
-      mentionRegexes,
-      explicit: {
-        hasAnyMention: true,
-        isExplicitlyMentioned: false,
-        canResolveExplicit: true,
-      },
-    });
-    expect(result).toBe(false);
-  });
-
-  it("returns true when explicitly mentioned even if regexes do not match", () => {
-    const result = matchesMentionWithExplicit({
-      text: "<@123456>",
-      mentionRegexes: [],
-      explicit: {
-        hasAnyMention: true,
-        isExplicitlyMentioned: true,
-        canResolveExplicit: true,
-      },
-    });
-    expect(result).toBe(true);
-  });
-
-  it("falls back to regex matching when explicit mention cannot be resolved", () => {
-    const result = matchesMentionWithExplicit({
-      text: "openclaw please",
-      mentionRegexes,
-      explicit: {
-        hasAnyMention: true,
-        isExplicitlyMentioned: false,
-        canResolveExplicit: false,
-      },
-    });
-    expect(result).toBe(true);
-  });
-});
diff --git a/src/auto-reply/reply/model-selection.override-respected.test.ts b/src/auto-reply/reply/model-selection.override-respected.test.ts
deleted file mode 100644
index b3457fc5596..00000000000
--- a/src/auto-reply/reply/model-selection.override-respected.test.ts
+++ /dev/null
@@ -1,132 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { createModelSelectionState } from "./model-selection.js";
-
-vi.mock("../../agents/model-catalog.js", () => ({
-  loadModelCatalog: vi.fn(async () => [
-    { provider: "inferencer", id: "deepseek-v3-4bit-mlx", name: "DeepSeek V3" },
-    { provider: "kimi-coding", id: "k2p5", name: "Kimi K2.5" },
-    { provider: "anthropic", id: "claude-opus-4-5", name: "Claude Opus 4.5" },
-  ]),
-}));
-
-const defaultProvider = "inferencer";
-const defaultModel = "deepseek-v3-4bit-mlx";
-
-const makeEntry = (overrides: Record<string, unknown> = {}) => ({
-  sessionId: "session-id",
-  updatedAt: Date.now(),
-  ...overrides,
-});
-
-describe("createModelSelectionState respects session model override", () => {
-  it("applies session modelOverride when set", async () => {
-    const cfg = {} as OpenClawConfig;
-    const sessionKey = "agent:main:main";
-    const sessionEntry = makeEntry({
-      providerOverride: "kimi-coding",
-      modelOverride: "k2p5",
-    });
-    const sessionStore = { [sessionKey]: sessionEntry };
-
-    const state = await createModelSelectionState({
-      cfg,
-      agentCfg: undefined,
-      sessionEntry,
-      sessionStore,
-      sessionKey,
-      defaultProvider,
-      defaultModel,
-      provider: defaultProvider,
-      model: defaultModel,
-      hasModelDirective: false,
-    });
-
-    expect(state.provider).toBe("kimi-coding");
-    expect(state.model).toBe("k2p5");
-  });
-
-  it("falls back to default when no modelOverride is set", async () => {
-    const cfg = {} as OpenClawConfig;
-    const sessionKey = "agent:main:main";
-    const sessionEntry = makeEntry();
-    const sessionStore = { [sessionKey]: sessionEntry };
-
-    const state = await createModelSelectionState({
-      cfg,
-      agentCfg: undefined,
-      sessionEntry,
-      sessionStore,
-      sessionKey,
-      defaultProvider,
-      defaultModel,
-      provider: defaultProvider,
-      model: defaultModel,
-      hasModelDirective: false,
-    });
-
-    expect(state.provider).toBe(defaultProvider);
-    expect(state.model).toBe(defaultModel);
-  });
-
-  it("respects modelOverride even when session model field differs", async () => {
-    // This tests the scenario from issue #14783: user switches model via /model,
-    // the override is stored, but session.model still reflects the last-used
-    // fallback model. The override should take precedence.
-    const cfg = {} as OpenClawConfig;
-    const sessionKey = "agent:main:main";
-    const sessionEntry = makeEntry({
-      // Last-used model (from fallback) - should NOT be used for selection
-      model: "k2p5",
-      modelProvider: "kimi-coding",
-      contextTokens: 262_000,
-      // User's explicit override - SHOULD be used
-      providerOverride: "anthropic",
-      modelOverride: "claude-opus-4-5",
-    });
-    const sessionStore = { [sessionKey]: sessionEntry };
-
-    const state = await createModelSelectionState({
-      cfg,
-      agentCfg: undefined,
-      sessionEntry,
-      sessionStore,
-      sessionKey,
-      defaultProvider,
-      defaultModel,
-      provider: defaultProvider,
-      model: defaultModel,
-      hasModelDirective: false,
-    });
-
-    // Should use the override, not the last-used model
-    expect(state.provider).toBe("anthropic");
-    expect(state.model).toBe("claude-opus-4-5");
-  });
-
-  it("uses default provider when providerOverride is not set but modelOverride is", async () => {
-    const cfg = {} as OpenClawConfig;
-    const sessionKey = "agent:main:main";
-    const sessionEntry = makeEntry({
-      modelOverride: "deepseek-v3-4bit-mlx",
-      // no providerOverride
-    });
-    const sessionStore = { [sessionKey]: sessionEntry };
-
-    const state = await createModelSelectionState({
-      cfg,
-      agentCfg: undefined,
-      sessionEntry,
-      sessionStore,
-      sessionKey,
-      defaultProvider,
-      defaultModel,
-      provider: defaultProvider,
-      model: defaultModel,
-      hasModelDirective: false,
-    });
-
-    expect(state.provider).toBe(defaultProvider);
-    expect(state.model).toBe("deepseek-v3-4bit-mlx");
-  });
-});
diff --git a/src/auto-reply/reply/model-selection.inherit-parent.test.ts b/src/auto-reply/reply/model-selection.test.ts
similarity index 56%
rename from src/auto-reply/reply/model-selection.inherit-parent.test.ts
rename to src/auto-reply/reply/model-selection.test.ts
index e80088b42a0..3da30c3c6da 100644
--- a/src/auto-reply/reply/model-selection.inherit-parent.test.ts
+++ b/src/auto-reply/reply/model-selection.test.ts
@@ -4,44 +4,46 @@ import { createModelSelectionState } from "./model-selection.js";
 
 vi.mock("../../agents/model-catalog.js", () => ({
   loadModelCatalog: vi.fn(async () => [
+    { provider: "anthropic", id: "claude-opus-4-5", name: "Claude Opus 4.5" },
+    { provider: "inferencer", id: "deepseek-v3-4bit-mlx", name: "DeepSeek V3" },
+    { provider: "kimi-coding", id: "k2p5", name: "Kimi K2.5" },
     { provider: "openai", id: "gpt-4o-mini", name: "GPT-4o mini" },
     { provider: "openai", id: "gpt-4o", name: "GPT-4o" },
-    { provider: "anthropic", id: "claude-opus-4-5", name: "Claude Opus 4.5" },
   ]),
 }));
 
-const defaultProvider = "openai";
-const defaultModel = "gpt-4o-mini";
-
 const makeEntry = (overrides: Record<string, unknown> = {}) => ({
   sessionId: "session-id",
   updatedAt: Date.now(),
   ...overrides,
 });
 
-async function resolveState(params: {
-  cfg: OpenClawConfig;
-  sessionEntry: ReturnType<typeof makeEntry>;
-  sessionStore: Record<string, ReturnType<typeof makeEntry>>;
-  sessionKey: string;
-  parentSessionKey?: string;
-}) {
-  return createModelSelectionState({
-    cfg: params.cfg,
-    agentCfg: params.cfg.agents?.defaults,
-    sessionEntry: params.sessionEntry,
-    sessionStore: params.sessionStore,
-    sessionKey: params.sessionKey,
-    parentSessionKey: params.parentSessionKey,
-    defaultProvider,
-    defaultModel,
-    provider: defaultProvider,
-    model: defaultModel,
-    hasModelDirective: false,
-  });
-}
-
 describe("createModelSelectionState parent inheritance", () => {
+  const defaultProvider = "openai";
+  const defaultModel = "gpt-4o-mini";
+
+  async function resolveState(params: {
+    cfg: OpenClawConfig;
+    sessionEntry: ReturnType<typeof makeEntry>;
+    sessionStore: Record<string, ReturnType<typeof makeEntry>>;
+    sessionKey: string;
+    parentSessionKey?: string;
+  }) {
+    return createModelSelectionState({
+      cfg: params.cfg,
+      agentCfg: params.cfg.agents?.defaults,
+      sessionEntry: params.sessionEntry,
+      sessionStore: params.sessionStore,
+      sessionKey: params.sessionKey,
+      parentSessionKey: params.parentSessionKey,
+      defaultProvider,
+      defaultModel,
+      provider: defaultProvider,
+      model: defaultModel,
+      hasModelDirective: false,
+    });
+  }
+
   it("inherits parent override from explicit parentSessionKey", async () => {
     const cfg = {} as OpenClawConfig;
     const parentKey = "agent:main:discord:channel:c1";
@@ -212,3 +214,112 @@ describe("createModelSelectionState parent inheritance", () => {
     expect(state.model).toBe("claude-opus-4-5");
   });
 });
+
+describe("createModelSelectionState respects session model override", () => {
+  const defaultProvider = "inferencer";
+  const defaultModel = "deepseek-v3-4bit-mlx";
+
+  it("applies session modelOverride when set", async () => {
+    const cfg = {} as OpenClawConfig;
+    const sessionKey = "agent:main:main";
+    const sessionEntry = makeEntry({
+      providerOverride: "kimi-coding",
+      modelOverride: "k2p5",
+    });
+    const sessionStore = { [sessionKey]: sessionEntry };
+
+    const state = await createModelSelectionState({
+      cfg,
+      agentCfg: undefined,
+      sessionEntry,
+      sessionStore,
+      sessionKey,
+      defaultProvider,
+      defaultModel,
+      provider: defaultProvider,
+      model: defaultModel,
+      hasModelDirective: false,
+    });
+
+    expect(state.provider).toBe("kimi-coding");
+    expect(state.model).toBe("k2p5");
+  });
+
+  it("falls back to default when no modelOverride is set", async () => {
+    const cfg = {} as OpenClawConfig;
+    const sessionKey = "agent:main:main";
+    const sessionEntry = makeEntry();
+    const sessionStore = { [sessionKey]: sessionEntry };
+
+    const state = await createModelSelectionState({
+      cfg,
+      agentCfg: undefined,
+      sessionEntry,
+      sessionStore,
+      sessionKey,
+      defaultProvider,
+      defaultModel,
+      provider: defaultProvider,
+      model: defaultModel,
+      hasModelDirective: false,
+    });
+
+    expect(state.provider).toBe(defaultProvider);
+    expect(state.model).toBe(defaultModel);
+  });
+
+  it("respects modelOverride even when session model field differs", async () => {
+    // From issue #14783: stored override should beat last-used fallback model.
+    const cfg = {} as OpenClawConfig;
+    const sessionKey = "agent:main:main";
+    const sessionEntry = makeEntry({
+      model: "k2p5",
+      modelProvider: "kimi-coding",
+      contextTokens: 262_000,
+      providerOverride: "anthropic",
+      modelOverride: "claude-opus-4-5",
+    });
+    const sessionStore = { [sessionKey]: sessionEntry };
+
+    const state = await createModelSelectionState({
+      cfg,
+      agentCfg: undefined,
+      sessionEntry,
+      sessionStore,
+      sessionKey,
+      defaultProvider,
+      defaultModel,
+      provider: defaultProvider,
+      model: defaultModel,
+      hasModelDirective: false,
+    });
+
+    expect(state.provider).toBe("anthropic");
+    expect(state.model).toBe("claude-opus-4-5");
+  });
+
+  it("uses default provider when providerOverride is not set but modelOverride is", async () => {
+    const cfg = {} as OpenClawConfig;
+    const sessionKey = "agent:main:main";
+    const sessionEntry = makeEntry({
+      modelOverride: "deepseek-v3-4bit-mlx",
+    });
+    const sessionStore = { [sessionKey]: sessionEntry };
+
+    const state = await createModelSelectionState({
+      cfg,
+      agentCfg: undefined,
+      sessionEntry,
+      sessionStore,
+      sessionKey,
+      defaultProvider,
+      defaultModel,
+      provider: defaultProvider,
+      model: defaultModel,
+      hasModelDirective: false,
+    });
+
+    expect(state.provider).toBe(defaultProvider);
+    expect(state.model).toBe("deepseek-v3-4bit-mlx");
+  });
+});
diff --git a/src/auto-reply/reply/normalize-reply.test.ts b/src/auto-reply/reply/normalize-reply.test.ts
deleted file mode 100644
index 26866892669..00000000000
--- a/src/auto-reply/reply/normalize-reply.test.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { SILENT_REPLY_TOKEN } from "../tokens.js";
-import { normalizeReplyPayload } from "./normalize-reply.js";
-
-// Keep channelData-only payloads so channel-specific replies survive normalization.
-describe("normalizeReplyPayload", () => {
-  it("keeps channelData-only replies", () => {
-    const payload = {
-      channelData: {
-        line: {
-          flexMessage: { type: "bubble" },
-        },
-      },
-    };
-
-    const normalized = normalizeReplyPayload(payload);
-
-    expect(normalized).not.toBeNull();
-    expect(normalized?.text).toBeUndefined();
-    expect(normalized?.channelData).toEqual(payload.channelData);
-  });
-
-  it("records silent skips", () => {
-    const reasons: string[] = [];
-    const normalized = normalizeReplyPayload(
-      { text: SILENT_REPLY_TOKEN },
-      {
-        onSkip: (reason) => reasons.push(reason),
-      },
-    );
-
-    expect(normalized).toBeNull();
-    expect(reasons).toEqual(["silent"]);
-  });
-
-  it("records empty skips", () => {
-    const reasons: string[] = [];
-    const normalized = normalizeReplyPayload(
-      { text: "   " },
-      {
-        onSkip: (reason) => reasons.push(reason),
-      },
-    );
-
-    expect(normalized).toBeNull();
-    expect(reasons).toEqual(["empty"]);
-  });
-});
diff --git a/src/auto-reply/reply/queue.collect-routing.test.ts b/src/auto-reply/reply/queue.collect-routing.test.ts
deleted file mode 100644
index 8d6fab2e9a3..00000000000
--- a/src/auto-reply/reply/queue.collect-routing.test.ts
+++ /dev/null
@@ -1,381 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import type { FollowupRun, QueueSettings } from "./queue.js";
-import { enqueueFollowupRun, scheduleFollowupDrain } from "./queue.js";
-
-const COLLECT_SETTINGS: QueueSettings = {
-  mode: "collect",
-  debounceMs: 0,
-  cap: 50,
-  dropPolicy: "summarize",
-};
-
-function createSettings(overrides?: Partial<QueueSettings>): QueueSettings {
-  return { ...COLLECT_SETTINGS, ...overrides } as QueueSettings;
-}
-
-function createRunCollector() {
-  const calls: FollowupRun[] = [];
-  const runFollowup = async (run: FollowupRun) => {
-    calls.push(run);
-  };
-  return { calls, runFollowup };
-}
-
-async function drainAndWait(params: {
-  key: string;
-  calls: FollowupRun[];
-  runFollowup: (run: FollowupRun) => Promise<void>;
-  count: number;
-}) {
-  scheduleFollowupDrain(params.key, params.runFollowup);
-  await expect.poll(() => params.calls.length).toBe(params.count);
-}
-
-function createRun(params: {
-  prompt: string;
-  messageId?: string;
-  originatingChannel?: FollowupRun["originatingChannel"];
-  originatingTo?: string;
-  originatingAccountId?: string;
-  originatingThreadId?: string | number;
-}): FollowupRun {
-  return {
-    prompt: params.prompt,
-    messageId: params.messageId,
-    enqueuedAt: Date.now(),
-    originatingChannel: params.originatingChannel,
-    originatingTo: params.originatingTo,
-    originatingAccountId: params.originatingAccountId,
-    originatingThreadId: params.originatingThreadId,
-    run: {
-      agentId: "agent",
-      agentDir: "/tmp",
-      sessionId: "sess",
-      sessionFile: "/tmp/session.json",
-      workspaceDir: "/tmp",
-      config: {} as OpenClawConfig,
-      provider: "openai",
-      model: "gpt-test",
-      timeoutMs: 10_000,
-      blockReplyBreak: "text_end",
-    },
-  };
-}
-
-describe("followup queue deduplication", () => {
-  it("deduplicates messages with same Discord message_id", async () => {
-    const key = `test-dedup-message-id-${Date.now()}`;
-    const { calls, runFollowup } = createRunCollector();
-    const settings = createSettings();
-
-    // First enqueue should succeed
-    const first = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "[Discord Guild #test channel id:123] Hello",
-        messageId: "m1",
-        originatingChannel: "discord",
-        originatingTo: "channel:123",
-      }),
-      settings,
-    );
-    expect(first).toBe(true);
-
-    // Second enqueue with same message id should be deduplicated
-    const second = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "[Discord Guild #test channel id:123] Hello (dupe)",
-        messageId: "m1",
-        originatingChannel: "discord",
-        originatingTo: "channel:123",
-      }),
-      settings,
-    );
-    expect(second).toBe(false);
-
-    // Third enqueue with different message id should succeed
-    const third = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "[Discord Guild #test channel id:123] World",
-        messageId: "m2",
-        originatingChannel: "discord",
-        originatingTo: "channel:123",
-      }),
-      settings,
-    );
-    expect(third).toBe(true);
-
-    await drainAndWait({ key, calls, runFollowup, count: 1 });
-    // Should collect both unique messages
-    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
-  });
-
-  it("deduplicates exact prompt when routing matches and no message id", async () => {
-    const key = `test-dedup-whatsapp-${Date.now()}`;
-    const settings = createSettings();
-
-    // First enqueue should succeed
-    const first = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Hello world",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-    );
-    expect(first).toBe(true);
-
-    // Second enqueue with same prompt should be allowed (default dedupe: message id only)
-    const second = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Hello world",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-    );
-    expect(second).toBe(true);
-
-    // Third enqueue with different prompt should succeed
-    const third = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Hello world 2",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-    );
-    expect(third).toBe(true);
-  });
-
-  it("does not deduplicate across different providers without message id", async () => {
-    const key = `test-dedup-cross-provider-${Date.now()}`;
-    const settings = createSettings();
-
-    const first = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Same text",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-    );
-    expect(first).toBe(true);
-
-    const second = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Same text",
-        originatingChannel: "discord",
-        originatingTo: "channel:123",
-      }),
-      settings,
-    );
-    expect(second).toBe(true);
-  });
-
-  it("can opt-in to prompt-based dedupe when message id is absent", async () => {
-    const key = `test-dedup-prompt-mode-${Date.now()}`;
-    const settings = createSettings();
-
-    const first = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Hello world",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-      "prompt",
-    );
-    expect(first).toBe(true);
-
-    const second = enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "Hello world",
-        originatingChannel: "whatsapp",
-        originatingTo: "+1234567890",
-      }),
-      settings,
-      "prompt",
-    );
-    expect(second).toBe(false);
-  });
-});
-
-describe("followup queue collect routing", () => {
-  it("does not collect when destinations differ", async () => {
-    const key = `test-collect-diff-to-${Date.now()}`;
-    const { calls, runFollowup } = createRunCollector();
-    const settings = createSettings();
-
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "one",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-      }),
-      settings,
-    );
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "two",
-        originatingChannel: "slack",
-        originatingTo: "channel:B",
-      }),
-      settings,
-    );
-
-    await drainAndWait({ key, calls, runFollowup, count: 2 });
-    expect(calls[0]?.prompt).toBe("one");
-    expect(calls[1]?.prompt).toBe("two");
-  });
-
-  it("collects when channel+destination match", async () => {
-    const key = `test-collect-same-to-${Date.now()}`;
-    const { calls, runFollowup } = createRunCollector();
-    const settings = createSettings();
-
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "one",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-      }),
-      settings,
-    );
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "two",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-      }),
-      settings,
-    );
-
-    await drainAndWait({ key, calls, runFollowup, count: 1 });
-    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
-    expect(calls[0]?.originatingChannel).toBe("slack");
-    expect(calls[0]?.originatingTo).toBe("channel:A");
-  });
-
-  it("collects Slack messages in same thread and preserves string thread id", async () => {
-    const key = `test-collect-slack-thread-same-${Date.now()}`;
-    const { calls, runFollowup } = createRunCollector();
-    const settings = createSettings();
-
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "one",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-        originatingThreadId: "1706000000.000001",
-      }),
-      settings,
-    );
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "two",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-        originatingThreadId: "1706000000.000001",
-      }),
-      settings,
-    );
-
-    await drainAndWait({ key, calls, runFollowup, count: 1 });
-    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
-    expect(calls[0]?.originatingThreadId).toBe("1706000000.000001");
-  });
-
-  it("does not collect Slack messages when thread ids differ", async () => {
-    const key = `test-collect-slack-thread-diff-${Date.now()}`;
-    const { calls, runFollowup } = createRunCollector();
-    const settings = createSettings();
-
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "one",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-        originatingThreadId: "1706000000.000001",
-      }),
-      settings,
-    );
-    enqueueFollowupRun(
-      key,
-      createRun({
-        prompt: "two",
-        originatingChannel: "slack",
-        originatingTo: "channel:A",
-        originatingThreadId: "1706000000.000002",
-      }),
-      settings,
-    );
-
-    await drainAndWait({ key, calls, runFollowup, count: 2 });
-    expect(calls[0]?.prompt).toBe("one");
-    expect(calls[1]?.prompt).toBe("two");
-    expect(calls[0]?.originatingThreadId).toBe("1706000000.000001");
-    expect(calls[1]?.originatingThreadId).toBe("1706000000.000002");
-  });
-
-  it("retries collect-mode batches without losing queued items", async () => {
-    const key = `test-collect-retry-${Date.now()}`;
-    const calls: FollowupRun[] = [];
-    let attempt = 0;
-    const runFollowup = async (run: FollowupRun) => {
-      attempt += 1;
-      if (attempt === 1) {
-        throw new Error("transient failure");
-      }
-      calls.push(run);
-    };
-    const settings = createSettings();
-
-    enqueueFollowupRun(key, createRun({ prompt: "one" }), settings);
-    enqueueFollowupRun(key, createRun({ prompt: "two" }), settings);
-
-    scheduleFollowupDrain(key, runFollowup);
-    await expect.poll(() => calls.length).toBe(1);
-    expect(calls[0]?.prompt).toContain("Queued #1\none");
-    expect(calls[0]?.prompt).toContain("Queued #2\ntwo");
-  });
-
-  it("retries overflow summary delivery without losing dropped previews", async () => {
-    const key = `test-overflow-summary-retry-${Date.now()}`;
-    const calls: FollowupRun[] = [];
-    let attempt = 0;
-    const runFollowup = async (run: FollowupRun) => {
-      attempt += 1;
-      if (attempt === 1) {
-        throw new Error("transient failure");
-      }
-      calls.push(run);
-    };
-    const settings = createSettings({ mode: "followup", cap: 1 });
-
-    enqueueFollowupRun(key, createRun({ prompt: "first" }), settings);
-    enqueueFollowupRun(key, createRun({ prompt: "second" }), settings);
-
-    scheduleFollowupDrain(key, runFollowup);
-    await expect.poll(() => calls.length).toBe(1);
-    expect(calls[0]?.prompt).toContain("[Queue overflow] Dropped 1 message due to cap.");
-    expect(calls[0]?.prompt).toContain("- first");
-  });
-});
diff --git a/src/auto-reply/reply/reply-flow.test.ts b/src/auto-reply/reply/reply-flow.test.ts
new file mode 100644
index 00000000000..c314997929f
--- /dev/null
+++ b/src/auto-reply/reply/reply-flow.test.ts
@@ -0,0 +1,1317 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { MsgContext, TemplateContext } from "../templating.js";
+import type { FollowupRun, QueueSettings } from "./queue.js";
+import { expectInboundContextContract } from "../../../test/helpers/inbound-contract.js";
+import { defaultRuntime } from "../../runtime.js";
+import { HEARTBEAT_TOKEN, SILENT_REPLY_TOKEN } from "../tokens.js";
+import { finalizeInboundContext } from "./inbound-context.js";
+import { buildInboundUserContextPrefix } from "./inbound-meta.js";
+import { normalizeInboundTextNewlines } from "./inbound-text.js";
+import { parseLineDirectives, hasLineDirectives } from "./line-directives.js";
+import { enqueueFollowupRun, scheduleFollowupDrain } from "./queue.js";
+import { createReplyDispatcher } from "./reply-dispatcher.js";
+import { createReplyToModeFilter, resolveReplyToMode } from "./reply-threading.js";
+
+describe("buildInboundUserContextPrefix", () => {
+  it("omits conversation label block for direct chats", () => {
+    const text = buildInboundUserContextPrefix({
+      ChatType: "direct",
+      ConversationLabel: "openclaw-tui",
+    } as TemplateContext);
+
+    expect(text).toBe("");
+  });
+
+  it("keeps conversation label for group chats", () => {
+    const text = buildInboundUserContextPrefix({
+      ChatType: "group",
+      ConversationLabel: "ops-room",
+    } as TemplateContext);
+
+    expect(text).toContain("Conversation info (untrusted metadata):");
+    expect(text).toContain('"conversation_label": "ops-room"');
+  });
+});
+
+describe("normalizeInboundTextNewlines", () => {
+  it("converts CRLF to LF", () => {
+    expect(normalizeInboundTextNewlines("hello\r\nworld")).toBe("hello\nworld");
+  });
+
+  it("converts CR to LF", () => {
+    expect(normalizeInboundTextNewlines("hello\rworld")).toBe("hello\nworld");
+  });
+
+  it("preserves literal backslash-n sequences in Windows paths", () => {
+    const windowsPath = "C:\\Work\\nxxx\\README.md";
+    expect(normalizeInboundTextNewlines(windowsPath)).toBe("C:\\Work\\nxxx\\README.md");
+  });
+
+  it("preserves backslash-n in messages containing Windows paths", () => {
+    const message = "Please read the file at C:\\Work\\nxxx\\README.md";
+    expect(normalizeInboundTextNewlines(message)).toBe(
+      "Please read the file at C:\\Work\\nxxx\\README.md",
+    );
+  });
+
+  it("preserves multiple backslash-n sequences", () => {
+    const message = "C:\\new\\notes\\nested";
+    expect(normalizeInboundTextNewlines(message)).toBe("C:\\new\\notes\\nested");
+  });
+
+  it("still normalizes actual CRLF while preserving backslash-n", () => {
+    const message = "Line 1\r\nC:\\Work\\nxxx";
+    expect(normalizeInboundTextNewlines(message)).toBe("Line 1\nC:\\Work\\nxxx");
+  });
+});
+
+describe("inbound context contract (providers + extensions)", () => {
+  const cases: Array<{ name: string; ctx: MsgContext }> = [
+    {
+      name: "whatsapp group",
+      ctx: {
+        Provider: "whatsapp",
+        Surface: "whatsapp",
+        ChatType: "group",
+        From: "123@g.us",
+        To: "+15550001111",
+        Body: "[WhatsApp 123@g.us] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "telegram group",
+      ctx: {
+        Provider: "telegram",
+        Surface: "telegram",
+        ChatType: "group",
+        From: "group:123",
+        To: "telegram:123",
+        Body: "[Telegram group:123] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "Telegram Group",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "slack channel",
+      ctx: {
+        Provider: "slack",
+        Surface: "slack",
+        ChatType: "channel",
+        From: "slack:channel:C123",
+        To: "channel:C123",
+        Body: "[Slack #general] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "#general",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "discord channel",
+      ctx: {
+        Provider: "discord",
+        Surface: "discord",
+        ChatType: "channel",
+        From: "group:123",
+        To: "channel:123",
+        Body: "[Discord #general] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "#general",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "signal dm",
+      ctx: {
+        Provider: "signal",
+        Surface: "signal",
+        ChatType: "direct",
+        From: "signal:+15550001111",
+        To: "signal:+15550002222",
+        Body: "[Signal] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+      },
+    },
+    {
+      name: "imessage group",
+      ctx: {
+        Provider: "imessage",
+        Surface: "imessage",
+        ChatType: "group",
+        From: "group:chat_id:123",
+        To: "chat_id:123",
+        Body: "[iMessage Group] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "iMessage Group",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "matrix channel",
+      ctx: {
+        Provider: "matrix",
+        Surface: "matrix",
+        ChatType: "channel",
+        From: "matrix:channel:!room:example.org",
+        To: "room:!room:example.org",
+        Body: "[Matrix] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "#general",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "msteams channel",
+      ctx: {
+        Provider: "msteams",
+        Surface: "msteams",
+        ChatType: "channel",
+        From: "msteams:channel:19:abc@thread.tacv2",
+        To: "msteams:channel:19:abc@thread.tacv2",
+        Body: "[Teams] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "Teams Channel",
+        SenderName: "Alice",
+      },
+    },
+    {
+      name: "zalo dm",
+      ctx: {
+        Provider: "zalo",
+        Surface: "zalo",
+        ChatType: "direct",
+        From: "zalo:123",
+        To: "zalo:123",
+        Body: "[Zalo] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+      },
+    },
+    {
+      name: "zalouser group",
+      ctx: {
+        Provider: "zalouser",
+        Surface: "zalouser",
+        ChatType: "group",
+        From: "group:123",
+        To: "zalouser:123",
+        Body: "[Zalo Personal] hi",
+        RawBody: "hi",
+        CommandBody: "hi",
+        GroupSubject: "Zalouser Group",
+        SenderName: "Alice",
+      },
+    },
+  ];
+
+  for (const entry of cases) {
+    it(entry.name, () => {
+      const ctx = finalizeInboundContext({ ...entry.ctx });
+      expectInboundContextContract(ctx);
+    });
+  }
+});
+
+const getLineData = (result: ReturnType<typeof parseLineDirectives>) =>
+  (result.channelData?.line as Record<string, unknown> | undefined) ?? {};
+
+describe("hasLineDirectives", () => {
+  it("detects quick_replies directive", () => {
+    expect(hasLineDirectives("Here are options [[quick_replies: A, B, C]]")).toBe(true);
+  });
+
+  it("detects location directive", () => {
+    expect(hasLineDirectives("[[location: Place | Address | 35.6 | 139.7]]")).toBe(true);
+  });
+
+  it("detects confirm directive", () => {
+    expect(hasLineDirectives("[[confirm: Continue? | Yes | No]]")).toBe(true);
+  });
+
+  it("detects buttons directive", () => {
+    expect(hasLineDirectives("[[buttons: Menu | Choose | Opt1:data1, Opt2:data2]]")).toBe(true);
+  });
+
+  it("returns false for regular text", () => {
+    expect(hasLineDirectives("Just regular text")).toBe(false);
+  });
+
+  it("returns false for similar but invalid patterns", () => {
+    expect(hasLineDirectives("[[not_a_directive: something]]")).toBe(false);
+  });
+
+  it("detects media_player directive", () => {
+    expect(hasLineDirectives("[[media_player: Song | Artist | Speaker]]")).toBe(true);
+  });
+
+  it("detects event directive", () => {
+    expect(hasLineDirectives("[[event: Meeting | Jan 24 | 2pm]]")).toBe(true);
+  });
+
+  it("detects agenda directive", () => {
+    expect(hasLineDirectives("[[agenda: Today | Meeting:9am, Lunch:12pm]]")).toBe(true);
+  });
+
+  it("detects device directive", () => {
+    expect(hasLineDirectives("[[device: TV | Room]]")).toBe(true);
+  });
+
+  it("detects appletv_remote directive", () => {
+    expect(hasLineDirectives("[[appletv_remote: Apple TV | Playing]]")).toBe(true);
+  });
+});
+
+describe("parseLineDirectives", () => {
+  describe("quick_replies", () => {
+    it("parses quick_replies and removes from text", () => {
+      const result = parseLineDirectives({
+        text: "Choose one:\n[[quick_replies: Option A, Option B, Option C]]",
+      });
+
+      expect(getLineData(result).quickReplies).toEqual(["Option A", "Option B", "Option C"]);
+      expect(result.text).toBe("Choose one:");
+    });
+
+    it("handles quick_replies in middle of text", () => {
+      const result = parseLineDirectives({
+        text: "Before [[quick_replies: A, B]] After",
+      });
+
+      expect(getLineData(result).quickReplies).toEqual(["A", "B"]);
+      expect(result.text).toBe("Before  After");
+    });
+
+    it("merges with existing quickReplies", () => {
+      const result = parseLineDirectives({
+        text: "Text [[quick_replies: C, D]]",
+        channelData: { line: { quickReplies: ["A", "B"] } },
+      });
+
+      expect(getLineData(result).quickReplies).toEqual(["A", "B", "C", "D"]);
+    });
+  });
+
+  describe("location", () => {
+    it("parses location with all fields", () => {
+      const result = parseLineDirectives({
+        text: "Here's the location:\n[[location: Tokyo Station | Tokyo, Japan | 35.6812 | 139.7671]]",
+      });
+
+      expect(getLineData(result).location).toEqual({
+        title: "Tokyo Station",
+        address: "Tokyo, Japan",
+        latitude: 35.6812,
+        longitude: 139.7671,
+      });
+      expect(result.text).toBe("Here's the location:");
+    });
+
+    it("ignores invalid coordinates", () => {
+      const result = parseLineDirectives({
+        text: "[[location: Place | Address | invalid | 139.7]]",
+      });
+
+      expect(getLineData(result).location).toBeUndefined();
+    });
+
+    it("does not override existing location", () => {
+      const existing = { title: "Existing", address: "Addr", latitude: 1, longitude: 2 };
+      const result = parseLineDirectives({
+        text: "[[location: New | New Addr | 35.6 | 139.7]]",
+        channelData: { line: { location: existing } },
+      });
+
+      expect(getLineData(result).location).toEqual(existing);
+    });
+  });
+
+  describe("confirm", () => {
+    it("parses simple confirm", () => {
+      const result = parseLineDirectives({
+        text: "[[confirm: Delete this item? | Yes | No]]",
+      });
+
+      expect(getLineData(result).templateMessage).toEqual({
+        type: "confirm",
+        text: "Delete this item?",
+        confirmLabel: "Yes",
+        confirmData: "yes",
+        cancelLabel: "No",
+        cancelData: "no",
+        altText: "Delete this item?",
+      });
+      // Text is undefined when directive consumes entire text
+      expect(result.text).toBeUndefined();
+    });
+
+    it("parses confirm with custom data", () => {
+      const result = parseLineDirectives({
+        text: "[[confirm: Proceed? | OK:action=confirm | Cancel:action=cancel]]",
+      });
+
+      expect(getLineData(result).templateMessage).toEqual({
+        type: "confirm",
+        text: "Proceed?",
+        confirmLabel: "OK",
+        confirmData: "action=confirm",
+        cancelLabel: "Cancel",
+        cancelData: "action=cancel",
+        altText: "Proceed?",
+      });
+    });
+  });
+
+  describe("buttons", () => {
+    it("parses buttons with message actions", () => {
+      const result = parseLineDirectives({
+        text: "[[buttons: Menu | Select an option | Help:/help, Status:/status]]",
+      });
+
+      expect(getLineData(result).templateMessage).toEqual({
+        type: "buttons",
+        title: "Menu",
+        text: "Select an option",
+        actions: [
+          { type: "message", label: "Help", data: "/help" },
+          { type: "message", label: "Status", data: "/status" },
+        ],
+        altText: "Menu: Select an option",
+      });
+    });
+
+    it("parses buttons with uri actions", () => {
+      const result = parseLineDirectives({
+        text: "[[buttons: Links | Visit us | Site:https://example.com]]",
+      });
+
+      const templateMessage = getLineData(result).templateMessage as {
+        type?: string;
+        actions?: Array<Record<string, unknown>>;
+      };
+      expect(templateMessage?.type).toBe("buttons");
+      if (templateMessage?.type === "buttons") {
+        expect(templateMessage.actions?.[0]).toEqual({
+          type: "uri",
+          label: "Site",
+          uri: "https://example.com",
+        });
+      }
+    });
+
+    it("parses buttons with postback actions", () => {
+      const result = parseLineDirectives({
+        text: "[[buttons: Actions | Choose | Select:action=select&id=1]]",
+      });
+
+      const templateMessage = getLineData(result).templateMessage as {
+        type?: string;
+        actions?: Array<Record<string, unknown>>;
+      };
+      expect(templateMessage?.type).toBe("buttons");
+      if (templateMessage?.type === "buttons") {
+        expect(templateMessage.actions?.[0]).toEqual({
+          type: "postback",
+          label: "Select",
+          data: "action=select&id=1",
+        });
+      }
+    });
+
+    it("limits to 4 actions", () => {
+      const result = parseLineDirectives({
+        text: "[[buttons: Menu | Text | A:a, B:b, C:c, D:d, E:e, F:f]]",
+      });
+
+      const templateMessage = getLineData(result).templateMessage as {
+        type?: string;
+        actions?: Array<Record<string, unknown>>;
+      };
+      expect(templateMessage?.type).toBe("buttons");
+      if (templateMessage?.type === "buttons") {
+        expect(templateMessage.actions?.length).toBe(4);
+      }
+    });
+  });
+
+  describe("media_player", () => {
+    it("parses media_player with all fields", () => {
+      const result = parseLineDirectives({
+        text: "Now playing:\n[[media_player: Bohemian Rhapsody | Queen | Speaker | https://example.com/album.jpg | playing]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as {
+        altText?: string;
+        contents?: { footer?: { contents?: unknown[] } };
+      };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("🎵 Bohemian Rhapsody - Queen");
+      const contents = flexMessage?.contents as { footer?: { contents?: unknown[] } };
+      expect(contents.footer?.contents?.length).toBeGreaterThan(0);
+      expect(result.text).toBe("Now playing:");
+    });
+
+    it("parses media_player with minimal fields", () => {
+      const result = parseLineDirectives({
+        text: "[[media_player: Unknown Track]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("🎵 Unknown Track");
+    });
+
+    it("handles paused status", () => {
+      const result = parseLineDirectives({
+        text: "[[media_player: Song | Artist | Player | | paused]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as {
+        contents?: { body: { contents: unknown[] } };
+      };
+      expect(flexMessage).toBeDefined();
+      const contents = flexMessage?.contents as { body: { contents: unknown[] } };
+      expect(contents).toBeDefined();
+    });
+  });
+
+  describe("event", () => {
+    it("parses event with all fields", () => {
+      const result = parseLineDirectives({
+        text: "[[event: Team Meeting | January 24, 2026 | 2:00 PM - 3:00 PM | Conference Room A | Discuss Q1 roadmap]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📅 Team Meeting - January 24, 2026 2:00 PM - 3:00 PM");
+    });
+
+    it("parses event with minimal fields", () => {
+      const result = parseLineDirectives({
+        text: "[[event: Birthday Party | March 15]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📅 Birthday Party - March 15");
+    });
+  });
+
+  describe("agenda", () => {
+    it("parses agenda with multiple events", () => {
+      const result = parseLineDirectives({
+        text: "[[agenda: Today's Schedule | Team Meeting:9:00 AM, Lunch:12:00 PM, Review:3:00 PM]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📋 Today's Schedule (3 events)");
+    });
+
+    it("parses agenda with events without times", () => {
+      const result = parseLineDirectives({
+        text: "[[agenda: Tasks | Buy groceries, Call mom, Workout]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📋 Tasks (3 events)");
+    });
+  });
+
+  describe("device", () => {
+    it("parses device with controls", () => {
+      const result = parseLineDirectives({
+        text: "[[device: TV | Streaming Box | Playing | Play/Pause:toggle, Menu:menu]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📱 TV: Playing");
+    });
+
+    it("parses device with minimal fields", () => {
+      const result = parseLineDirectives({
+        text: "[[device: Speaker]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toBe("📱 Speaker");
+    });
+  });
+
+  describe("appletv_remote", () => {
+    it("parses appletv_remote with status", () => {
+      const result = parseLineDirectives({
+        text: "[[appletv_remote: Apple TV | Playing]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+      expect(flexMessage?.altText).toContain("Apple TV");
+    });
+
+    it("parses appletv_remote with minimal fields", () => {
+      const result = parseLineDirectives({
+        text: "[[appletv_remote: Apple TV]]",
+      });
+
+      const flexMessage = getLineData(result).flexMessage as { altText?: string };
+      expect(flexMessage).toBeDefined();
+    });
+  });
+
+  describe("combined directives", () => {
+    it("handles text with no directives", () => {
+      const result = parseLineDirectives({
+        text: "Just plain text here",
+      });
+
+      expect(result.text).toBe("Just plain text here");
+      expect(getLineData(result).quickReplies).toBeUndefined();
+      expect(getLineData(result).location).toBeUndefined();
+      expect(getLineData(result).templateMessage).toBeUndefined();
+    });
+
+    it("preserves other payload fields", () => {
+      const result = parseLineDirectives({
+        text: "Hello [[quick_replies: A, B]]",
+        mediaUrl: "https://example.com/image.jpg",
+        replyToId: "msg123",
+      });
+
+      expect(result.mediaUrl).toBe("https://example.com/image.jpg");
+      expect(result.replyToId).toBe("msg123");
+      expect(getLineData(result).quickReplies).toEqual(["A", "B"]);
+    });
+  });
+});
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+let previousRuntimeError: typeof defaultRuntime.error;
+
+beforeAll(() => {
+  previousRuntimeError = defaultRuntime.error;
+  defaultRuntime.error = undefined;
+});
+
+afterAll(() => {
+  defaultRuntime.error = previousRuntimeError;
+});
+
+function createRun(params: {
+  prompt: string;
+  messageId?: string;
+  originatingChannel?: FollowupRun["originatingChannel"];
+  originatingTo?: string;
+  originatingAccountId?: string;
+  originatingThreadId?: string | number;
+}): FollowupRun {
+  return {
+    prompt: params.prompt,
+    messageId: params.messageId,
+    enqueuedAt: Date.now(),
+    originatingChannel: params.originatingChannel,
+    originatingTo: params.originatingTo,
+    originatingAccountId: params.originatingAccountId,
+    originatingThreadId: params.originatingThreadId,
+    run: {
+      agentId: "agent",
+      agentDir: "/tmp",
+      sessionId: "sess",
+      sessionFile: "/tmp/session.json",
+      workspaceDir: "/tmp",
+      config: {} as OpenClawConfig,
+      provider: "openai",
+      model: "gpt-test",
+      timeoutMs: 10_000,
+      blockReplyBreak: "text_end",
+    },
+  };
+}
+
+describe("followup queue deduplication", () => {
+  it("deduplicates messages with same Discord message_id", async () => {
+    const key = `test-dedup-message-id-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 1;
+    const runFollowup = async (run: FollowupRun) => {
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    // First enqueue should succeed
+    const first = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "[Discord Guild #test channel id:123] Hello",
+        messageId: "m1",
+        originatingChannel: "discord",
+        originatingTo: "channel:123",
+      }),
+      settings,
+    );
+    expect(first).toBe(true);
+
+    // Second enqueue with same message id should be deduplicated
+    const second = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "[Discord Guild #test channel id:123] Hello (dupe)",
+        messageId: "m1",
+        originatingChannel: "discord",
+        originatingTo: "channel:123",
+      }),
+      settings,
+    );
+    expect(second).toBe(false);
+
+    // Third enqueue with different message id should succeed
+    const third = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "[Discord Guild #test channel id:123] World",
+        messageId: "m2",
+        originatingChannel: "discord",
+        originatingTo: "channel:123",
+      }),
+      settings,
+    );
+    expect(third).toBe(true);
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    // Should collect both unique messages
+    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
+  });
+
+  it("deduplicates exact prompt when routing matches and no message id", async () => {
+    const key = `test-dedup-whatsapp-${Date.now()}`;
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    // First enqueue should succeed
+    const first = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Hello world",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+    );
+    expect(first).toBe(true);
+
+    // Second enqueue with same prompt should be allowed (default dedupe: message id only)
+    const second = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Hello world",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+    );
+    expect(second).toBe(true);
+
+    // Third enqueue with different prompt should succeed
+    const third = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Hello world 2",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+    );
+    expect(third).toBe(true);
+  });
+
+  it("does not deduplicate across different providers without message id", async () => {
+    const key = `test-dedup-cross-provider-${Date.now()}`;
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    const first = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Same text",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+    );
+    expect(first).toBe(true);
+
+    const second = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Same text",
+        originatingChannel: "discord",
+        originatingTo: "channel:123",
+      }),
+      settings,
+    );
+    expect(second).toBe(true);
+  });
+
+  it("can opt-in to prompt-based dedupe when message id is absent", async () => {
+    const key = `test-dedup-prompt-mode-${Date.now()}`;
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    const first = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Hello world",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+      "prompt",
+    );
+    expect(first).toBe(true);
+
+    const second = enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "Hello world",
+        originatingChannel: "whatsapp",
+        originatingTo: "+1234567890",
+      }),
+      settings,
+      "prompt",
+    );
+    expect(second).toBe(false);
+  });
+});
+
+describe("followup queue collect routing", () => {
+  it("does not collect when destinations differ", async () => {
+    const key = `test-collect-diff-to-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 2;
+    const runFollowup = async (run: FollowupRun) => {
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "one",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+      }),
+      settings,
+    );
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "two",
+        originatingChannel: "slack",
+        originatingTo: "channel:B",
+      }),
+      settings,
+    );
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toBe("one");
+    expect(calls[1]?.prompt).toBe("two");
+  });
+
+  it("collects when channel+destination match", async () => {
+    const key = `test-collect-same-to-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 1;
+    const runFollowup = async (run: FollowupRun) => {
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "one",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+      }),
+      settings,
+    );
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "two",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+      }),
+      settings,
+    );
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
+    expect(calls[0]?.originatingChannel).toBe("slack");
+    expect(calls[0]?.originatingTo).toBe("channel:A");
+  });
+
+  it("collects Slack messages in same thread and preserves string thread id", async () => {
+    const key = `test-collect-slack-thread-same-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 1;
+    const runFollowup = async (run: FollowupRun) => {
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "one",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+        originatingThreadId: "1706000000.000001",
+      }),
+      settings,
+    );
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "two",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+        originatingThreadId: "1706000000.000001",
+      }),
+      settings,
+    );
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toContain("[Queued messages while agent was busy]");
+    expect(calls[0]?.originatingThreadId).toBe("1706000000.000001");
+  });
+
+  it("does not collect Slack messages when thread ids differ", async () => {
+    const key = `test-collect-slack-thread-diff-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 2;
+    const runFollowup = async (run: FollowupRun) => {
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "one",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+        originatingThreadId: "1706000000.000001",
+      }),
+      settings,
+    );
+    enqueueFollowupRun(
+      key,
+      createRun({
+        prompt: "two",
+        originatingChannel: "slack",
+        originatingTo: "channel:A",
+        originatingThreadId: "1706000000.000002",
+      }),
+      settings,
+    );
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toBe("one");
+    expect(calls[1]?.prompt).toBe("two");
+    expect(calls[0]?.originatingThreadId).toBe("1706000000.000001");
+    expect(calls[1]?.originatingThreadId).toBe("1706000000.000002");
+  });
+
+  it("retries collect-mode batches without losing queued items", async () => {
+    const key = `test-collect-retry-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 1;
+    let attempt = 0;
+    const runFollowup = async (run: FollowupRun) => {
+      attempt += 1;
+      if (attempt === 1) {
+        throw new Error("transient failure");
+      }
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "collect",
+      debounceMs: 0,
+      cap: 50,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(key, createRun({ prompt: "one" }), settings);
+    enqueueFollowupRun(key, createRun({ prompt: "two" }), settings);
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toContain("Queued #1\none");
+    expect(calls[0]?.prompt).toContain("Queued #2\ntwo");
+  });
+
+  it("retries overflow summary delivery without losing dropped previews", async () => {
+    const key = `test-overflow-summary-retry-${Date.now()}`;
+    const calls: FollowupRun[] = [];
+    const done = createDeferred<void>();
+    const expectedCalls = 1;
+    let attempt = 0;
+    const runFollowup = async (run: FollowupRun) => {
+      attempt += 1;
+      if (attempt === 1) {
+        throw new Error("transient failure");
+      }
+      calls.push(run);
+      if (calls.length >= expectedCalls) {
+        done.resolve();
+      }
+    };
+    const settings: QueueSettings = {
+      mode: "followup",
+      debounceMs: 0,
+      cap: 1,
+      dropPolicy: "summarize",
+    };
+
+    enqueueFollowupRun(key, createRun({ prompt: "first" }), settings);
+    enqueueFollowupRun(key, createRun({ prompt: "second" }), settings);
+
+    scheduleFollowupDrain(key, runFollowup);
+    await done.promise;
+    expect(calls[0]?.prompt).toContain("[Queue overflow] Dropped 1 message due to cap.");
+    expect(calls[0]?.prompt).toContain("- first");
+  });
+});
+
+const emptyCfg = {} as OpenClawConfig;
+
+describe("createReplyDispatcher", () => {
+  it("drops empty payloads and silent tokens without media", async () => {
+    const deliver = vi.fn().mockResolvedValue(undefined);
+    const dispatcher = createReplyDispatcher({ deliver });
+
+    expect(dispatcher.sendFinalReply({})).toBe(false);
+    expect(dispatcher.sendFinalReply({ text: " " })).toBe(false);
+    expect(dispatcher.sendFinalReply({ text: SILENT_REPLY_TOKEN })).toBe(false);
+    expect(dispatcher.sendFinalReply({ text: `${SILENT_REPLY_TOKEN} -- nope` })).toBe(false);
+    expect(dispatcher.sendFinalReply({ text: `interject.${SILENT_REPLY_TOKEN}` })).toBe(false);
+
+    await dispatcher.waitForIdle();
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it("strips heartbeat tokens and applies responsePrefix", async () => {
+    const deliver = vi.fn().mockResolvedValue(undefined);
+    const onHeartbeatStrip = vi.fn();
+    const dispatcher = createReplyDispatcher({
+      deliver,
+      responsePrefix: "PFX",
+      onHeartbeatStrip,
+    });
+
+    expect(dispatcher.sendFinalReply({ text: HEARTBEAT_TOKEN })).toBe(false);
+    expect(dispatcher.sendToolResult({ text: `${HEARTBEAT_TOKEN} hello` })).toBe(true);
+    await dispatcher.waitForIdle();
+
+    expect(deliver).toHaveBeenCalledTimes(1);
+    expect(deliver.mock.calls[0][0].text).toBe("PFX hello");
+    expect(onHeartbeatStrip).toHaveBeenCalledTimes(2);
+  });
+
+  it("avoids double-prefixing and keeps media when heartbeat is the only text", async () => {
+    const deliver = vi.fn().mockResolvedValue(undefined);
+    const dispatcher = createReplyDispatcher({
+      deliver,
+      responsePrefix: "PFX",
+    });
+
+    expect(
+      dispatcher.sendFinalReply({
+        text: "PFX already",
+        mediaUrl: "file:///tmp/photo.jpg",
+      }),
+    ).toBe(true);
+    expect(
+      dispatcher.sendFinalReply({
+        text: HEARTBEAT_TOKEN,
+        mediaUrl: "file:///tmp/photo.jpg",
+      }),
+    ).toBe(true);
+    expect(
+      dispatcher.sendFinalReply({
+        text: `${SILENT_REPLY_TOKEN} -- explanation`,
+        mediaUrl: "file:///tmp/photo.jpg",
+      }),
+    ).toBe(true);
+
+    await dispatcher.waitForIdle();
+
+    expect(deliver).toHaveBeenCalledTimes(3);
+    expect(deliver.mock.calls[0][0].text).toBe("PFX already");
+    expect(deliver.mock.calls[1][0].text).toBe("");
+    expect(deliver.mock.calls[2][0].text).toBe("");
+  });
+
+  it("preserves ordering across tool, block, and final replies", async () => {
+    const delivered: string[] = [];
+    const deliver = vi.fn(async (_payload, info) => {
+      delivered.push(info.kind);
+      if (info.kind === "tool") {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+    });
+    const dispatcher = createReplyDispatcher({ deliver });
+
+    dispatcher.sendToolResult({ text: "tool" });
+    dispatcher.sendBlockReply({ text: "block" });
+    dispatcher.sendFinalReply({ text: "final" });
+
+    await dispatcher.waitForIdle();
+    expect(delivered).toEqual(["tool", "block", "final"]);
+  });
+
+  it("fires onIdle when the queue drains", async () => {
+    const deliver = vi.fn(async () => await new Promise((resolve) => setTimeout(resolve, 5)));
+    const onIdle = vi.fn();
+    const dispatcher = createReplyDispatcher({ deliver, onIdle });
+
+    dispatcher.sendToolResult({ text: "one" });
+    dispatcher.sendFinalReply({ text: "two" });
+
+    await dispatcher.waitForIdle();
+    dispatcher.markComplete();
+    await Promise.resolve();
+    expect(onIdle).toHaveBeenCalledTimes(1);
+  });
+
+  it("delays block replies after the first when humanDelay is natural", async () => {
+    vi.useFakeTimers();
+    const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0);
+    const deliver = vi.fn().mockResolvedValue(undefined);
+    const dispatcher = createReplyDispatcher({
+      deliver,
+      humanDelay: { mode: "natural" },
+    });
+
+    dispatcher.sendBlockReply({ text: "first" });
+    await Promise.resolve();
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    dispatcher.sendBlockReply({ text: "second" });
+    await Promise.resolve();
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(799);
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await dispatcher.waitForIdle();
+    expect(deliver).toHaveBeenCalledTimes(2);
+
+    randomSpy.mockRestore();
+    vi.useRealTimers();
+  });
+
+  it("uses custom bounds for humanDelay and clamps when max <= min", async () => {
+    vi.useFakeTimers();
+    const deliver = vi.fn().mockResolvedValue(undefined);
+    const dispatcher = createReplyDispatcher({
+      deliver,
+      humanDelay: { mode: "custom", minMs: 1200, maxMs: 400 },
+    });
+
+    dispatcher.sendBlockReply({ text: "first" });
+    await Promise.resolve();
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    dispatcher.sendBlockReply({ text: "second" });
+    await vi.advanceTimersByTimeAsync(1199);
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await dispatcher.waitForIdle();
+    expect(deliver).toHaveBeenCalledTimes(2);
+
+    vi.useRealTimers();
+  });
+});
+
+describe("resolveReplyToMode", () => {
+  it("defaults to off for Telegram", () => {
+    expect(resolveReplyToMode(emptyCfg, "telegram")).toBe("off");
+  });
+
+  it("defaults to off for Discord and Slack", () => {
+    expect(resolveReplyToMode(emptyCfg, "discord")).toBe("off");
+    expect(resolveReplyToMode(emptyCfg, "slack")).toBe("off");
+  });
+
+  it("defaults to all when channel is unknown", () => {
+    expect(resolveReplyToMode(emptyCfg, undefined)).toBe("all");
+  });
+
+  it("uses configured value when present", () => {
+    const cfg = {
+      channels: {
+        telegram: { replyToMode: "all" },
+        discord: { replyToMode: "first" },
+        slack: { replyToMode: "all" },
+      },
+    } as OpenClawConfig;
+    expect(resolveReplyToMode(cfg, "telegram")).toBe("all");
+    expect(resolveReplyToMode(cfg, "discord")).toBe("first");
+    expect(resolveReplyToMode(cfg, "slack")).toBe("all");
+  });
+
+  it("uses chat-type replyToMode overrides for Slack when configured", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "off",
+          replyToModeByChatType: { direct: "all", group: "first" },
+        },
+      },
+    } as OpenClawConfig;
+    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("all");
+    expect(resolveReplyToMode(cfg, "slack", null, "group")).toBe("first");
+    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("off");
+    expect(resolveReplyToMode(cfg, "slack", null, undefined)).toBe("off");
+  });
+
+  it("falls back to top-level replyToMode when no chat-type override is set", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "first",
+        },
+      },
+    } as OpenClawConfig;
+    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("first");
+    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("first");
+  });
+
+  it("uses legacy dm.replyToMode for direct messages when no chat-type override exists", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          replyToMode: "off",
+          dm: { replyToMode: "all" },
+        },
+      },
+    } as OpenClawConfig;
+    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("all");
+    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("off");
+  });
+});
+
+describe("createReplyToModeFilter", () => {
+  it("drops replyToId when mode is off", () => {
+    const filter = createReplyToModeFilter("off");
+    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBeUndefined();
+  });
+
+  it("keeps replyToId when mode is off and reply tags are allowed", () => {
+    const filter = createReplyToModeFilter("off", { allowExplicitReplyTagsWhenOff: true });
+    expect(filter({ text: "hi", replyToId: "1", replyToTag: true }).replyToId).toBe("1");
+  });
+
+  it("keeps replyToId when mode is all", () => {
+    const filter = createReplyToModeFilter("all");
+    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBe("1");
+  });
+
+  it("keeps only the first replyToId when mode is first", () => {
+    const filter = createReplyToModeFilter("first");
+    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBe("1");
+    expect(filter({ text: "next", replyToId: "1" }).replyToId).toBeUndefined();
+  });
+});
diff --git a/src/auto-reply/reply/reply-payloads.auto-threading.test.ts b/src/auto-reply/reply/reply-payloads.auto-threading.test.ts
deleted file mode 100644
index 80578f4b721..00000000000
--- a/src/auto-reply/reply/reply-payloads.auto-threading.test.ts
+++ /dev/null
@@ -1,88 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { applyReplyThreading } from "./reply-payloads.js";
-
-describe("applyReplyThreading auto-threading", () => {
-  it("sets replyToId to currentMessageId even without [[reply_to_current]] tag", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "Hello" }],
-      replyToMode: "first",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].replyToId).toBe("42");
-  });
-
-  it("threads only first payload when mode is 'first'", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "A" }, { text: "B" }],
-      replyToMode: "first",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(2);
-    expect(result[0].replyToId).toBe("42");
-    expect(result[1].replyToId).toBeUndefined();
-  });
-
-  it("threads all payloads when mode is 'all'", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "A" }, { text: "B" }],
-      replyToMode: "all",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(2);
-    expect(result[0].replyToId).toBe("42");
-    expect(result[1].replyToId).toBe("42");
-  });
-
-  it("strips replyToId when mode is 'off'", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "A" }],
-      replyToMode: "off",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].replyToId).toBeUndefined();
-  });
-
-  it("does not bypass off mode for Slack when reply is implicit", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "A" }],
-      replyToMode: "off",
-      replyToChannel: "slack",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].replyToId).toBeUndefined();
-  });
-
-  it("keeps explicit tags for Slack when off mode allows tags", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "[[reply_to_current]]A" }],
-      replyToMode: "off",
-      replyToChannel: "slack",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].replyToId).toBe("42");
-    expect(result[0].replyToTag).toBe(true);
-  });
-
-  it("keeps explicit tags for Telegram when off mode is enabled", () => {
-    const result = applyReplyThreading({
-      payloads: [{ text: "[[reply_to_current]]A" }],
-      replyToMode: "off",
-      replyToChannel: "telegram",
-      currentMessageId: "42",
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].replyToId).toBe("42");
-    expect(result[0].replyToTag).toBe(true);
-  });
-});
diff --git a/src/auto-reply/reply/reply-plumbing.test.ts b/src/auto-reply/reply/reply-plumbing.test.ts
new file mode 100644
index 00000000000..2b1d1367ac3
--- /dev/null
+++ b/src/auto-reply/reply/reply-plumbing.test.ts
@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import type { SubagentRunRecord } from "../../agents/subagent-registry.js";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { TemplateContext } from "../templating.js";
+import { formatDurationCompact } from "../../infra/format-time/format-duration.js";
+import { buildThreadingToolContext } from "./agent-runner-utils.js";
+import { applyReplyThreading } from "./reply-payloads.js";
+import {
+  formatRunLabel,
+  formatRunStatus,
+  resolveSubagentLabel,
+  sortSubagentRuns,
+} from "./subagents-utils.js";
+
+describe("buildThreadingToolContext", () => {
+  const cfg = {} as OpenClawConfig;
+
+  it("uses conversation id for WhatsApp", () => {
+    const sessionCtx = {
+      Provider: "whatsapp",
+      From: "123@g.us",
+      To: "+15550001",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: cfg,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("123@g.us");
+  });
+
+  it("falls back to To for WhatsApp when From is missing", () => {
+    const sessionCtx = {
+      Provider: "whatsapp",
+      To: "+15550001",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: cfg,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("+15550001");
+  });
+
+  it("uses the recipient id for other channels", () => {
+    const sessionCtx = {
+      Provider: "telegram",
+      From: "user:42",
+      To: "chat:99",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: cfg,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("chat:99");
+  });
+
+  it("uses the sender handle for iMessage direct chats", () => {
+    const sessionCtx = {
+      Provider: "imessage",
+      ChatType: "direct",
+      From: "imessage:+15550001",
+      To: "chat_id:12",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: cfg,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("imessage:+15550001");
+  });
+
+  it("uses chat_id for iMessage groups", () => {
+    const sessionCtx = {
+      Provider: "imessage",
+      ChatType: "group",
+      From: "imessage:group:7",
+      To: "chat_id:7",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: cfg,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("chat_id:7");
+  });
+
+  it("prefers MessageThreadId for Slack tool threading", () => {
+    const sessionCtx = {
+      Provider: "slack",
+      To: "channel:C1",
+      MessageThreadId: "123.456",
+    } as TemplateContext;
+
+    const result = buildThreadingToolContext({
+      sessionCtx,
+      config: { channels: { slack: { replyToMode: "all" } } } as OpenClawConfig,
+      hasRepliedRef: undefined,
+    });
+
+    expect(result.currentChannelId).toBe("C1");
+    expect(result.currentThreadTs).toBe("123.456");
+  });
+});
+
+describe("applyReplyThreading auto-threading", () => {
+  it("sets replyToId to currentMessageId even without [[reply_to_current]] tag", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "Hello" }],
+      replyToMode: "first",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].replyToId).toBe("42");
+  });
+
+  it("threads only first payload when mode is 'first'", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "A" }, { text: "B" }],
+      replyToMode: "first",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].replyToId).toBe("42");
+    expect(result[1].replyToId).toBeUndefined();
+  });
+
+  it("threads all payloads when mode is 'all'", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "A" }, { text: "B" }],
+      replyToMode: "all",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].replyToId).toBe("42");
+    expect(result[1].replyToId).toBe("42");
+  });
+
+  it("strips replyToId when mode is 'off'", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "A" }],
+      replyToMode: "off",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].replyToId).toBeUndefined();
+  });
+
+  it("does not bypass off mode for Slack when reply is implicit", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "A" }],
+      replyToMode: "off",
+      replyToChannel: "slack",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].replyToId).toBeUndefined();
+  });
+
+  it("keeps explicit tags for Slack when off mode allows tags", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "[[reply_to_current]]A" }],
+      replyToMode: "off",
+      replyToChannel: "slack",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].replyToId).toBe("42");
+    expect(result[0].replyToTag).toBe(true);
+  });
+
+  it("keeps explicit tags for Telegram when off mode is enabled", () => {
+    const result = applyReplyThreading({
+      payloads: [{ text: "[[reply_to_current]]A" }],
+      replyToMode: "off",
+      replyToChannel: "telegram",
+      currentMessageId: "42",
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].replyToId).toBe("42");
+    expect(result[0].replyToTag).toBe(true);
+  });
+});
+
+const baseRun: SubagentRunRecord = {
+  runId: "run-1",
+  childSessionKey: "agent:main:subagent:abc",
+  requesterSessionKey: "agent:main:main",
+  requesterDisplayKey: "main",
+  task: "do thing",
+  cleanup: "keep",
+  createdAt: 1000,
+  startedAt: 1000,
+};
+
+describe("subagents utils", () => {
+  it("resolves labels from label, task, or fallback", () => {
+    expect(resolveSubagentLabel({ ...baseRun, label: "Label" })).toBe("Label");
+    expect(resolveSubagentLabel({ ...baseRun, label: " ", task: "Task" })).toBe("Task");
+    expect(resolveSubagentLabel({ ...baseRun, label: " ", task: " " }, "fallback")).toBe(
+      "fallback",
+    );
+  });
+
+  it("formats run labels with truncation", () => {
+    const long = "x".repeat(100);
+    const run = { ...baseRun, label: long };
+    const formatted = formatRunLabel(run, { maxLength: 10 });
+    expect(formatted.startsWith("x".repeat(10))).toBe(true);
+    expect(formatted.endsWith("…")).toBe(true);
+  });
+
+  it("sorts subagent runs by newest start/created time", () => {
+    const runs: SubagentRunRecord[] = [
+      { ...baseRun, runId: "run-1", createdAt: 1000, startedAt: 1000 },
+      { ...baseRun, runId: "run-2", createdAt: 1200, startedAt: 1200 },
+      { ...baseRun, runId: "run-3", createdAt: 900 },
+    ];
+    const sorted = sortSubagentRuns(runs);
+    expect(sorted.map((run) => run.runId)).toEqual(["run-2", "run-1", "run-3"]);
+  });
+
+  it("formats run status from outcome and timestamps", () => {
+    expect(formatRunStatus({ ...baseRun })).toBe("running");
+    expect(formatRunStatus({ ...baseRun, endedAt: 2000, outcome: { status: "ok" } })).toBe("done");
+    expect(formatRunStatus({ ...baseRun, endedAt: 2000, outcome: { status: "timeout" } })).toBe(
+      "timeout",
+    );
+  });
+
+  it("formats duration compact for seconds and minutes", () => {
+    expect(formatDurationCompact(45_000)).toBe("45s");
+    expect(formatDurationCompact(65_000)).toBe("1m5s");
+  });
+});
diff --git a/src/auto-reply/reply/reply-routing.test.ts b/src/auto-reply/reply/reply-routing.test.ts
deleted file mode 100644
index 78a4010c53c..00000000000
--- a/src/auto-reply/reply/reply-routing.test.ts
+++ /dev/null
@@ -1,249 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { HEARTBEAT_TOKEN, SILENT_REPLY_TOKEN } from "../tokens.js";
-import { createReplyDispatcher } from "./reply-dispatcher.js";
-import { createReplyToModeFilter, resolveReplyToMode } from "./reply-threading.js";
-
-const emptyCfg = {} as OpenClawConfig;
-
-describe("createReplyDispatcher", () => {
-  it("drops empty payloads and silent tokens without media", async () => {
-    const deliver = vi.fn().mockResolvedValue(undefined);
-    const dispatcher = createReplyDispatcher({ deliver });
-
-    expect(dispatcher.sendFinalReply({})).toBe(false);
-    expect(dispatcher.sendFinalReply({ text: " " })).toBe(false);
-    expect(dispatcher.sendFinalReply({ text: SILENT_REPLY_TOKEN })).toBe(false);
-    expect(dispatcher.sendFinalReply({ text: `${SILENT_REPLY_TOKEN} -- nope` })).toBe(false);
-    expect(dispatcher.sendFinalReply({ text: `interject.${SILENT_REPLY_TOKEN}` })).toBe(false);
-
-    await dispatcher.waitForIdle();
-    expect(deliver).not.toHaveBeenCalled();
-  });
-
-  it("strips heartbeat tokens and applies responsePrefix", async () => {
-    const deliver = vi.fn().mockResolvedValue(undefined);
-    const onHeartbeatStrip = vi.fn();
-    const dispatcher = createReplyDispatcher({
-      deliver,
-      responsePrefix: "PFX",
-      onHeartbeatStrip,
-    });
-
-    expect(dispatcher.sendFinalReply({ text: HEARTBEAT_TOKEN })).toBe(false);
-    expect(dispatcher.sendToolResult({ text: `${HEARTBEAT_TOKEN} hello` })).toBe(true);
-    await dispatcher.waitForIdle();
-
-    expect(deliver).toHaveBeenCalledTimes(1);
-    expect(deliver.mock.calls[0][0].text).toBe("PFX hello");
-    expect(onHeartbeatStrip).toHaveBeenCalledTimes(2);
-  });
-
-  it("avoids double-prefixing and keeps media when heartbeat is the only text", async () => {
-    const deliver = vi.fn().mockResolvedValue(undefined);
-    const dispatcher = createReplyDispatcher({
-      deliver,
-      responsePrefix: "PFX",
-    });
-
-    expect(
-      dispatcher.sendFinalReply({
-        text: "PFX already",
-        mediaUrl: "file:///tmp/photo.jpg",
-      }),
-    ).toBe(true);
-    expect(
-      dispatcher.sendFinalReply({
-        text: HEARTBEAT_TOKEN,
-        mediaUrl: "file:///tmp/photo.jpg",
-      }),
-    ).toBe(true);
-    expect(
-      dispatcher.sendFinalReply({
-        text: `${SILENT_REPLY_TOKEN} -- explanation`,
-        mediaUrl: "file:///tmp/photo.jpg",
-      }),
-    ).toBe(true);
-
-    await dispatcher.waitForIdle();
-
-    expect(deliver).toHaveBeenCalledTimes(3);
-    expect(deliver.mock.calls[0][0].text).toBe("PFX already");
-    expect(deliver.mock.calls[1][0].text).toBe("");
-    expect(deliver.mock.calls[2][0].text).toBe("");
-  });
-
-  it("preserves ordering across tool, block, and final replies", async () => {
-    const delivered: string[] = [];
-    const deliver = vi.fn(async (_payload, info) => {
-      delivered.push(info.kind);
-      if (info.kind === "tool") {
-        await new Promise((resolve) => setTimeout(resolve, 5));
-      }
-    });
-    const dispatcher = createReplyDispatcher({ deliver });
-
-    dispatcher.sendToolResult({ text: "tool" });
-    dispatcher.sendBlockReply({ text: "block" });
-    dispatcher.sendFinalReply({ text: "final" });
-
-    await dispatcher.waitForIdle();
-    expect(delivered).toEqual(["tool", "block", "final"]);
-  });
-
-  it("fires onIdle when the queue drains", async () => {
-    const deliver = vi.fn(async () => await new Promise((resolve) => setTimeout(resolve, 5)));
-    const onIdle = vi.fn();
-    const dispatcher = createReplyDispatcher({ deliver, onIdle });
-
-    dispatcher.sendToolResult({ text: "one" });
-    dispatcher.sendFinalReply({ text: "two" });
-
-    await dispatcher.waitForIdle();
-    dispatcher.markComplete();
-    await Promise.resolve();
-    expect(onIdle).toHaveBeenCalledTimes(1);
-  });
-
-  it("delays block replies after the first when humanDelay is natural", async () => {
-    vi.useFakeTimers();
-    const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0);
-    const deliver = vi.fn().mockResolvedValue(undefined);
-    const dispatcher = createReplyDispatcher({
-      deliver,
-      humanDelay: { mode: "natural" },
-    });
-
-    dispatcher.sendBlockReply({ text: "first" });
-    await Promise.resolve();
-    expect(deliver).toHaveBeenCalledTimes(1);
-
-    dispatcher.sendBlockReply({ text: "second" });
-    await Promise.resolve();
-    expect(deliver).toHaveBeenCalledTimes(1);
-
-    await vi.advanceTimersByTimeAsync(799);
-    expect(deliver).toHaveBeenCalledTimes(1);
-
-    await vi.advanceTimersByTimeAsync(1);
-    await dispatcher.waitForIdle();
-    expect(deliver).toHaveBeenCalledTimes(2);
-
-    randomSpy.mockRestore();
-    vi.useRealTimers();
-  });
-
-  it("uses custom bounds for humanDelay and clamps when max <= min", async () => {
-    vi.useFakeTimers();
-    const deliver = vi.fn().mockResolvedValue(undefined);
-    const dispatcher = createReplyDispatcher({
-      deliver,
-      humanDelay: { mode: "custom", minMs: 1200, maxMs: 400 },
-    });
-
-    dispatcher.sendBlockReply({ text: "first" });
-    await Promise.resolve();
-    expect(deliver).toHaveBeenCalledTimes(1);
-
-    dispatcher.sendBlockReply({ text: "second" });
-    await vi.advanceTimersByTimeAsync(1199);
-    expect(deliver).toHaveBeenCalledTimes(1);
-
-    await vi.advanceTimersByTimeAsync(1);
-    await dispatcher.waitForIdle();
-    expect(deliver).toHaveBeenCalledTimes(2);
-
-    vi.useRealTimers();
-  });
-});
-
-describe("resolveReplyToMode", () => {
-  it("defaults to off for Telegram", () => {
-    expect(resolveReplyToMode(emptyCfg, "telegram")).toBe("off");
-  });
-
-  it("defaults to off for Discord and Slack", () => {
-    expect(resolveReplyToMode(emptyCfg, "discord")).toBe("off");
-    expect(resolveReplyToMode(emptyCfg, "slack")).toBe("off");
-  });
-
-  it("defaults to all when channel is unknown", () => {
-    expect(resolveReplyToMode(emptyCfg, undefined)).toBe("all");
-  });
-
-  it("uses configured value when present", () => {
-    const cfg = {
-      channels: {
-        telegram: { replyToMode: "all" },
-        discord: { replyToMode: "first" },
-        slack: { replyToMode: "all" },
-      },
-    } as OpenClawConfig;
-    expect(resolveReplyToMode(cfg, "telegram")).toBe("all");
-    expect(resolveReplyToMode(cfg, "discord")).toBe("first");
-    expect(resolveReplyToMode(cfg, "slack")).toBe("all");
-  });
-
-  it("uses chat-type replyToMode overrides for Slack when configured", () => {
-    const cfg = {
-      channels: {
-        slack: {
-          replyToMode: "off",
-          replyToModeByChatType: { direct: "all", group: "first" },
-        },
-      },
-    } as OpenClawConfig;
-    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("all");
-    expect(resolveReplyToMode(cfg, "slack", null, "group")).toBe("first");
-    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("off");
-    expect(resolveReplyToMode(cfg, "slack", null, undefined)).toBe("off");
-  });
-
-  it("falls back to top-level replyToMode when no chat-type override is set", () => {
-    const cfg = {
-      channels: {
-        slack: {
-          replyToMode: "first",
-        },
-      },
-    } as OpenClawConfig;
-    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("first");
-    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("first");
-  });
-
-  it("uses legacy dm.replyToMode for direct messages when no chat-type override exists", () => {
-    const cfg = {
-      channels: {
-        slack: {
-          replyToMode: "off",
-          dm: { replyToMode: "all" },
-        },
-      },
-    } as OpenClawConfig;
-    expect(resolveReplyToMode(cfg, "slack", null, "direct")).toBe("all");
-    expect(resolveReplyToMode(cfg, "slack", null, "channel")).toBe("off");
-  });
-});
-
-describe("createReplyToModeFilter", () => {
-  it("drops replyToId when mode is off", () => {
-    const filter = createReplyToModeFilter("off");
-    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBeUndefined();
-  });
-
-  it("keeps replyToId when mode is off and reply tags are allowed", () => {
-    const filter = createReplyToModeFilter("off", { allowExplicitReplyTagsWhenOff: true });
-    expect(filter({ text: "hi", replyToId: "1", replyToTag: true }).replyToId).toBe("1");
-  });
-
-  it("keeps replyToId when mode is all", () => {
-    const filter = createReplyToModeFilter("all");
-    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBe("1");
-  });
-
-  it("keeps only the first replyToId when mode is first", () => {
-    const filter = createReplyToModeFilter("first");
-    expect(filter({ text: "hi", replyToId: "1" }).replyToId).toBe("1");
-    expect(filter({ text: "next", replyToId: "1" }).replyToId).toBeUndefined();
-  });
-});
diff --git a/src/auto-reply/reply/reply-state.test.ts b/src/auto-reply/reply/reply-state.test.ts
new file mode 100644
index 00000000000..182506b4e48
--- /dev/null
+++ b/src/auto-reply/reply/reply-state.test.ts
@@ -0,0 +1,381 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { SessionEntry } from "../../config/sessions.js";
+import {
+  appendHistoryEntry,
+  buildHistoryContext,
+  buildHistoryContextFromEntries,
+  buildHistoryContextFromMap,
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntriesIfEnabled,
+  HISTORY_CONTEXT_MARKER,
+  recordPendingHistoryEntryIfEnabled,
+} from "./history.js";
+import {
+  DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
+  resolveMemoryFlushContextWindowTokens,
+  resolveMemoryFlushSettings,
+  shouldRunMemoryFlush,
+} from "./memory-flush.js";
+import { CURRENT_MESSAGE_MARKER } from "./mentions.js";
+import { incrementCompactionCount } from "./session-updates.js";
+
+async function seedSessionStore(params: {
+  storePath: string;
+  sessionKey: string;
+  entry: Record<string, unknown>;
+}) {
+  await fs.mkdir(path.dirname(params.storePath), { recursive: true });
+  await fs.writeFile(
+    params.storePath,
+    JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
+    "utf-8",
+  );
+}
+
+describe("history helpers", () => {
+  it("returns current message when history is empty", () => {
+    const result = buildHistoryContext({
+      historyText: "  ",
+      currentMessage: "hello",
+    });
+    expect(result).toBe("hello");
+  });
+
+  it("wraps history entries and excludes current by default", () => {
+    const result = buildHistoryContextFromEntries({
+      entries: [
+        { sender: "A", body: "one" },
+        { sender: "B", body: "two" },
+      ],
+      currentMessage: "current",
+      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
+    });
+
+    expect(result).toContain(HISTORY_CONTEXT_MARKER);
+    expect(result).toContain("A: one");
+    expect(result).not.toContain("B: two");
+    expect(result).toContain(CURRENT_MESSAGE_MARKER);
+    expect(result).toContain("current");
+  });
+
+  it("trims history to configured limit", () => {
+    const historyMap = new Map<string, { sender: string; body: string }[]>();
+
+    appendHistoryEntry({
+      historyMap,
+      historyKey: "group",
+      limit: 2,
+      entry: { sender: "A", body: "one" },
+    });
+    appendHistoryEntry({
+      historyMap,
+      historyKey: "group",
+      limit: 2,
+      entry: { sender: "B", body: "two" },
+    });
+    appendHistoryEntry({
+      historyMap,
+      historyKey: "group",
+      limit: 2,
+      entry: { sender: "C", body: "three" },
+    });
+
+    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["two", "three"]);
+  });
+
+  it("builds context from map and appends entry", () => {
+    const historyMap = new Map<string, { sender: string; body: string }[]>();
+    historyMap.set("group", [
+      { sender: "A", body: "one" },
+      { sender: "B", body: "two" },
+    ]);
+
+    const result = buildHistoryContextFromMap({
+      historyMap,
+      historyKey: "group",
+      limit: 3,
+      entry: { sender: "C", body: "three" },
+      currentMessage: "current",
+      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
+    });
+
+    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two", "three"]);
+    expect(result).toContain(HISTORY_CONTEXT_MARKER);
+    expect(result).toContain("A: one");
+    expect(result).toContain("B: two");
+    expect(result).not.toContain("C: three");
+  });
+
+  it("builds context from pending map without appending", () => {
+    const historyMap = new Map<string, { sender: string; body: string }[]>();
+    historyMap.set("group", [
+      { sender: "A", body: "one" },
+      { sender: "B", body: "two" },
+    ]);
+
+    const result = buildPendingHistoryContextFromMap({
+      historyMap,
+      historyKey: "group",
+      limit: 3,
+      currentMessage: "current",
+      formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
+    });
+
+    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two"]);
+    expect(result).toContain(HISTORY_CONTEXT_MARKER);
+    expect(result).toContain("A: one");
+    expect(result).toContain("B: two");
+    expect(result).toContain(CURRENT_MESSAGE_MARKER);
+    expect(result).toContain("current");
+  });
+
+  it("records pending entries only when enabled", () => {
+    const historyMap = new Map<string, { sender: string; body: string }[]>();
+
+    recordPendingHistoryEntryIfEnabled({
+      historyMap,
+      historyKey: "group",
+      limit: 0,
+      entry: { sender: "A", body: "one" },
+    });
+    expect(historyMap.get("group")).toEqual(undefined);
+
+    recordPendingHistoryEntryIfEnabled({
+      historyMap,
+      historyKey: "group",
+      limit: 2,
+      entry: null,
+    });
+    expect(historyMap.get("group")).toEqual(undefined);
+
+    recordPendingHistoryEntryIfEnabled({
+      historyMap,
+      historyKey: "group",
+      limit: 2,
+      entry: { sender: "B", body: "two" },
+    });
+    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["two"]);
+  });
+
+  it("clears history entries only when enabled", () => {
+    const historyMap = new Map<string, { sender: string; body: string }[]>();
+    historyMap.set("group", [
+      { sender: "A", body: "one" },
+      { sender: "B", body: "two" },
+    ]);
+
+    clearHistoryEntriesIfEnabled({ historyMap, historyKey: "group", limit: 0 });
+    expect(historyMap.get("group")?.map((entry) => entry.body)).toEqual(["one", "two"]);
+
+    clearHistoryEntriesIfEnabled({ historyMap, historyKey: "group", limit: 2 });
+    expect(historyMap.get("group")).toEqual([]);
+  });
+});
+
+describe("memory flush settings", () => {
+  it("defaults to enabled with fallback prompt and system prompt", () => {
+    const settings = resolveMemoryFlushSettings();
+    expect(settings).not.toBeNull();
+    expect(settings?.enabled).toBe(true);
+    expect(settings?.prompt.length).toBeGreaterThan(0);
+    expect(settings?.systemPrompt.length).toBeGreaterThan(0);
+  });
+
+  it("respects disable flag", () => {
+    expect(
+      resolveMemoryFlushSettings({
+        agents: {
+          defaults: { compaction: { memoryFlush: { enabled: false } } },
+        },
+      }),
+    ).toBeNull();
+  });
+
+  it("appends NO_REPLY hint when missing", () => {
+    const settings = resolveMemoryFlushSettings({
+      agents: {
+        defaults: {
+          compaction: {
+            memoryFlush: {
+              prompt: "Write memories now.",
+              systemPrompt: "Flush memory.",
+            },
+          },
+        },
+      },
+    });
+    expect(settings?.prompt).toContain("NO_REPLY");
+    expect(settings?.systemPrompt).toContain("NO_REPLY");
+  });
+});
+
+describe("shouldRunMemoryFlush", () => {
+  it("requires totalTokens and threshold", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: { totalTokens: 0 },
+        contextWindowTokens: 16_000,
+        reserveTokensFloor: 20_000,
+        softThresholdTokens: DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
+      }),
+    ).toBe(false);
+  });
+
+  it("skips when entry is missing", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: undefined,
+        contextWindowTokens: 16_000,
+        reserveTokensFloor: 1_000,
+        softThresholdTokens: DEFAULT_MEMORY_FLUSH_SOFT_TOKENS,
+      }),
+    ).toBe(false);
+  });
+
+  it("skips when under threshold", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: { totalTokens: 10_000 },
+        contextWindowTokens: 100_000,
+        reserveTokensFloor: 20_000,
+        softThresholdTokens: 10_000,
+      }),
+    ).toBe(false);
+  });
+
+  it("triggers at the threshold boundary", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: { totalTokens: 85 },
+        contextWindowTokens: 100,
+        reserveTokensFloor: 10,
+        softThresholdTokens: 5,
+      }),
+    ).toBe(true);
+  });
+
+  it("skips when already flushed for current compaction count", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: {
+          totalTokens: 90_000,
+          compactionCount: 2,
+          memoryFlushCompactionCount: 2,
+        },
+        contextWindowTokens: 100_000,
+        reserveTokensFloor: 5_000,
+        softThresholdTokens: 2_000,
+      }),
+    ).toBe(false);
+  });
+
+  it("runs when above threshold and not flushed", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: { totalTokens: 96_000, compactionCount: 1 },
+        contextWindowTokens: 100_000,
+        reserveTokensFloor: 5_000,
+        softThresholdTokens: 2_000,
+      }),
+    ).toBe(true);
+  });
+
+  it("ignores stale cached totals", () => {
+    expect(
+      shouldRunMemoryFlush({
+        entry: { totalTokens: 96_000, totalTokensFresh: false, compactionCount: 1 },
+        contextWindowTokens: 100_000,
+        reserveTokensFloor: 5_000,
+        softThresholdTokens: 2_000,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("resolveMemoryFlushContextWindowTokens", () => {
+  it("falls back to agent config or default tokens", () => {
+    expect(resolveMemoryFlushContextWindowTokens({ agentCfgContextTokens: 42_000 })).toBe(42_000);
+  });
+});
+
+describe("incrementCompactionCount", () => {
+  it("increments compaction count", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
+    const storePath = path.join(tmp, "sessions.json");
+    const sessionKey = "main";
+    const entry = { sessionId: "s1", updatedAt: Date.now(), compactionCount: 2 } as SessionEntry;
+    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
+    await seedSessionStore({ storePath, sessionKey, entry });
+
+    const count = await incrementCompactionCount({
+      sessionEntry: entry,
+      sessionStore,
+      sessionKey,
+      storePath,
+    });
+    expect(count).toBe(3);
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].compactionCount).toBe(3);
+  });
+
+  it("updates totalTokens when tokensAfter is provided", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
+    const storePath = path.join(tmp, "sessions.json");
+    const sessionKey = "main";
+    const entry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+      compactionCount: 0,
+      totalTokens: 180_000,
+      inputTokens: 170_000,
+      outputTokens: 10_000,
+    } as SessionEntry;
+    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
+    await seedSessionStore({ storePath, sessionKey, entry });
+
+    await incrementCompactionCount({
+      sessionEntry: entry,
+      sessionStore,
+      sessionKey,
+      storePath,
+      tokensAfter: 12_000,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].compactionCount).toBe(1);
+    expect(stored[sessionKey].totalTokens).toBe(12_000);
+    // input/output cleared since we only have the total estimate
+    expect(stored[sessionKey].inputTokens).toBeUndefined();
+    expect(stored[sessionKey].outputTokens).toBeUndefined();
+  });
+
+  it("does not update totalTokens when tokensAfter is not provided", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
+    const storePath = path.join(tmp, "sessions.json");
+    const sessionKey = "main";
+    const entry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+      compactionCount: 0,
+      totalTokens: 180_000,
+    } as SessionEntry;
+    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
+    await seedSessionStore({ storePath, sessionKey, entry });
+
+    await incrementCompactionCount({
+      sessionEntry: entry,
+      sessionStore,
+      sessionKey,
+      storePath,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].compactionCount).toBe(1);
+    // totalTokens unchanged
+    expect(stored[sessionKey].totalTokens).toBe(180_000);
+  });
+});
diff --git a/src/auto-reply/reply/reply-utils.test.ts b/src/auto-reply/reply/reply-utils.test.ts
new file mode 100644
index 00000000000..94f68652f11
--- /dev/null
+++ b/src/auto-reply/reply/reply-utils.test.ts
@@ -0,0 +1,781 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import { parseAudioTag } from "./audio-tags.js";
+import { createBlockReplyCoalescer } from "./block-reply-coalescer.js";
+import { matchesMentionWithExplicit } from "./mentions.js";
+import { normalizeReplyPayload } from "./normalize-reply.js";
+import { createReplyReferencePlanner } from "./reply-reference.js";
+import {
+  extractShortModelName,
+  hasTemplateVariables,
+  resolveResponsePrefixTemplate,
+} from "./response-prefix-template.js";
+import { createStreamingDirectiveAccumulator } from "./streaming-directives.js";
+import { createMockTypingController } from "./test-helpers.js";
+import { createTypingSignaler, resolveTypingMode } from "./typing-mode.js";
+import { createTypingController } from "./typing.js";
+
+describe("matchesMentionWithExplicit", () => {
+  const mentionRegexes = [/\bopenclaw\b/i];
+
+  it("checks mentionPatterns even when explicit mention is available", () => {
+    const result = matchesMentionWithExplicit({
+      text: "@openclaw hello",
+      mentionRegexes,
+      explicit: {
+        hasAnyMention: true,
+        isExplicitlyMentioned: false,
+        canResolveExplicit: true,
+      },
+    });
+    expect(result).toBe(true);
+  });
+
+  it("returns false when explicit is false and no regex match", () => {
+    const result = matchesMentionWithExplicit({
+      text: "<@999999> hello",
+      mentionRegexes,
+      explicit: {
+        hasAnyMention: true,
+        isExplicitlyMentioned: false,
+        canResolveExplicit: true,
+      },
+    });
+    expect(result).toBe(false);
+  });
+
+  it("returns true when explicitly mentioned even if regexes do not match", () => {
+    const result = matchesMentionWithExplicit({
+      text: "<@123456>",
+      mentionRegexes: [],
+      explicit: {
+        hasAnyMention: true,
+        isExplicitlyMentioned: true,
+        canResolveExplicit: true,
+      },
+    });
+    expect(result).toBe(true);
+  });
+
+  it("falls back to regex matching when explicit mention cannot be resolved", () => {
+    const result = matchesMentionWithExplicit({
+      text: "openclaw please",
+      mentionRegexes,
+      explicit: {
+        hasAnyMention: true,
+        isExplicitlyMentioned: false,
+        canResolveExplicit: false,
+      },
+    });
+    expect(result).toBe(true);
+  });
+});
+
+// Keep channelData-only payloads so channel-specific replies survive normalization.
+describe("normalizeReplyPayload", () => {
+  it("keeps channelData-only replies", () => {
+    const payload = {
+      channelData: {
+        line: {
+          flexMessage: { type: "bubble" },
+        },
+      },
+    };
+
+    const normalized = normalizeReplyPayload(payload);
+
+    expect(normalized).not.toBeNull();
+    expect(normalized?.text).toBeUndefined();
+    expect(normalized?.channelData).toEqual(payload.channelData);
+  });
+
+  it("records silent skips", () => {
+    const reasons: string[] = [];
+    const normalized = normalizeReplyPayload(
+      { text: SILENT_REPLY_TOKEN },
+      {
+        onSkip: (reason) => reasons.push(reason),
+      },
+    );
+
+    expect(normalized).toBeNull();
+    expect(reasons).toEqual(["silent"]);
+  });
+
+  it("records empty skips", () => {
+    const reasons: string[] = [];
+    const normalized = normalizeReplyPayload(
+      { text: "   " },
+      {
+        onSkip: (reason) => reasons.push(reason),
+      },
+    );
+
+    expect(normalized).toBeNull();
+    expect(reasons).toEqual(["empty"]);
+  });
+});
+
+describe("typing controller", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("stops after run completion and dispatcher idle", async () => {
+    vi.useFakeTimers();
+    const onReplyStart = vi.fn(async () => {});
+    const typing = createTypingController({
+      onReplyStart,
+      typingIntervalSeconds: 1,
+      typingTtlMs: 30_000,
+    });
+
+    await typing.startTypingLoop();
+    expect(onReplyStart).toHaveBeenCalledTimes(1);
+
+    vi.advanceTimersByTime(2_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(3);
+
+    typing.markRunComplete();
+    vi.advanceTimersByTime(1_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(4);
+
+    typing.markDispatchIdle();
+    vi.advanceTimersByTime(2_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(4);
+  });
+
+  it("keeps typing until both idle and run completion are set", async () => {
+    vi.useFakeTimers();
+    const onReplyStart = vi.fn(async () => {});
+    const typing = createTypingController({
+      onReplyStart,
+      typingIntervalSeconds: 1,
+      typingTtlMs: 30_000,
+    });
+
+    await typing.startTypingLoop();
+    expect(onReplyStart).toHaveBeenCalledTimes(1);
+
+    typing.markDispatchIdle();
+    vi.advanceTimersByTime(2_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(3);
+
+    typing.markRunComplete();
+    vi.advanceTimersByTime(2_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not start typing after run completion", async () => {
+    vi.useFakeTimers();
+    const onReplyStart = vi.fn(async () => {});
+    const typing = createTypingController({
+      onReplyStart,
+      typingIntervalSeconds: 1,
+      typingTtlMs: 30_000,
+    });
+
+    typing.markRunComplete();
+    await typing.startTypingOnText("late text");
+    vi.advanceTimersByTime(2_000);
+    expect(onReplyStart).not.toHaveBeenCalled();
+  });
+
+  it("does not restart typing after it has stopped", async () => {
+    vi.useFakeTimers();
+    const onReplyStart = vi.fn(async () => {});
+    const typing = createTypingController({
+      onReplyStart,
+      typingIntervalSeconds: 1,
+      typingTtlMs: 30_000,
+    });
+
+    await typing.startTypingLoop();
+    expect(onReplyStart).toHaveBeenCalledTimes(1);
+
+    typing.markRunComplete();
+    typing.markDispatchIdle();
+
+    vi.advanceTimersByTime(5_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(1);
+
+    // Late callbacks should be ignored and must not restart the interval.
+    await typing.startTypingOnText("late tool result");
+    vi.advanceTimersByTime(5_000);
+    expect(onReplyStart).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("resolveTypingMode", () => {
+  it("defaults to instant for direct chats", () => {
+    expect(
+      resolveTypingMode({
+        configured: undefined,
+        isGroupChat: false,
+        wasMentioned: false,
+        isHeartbeat: false,
+      }),
+    ).toBe("instant");
+  });
+
+  it("defaults to message for group chats without mentions", () => {
+    expect(
+      resolveTypingMode({
+        configured: undefined,
+        isGroupChat: true,
+        wasMentioned: false,
+        isHeartbeat: false,
+      }),
+    ).toBe("message");
+  });
+
+  it("defaults to instant for mentioned group chats", () => {
+    expect(
+      resolveTypingMode({
+        configured: undefined,
+        isGroupChat: true,
+        wasMentioned: true,
+        isHeartbeat: false,
+      }),
+    ).toBe("instant");
+  });
+
+  it("honors configured mode across contexts", () => {
+    expect(
+      resolveTypingMode({
+        configured: "thinking",
+        isGroupChat: false,
+        wasMentioned: false,
+        isHeartbeat: false,
+      }),
+    ).toBe("thinking");
+    expect(
+      resolveTypingMode({
+        configured: "message",
+        isGroupChat: true,
+        wasMentioned: true,
+        isHeartbeat: false,
+      }),
+    ).toBe("message");
+  });
+
+  it("forces never for heartbeat runs", () => {
+    expect(
+      resolveTypingMode({
+        configured: "instant",
+        isGroupChat: false,
+        wasMentioned: false,
+        isHeartbeat: true,
+      }),
+    ).toBe("never");
+  });
+});
+
+describe("createTypingSignaler", () => {
+  it("signals immediately for instant mode", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "instant",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalRunStart();
+
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+  });
+
+  it("signals on text for message mode", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "message",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalTextDelta("hello");
+
+    expect(typing.startTypingOnText).toHaveBeenCalledWith("hello");
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+  });
+
+  it("signals on message start for message mode", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "message",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalMessageStart();
+
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+    await signaler.signalTextDelta("hello");
+    expect(typing.startTypingOnText).toHaveBeenCalledWith("hello");
+  });
+
+  it("signals on reasoning for thinking mode", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "thinking",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalReasoningDelta();
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+    await signaler.signalTextDelta("hi");
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+  });
+
+  it("refreshes ttl on text for thinking mode", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "thinking",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalTextDelta("hi");
+
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+    expect(typing.refreshTypingTtl).toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+  });
+
+  it("starts typing on tool start before text", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "message",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalToolStart();
+
+    expect(typing.startTypingLoop).toHaveBeenCalled();
+    expect(typing.refreshTypingTtl).toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+  });
+
+  it("refreshes ttl on tool start when active after text", async () => {
+    const typing = createMockTypingController({
+      isActive: vi.fn(() => true),
+    });
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "message",
+      isHeartbeat: false,
+    });
+
+    await signaler.signalTextDelta("hello");
+    typing.startTypingLoop.mockClear();
+    typing.startTypingOnText.mockClear();
+    typing.refreshTypingTtl.mockClear();
+    await signaler.signalToolStart();
+
+    expect(typing.refreshTypingTtl).toHaveBeenCalled();
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+  });
+
+  it("suppresses typing when disabled", async () => {
+    const typing = createMockTypingController();
+    const signaler = createTypingSignaler({
+      typing,
+      mode: "instant",
+      isHeartbeat: true,
+    });
+
+    await signaler.signalRunStart();
+    await signaler.signalTextDelta("hi");
+    await signaler.signalReasoningDelta();
+
+    expect(typing.startTypingLoop).not.toHaveBeenCalled();
+    expect(typing.startTypingOnText).not.toHaveBeenCalled();
+  });
+});
+
+describe("parseAudioTag", () => {
+  it("detects audio_as_voice and strips the tag", () => {
+    const result = parseAudioTag("Hello [[audio_as_voice]] world");
+    expect(result.audioAsVoice).toBe(true);
+    expect(result.hadTag).toBe(true);
+    expect(result.text).toBe("Hello world");
+  });
+
+  it("returns empty output for missing text", () => {
+    const result = parseAudioTag(undefined);
+    expect(result.audioAsVoice).toBe(false);
+    expect(result.hadTag).toBe(false);
+    expect(result.text).toBe("");
+  });
+
+  it("removes tag-only messages", () => {
+    const result = parseAudioTag("[[audio_as_voice]]");
+    expect(result.audioAsVoice).toBe(true);
+    expect(result.text).toBe("");
+  });
+});
+
+describe("block reply coalescer", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("coalesces chunks within the idle window", async () => {
+    vi.useFakeTimers();
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 1, maxChars: 200, idleMs: 100, joiner: " " },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    coalescer.enqueue({ text: "Hello" });
+    coalescer.enqueue({ text: "world" });
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(flushes).toEqual(["Hello world"]);
+    coalescer.stop();
+  });
+
+  it("waits until minChars before idle flush", async () => {
+    vi.useFakeTimers();
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 10, maxChars: 200, idleMs: 50, joiner: " " },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    coalescer.enqueue({ text: "short" });
+    await vi.advanceTimersByTimeAsync(50);
+    expect(flushes).toEqual([]);
+
+    coalescer.enqueue({ text: "message" });
+    await vi.advanceTimersByTimeAsync(50);
+    expect(flushes).toEqual(["short message"]);
+    coalescer.stop();
+  });
+
+  it("flushes each enqueued payload separately when flushOnEnqueue is set", async () => {
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 1, maxChars: 200, idleMs: 100, joiner: "\n\n", flushOnEnqueue: true },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    coalescer.enqueue({ text: "First paragraph" });
+    coalescer.enqueue({ text: "Second paragraph" });
+    coalescer.enqueue({ text: "Third paragraph" });
+
+    await Promise.resolve();
+    expect(flushes).toEqual(["First paragraph", "Second paragraph", "Third paragraph"]);
+    coalescer.stop();
+  });
+
+  it("still accumulates when flushOnEnqueue is not set (default)", async () => {
+    vi.useFakeTimers();
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 1, maxChars: 2000, idleMs: 100, joiner: "\n\n" },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    coalescer.enqueue({ text: "First paragraph" });
+    coalescer.enqueue({ text: "Second paragraph" });
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(flushes).toEqual(["First paragraph\n\nSecond paragraph"]);
+    coalescer.stop();
+  });
+
+  it("flushes short payloads immediately when flushOnEnqueue is set", async () => {
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 10, maxChars: 200, idleMs: 50, joiner: "\n\n", flushOnEnqueue: true },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    coalescer.enqueue({ text: "Hi" });
+    await Promise.resolve();
+    expect(flushes).toEqual(["Hi"]);
+    coalescer.stop();
+  });
+
+  it("resets char budget per paragraph with flushOnEnqueue", async () => {
+    const flushes: string[] = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 1, maxChars: 30, idleMs: 100, joiner: "\n\n", flushOnEnqueue: true },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push(payload.text ?? "");
+      },
+    });
+
+    // Each 20-char payload fits within maxChars=30 individually
+    coalescer.enqueue({ text: "12345678901234567890" });
+    coalescer.enqueue({ text: "abcdefghijklmnopqrst" });
+
+    await Promise.resolve();
+    // Without flushOnEnqueue, these would be joined to 40+ chars and trigger maxChars split.
+    // With flushOnEnqueue, each is sent independently within budget.
+    expect(flushes).toEqual(["12345678901234567890", "abcdefghijklmnopqrst"]);
+    coalescer.stop();
+  });
+
+  it("flushes buffered text before media payloads", () => {
+    const flushes: Array<{ text?: string; mediaUrls?: string[] }> = [];
+    const coalescer = createBlockReplyCoalescer({
+      config: { minChars: 1, maxChars: 200, idleMs: 0, joiner: " " },
+      shouldAbort: () => false,
+      onFlush: (payload) => {
+        flushes.push({
+          text: payload.text,
+          mediaUrls: payload.mediaUrls,
+        });
+      },
+    });
+
+    coalescer.enqueue({ text: "Hello" });
+    coalescer.enqueue({ text: "world" });
+    coalescer.enqueue({ mediaUrls: ["https://example.com/a.png"] });
+    void coalescer.flush({ force: true });
+
+    expect(flushes[0].text).toBe("Hello world");
+    expect(flushes[1].mediaUrls).toEqual(["https://example.com/a.png"]);
+    coalescer.stop();
+  });
+});
+
+describe("createReplyReferencePlanner", () => {
+  it("disables references when mode is off", () => {
+    const planner = createReplyReferencePlanner({
+      replyToMode: "off",
+      startId: "parent",
+    });
+    expect(planner.use()).toBeUndefined();
+  });
+
+  it("uses startId once when mode is first", () => {
+    const planner = createReplyReferencePlanner({
+      replyToMode: "first",
+      startId: "parent",
+    });
+    expect(planner.use()).toBe("parent");
+    expect(planner.hasReplied()).toBe(true);
+    planner.markSent();
+    expect(planner.use()).toBeUndefined();
+  });
+
+  it("returns startId for every call when mode is all", () => {
+    const planner = createReplyReferencePlanner({
+      replyToMode: "all",
+      startId: "parent",
+    });
+    expect(planner.use()).toBe("parent");
+    expect(planner.use()).toBe("parent");
+  });
+
+  it("uses existingId once when mode is first", () => {
+    const planner = createReplyReferencePlanner({
+      replyToMode: "first",
+      existingId: "thread-1",
+      startId: "parent",
+    });
+    expect(planner.use()).toBe("thread-1");
+    expect(planner.use()).toBeUndefined();
+  });
+
+  it("honors allowReference=false", () => {
+    const planner = createReplyReferencePlanner({
+      replyToMode: "all",
+      startId: "parent",
+      allowReference: false,
+    });
+    expect(planner.use()).toBeUndefined();
+    expect(planner.hasReplied()).toBe(false);
+    planner.markSent();
+    expect(planner.hasReplied()).toBe(true);
+  });
+});
+
+describe("createStreamingDirectiveAccumulator", () => {
+  it("stashes reply_to_current until a renderable chunk arrives", () => {
+    const accumulator = createStreamingDirectiveAccumulator();
+
+    expect(accumulator.consume("[[reply_to_current]]")).toBeNull();
+
+    const result = accumulator.consume("Hello");
+    expect(result?.text).toBe("Hello");
+    expect(result?.replyToCurrent).toBe(true);
+    expect(result?.replyToTag).toBe(true);
+  });
+
+  it("handles reply tags split across chunks", () => {
+    const accumulator = createStreamingDirectiveAccumulator();
+    expect(accumulator.consume("[[reply_to_")).toBeNull();
+
+    const result = accumulator.consume("current]] Yo");
+    expect(result?.text).toBe("Yo");
+    expect(result?.replyToCurrent).toBe(true);
+  });
+
+  it("propagates explicit reply ids across chunks", () => {
+    const accumulator = createStreamingDirectiveAccumulator();
+
+    expect(accumulator.consume("[[reply_to: abc-123]]")).toBeNull();
+
+    const result = accumulator.consume("Hi");
+    expect(result?.text).toBe("Hi");
+    expect(result?.replyToId).toBe("abc-123");
+    expect(result?.replyToTag).toBe(true);
+  });
+});
+
+describe("resolveResponsePrefixTemplate", () => {
+  it("returns undefined for undefined template", () => {
+    expect(resolveResponsePrefixTemplate(undefined, {})).toBeUndefined();
+  });
+
+  it("returns template as-is when no variables present", () => {
+    expect(resolveResponsePrefixTemplate("[Claude]", {})).toBe("[Claude]");
+  });
+
+  it("resolves {model} variable", () => {
+    const result = resolveResponsePrefixTemplate("[{model}]", {
+      model: "gpt-5.2",
+    });
+    expect(result).toBe("[gpt-5.2]");
+  });
+
+  it("resolves {modelFull} variable", () => {
+    const result = resolveResponsePrefixTemplate("[{modelFull}]", {
+      modelFull: "openai-codex/gpt-5.2",
+    });
+    expect(result).toBe("[openai-codex/gpt-5.2]");
+  });
+
+  it("resolves {provider} variable", () => {
+    const result = resolveResponsePrefixTemplate("[{provider}]", {
+      provider: "anthropic",
+    });
+    expect(result).toBe("[anthropic]");
+  });
+
+  it("resolves {thinkingLevel} variable", () => {
+    const result = resolveResponsePrefixTemplate("think:{thinkingLevel}", {
+      thinkingLevel: "high",
+    });
+    expect(result).toBe("think:high");
+  });
+
+  it("resolves {think} as alias for thinkingLevel", () => {
+    const result = resolveResponsePrefixTemplate("think:{think}", {
+      thinkingLevel: "low",
+    });
+    expect(result).toBe("think:low");
+  });
+
+  it("resolves {identity.name} variable", () => {
+    const result = resolveResponsePrefixTemplate("[{identity.name}]", {
+      identityName: "OpenClaw",
+    });
+    expect(result).toBe("[OpenClaw]");
+  });
+
+  it("resolves {identityName} as alias", () => {
+    const result = resolveResponsePrefixTemplate("[{identityName}]", {
+      identityName: "OpenClaw",
+    });
+    expect(result).toBe("[OpenClaw]");
+  });
+
+  it("leaves unresolved variables as-is", () => {
+    const result = resolveResponsePrefixTemplate("[{model}]", {});
+    expect(result).toBe("[{model}]");
+  });
+
+  it("leaves unrecognized variables as-is", () => {
+    const result = resolveResponsePrefixTemplate("[{unknownVar}]", {
+      model: "gpt-5.2",
+    });
+    expect(result).toBe("[{unknownVar}]");
+  });
+
+  it("handles case insensitivity", () => {
+    const result = resolveResponsePrefixTemplate("[{MODEL} | {ThinkingLevel}]", {
+      model: "gpt-5.2",
+      thinkingLevel: "low",
+    });
+    expect(result).toBe("[gpt-5.2 | low]");
+  });
+
+  it("handles mixed resolved and unresolved variables", () => {
+    const result = resolveResponsePrefixTemplate("[{model} | {provider}]", {
+      model: "gpt-5.2",
+      // provider not provided
+    });
+    expect(result).toBe("[gpt-5.2 | {provider}]");
+  });
+
+  it("handles complex template with all variables", () => {
+    const result = resolveResponsePrefixTemplate(
+      "[{identity.name}] {provider}/{model} (think:{thinkingLevel})",
+      {
+        identityName: "OpenClaw",
+        provider: "anthropic",
+        model: "claude-opus-4-5",
+        thinkingLevel: "high",
+      },
+    );
+    expect(result).toBe("[OpenClaw] anthropic/claude-opus-4-5 (think:high)");
+  });
+});
+
+describe("extractShortModelName", () => {
+  it("strips provider prefix", () => {
+    expect(extractShortModelName("openai-codex/gpt-5.2-codex")).toBe("gpt-5.2-codex");
+  });
+
+  it("strips date suffix", () => {
+    expect(extractShortModelName("claude-opus-4-5-20251101")).toBe("claude-opus-4-5");
+  });
+
+  it("strips -latest suffix", () => {
+    expect(extractShortModelName("gpt-5.2-latest")).toBe("gpt-5.2");
+  });
+
+  it("preserves version numbers that look like dates but are not", () => {
+    // Date suffix must be exactly 8 digits at the end
+    expect(extractShortModelName("model-123456789")).toBe("model-123456789");
+  });
+});
+
+describe("hasTemplateVariables", () => {
+  it("returns false for empty string", () => {
+    expect(hasTemplateVariables("")).toBe(false);
+  });
+
+  it("handles consecutive calls correctly (regex lastIndex reset)", () => {
+    // First call
+    expect(hasTemplateVariables("[{model}]")).toBe(true);
+    // Second call should still work
+    expect(hasTemplateVariables("[{model}]")).toBe(true);
+    // Static string should return false
+    expect(hasTemplateVariables("[Claude]")).toBe(false);
+  });
+});
diff --git a/src/auto-reply/reply/response-prefix-template.test.ts b/src/auto-reply/reply/response-prefix-template.test.ts
deleted file mode 100644
index 41c28e23ed9..00000000000
--- a/src/auto-reply/reply/response-prefix-template.test.ts
+++ /dev/null
@@ -1,180 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  extractShortModelName,
-  hasTemplateVariables,
-  resolveResponsePrefixTemplate,
-} from "./response-prefix-template.js";
-
-describe("resolveResponsePrefixTemplate", () => {
-  it("returns undefined for undefined template", () => {
-    expect(resolveResponsePrefixTemplate(undefined, {})).toBeUndefined();
-  });
-
-  it("returns template as-is when no variables present", () => {
-    expect(resolveResponsePrefixTemplate("[Claude]", {})).toBe("[Claude]");
-  });
-
-  it("resolves {model} variable", () => {
-    const result = resolveResponsePrefixTemplate("[{model}]", {
-      model: "gpt-5.2",
-    });
-    expect(result).toBe("[gpt-5.2]");
-  });
-
-  it("resolves {modelFull} variable", () => {
-    const result = resolveResponsePrefixTemplate("[{modelFull}]", {
-      modelFull: "openai-codex/gpt-5.2",
-    });
-    expect(result).toBe("[openai-codex/gpt-5.2]");
-  });
-
-  it("resolves {provider} variable", () => {
-    const result = resolveResponsePrefixTemplate("[{provider}]", {
-      provider: "anthropic",
-    });
-    expect(result).toBe("[anthropic]");
-  });
-
-  it("resolves {thinkingLevel} variable", () => {
-    const result = resolveResponsePrefixTemplate("think:{thinkingLevel}", {
-      thinkingLevel: "high",
-    });
-    expect(result).toBe("think:high");
-  });
-
-  it("resolves {think} as alias for thinkingLevel", () => {
-    const result = resolveResponsePrefixTemplate("think:{think}", {
-      thinkingLevel: "low",
-    });
-    expect(result).toBe("think:low");
-  });
-
-  it("resolves {identity.name} variable", () => {
-    const result = resolveResponsePrefixTemplate("[{identity.name}]", {
-      identityName: "OpenClaw",
-    });
-    expect(result).toBe("[OpenClaw]");
-  });
-
-  it("resolves {identityName} as alias", () => {
-    const result = resolveResponsePrefixTemplate("[{identityName}]", {
-      identityName: "OpenClaw",
-    });
-    expect(result).toBe("[OpenClaw]");
-  });
-
-  it("resolves multiple variables", () => {
-    const result = resolveResponsePrefixTemplate("[{model} | think:{thinkingLevel}]", {
-      model: "claude-opus-4-5",
-      thinkingLevel: "high",
-    });
-    expect(result).toBe("[claude-opus-4-5 | think:high]");
-  });
-
-  it("leaves unresolved variables as-is", () => {
-    const result = resolveResponsePrefixTemplate("[{model}]", {});
-    expect(result).toBe("[{model}]");
-  });
-
-  it("leaves unrecognized variables as-is", () => {
-    const result = resolveResponsePrefixTemplate("[{unknownVar}]", {
-      model: "gpt-5.2",
-    });
-    expect(result).toBe("[{unknownVar}]");
-  });
-
-  it("handles case insensitivity", () => {
-    const result = resolveResponsePrefixTemplate("[{MODEL} | {ThinkingLevel}]", {
-      model: "gpt-5.2",
-      thinkingLevel: "low",
-    });
-    expect(result).toBe("[gpt-5.2 | low]");
-  });
-
-  it("handles mixed resolved and unresolved variables", () => {
-    const result = resolveResponsePrefixTemplate("[{model} | {provider}]", {
-      model: "gpt-5.2",
-      // provider not provided
-    });
-    expect(result).toBe("[gpt-5.2 | {provider}]");
-  });
-
-  it("handles complex template with all variables", () => {
-    const result = resolveResponsePrefixTemplate(
-      "[{identity.name}] {provider}/{model} (think:{thinkingLevel})",
-      {
-        identityName: "OpenClaw",
-        provider: "anthropic",
-        model: "claude-opus-4-5",
-        thinkingLevel: "high",
-      },
-    );
-    expect(result).toBe("[OpenClaw] anthropic/claude-opus-4-5 (think:high)");
-  });
-});
-
-describe("extractShortModelName", () => {
-  it("strips provider prefix", () => {
-    expect(extractShortModelName("openai/gpt-5.2")).toBe("gpt-5.2");
-    expect(extractShortModelName("anthropic/claude-opus-4-5")).toBe("claude-opus-4-5");
-    expect(extractShortModelName("openai-codex/gpt-5.2-codex")).toBe("gpt-5.2-codex");
-  });
-
-  it("strips date suffix", () => {
-    expect(extractShortModelName("claude-opus-4-5-20251101")).toBe("claude-opus-4-5");
-    expect(extractShortModelName("gpt-5.2-20250115")).toBe("gpt-5.2");
-  });
-
-  it("strips -latest suffix", () => {
-    expect(extractShortModelName("gpt-5.2-latest")).toBe("gpt-5.2");
-    expect(extractShortModelName("claude-sonnet-latest")).toBe("claude-sonnet");
-  });
-
-  it("handles model without provider", () => {
-    expect(extractShortModelName("gpt-5.2")).toBe("gpt-5.2");
-    expect(extractShortModelName("claude-opus-4-5")).toBe("claude-opus-4-5");
-  });
-
-  it("handles full path with provider and date suffix", () => {
-    expect(extractShortModelName("anthropic/claude-opus-4-5-20251101")).toBe("claude-opus-4-5");
-  });
-
-  it("preserves version numbers that look like dates but are not", () => {
-    // Date suffix must be exactly 8 digits at the end
-    expect(extractShortModelName("model-v1234567")).toBe("model-v1234567");
-    expect(extractShortModelName("model-123456789")).toBe("model-123456789");
-  });
-});
-
-describe("hasTemplateVariables", () => {
-  it("returns false for undefined", () => {
-    expect(hasTemplateVariables(undefined)).toBe(false);
-  });
-
-  it("returns false for empty string", () => {
-    expect(hasTemplateVariables("")).toBe(false);
-  });
-
-  it("returns false for static prefix", () => {
-    expect(hasTemplateVariables("[Claude]")).toBe(false);
-  });
-
-  it("returns true when template variables present", () => {
-    expect(hasTemplateVariables("[{model}]")).toBe(true);
-    expect(hasTemplateVariables("{provider}")).toBe(true);
-    expect(hasTemplateVariables("prefix {thinkingLevel} suffix")).toBe(true);
-  });
-
-  it("returns true for multiple variables", () => {
-    expect(hasTemplateVariables("[{model} | {provider}]")).toBe(true);
-  });
-
-  it("handles consecutive calls correctly (regex lastIndex reset)", () => {
-    // First call
-    expect(hasTemplateVariables("[{model}]")).toBe(true);
-    // Second call should still work
-    expect(hasTemplateVariables("[{model}]")).toBe(true);
-    // Static string should return false
-    expect(hasTemplateVariables("[Claude]")).toBe(false);
-  });
-});
diff --git a/src/auto-reply/reply/session-resets.test.ts b/src/auto-reply/reply/session-resets.test.ts
deleted file mode 100644
index 9c105c0307b..00000000000
--- a/src/auto-reply/reply/session-resets.test.ts
+++ /dev/null
@@ -1,689 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { buildModelAliasIndex } from "../../agents/model-selection.js";
-import { saveSessionStore } from "../../config/sessions.js";
-import { formatZonedTimestamp } from "../../infra/format-time/format-datetime.ts";
-import { enqueueSystemEvent, resetSystemEventsForTest } from "../../infra/system-events.js";
-import { applyResetModelOverride } from "./session-reset-model.js";
-import { prependSystemEvents } from "./session-updates.js";
-import { initSessionState } from "./session.js";
-
-vi.mock("../../agents/model-catalog.js", () => ({
-  loadModelCatalog: vi.fn(async () => [
-    { provider: "minimax", id: "m2.1", name: "M2.1" },
-    { provider: "openai", id: "gpt-4o-mini", name: "GPT-4o mini" },
-  ]),
-}));
-
-let suiteRoot = "";
-let suiteCase = 0;
-
-beforeAll(async () => {
-  suiteRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-session-resets-suite-"));
-});
-
-afterAll(async () => {
-  await fs.rm(suiteRoot, { recursive: true, force: true });
-  suiteRoot = "";
-  suiteCase = 0;
-});
-
-async function createStorePath(prefix: string): Promise<string> {
-  const root = path.join(suiteRoot, `${prefix}${++suiteCase}`);
-  await fs.mkdir(root);
-  return path.join(root, "sessions.json");
-}
-
-describe("initSessionState reset triggers in WhatsApp groups", () => {
-  async function seedSessionStore(params: {
-    storePath: string;
-    sessionKey: string;
-    sessionId: string;
-  }): Promise<void> {
-    await saveSessionStore(params.storePath, {
-      [params.sessionKey]: {
-        sessionId: params.sessionId,
-        updatedAt: Date.now(),
-      },
-    });
-  }
-
-  function makeCfg(params: { storePath: string; allowFrom: string[] }): OpenClawConfig {
-    return {
-      session: { store: params.storePath, idleMinutes: 999 },
-      channels: {
-        whatsapp: {
-          allowFrom: params.allowFrom,
-          groupPolicy: "open",
-        },
-      },
-    } as OpenClawConfig;
-  }
-
-  it("Reset trigger /new works for authorized sender in WhatsApp group", async () => {
-    const storePath = await createStorePath("openclaw-group-reset-");
-    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = makeCfg({
-      storePath,
-      allowFrom: ["+41796666864"],
-    });
-
-    const groupMessageCtx = {
-      Body: `[Chat messages since your last reply - for context]\\n[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Someone: hello\\n\\n[Current message - respond to this]\\n[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Peschiño: /new\\n[from: Peschiño (+41796666864)]`,
-      RawBody: "/new",
-      CommandBody: "/new",
-      From: "120363406150318674@g.us",
-      To: "+41779241027",
-      ChatType: "group",
-      SessionKey: sessionKey,
-      Provider: "whatsapp",
-      Surface: "whatsapp",
-      SenderName: "Peschiño",
-      SenderE164: "+41796666864",
-      SenderId: "41796666864:0@s.whatsapp.net",
-    };
-
-    const result = await initSessionState({
-      ctx: groupMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.triggerBodyNormalized).toBe("/new");
-    expect(result.isNewSession).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.bodyStripped).toBe("");
-  });
-
-  it("Reset trigger /new blocked for unauthorized sender in existing session", async () => {
-    const storePath = await createStorePath("openclaw-group-reset-unauth-");
-    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
-    const existingSessionId = "existing-session-123";
-
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = makeCfg({
-      storePath,
-      allowFrom: ["+41796666864"],
-    });
-
-    const groupMessageCtx = {
-      Body: `[Context]\\n[WhatsApp ...] OtherPerson: /new\\n[from: OtherPerson (+1555123456)]`,
-      RawBody: "/new",
-      CommandBody: "/new",
-      From: "120363406150318674@g.us",
-      To: "+41779241027",
-      ChatType: "group",
-      SessionKey: sessionKey,
-      Provider: "whatsapp",
-      Surface: "whatsapp",
-      SenderName: "OtherPerson",
-      SenderE164: "+1555123456",
-      SenderId: "1555123456:0@s.whatsapp.net",
-    };
-
-    const result = await initSessionState({
-      ctx: groupMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.triggerBodyNormalized).toBe("/new");
-    expect(result.sessionId).toBe(existingSessionId);
-    expect(result.isNewSession).toBe(false);
-  });
-
-  it("Reset trigger works when RawBody is clean but Body has wrapped context", async () => {
-    const storePath = await createStorePath("openclaw-group-rawbody-");
-    const sessionKey = "agent:main:whatsapp:group:g1";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = makeCfg({
-      storePath,
-      allowFrom: ["*"],
-    });
-
-    const groupMessageCtx = {
-      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Jake: /new\n[from: Jake (+1222)]`,
-      RawBody: "/new",
-      CommandBody: "/new",
-      From: "120363406150318674@g.us",
-      To: "+1111",
-      ChatType: "group",
-      SessionKey: sessionKey,
-      Provider: "whatsapp",
-      SenderE164: "+1222",
-    };
-
-    const result = await initSessionState({
-      ctx: groupMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.triggerBodyNormalized).toBe("/new");
-    expect(result.isNewSession).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.bodyStripped).toBe("");
-  });
-
-  it("Reset trigger /new works when SenderId is LID but SenderE164 is authorized", async () => {
-    const storePath = await createStorePath("openclaw-group-reset-lid-");
-    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = makeCfg({
-      storePath,
-      allowFrom: ["+41796666864"],
-    });
-
-    const groupMessageCtx = {
-      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Owner: /new\n[from: Owner (+41796666864)]`,
-      RawBody: "/new",
-      CommandBody: "/new",
-      From: "120363406150318674@g.us",
-      To: "+41779241027",
-      ChatType: "group",
-      SessionKey: sessionKey,
-      Provider: "whatsapp",
-      Surface: "whatsapp",
-      SenderName: "Owner",
-      SenderE164: "+41796666864",
-      SenderId: "123@lid",
-    };
-
-    const result = await initSessionState({
-      ctx: groupMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.triggerBodyNormalized).toBe("/new");
-    expect(result.isNewSession).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.bodyStripped).toBe("");
-  });
-
-  it("Reset trigger /new blocked when SenderId is LID but SenderE164 is unauthorized", async () => {
-    const storePath = await createStorePath("openclaw-group-reset-lid-unauth-");
-    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = makeCfg({
-      storePath,
-      allowFrom: ["+41796666864"],
-    });
-
-    const groupMessageCtx = {
-      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Other: /new\n[from: Other (+1555123456)]`,
-      RawBody: "/new",
-      CommandBody: "/new",
-      From: "120363406150318674@g.us",
-      To: "+41779241027",
-      ChatType: "group",
-      SessionKey: sessionKey,
-      Provider: "whatsapp",
-      Surface: "whatsapp",
-      SenderName: "Other",
-      SenderE164: "+1555123456",
-      SenderId: "123@lid",
-    };
-
-    const result = await initSessionState({
-      ctx: groupMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.triggerBodyNormalized).toBe("/new");
-    expect(result.sessionId).toBe(existingSessionId);
-    expect(result.isNewSession).toBe(false);
-  });
-});
-
-describe("initSessionState reset triggers in Slack channels", () => {
-  async function seedSessionStore(params: {
-    storePath: string;
-    sessionKey: string;
-    sessionId: string;
-  }): Promise<void> {
-    const { saveSessionStore } = await import("../../config/sessions.js");
-    await saveSessionStore(params.storePath, {
-      [params.sessionKey]: {
-        sessionId: params.sessionId,
-        updatedAt: Date.now(),
-      },
-    });
-  }
-
-  it("Reset trigger /reset works when Slack message has a leading <@...> mention token", async () => {
-    const storePath = await createStorePath("openclaw-slack-channel-reset-");
-    const sessionKey = "agent:main:slack:channel:c1";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const channelMessageCtx = {
-      Body: "<@U123> /reset",
-      RawBody: "<@U123> /reset",
-      CommandBody: "<@U123> /reset",
-      From: "slack:channel:C1",
-      To: "channel:C1",
-      ChatType: "channel",
-      SessionKey: sessionKey,
-      Provider: "slack",
-      Surface: "slack",
-      SenderId: "U123",
-      SenderName: "Owner",
-    };
-
-    const result = await initSessionState({
-      ctx: channelMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.bodyStripped).toBe("");
-  });
-
-  it("Reset trigger /new preserves args when Slack message has a leading <@...> mention token", async () => {
-    const storePath = await createStorePath("openclaw-slack-channel-new-");
-    const sessionKey = "agent:main:slack:channel:c2";
-    const existingSessionId = "existing-session-123";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-    });
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const channelMessageCtx = {
-      Body: "<@U123> /new take notes",
-      RawBody: "<@U123> /new take notes",
-      CommandBody: "<@U123> /new take notes",
-      From: "slack:channel:C2",
-      To: "channel:C2",
-      ChatType: "channel",
-      SessionKey: sessionKey,
-      Provider: "slack",
-      Surface: "slack",
-      SenderId: "U123",
-      SenderName: "Owner",
-    };
-
-    const result = await initSessionState({
-      ctx: channelMessageCtx,
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.bodyStripped).toBe("take notes");
-  });
-});
-
-describe("applyResetModelOverride", () => {
-  it("selects a model hint and strips it from the body", async () => {
-    const cfg = {} as OpenClawConfig;
-    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
-    const sessionEntry = {
-      sessionId: "s1",
-      updatedAt: Date.now(),
-    };
-    const sessionStore = { "agent:main:dm:1": sessionEntry };
-    const sessionCtx = { BodyStripped: "minimax summarize" };
-    const ctx = { ChatType: "direct" };
-
-    await applyResetModelOverride({
-      cfg,
-      resetTriggered: true,
-      bodyStripped: "minimax summarize",
-      sessionCtx,
-      ctx,
-      sessionEntry,
-      sessionStore,
-      sessionKey: "agent:main:dm:1",
-      defaultProvider: "openai",
-      defaultModel: "gpt-4o-mini",
-      aliasIndex,
-    });
-
-    expect(sessionEntry.providerOverride).toBe("minimax");
-    expect(sessionEntry.modelOverride).toBe("m2.1");
-    expect(sessionCtx.BodyStripped).toBe("summarize");
-  });
-
-  it("clears auth profile overrides when reset applies a model", async () => {
-    const cfg = {} as OpenClawConfig;
-    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
-    const sessionEntry = {
-      sessionId: "s1",
-      updatedAt: Date.now(),
-      authProfileOverride: "anthropic:default",
-      authProfileOverrideSource: "user",
-      authProfileOverrideCompactionCount: 2,
-    };
-    const sessionStore = { "agent:main:dm:1": sessionEntry };
-    const sessionCtx = { BodyStripped: "minimax summarize" };
-    const ctx = { ChatType: "direct" };
-
-    await applyResetModelOverride({
-      cfg,
-      resetTriggered: true,
-      bodyStripped: "minimax summarize",
-      sessionCtx,
-      ctx,
-      sessionEntry,
-      sessionStore,
-      sessionKey: "agent:main:dm:1",
-      defaultProvider: "openai",
-      defaultModel: "gpt-4o-mini",
-      aliasIndex,
-    });
-
-    expect(sessionEntry.authProfileOverride).toBeUndefined();
-    expect(sessionEntry.authProfileOverrideSource).toBeUndefined();
-    expect(sessionEntry.authProfileOverrideCompactionCount).toBeUndefined();
-  });
-
-  it("skips when resetTriggered is false", async () => {
-    const cfg = {} as OpenClawConfig;
-    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
-    const sessionEntry = {
-      sessionId: "s1",
-      updatedAt: Date.now(),
-    };
-    const sessionStore = { "agent:main:dm:1": sessionEntry };
-    const sessionCtx = { BodyStripped: "minimax summarize" };
-    const ctx = { ChatType: "direct" };
-
-    await applyResetModelOverride({
-      cfg,
-      resetTriggered: false,
-      bodyStripped: "minimax summarize",
-      sessionCtx,
-      ctx,
-      sessionEntry,
-      sessionStore,
-      sessionKey: "agent:main:dm:1",
-      defaultProvider: "openai",
-      defaultModel: "gpt-4o-mini",
-      aliasIndex,
-    });
-
-    expect(sessionEntry.providerOverride).toBeUndefined();
-    expect(sessionEntry.modelOverride).toBeUndefined();
-    expect(sessionCtx.BodyStripped).toBe("minimax summarize");
-  });
-});
-
-describe("initSessionState preserves behavior overrides across /new and /reset", () => {
-  async function seedSessionStoreWithOverrides(params: {
-    storePath: string;
-    sessionKey: string;
-    sessionId: string;
-    overrides: Record<string, unknown>;
-  }): Promise<void> {
-    const { saveSessionStore } = await import("../../config/sessions.js");
-    await saveSessionStore(params.storePath, {
-      [params.sessionKey]: {
-        sessionId: params.sessionId,
-        updatedAt: Date.now(),
-        ...params.overrides,
-      },
-    });
-  }
-
-  it("/new preserves verboseLevel from previous session", async () => {
-    const storePath = await createStorePath("openclaw-reset-verbose-");
-    const sessionKey = "agent:main:telegram:dm:user1";
-    const existingSessionId = "existing-session-verbose";
-    await seedSessionStoreWithOverrides({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-      overrides: { verboseLevel: "on" },
-    });
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const result = await initSessionState({
-      ctx: {
-        Body: "/new",
-        RawBody: "/new",
-        CommandBody: "/new",
-        From: "user1",
-        To: "bot",
-        ChatType: "direct",
-        SessionKey: sessionKey,
-        Provider: "telegram",
-        Surface: "telegram",
-      },
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(true);
-    expect(result.sessionId).not.toBe(existingSessionId);
-    expect(result.sessionEntry.verboseLevel).toBe("on");
-  });
-
-  it("/reset preserves thinkingLevel and reasoningLevel from previous session", async () => {
-    const storePath = await createStorePath("openclaw-reset-thinking-");
-    const sessionKey = "agent:main:telegram:dm:user2";
-    const existingSessionId = "existing-session-thinking";
-    await seedSessionStoreWithOverrides({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-      overrides: { thinkingLevel: "full", reasoningLevel: "high" },
-    });
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const result = await initSessionState({
-      ctx: {
-        Body: "/reset",
-        RawBody: "/reset",
-        CommandBody: "/reset",
-        From: "user2",
-        To: "bot",
-        ChatType: "direct",
-        SessionKey: sessionKey,
-        Provider: "telegram",
-        Surface: "telegram",
-      },
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(true);
-    expect(result.sessionEntry.thinkingLevel).toBe("full");
-    expect(result.sessionEntry.reasoningLevel).toBe("high");
-  });
-
-  it("/new preserves ttsAuto from previous session", async () => {
-    const storePath = await createStorePath("openclaw-reset-tts-");
-    const sessionKey = "agent:main:telegram:dm:user3";
-    const existingSessionId = "existing-session-tts";
-    await seedSessionStoreWithOverrides({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-      overrides: { ttsAuto: "on" },
-    });
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const result = await initSessionState({
-      ctx: {
-        Body: "/new",
-        RawBody: "/new",
-        CommandBody: "/new",
-        From: "user3",
-        To: "bot",
-        ChatType: "direct",
-        SessionKey: sessionKey,
-        Provider: "telegram",
-        Surface: "telegram",
-      },
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.sessionEntry.ttsAuto).toBe("on");
-  });
-
-  it("archives previous transcript file on /new reset", async () => {
-    const storePath = await createStorePath("openclaw-reset-archive-");
-    const sessionKey = "agent:main:telegram:dm:user-archive";
-    const existingSessionId = "existing-session-archive";
-    await seedSessionStoreWithOverrides({
-      storePath,
-      sessionKey,
-      sessionId: existingSessionId,
-      overrides: {},
-    });
-    const transcriptPath = path.join(path.dirname(storePath), `${existingSessionId}.jsonl`);
-    await fs.writeFile(
-      transcriptPath,
-      `${JSON.stringify({ message: { role: "user", content: "hello" } })}\n`,
-      "utf-8",
-    );
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 999 },
-    } as OpenClawConfig;
-
-    const result = await initSessionState({
-      ctx: {
-        Body: "/new",
-        RawBody: "/new",
-        CommandBody: "/new",
-        From: "user-archive",
-        To: "bot",
-        ChatType: "direct",
-        SessionKey: sessionKey,
-        Provider: "telegram",
-        Surface: "telegram",
-      },
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(true);
-    const files = await fs.readdir(path.dirname(storePath));
-    expect(files.some((f) => f.startsWith(`${existingSessionId}.jsonl.reset.`))).toBe(true);
-  });
-
-  it("idle-based new session does NOT preserve overrides (no entry to read)", async () => {
-    const storePath = await createStorePath("openclaw-idle-no-preserve-");
-    const sessionKey = "agent:main:telegram:dm:new-user";
-
-    const cfg = {
-      session: { store: storePath, idleMinutes: 0 },
-    } as OpenClawConfig;
-
-    const result = await initSessionState({
-      ctx: {
-        Body: "hello",
-        RawBody: "hello",
-        CommandBody: "hello",
-        From: "new-user",
-        To: "bot",
-        ChatType: "direct",
-        SessionKey: sessionKey,
-        Provider: "telegram",
-        Surface: "telegram",
-      },
-      cfg,
-      commandAuthorized: true,
-    });
-
-    expect(result.isNewSession).toBe(true);
-    expect(result.resetTriggered).toBe(false);
-    expect(result.sessionEntry.verboseLevel).toBeUndefined();
-    expect(result.sessionEntry.thinkingLevel).toBeUndefined();
-  });
-});
-
-describe("prependSystemEvents", () => {
-  it("adds a local timestamp to queued system events by default", async () => {
-    vi.useFakeTimers();
-    try {
-      const timestamp = new Date("2026-01-12T20:19:17Z");
-      const expectedTimestamp = formatZonedTimestamp(timestamp, { displaySeconds: true });
-      vi.setSystemTime(timestamp);
-
-      enqueueSystemEvent("Model switched.", { sessionKey: "agent:main:main" });
-
-      const result = await prependSystemEvents({
-        cfg: {} as OpenClawConfig,
-        sessionKey: "agent:main:main",
-        isMainSession: false,
-        isNewSession: false,
-        prefixedBodyBase: "User: hi",
-      });
-
-      expect(expectedTimestamp).toBeDefined();
-      expect(result).toContain(`System: [${expectedTimestamp}] Model switched.`);
-    } finally {
-      resetSystemEventsForTest();
-      vi.useRealTimers();
-    }
-  });
-});
diff --git a/src/auto-reply/reply/session-updates.incrementcompactioncount.test.ts b/src/auto-reply/reply/session-updates.incrementcompactioncount.test.ts
deleted file mode 100644
index 5a90b4ed5f8..00000000000
--- a/src/auto-reply/reply/session-updates.incrementcompactioncount.test.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import type { SessionEntry } from "../../config/sessions.js";
-import { incrementCompactionCount } from "./session-updates.js";
-
-async function seedSessionStore(params: {
-  storePath: string;
-  sessionKey: string;
-  entry: Record<string, unknown>;
-}) {
-  await fs.mkdir(path.dirname(params.storePath), { recursive: true });
-  await fs.writeFile(
-    params.storePath,
-    JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
-    "utf-8",
-  );
-}
-
-describe("incrementCompactionCount", () => {
-  it("increments compaction count", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    const entry = { sessionId: "s1", updatedAt: Date.now(), compactionCount: 2 } as SessionEntry;
-    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
-    await seedSessionStore({ storePath, sessionKey, entry });
-
-    const count = await incrementCompactionCount({
-      sessionEntry: entry,
-      sessionStore,
-      sessionKey,
-      storePath,
-    });
-    expect(count).toBe(3);
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].compactionCount).toBe(3);
-  });
-
-  it("updates totalTokens when tokensAfter is provided", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    const entry = {
-      sessionId: "s1",
-      updatedAt: Date.now(),
-      compactionCount: 0,
-      totalTokens: 180_000,
-      inputTokens: 170_000,
-      outputTokens: 10_000,
-    } as SessionEntry;
-    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
-    await seedSessionStore({ storePath, sessionKey, entry });
-
-    await incrementCompactionCount({
-      sessionEntry: entry,
-      sessionStore,
-      sessionKey,
-      storePath,
-      tokensAfter: 12_000,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].compactionCount).toBe(1);
-    expect(stored[sessionKey].totalTokens).toBe(12_000);
-    // input/output cleared since we only have the total estimate
-    expect(stored[sessionKey].inputTokens).toBeUndefined();
-    expect(stored[sessionKey].outputTokens).toBeUndefined();
-  });
-
-  it("does not update totalTokens when tokensAfter is not provided", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-compact-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    const entry = {
-      sessionId: "s1",
-      updatedAt: Date.now(),
-      compactionCount: 0,
-      totalTokens: 180_000,
-    } as SessionEntry;
-    const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
-    await seedSessionStore({ storePath, sessionKey, entry });
-
-    await incrementCompactionCount({
-      sessionEntry: entry,
-      sessionStore,
-      sessionKey,
-      storePath,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].compactionCount).toBe(1);
-    // totalTokens unchanged
-    expect(stored[sessionKey].totalTokens).toBe(180_000);
-  });
-});
diff --git a/src/auto-reply/reply/session-usage.test.ts b/src/auto-reply/reply/session-usage.test.ts
deleted file mode 100644
index ab44c53ed29..00000000000
--- a/src/auto-reply/reply/session-usage.test.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { persistSessionUsageUpdate } from "./session-usage.js";
-
-async function seedSessionStore(params: {
-  storePath: string;
-  sessionKey: string;
-  entry: Record<string, unknown>;
-}) {
-  await fs.mkdir(path.dirname(params.storePath), { recursive: true });
-  await fs.writeFile(
-    params.storePath,
-    JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
-    "utf-8",
-  );
-}
-
-describe("persistSessionUsageUpdate", () => {
-  it("uses lastCallUsage for totalTokens when provided", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-usage-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      entry: { sessionId: "s1", updatedAt: Date.now(), totalTokens: 100_000 },
-    });
-
-    // Accumulated usage (sums all API calls) — inflated
-    const accumulatedUsage = { input: 180_000, output: 10_000, total: 190_000 };
-    // Last individual API call's usage — actual context after compaction
-    const lastCallUsage = { input: 12_000, output: 2_000, total: 14_000 };
-
-    await persistSessionUsageUpdate({
-      storePath,
-      sessionKey,
-      usage: accumulatedUsage,
-      lastCallUsage,
-      contextTokensUsed: 200_000,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    // totalTokens should reflect lastCallUsage (12_000 input), not accumulated (180_000)
-    expect(stored[sessionKey].totalTokens).toBe(12_000);
-    expect(stored[sessionKey].totalTokensFresh).toBe(true);
-    // inputTokens/outputTokens still reflect accumulated usage for cost tracking
-    expect(stored[sessionKey].inputTokens).toBe(180_000);
-    expect(stored[sessionKey].outputTokens).toBe(10_000);
-  });
-
-  it("marks totalTokens as unknown when no fresh context snapshot is available", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-usage-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      entry: { sessionId: "s1", updatedAt: Date.now() },
-    });
-
-    await persistSessionUsageUpdate({
-      storePath,
-      sessionKey,
-      usage: { input: 50_000, output: 5_000, total: 55_000 },
-      contextTokensUsed: 200_000,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].totalTokens).toBeUndefined();
-    expect(stored[sessionKey].totalTokensFresh).toBe(false);
-  });
-
-  it("uses promptTokens when available without lastCallUsage", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-usage-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      entry: { sessionId: "s1", updatedAt: Date.now() },
-    });
-
-    await persistSessionUsageUpdate({
-      storePath,
-      sessionKey,
-      usage: { input: 50_000, output: 5_000, total: 55_000 },
-      promptTokens: 42_000,
-      contextTokensUsed: 200_000,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].totalTokens).toBe(42_000);
-    expect(stored[sessionKey].totalTokensFresh).toBe(true);
-  });
-
-  it("keeps non-clamped lastCallUsage totalTokens when exceeding context window", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-usage-"));
-    const storePath = path.join(tmp, "sessions.json");
-    const sessionKey = "main";
-    await seedSessionStore({
-      storePath,
-      sessionKey,
-      entry: { sessionId: "s1", updatedAt: Date.now() },
-    });
-
-    await persistSessionUsageUpdate({
-      storePath,
-      sessionKey,
-      usage: { input: 300_000, output: 10_000, total: 310_000 },
-      lastCallUsage: { input: 250_000, output: 5_000, total: 255_000 },
-      contextTokensUsed: 200_000,
-    });
-
-    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
-    expect(stored[sessionKey].totalTokens).toBe(250_000);
-    expect(stored[sessionKey].totalTokensFresh).toBe(true);
-  });
-});
diff --git a/src/auto-reply/reply/session.test.ts b/src/auto-reply/reply/session.test.ts
index b1215603737..5eb8bedc65b 100644
--- a/src/auto-reply/reply/session.test.ts
+++ b/src/auto-reply/reply/session.test.ts
@@ -3,9 +3,27 @@ import os from "node:os";
 import path from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../../config/config.js";
+import { buildModelAliasIndex } from "../../agents/model-selection.js";
 import { saveSessionStore } from "../../config/sessions.js";
+import { formatZonedTimestamp } from "../../infra/format-time/format-datetime.ts";
+import { enqueueSystemEvent, resetSystemEventsForTest } from "../../infra/system-events.js";
+import { applyResetModelOverride } from "./session-reset-model.js";
+import { prependSystemEvents } from "./session-updates.js";
+import { persistSessionUsageUpdate } from "./session-usage.js";
 import { initSessionState } from "./session.js";
 
+// Perf: session-store locks are exercised elsewhere; most session tests don't need FS lock files.
+vi.mock("../../agents/session-write-lock.js", () => ({
+  acquireSessionWriteLock: async () => ({ release: async () => {} }),
+}));
+
+vi.mock("../../agents/model-catalog.js", () => ({
+  loadModelCatalog: vi.fn(async () => [
+    { provider: "minimax", id: "m2.1", name: "M2.1" },
+    { provider: "openai", id: "gpt-4o-mini", name: "GPT-4o mini" },
+  ]),
+}));
+
 let suiteRoot = "";
 let suiteCase = 0;
 
@@ -25,8 +43,16 @@ async function makeCaseDir(prefix: string): Promise<string> {
   return dir;
 }
 
+async function makeStorePath(prefix: string): Promise<string> {
+  const root = await makeCaseDir(prefix);
+  return path.join(root, "sessions.json");
+}
+
+const createStorePath = makeStorePath;
+
 describe("initSessionState thread forking", () => {
   it("forks a new session from the parent session file", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     const root = await makeCaseDir("openclaw-thread-session-");
     const sessionsDir = path.join(root, "sessions");
     await fs.mkdir(sessionsDir);
@@ -96,6 +122,7 @@ describe("initSessionState thread forking", () => {
       parentSession?: string;
     };
     expect(parsedHeader.parentSession).toBe(parentSessionFile);
+    warn.mockRestore();
   });
 
   it("records topic-specific session files when MessageThreadId is present", async () => {
@@ -506,3 +533,762 @@ describe("initSessionState channel reset overrides", () => {
     expect(result.sessionEntry.sessionId).toBe(sessionId);
   });
 });
+
+describe("initSessionState reset triggers in WhatsApp groups", () => {
+  async function seedSessionStore(params: {
+    storePath: string;
+    sessionKey: string;
+    sessionId: string;
+  }): Promise<void> {
+    await saveSessionStore(params.storePath, {
+      [params.sessionKey]: {
+        sessionId: params.sessionId,
+        updatedAt: Date.now(),
+      },
+    });
+  }
+
+  function makeCfg(params: { storePath: string; allowFrom: string[] }): OpenClawConfig {
+    return {
+      session: { store: params.storePath, idleMinutes: 999 },
+      channels: {
+        whatsapp: {
+          allowFrom: params.allowFrom,
+          groupPolicy: "open",
+        },
+      },
+    } as OpenClawConfig;
+  }
+
+  it("Reset trigger /new works for authorized sender in WhatsApp group", async () => {
+    const storePath = await createStorePath("openclaw-group-reset-");
+    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = makeCfg({
+      storePath,
+      allowFrom: ["+41796666864"],
+    });
+
+    const groupMessageCtx = {
+      Body: `[Chat messages since your last reply - for context]\\n[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Someone: hello\\n\\n[Current message - respond to this]\\n[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Peschiño: /new\\n[from: Peschiño (+41796666864)]`,
+      RawBody: "/new",
+      CommandBody: "/new",
+      From: "120363406150318674@g.us",
+      To: "+41779241027",
+      ChatType: "group",
+      SessionKey: sessionKey,
+      Provider: "whatsapp",
+      Surface: "whatsapp",
+      SenderName: "Peschiño",
+      SenderE164: "+41796666864",
+      SenderId: "41796666864:0@s.whatsapp.net",
+    };
+
+    const result = await initSessionState({
+      ctx: groupMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.triggerBodyNormalized).toBe("/new");
+    expect(result.isNewSession).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.bodyStripped).toBe("");
+  });
+
+  it("Reset trigger /new blocked for unauthorized sender in existing session", async () => {
+    const storePath = await createStorePath("openclaw-group-reset-unauth-");
+    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
+    const existingSessionId = "existing-session-123";
+
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = makeCfg({
+      storePath,
+      allowFrom: ["+41796666864"],
+    });
+
+    const groupMessageCtx = {
+      Body: `[Context]\\n[WhatsApp ...] OtherPerson: /new\\n[from: OtherPerson (+1555123456)]`,
+      RawBody: "/new",
+      CommandBody: "/new",
+      From: "120363406150318674@g.us",
+      To: "+41779241027",
+      ChatType: "group",
+      SessionKey: sessionKey,
+      Provider: "whatsapp",
+      Surface: "whatsapp",
+      SenderName: "OtherPerson",
+      SenderE164: "+1555123456",
+      SenderId: "1555123456:0@s.whatsapp.net",
+    };
+
+    const result = await initSessionState({
+      ctx: groupMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.triggerBodyNormalized).toBe("/new");
+    expect(result.sessionId).toBe(existingSessionId);
+    expect(result.isNewSession).toBe(false);
+  });
+
+  it("Reset trigger works when RawBody is clean but Body has wrapped context", async () => {
+    const storePath = await createStorePath("openclaw-group-rawbody-");
+    const sessionKey = "agent:main:whatsapp:group:g1";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = makeCfg({
+      storePath,
+      allowFrom: ["*"],
+    });
+
+    const groupMessageCtx = {
+      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Jake: /new\n[from: Jake (+1222)]`,
+      RawBody: "/new",
+      CommandBody: "/new",
+      From: "120363406150318674@g.us",
+      To: "+1111",
+      ChatType: "group",
+      SessionKey: sessionKey,
+      Provider: "whatsapp",
+      SenderE164: "+1222",
+    };
+
+    const result = await initSessionState({
+      ctx: groupMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.triggerBodyNormalized).toBe("/new");
+    expect(result.isNewSession).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.bodyStripped).toBe("");
+  });
+
+  it("Reset trigger /new works when SenderId is LID but SenderE164 is authorized", async () => {
+    const storePath = await createStorePath("openclaw-group-reset-lid-");
+    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = makeCfg({
+      storePath,
+      allowFrom: ["+41796666864"],
+    });
+
+    const groupMessageCtx = {
+      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Owner: /new\n[from: Owner (+41796666864)]`,
+      RawBody: "/new",
+      CommandBody: "/new",
+      From: "120363406150318674@g.us",
+      To: "+41779241027",
+      ChatType: "group",
+      SessionKey: sessionKey,
+      Provider: "whatsapp",
+      Surface: "whatsapp",
+      SenderName: "Owner",
+      SenderE164: "+41796666864",
+      SenderId: "123@lid",
+    };
+
+    const result = await initSessionState({
+      ctx: groupMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.triggerBodyNormalized).toBe("/new");
+    expect(result.isNewSession).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.bodyStripped).toBe("");
+  });
+
+  it("Reset trigger /new blocked when SenderId is LID but SenderE164 is unauthorized", async () => {
+    const storePath = await createStorePath("openclaw-group-reset-lid-unauth-");
+    const sessionKey = "agent:main:whatsapp:group:120363406150318674@g.us";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = makeCfg({
+      storePath,
+      allowFrom: ["+41796666864"],
+    });
+
+    const groupMessageCtx = {
+      Body: `[WhatsApp 120363406150318674@g.us 2026-01-13T07:45Z] Other: /new\n[from: Other (+1555123456)]`,
+      RawBody: "/new",
+      CommandBody: "/new",
+      From: "120363406150318674@g.us",
+      To: "+41779241027",
+      ChatType: "group",
+      SessionKey: sessionKey,
+      Provider: "whatsapp",
+      Surface: "whatsapp",
+      SenderName: "Other",
+      SenderE164: "+1555123456",
+      SenderId: "123@lid",
+    };
+
+    const result = await initSessionState({
+      ctx: groupMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.triggerBodyNormalized).toBe("/new");
+    expect(result.sessionId).toBe(existingSessionId);
+    expect(result.isNewSession).toBe(false);
+  });
+});
+
+describe("initSessionState reset triggers in Slack channels", () => {
+  async function seedSessionStore(params: {
+    storePath: string;
+    sessionKey: string;
+    sessionId: string;
+  }): Promise<void> {
+    await saveSessionStore(params.storePath, {
+      [params.sessionKey]: {
+        sessionId: params.sessionId,
+        updatedAt: Date.now(),
+      },
+    });
+  }
+
+  it("Reset trigger /reset works when Slack message has a leading <@...> mention token", async () => {
+    const storePath = await createStorePath("openclaw-slack-channel-reset-");
+    const sessionKey = "agent:main:slack:channel:c1";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const channelMessageCtx = {
+      Body: "<@U123> /reset",
+      RawBody: "<@U123> /reset",
+      CommandBody: "<@U123> /reset",
+      From: "slack:channel:C1",
+      To: "channel:C1",
+      ChatType: "channel",
+      SessionKey: sessionKey,
+      Provider: "slack",
+      Surface: "slack",
+      SenderId: "U123",
+      SenderName: "Owner",
+    };
+
+    const result = await initSessionState({
+      ctx: channelMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.bodyStripped).toBe("");
+  });
+
+  it("Reset trigger /new preserves args when Slack message has a leading <@...> mention token", async () => {
+    const storePath = await createStorePath("openclaw-slack-channel-new-");
+    const sessionKey = "agent:main:slack:channel:c2";
+    const existingSessionId = "existing-session-123";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+    });
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const channelMessageCtx = {
+      Body: "<@U123> /new take notes",
+      RawBody: "<@U123> /new take notes",
+      CommandBody: "<@U123> /new take notes",
+      From: "slack:channel:C2",
+      To: "channel:C2",
+      ChatType: "channel",
+      SessionKey: sessionKey,
+      Provider: "slack",
+      Surface: "slack",
+      SenderId: "U123",
+      SenderName: "Owner",
+    };
+
+    const result = await initSessionState({
+      ctx: channelMessageCtx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.bodyStripped).toBe("take notes");
+  });
+});
+
+describe("applyResetModelOverride", () => {
+  it("selects a model hint and strips it from the body", async () => {
+    const cfg = {} as OpenClawConfig;
+    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
+    const sessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+    const sessionCtx = { BodyStripped: "minimax summarize" };
+    const ctx = { ChatType: "direct" };
+
+    await applyResetModelOverride({
+      cfg,
+      resetTriggered: true,
+      bodyStripped: "minimax summarize",
+      sessionCtx,
+      ctx,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      defaultProvider: "openai",
+      defaultModel: "gpt-4o-mini",
+      aliasIndex,
+    });
+
+    expect(sessionEntry.providerOverride).toBe("minimax");
+    expect(sessionEntry.modelOverride).toBe("m2.1");
+    expect(sessionCtx.BodyStripped).toBe("summarize");
+  });
+
+  it("clears auth profile overrides when reset applies a model", async () => {
+    const cfg = {} as OpenClawConfig;
+    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
+    const sessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+      authProfileOverride: "anthropic:default",
+      authProfileOverrideSource: "user",
+      authProfileOverrideCompactionCount: 2,
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+    const sessionCtx = { BodyStripped: "minimax summarize" };
+    const ctx = { ChatType: "direct" };
+
+    await applyResetModelOverride({
+      cfg,
+      resetTriggered: true,
+      bodyStripped: "minimax summarize",
+      sessionCtx,
+      ctx,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      defaultProvider: "openai",
+      defaultModel: "gpt-4o-mini",
+      aliasIndex,
+    });
+
+    expect(sessionEntry.authProfileOverride).toBeUndefined();
+    expect(sessionEntry.authProfileOverrideSource).toBeUndefined();
+    expect(sessionEntry.authProfileOverrideCompactionCount).toBeUndefined();
+  });
+
+  it("skips when resetTriggered is false", async () => {
+    const cfg = {} as OpenClawConfig;
+    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
+    const sessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+    const sessionCtx = { BodyStripped: "minimax summarize" };
+    const ctx = { ChatType: "direct" };
+
+    await applyResetModelOverride({
+      cfg,
+      resetTriggered: false,
+      bodyStripped: "minimax summarize",
+      sessionCtx,
+      ctx,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      defaultProvider: "openai",
+      defaultModel: "gpt-4o-mini",
+      aliasIndex,
+    });
+
+    expect(sessionEntry.providerOverride).toBeUndefined();
+    expect(sessionEntry.modelOverride).toBeUndefined();
+    expect(sessionCtx.BodyStripped).toBe("minimax summarize");
+  });
+});
+
+describe("initSessionState preserves behavior overrides across /new and /reset", () => {
+  async function seedSessionStoreWithOverrides(params: {
+    storePath: string;
+    sessionKey: string;
+    sessionId: string;
+    overrides: Record<string, unknown>;
+  }): Promise<void> {
+    await saveSessionStore(params.storePath, {
+      [params.sessionKey]: {
+        sessionId: params.sessionId,
+        updatedAt: Date.now(),
+        ...params.overrides,
+      },
+    });
+  }
+
+  it("/new preserves verboseLevel from previous session", async () => {
+    const storePath = await createStorePath("openclaw-reset-verbose-");
+    const sessionKey = "agent:main:telegram:dm:user1";
+    const existingSessionId = "existing-session-verbose";
+    await seedSessionStoreWithOverrides({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+      overrides: { verboseLevel: "on" },
+    });
+    await fs.writeFile(
+      path.join(path.dirname(storePath), `${existingSessionId}.jsonl`),
+      "",
+      "utf-8",
+    );
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const result = await initSessionState({
+      ctx: {
+        Body: "/new",
+        RawBody: "/new",
+        CommandBody: "/new",
+        From: "user1",
+        To: "bot",
+        ChatType: "direct",
+        SessionKey: sessionKey,
+        Provider: "telegram",
+        Surface: "telegram",
+      },
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.sessionEntry.verboseLevel).toBe("on");
+  });
+
+  it("/reset preserves thinkingLevel and reasoningLevel from previous session", async () => {
+    const storePath = await createStorePath("openclaw-reset-thinking-");
+    const sessionKey = "agent:main:telegram:dm:user2";
+    const existingSessionId = "existing-session-thinking";
+    await seedSessionStoreWithOverrides({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+      overrides: { thinkingLevel: "high", reasoningLevel: "low" },
+    });
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const result = await initSessionState({
+      ctx: {
+        Body: "/reset",
+        RawBody: "/reset",
+        CommandBody: "/reset",
+        From: "user2",
+        To: "bot",
+        ChatType: "direct",
+        SessionKey: sessionKey,
+        Provider: "telegram",
+        Surface: "telegram",
+      },
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(result.sessionId).not.toBe(existingSessionId);
+    expect(result.sessionEntry.thinkingLevel).toBe("high");
+    expect(result.sessionEntry.reasoningLevel).toBe("low");
+  });
+
+  it("/new in a new session does not preserve overrides", async () => {
+    const storePath = await createStorePath("openclaw-new-no-preserve-");
+    const sessionKey = "agent:main:telegram:dm:user3";
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const result = await initSessionState({
+      ctx: {
+        Body: "/new",
+        RawBody: "/new",
+        CommandBody: "/new",
+        From: "user3",
+        To: "bot",
+        ChatType: "direct",
+        SessionKey: sessionKey,
+        Provider: "telegram",
+        Surface: "telegram",
+      },
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(result.sessionEntry.verboseLevel).toBeUndefined();
+    expect(result.sessionEntry.thinkingLevel).toBeUndefined();
+  });
+
+  it("archives the old session store entry on /new", async () => {
+    const storePath = await createStorePath("openclaw-archive-old-");
+    const sessionKey = "agent:main:telegram:dm:user-archive";
+    const existingSessionId = "existing-session-archive";
+    await seedSessionStoreWithOverrides({
+      storePath,
+      sessionKey,
+      sessionId: existingSessionId,
+      overrides: { verboseLevel: "on" },
+    });
+    const sessionUtils = await import("../../gateway/session-utils.fs.js");
+    const archiveSpy = vi.spyOn(sessionUtils, "archiveSessionTranscripts");
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 999 },
+    } as OpenClawConfig;
+
+    const result = await initSessionState({
+      ctx: {
+        Body: "/new",
+        RawBody: "/new",
+        CommandBody: "/new",
+        From: "user-archive",
+        To: "bot",
+        ChatType: "direct",
+        SessionKey: sessionKey,
+        Provider: "telegram",
+        Surface: "telegram",
+      },
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(true);
+    expect(archiveSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: existingSessionId,
+        storePath,
+        reason: "reset",
+      }),
+    );
+    archiveSpy.mockRestore();
+  });
+
+  it("idle-based new session does NOT preserve overrides (no entry to read)", async () => {
+    const storePath = await createStorePath("openclaw-idle-no-preserve-");
+    const sessionKey = "agent:main:telegram:dm:new-user";
+
+    const cfg = {
+      session: { store: storePath, idleMinutes: 0 },
+    } as OpenClawConfig;
+
+    const result = await initSessionState({
+      ctx: {
+        Body: "hello",
+        RawBody: "hello",
+        CommandBody: "hello",
+        From: "new-user",
+        To: "bot",
+        ChatType: "direct",
+        SessionKey: sessionKey,
+        Provider: "telegram",
+        Surface: "telegram",
+      },
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.resetTriggered).toBe(false);
+    expect(result.sessionEntry.verboseLevel).toBeUndefined();
+    expect(result.sessionEntry.thinkingLevel).toBeUndefined();
+  });
+});
+
+describe("prependSystemEvents", () => {
+  it("adds a local timestamp to queued system events by default", async () => {
+    vi.useFakeTimers();
+    try {
+      const timestamp = new Date("2026-01-12T20:19:17Z");
+      const expectedTimestamp = formatZonedTimestamp(timestamp, { displaySeconds: true });
+      vi.setSystemTime(timestamp);
+
+      enqueueSystemEvent("Model switched.", { sessionKey: "agent:main:main" });
+
+      const result = await prependSystemEvents({
+        cfg: {} as OpenClawConfig,
+        sessionKey: "agent:main:main",
+        isMainSession: false,
+        isNewSession: false,
+        prefixedBodyBase: "User: hi",
+      });
+
+      expect(expectedTimestamp).toBeDefined();
+      expect(result).toContain(`System: [${expectedTimestamp}] Model switched.`);
+    } finally {
+      resetSystemEventsForTest();
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("persistSessionUsageUpdate", () => {
+  async function seedSessionStore(params: {
+    storePath: string;
+    sessionKey: string;
+    entry: Record<string, unknown>;
+  }) {
+    await fs.mkdir(path.dirname(params.storePath), { recursive: true });
+    await fs.writeFile(
+      params.storePath,
+      JSON.stringify({ [params.sessionKey]: params.entry }, null, 2),
+      "utf-8",
+    );
+  }
+
+  it("uses lastCallUsage for totalTokens when provided", async () => {
+    const storePath = await createStorePath("openclaw-usage-");
+    const sessionKey = "main";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      entry: { sessionId: "s1", updatedAt: Date.now(), totalTokens: 100_000 },
+    });
+
+    const accumulatedUsage = { input: 180_000, output: 10_000, total: 190_000 };
+    const lastCallUsage = { input: 12_000, output: 2_000, total: 14_000 };
+
+    await persistSessionUsageUpdate({
+      storePath,
+      sessionKey,
+      usage: accumulatedUsage,
+      lastCallUsage,
+      contextTokensUsed: 200_000,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].totalTokens).toBe(12_000);
+    expect(stored[sessionKey].totalTokensFresh).toBe(true);
+    expect(stored[sessionKey].inputTokens).toBe(180_000);
+    expect(stored[sessionKey].outputTokens).toBe(10_000);
+  });
+
+  it("marks totalTokens as unknown when no fresh context snapshot is available", async () => {
+    const storePath = await createStorePath("openclaw-usage-");
+    const sessionKey = "main";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      entry: { sessionId: "s1", updatedAt: Date.now() },
+    });
+
+    await persistSessionUsageUpdate({
+      storePath,
+      sessionKey,
+      usage: { input: 50_000, output: 5_000, total: 55_000 },
+      contextTokensUsed: 200_000,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].totalTokens).toBeUndefined();
+    expect(stored[sessionKey].totalTokensFresh).toBe(false);
+  });
+
+  it("uses promptTokens when available without lastCallUsage", async () => {
+    const storePath = await createStorePath("openclaw-usage-");
+    const sessionKey = "main";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      entry: { sessionId: "s1", updatedAt: Date.now() },
+    });
+
+    await persistSessionUsageUpdate({
+      storePath,
+      sessionKey,
+      usage: { input: 50_000, output: 5_000, total: 55_000 },
+      promptTokens: 42_000,
+      contextTokensUsed: 200_000,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].totalTokens).toBe(42_000);
+    expect(stored[sessionKey].totalTokensFresh).toBe(true);
+  });
+
+  it("keeps non-clamped lastCallUsage totalTokens when exceeding context window", async () => {
+    const storePath = await createStorePath("openclaw-usage-");
+    const sessionKey = "main";
+    await seedSessionStore({
+      storePath,
+      sessionKey,
+      entry: { sessionId: "s1", updatedAt: Date.now() },
+    });
+
+    await persistSessionUsageUpdate({
+      storePath,
+      sessionKey,
+      usage: { input: 300_000, output: 10_000, total: 310_000 },
+      lastCallUsage: { input: 250_000, output: 5_000, total: 255_000 },
+      contextTokensUsed: 200_000,
+    });
+
+    const stored = JSON.parse(await fs.readFile(storePath, "utf-8"));
+    expect(stored[sessionKey].totalTokens).toBe(250_000);
+    expect(stored[sessionKey].totalTokensFresh).toBe(true);
+  });
+});
diff --git a/src/auto-reply/reply/subagents-utils.test.ts b/src/auto-reply/reply/subagents-utils.test.ts
deleted file mode 100644
index b66a70680da..00000000000
--- a/src/auto-reply/reply/subagents-utils.test.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { SubagentRunRecord } from "../../agents/subagent-registry.js";
-import { formatDurationCompact } from "../../infra/format-time/format-duration.js";
-import {
-  formatRunLabel,
-  formatRunStatus,
-  resolveSubagentLabel,
-  sortSubagentRuns,
-} from "./subagents-utils.js";
-
-const baseRun: SubagentRunRecord = {
-  runId: "run-1",
-  childSessionKey: "agent:main:subagent:abc",
-  requesterSessionKey: "agent:main:main",
-  requesterDisplayKey: "main",
-  task: "do thing",
-  cleanup: "keep",
-  createdAt: 1000,
-  startedAt: 1000,
-};
-
-describe("subagents utils", () => {
-  it("resolves labels from label, task, or fallback", () => {
-    expect(resolveSubagentLabel({ ...baseRun, label: "Label" })).toBe("Label");
-    expect(resolveSubagentLabel({ ...baseRun, label: " ", task: "Task" })).toBe("Task");
-    expect(resolveSubagentLabel({ ...baseRun, label: " ", task: " " }, "fallback")).toBe(
-      "fallback",
-    );
-  });
-
-  it("formats run labels with truncation", () => {
-    const long = "x".repeat(100);
-    const run = { ...baseRun, label: long };
-    const formatted = formatRunLabel(run, { maxLength: 10 });
-    expect(formatted.startsWith("x".repeat(10))).toBe(true);
-    expect(formatted.endsWith("…")).toBe(true);
-  });
-
-  it("sorts subagent runs by newest start/created time", () => {
-    const runs: SubagentRunRecord[] = [
-      { ...baseRun, runId: "run-1", createdAt: 1000, startedAt: 1000 },
-      { ...baseRun, runId: "run-2", createdAt: 1200, startedAt: 1200 },
-      { ...baseRun, runId: "run-3", createdAt: 900 },
-    ];
-    const sorted = sortSubagentRuns(runs);
-    expect(sorted.map((run) => run.runId)).toEqual(["run-2", "run-1", "run-3"]);
-  });
-
-  it("formats run status from outcome and timestamps", () => {
-    expect(formatRunStatus({ ...baseRun })).toBe("running");
-    expect(formatRunStatus({ ...baseRun, endedAt: 2000, outcome: { status: "ok" } })).toBe("done");
-    expect(formatRunStatus({ ...baseRun, endedAt: 2000, outcome: { status: "timeout" } })).toBe(
-      "timeout",
-    );
-  });
-
-  it("formats duration compact for seconds and minutes", () => {
-    expect(formatDurationCompact(45_000)).toBe("45s");
-    expect(formatDurationCompact(65_000)).toBe("1m5s");
-  });
-});
diff --git a/src/auto-reply/reply/typing.test.ts b/src/auto-reply/reply/typing.test.ts
deleted file mode 100644
index edefc57f8ee..00000000000
--- a/src/auto-reply/reply/typing.test.ts
+++ /dev/null
@@ -1,283 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { createMockTypingController } from "./test-helpers.js";
-import { createTypingSignaler, resolveTypingMode } from "./typing-mode.js";
-import { createTypingController } from "./typing.js";
-
-describe("typing controller", () => {
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("stops after run completion and dispatcher idle", async () => {
-    vi.useFakeTimers();
-    const onReplyStart = vi.fn(async () => {});
-    const typing = createTypingController({
-      onReplyStart,
-      typingIntervalSeconds: 1,
-      typingTtlMs: 30_000,
-    });
-
-    await typing.startTypingLoop();
-    expect(onReplyStart).toHaveBeenCalledTimes(1);
-
-    vi.advanceTimersByTime(2_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(3);
-
-    typing.markRunComplete();
-    vi.advanceTimersByTime(1_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(4);
-
-    typing.markDispatchIdle();
-    vi.advanceTimersByTime(2_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(4);
-  });
-
-  it("keeps typing until both idle and run completion are set", async () => {
-    vi.useFakeTimers();
-    const onReplyStart = vi.fn(async () => {});
-    const typing = createTypingController({
-      onReplyStart,
-      typingIntervalSeconds: 1,
-      typingTtlMs: 30_000,
-    });
-
-    await typing.startTypingLoop();
-    expect(onReplyStart).toHaveBeenCalledTimes(1);
-
-    typing.markDispatchIdle();
-    vi.advanceTimersByTime(2_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(3);
-
-    typing.markRunComplete();
-    vi.advanceTimersByTime(2_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(3);
-  });
-
-  it("does not start typing after run completion", async () => {
-    vi.useFakeTimers();
-    const onReplyStart = vi.fn(async () => {});
-    const typing = createTypingController({
-      onReplyStart,
-      typingIntervalSeconds: 1,
-      typingTtlMs: 30_000,
-    });
-
-    typing.markRunComplete();
-    await typing.startTypingOnText("late text");
-    vi.advanceTimersByTime(2_000);
-    expect(onReplyStart).not.toHaveBeenCalled();
-  });
-
-  it("does not restart typing after it has stopped", async () => {
-    vi.useFakeTimers();
-    const onReplyStart = vi.fn(async () => {});
-    const typing = createTypingController({
-      onReplyStart,
-      typingIntervalSeconds: 1,
-      typingTtlMs: 30_000,
-    });
-
-    await typing.startTypingLoop();
-    expect(onReplyStart).toHaveBeenCalledTimes(1);
-
-    typing.markRunComplete();
-    typing.markDispatchIdle();
-
-    vi.advanceTimersByTime(5_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(1);
-
-    // Late callbacks should be ignored and must not restart the interval.
-    await typing.startTypingOnText("late tool result");
-    vi.advanceTimersByTime(5_000);
-    expect(onReplyStart).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("resolveTypingMode", () => {
-  it("defaults to instant for direct chats", () => {
-    expect(
-      resolveTypingMode({
-        configured: undefined,
-        isGroupChat: false,
-        wasMentioned: false,
-        isHeartbeat: false,
-      }),
-    ).toBe("instant");
-  });
-
-  it("defaults to message for group chats without mentions", () => {
-    expect(
-      resolveTypingMode({
-        configured: undefined,
-        isGroupChat: true,
-        wasMentioned: false,
-        isHeartbeat: false,
-      }),
-    ).toBe("message");
-  });
-
-  it("defaults to instant for mentioned group chats", () => {
-    expect(
-      resolveTypingMode({
-        configured: undefined,
-        isGroupChat: true,
-        wasMentioned: true,
-        isHeartbeat: false,
-      }),
-    ).toBe("instant");
-  });
-
-  it("honors configured mode across contexts", () => {
-    expect(
-      resolveTypingMode({
-        configured: "thinking",
-        isGroupChat: false,
-        wasMentioned: false,
-        isHeartbeat: false,
-      }),
-    ).toBe("thinking");
-    expect(
-      resolveTypingMode({
-        configured: "message",
-        isGroupChat: true,
-        wasMentioned: true,
-        isHeartbeat: false,
-      }),
-    ).toBe("message");
-  });
-
-  it("forces never for heartbeat runs", () => {
-    expect(
-      resolveTypingMode({
-        configured: "instant",
-        isGroupChat: false,
-        wasMentioned: false,
-        isHeartbeat: true,
-      }),
-    ).toBe("never");
-  });
-});
-
-describe("createTypingSignaler", () => {
-  it("signals immediately for instant mode", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "instant",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalRunStart();
-
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-  });
-
-  it("signals on text for message mode", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "message",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalTextDelta("hello");
-
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("hello");
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("signals on message start for message mode", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "message",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalMessageStart();
-
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-    await signaler.signalTextDelta("hello");
-    expect(typing.startTypingOnText).toHaveBeenCalledWith("hello");
-  });
-
-  it("signals on reasoning for thinking mode", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "thinking",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalReasoningDelta();
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-    await signaler.signalTextDelta("hi");
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-  });
-
-  it("refreshes ttl on text for thinking mode", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "thinking",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalTextDelta("hi");
-
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-    expect(typing.refreshTypingTtl).toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-  });
-
-  it("starts typing on tool start before text", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "message",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalToolStart();
-
-    expect(typing.startTypingLoop).toHaveBeenCalled();
-    expect(typing.refreshTypingTtl).toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-  });
-
-  it("refreshes ttl on tool start when active after text", async () => {
-    const typing = createMockTypingController({
-      isActive: vi.fn(() => true),
-    });
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "message",
-      isHeartbeat: false,
-    });
-
-    await signaler.signalTextDelta("hello");
-    typing.startTypingLoop.mockClear();
-    typing.startTypingOnText.mockClear();
-    typing.refreshTypingTtl.mockClear();
-    await signaler.signalToolStart();
-
-    expect(typing.refreshTypingTtl).toHaveBeenCalled();
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-  });
-
-  it("suppresses typing when disabled", async () => {
-    const typing = createMockTypingController();
-    const signaler = createTypingSignaler({
-      typing,
-      mode: "instant",
-      isHeartbeat: true,
-    });
-
-    await signaler.signalRunStart();
-    await signaler.signalTextDelta("hi");
-    await signaler.signalReasoningDelta();
-
-    expect(typing.startTypingLoop).not.toHaveBeenCalled();
-    expect(typing.startTypingOnText).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/browser/browser-utils.test.ts b/src/browser/browser-utils.test.ts
new file mode 100644
index 00000000000..ab23bca95e7
--- /dev/null
+++ b/src/browser/browser-utils.test.ts
@@ -0,0 +1,217 @@
+import { describe, expect, it, vi } from "vitest";
+import type { BrowserServerState } from "./server-context.js";
+import { appendCdpPath, getHeadersWithAuth } from "./cdp.helpers.js";
+import { __test } from "./client-fetch.js";
+import { resolveBrowserConfig, resolveProfile } from "./config.js";
+import { shouldRejectBrowserMutation } from "./csrf.js";
+import { toBoolean } from "./routes/utils.js";
+import { listKnownProfileNames } from "./server-context.js";
+import { resolveTargetIdFromTabs } from "./target-id.js";
+
+describe("toBoolean", () => {
+  it("parses yes/no and 1/0", () => {
+    expect(toBoolean("yes")).toBe(true);
+    expect(toBoolean("1")).toBe(true);
+    expect(toBoolean("no")).toBe(false);
+    expect(toBoolean("0")).toBe(false);
+  });
+
+  it("returns undefined for on/off strings", () => {
+    expect(toBoolean("on")).toBeUndefined();
+    expect(toBoolean("off")).toBeUndefined();
+  });
+
+  it("passes through boolean values", () => {
+    expect(toBoolean(true)).toBe(true);
+    expect(toBoolean(false)).toBe(false);
+  });
+});
+
+describe("browser target id resolution", () => {
+  it("resolves exact ids", () => {
+    const res = resolveTargetIdFromTabs("FULL", [{ targetId: "AAA" }, { targetId: "FULL" }]);
+    expect(res).toEqual({ ok: true, targetId: "FULL" });
+  });
+
+  it("resolves unique prefixes (case-insensitive)", () => {
+    const res = resolveTargetIdFromTabs("57a01309", [
+      { targetId: "57A01309E14B5DEE0FB41F908515A2FC" },
+    ]);
+    expect(res).toEqual({
+      ok: true,
+      targetId: "57A01309E14B5DEE0FB41F908515A2FC",
+    });
+  });
+
+  it("fails on ambiguous prefixes", () => {
+    const res = resolveTargetIdFromTabs("57A0", [
+      { targetId: "57A01309E14B5DEE0FB41F908515A2FC" },
+      { targetId: "57A0BEEF000000000000000000000000" },
+    ]);
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.reason).toBe("ambiguous");
+      expect(res.matches?.length).toBe(2);
+    }
+  });
+
+  it("fails when no tab matches", () => {
+    const res = resolveTargetIdFromTabs("NOPE", [{ targetId: "AAA" }]);
+    expect(res).toEqual({ ok: false, reason: "not_found" });
+  });
+});
+
+describe("browser CSRF loopback mutation guard", () => {
+  it("rejects mutating methods from non-loopback origin", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        origin: "https://evil.example",
+      }),
+    ).toBe(true);
+  });
+
+  it("allows mutating methods from loopback origin", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        origin: "http://127.0.0.1:18789",
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        origin: "http://localhost:18789",
+      }),
+    ).toBe(false);
+  });
+
+  it("allows mutating methods without origin/referer (non-browser clients)", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects mutating methods with origin=null", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        origin: "null",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects mutating methods from non-loopback referer", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        referer: "https://evil.example/attack",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects cross-site mutations via Sec-Fetch-Site when present", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "POST",
+        secFetchSite: "cross-site",
+      }),
+    ).toBe(true);
+  });
+
+  it("does not reject non-mutating methods", () => {
+    expect(
+      shouldRejectBrowserMutation({
+        method: "GET",
+        origin: "https://evil.example",
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldRejectBrowserMutation({
+        method: "OPTIONS",
+        origin: "https://evil.example",
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("cdp.helpers", () => {
+  it("preserves query params when appending CDP paths", () => {
+    const url = appendCdpPath("https://example.com?token=abc", "/json/version");
+    expect(url).toBe("https://example.com/json/version?token=abc");
+  });
+
+  it("appends paths under a base prefix", () => {
+    const url = appendCdpPath("https://example.com/chrome/?token=abc", "json/list");
+    expect(url).toBe("https://example.com/chrome/json/list?token=abc");
+  });
+
+  it("adds basic auth headers when credentials are present", () => {
+    const headers = getHeadersWithAuth("https://user:pass@example.com");
+    expect(headers.Authorization).toBe(`Basic ${Buffer.from("user:pass").toString("base64")}`);
+  });
+
+  it("keeps preexisting authorization headers", () => {
+    const headers = getHeadersWithAuth("https://user:pass@example.com", {
+      Authorization: "Bearer token",
+    });
+    expect(headers.Authorization).toBe("Bearer token");
+  });
+});
+
+describe("fetchBrowserJson loopback auth (bridge auth registry)", () => {
+  it("falls back to per-port bridge auth when config auth is not available", async () => {
+    const port = 18765;
+    const getBridgeAuthForPort = vi.fn((candidate: number) =>
+      candidate === port ? { token: "registry-token" } : undefined,
+    );
+    const init = __test.withLoopbackBrowserAuth(`http://127.0.0.1:${port}/`, undefined, {
+      loadConfig: () => ({}),
+      resolveBrowserControlAuth: () => ({}),
+      getBridgeAuthForPort,
+    });
+    const headers = new Headers(init.headers ?? {});
+    expect(headers.get("authorization")).toBe("Bearer registry-token");
+    expect(getBridgeAuthForPort).toHaveBeenCalledWith(port);
+  });
+});
+
+describe("browser server-context listKnownProfileNames", () => {
+  it("includes configured and runtime-only profile names", () => {
+    const resolved = resolveBrowserConfig({
+      defaultProfile: "openclaw",
+      profiles: {
+        openclaw: { cdpPort: 18800, color: "#FF4500" },
+      },
+    });
+    const openclaw = resolveProfile(resolved, "openclaw");
+    if (!openclaw) {
+      throw new Error("expected openclaw profile");
+    }
+
+    const state: BrowserServerState = {
+      server: null as unknown as BrowserServerState["server"],
+      port: 18791,
+      resolved,
+      profiles: new Map([
+        [
+          "stale-removed",
+          {
+            profile: { ...openclaw, name: "stale-removed" },
+            running: null,
+          },
+        ],
+      ]),
+    };
+
+    expect(listKnownProfileNames(state).toSorted()).toEqual([
+      "chrome",
+      "openclaw",
+      "stale-removed",
+    ]);
+  });
+});
diff --git a/src/browser/cdp.helpers.test.ts b/src/browser/cdp.helpers.test.ts
deleted file mode 100644
index b41864ee431..00000000000
--- a/src/browser/cdp.helpers.test.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { appendCdpPath, getHeadersWithAuth } from "./cdp.helpers.js";
-
-describe("cdp.helpers", () => {
-  it("preserves query params when appending CDP paths", () => {
-    const url = appendCdpPath("https://example.com?token=abc", "/json/version");
-    expect(url).toBe("https://example.com/json/version?token=abc");
-  });
-
-  it("appends paths under a base prefix", () => {
-    const url = appendCdpPath("https://example.com/chrome/?token=abc", "json/list");
-    expect(url).toBe("https://example.com/chrome/json/list?token=abc");
-  });
-
-  it("adds basic auth headers when credentials are present", () => {
-    const headers = getHeadersWithAuth("https://user:pass@example.com");
-    expect(headers.Authorization).toBe(`Basic ${Buffer.from("user:pass").toString("base64")}`);
-  });
-
-  it("keeps preexisting authorization headers", () => {
-    const headers = getHeadersWithAuth("https://user:pass@example.com", {
-      Authorization: "Bearer token",
-    });
-    expect(headers.Authorization).toBe("Bearer token");
-  });
-});
diff --git a/src/browser/chrome.test.ts b/src/browser/chrome.test.ts
index 471218a1c7c..0551b27c287 100644
--- a/src/browser/chrome.test.ts
+++ b/src/browser/chrome.test.ts
@@ -2,7 +2,7 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import {
   decorateOpenClawProfile,
   ensureProfileCleanExit,
@@ -23,112 +23,111 @@ async function readJson(filePath: string): Promise<Record<string, unknown>> {
 }
 
 describe("browser chrome profile decoration", () => {
+  let fixtureRoot = "";
+  let fixtureCount = 0;
+
+  const createUserDataDir = async () => {
+    const dir = path.join(fixtureRoot, `profile-${fixtureCount++}`);
+    await fsp.mkdir(dir, { recursive: true });
+    return dir;
+  };
+
+  beforeAll(async () => {
+    fixtureRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-suite-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fsp.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
   afterEach(() => {
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
   });
 
   it("writes expected name + signed ARGB seed to Chrome prefs", async () => {
-    const userDataDir = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-test-"));
-    try {
-      decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
+    const userDataDir = await createUserDataDir();
+    decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
 
-      const expectedSignedArgb = ((0xff << 24) | 0xff4500) >> 0;
+    const expectedSignedArgb = ((0xff << 24) | 0xff4500) >> 0;
 
-      const localState = await readJson(path.join(userDataDir, "Local State"));
-      const profile = localState.profile as Record<string, unknown>;
-      const infoCache = profile.info_cache as Record<string, unknown>;
-      const def = infoCache.Default as Record<string, unknown>;
+    const localState = await readJson(path.join(userDataDir, "Local State"));
+    const profile = localState.profile as Record<string, unknown>;
+    const infoCache = profile.info_cache as Record<string, unknown>;
+    const def = infoCache.Default as Record<string, unknown>;
 
-      expect(def.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
-      expect(def.shortcut_name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
-      expect(def.profile_color_seed).toBe(expectedSignedArgb);
-      expect(def.profile_highlight_color).toBe(expectedSignedArgb);
-      expect(def.default_avatar_fill_color).toBe(expectedSignedArgb);
-      expect(def.default_avatar_stroke_color).toBe(expectedSignedArgb);
+    expect(def.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
+    expect(def.shortcut_name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
+    expect(def.profile_color_seed).toBe(expectedSignedArgb);
+    expect(def.profile_highlight_color).toBe(expectedSignedArgb);
+    expect(def.default_avatar_fill_color).toBe(expectedSignedArgb);
+    expect(def.default_avatar_stroke_color).toBe(expectedSignedArgb);
 
-      const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
-      const browser = prefs.browser as Record<string, unknown>;
-      const theme = browser.theme as Record<string, unknown>;
-      const autogenerated = prefs.autogenerated as Record<string, unknown>;
-      const autogeneratedTheme = autogenerated.theme as Record<string, unknown>;
+    const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
+    const browser = prefs.browser as Record<string, unknown>;
+    const theme = browser.theme as Record<string, unknown>;
+    const autogenerated = prefs.autogenerated as Record<string, unknown>;
+    const autogeneratedTheme = autogenerated.theme as Record<string, unknown>;
 
-      expect(theme.user_color2).toBe(expectedSignedArgb);
-      expect(autogeneratedTheme.color).toBe(expectedSignedArgb);
+    expect(theme.user_color2).toBe(expectedSignedArgb);
+    expect(autogeneratedTheme.color).toBe(expectedSignedArgb);
 
-      const marker = await fsp.readFile(
-        path.join(userDataDir, ".openclaw-profile-decorated"),
-        "utf-8",
-      );
-      expect(marker.trim()).toMatch(/^\d+$/);
-    } finally {
-      await fsp.rm(userDataDir, { recursive: true, force: true });
-    }
+    const marker = await fsp.readFile(
+      path.join(userDataDir, ".openclaw-profile-decorated"),
+      "utf-8",
+    );
+    expect(marker.trim()).toMatch(/^\d+$/);
   });
 
   it("best-effort writes name when color is invalid", async () => {
-    const userDataDir = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-test-"));
-    try {
-      decorateOpenClawProfile(userDataDir, { color: "lobster-orange" });
-      const localState = await readJson(path.join(userDataDir, "Local State"));
-      const profile = localState.profile as Record<string, unknown>;
-      const infoCache = profile.info_cache as Record<string, unknown>;
-      const def = infoCache.Default as Record<string, unknown>;
+    const userDataDir = await createUserDataDir();
+    decorateOpenClawProfile(userDataDir, { color: "lobster-orange" });
+    const localState = await readJson(path.join(userDataDir, "Local State"));
+    const profile = localState.profile as Record<string, unknown>;
+    const infoCache = profile.info_cache as Record<string, unknown>;
+    const def = infoCache.Default as Record<string, unknown>;
 
-      expect(def.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
-      expect(def.profile_color_seed).toBeUndefined();
-    } finally {
-      await fsp.rm(userDataDir, { recursive: true, force: true });
-    }
+    expect(def.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
+    expect(def.profile_color_seed).toBeUndefined();
   });
 
   it("recovers from missing/invalid preference files", async () => {
-    const userDataDir = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-test-"));
-    try {
-      await fsp.mkdir(path.join(userDataDir, "Default"), { recursive: true });
-      await fsp.writeFile(path.join(userDataDir, "Local State"), "{", "utf-8"); // invalid JSON
-      await fsp.writeFile(
-        path.join(userDataDir, "Default", "Preferences"),
-        "[]", // valid JSON but wrong shape
-        "utf-8",
-      );
+    const userDataDir = await createUserDataDir();
+    await fsp.mkdir(path.join(userDataDir, "Default"), { recursive: true });
+    await fsp.writeFile(path.join(userDataDir, "Local State"), "{", "utf-8"); // invalid JSON
+    await fsp.writeFile(
+      path.join(userDataDir, "Default", "Preferences"),
+      "[]", // valid JSON but wrong shape
+      "utf-8",
+    );
 
-      decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
+    decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
 
-      const localState = await readJson(path.join(userDataDir, "Local State"));
-      expect(typeof localState.profile).toBe("object");
+    const localState = await readJson(path.join(userDataDir, "Local State"));
+    expect(typeof localState.profile).toBe("object");
 
-      const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
-      expect(typeof prefs.profile).toBe("object");
-    } finally {
-      await fsp.rm(userDataDir, { recursive: true, force: true });
-    }
+    const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
+    expect(typeof prefs.profile).toBe("object");
   });
 
   it("writes clean exit prefs to avoid restore prompts", async () => {
-    const userDataDir = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-test-"));
-    try {
-      ensureProfileCleanExit(userDataDir);
-      const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
-      expect(prefs.exit_type).toBe("Normal");
-      expect(prefs.exited_cleanly).toBe(true);
-    } finally {
-      await fsp.rm(userDataDir, { recursive: true, force: true });
-    }
+    const userDataDir = await createUserDataDir();
+    ensureProfileCleanExit(userDataDir);
+    const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
+    expect(prefs.exit_type).toBe("Normal");
+    expect(prefs.exited_cleanly).toBe(true);
   });
 
   it("is idempotent when rerun on an existing profile", async () => {
-    const userDataDir = await fsp.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-test-"));
-    try {
-      decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
-      decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
+    const userDataDir = await createUserDataDir();
+    decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
+    decorateOpenClawProfile(userDataDir, { color: DEFAULT_OPENCLAW_BROWSER_COLOR });
 
-      const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
-      const profile = prefs.profile as Record<string, unknown>;
-      expect(profile.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
-    } finally {
-      await fsp.rm(userDataDir, { recursive: true, force: true });
-    }
+    const prefs = await readJson(path.join(userDataDir, "Default", "Preferences"));
+    const profile = prefs.profile as Record<string, unknown>;
+    expect(profile.name).toBe(DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
   });
 });
 
diff --git a/src/browser/client-actions-core.ts b/src/browser/client-actions-core.ts
index c3d17922c65..cce39c03e27 100644
--- a/src/browser/client-actions-core.ts
+++ b/src/browser/client-actions-core.ts
@@ -3,20 +3,9 @@ import type {
   BrowserActionPathResult,
   BrowserActionTabResult,
 } from "./client-actions-types.js";
+import { buildProfileQuery, withBaseUrl } from "./client-actions-url.js";
 import { fetchBrowserJson } from "./client-fetch.js";
 
-function buildProfileQuery(profile?: string): string {
-  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
-}
-
-function withBaseUrl(baseUrl: string | undefined, path: string): string {
-  const trimmed = baseUrl?.trim();
-  if (!trimmed) {
-    return path;
-  }
-  return `${trimmed.replace(/\/$/, "")}${path}`;
-}
-
 export type BrowserFormField = {
   ref: string;
   type: string;
diff --git a/src/browser/client-actions-observe.ts b/src/browser/client-actions-observe.ts
index 13ac92b05b7..6cc68541c20 100644
--- a/src/browser/client-actions-observe.ts
+++ b/src/browser/client-actions-observe.ts
@@ -4,20 +4,9 @@ import type {
   BrowserNetworkRequest,
   BrowserPageError,
 } from "./pw-session.js";
+import { buildProfileQuery, withBaseUrl } from "./client-actions-url.js";
 import { fetchBrowserJson } from "./client-fetch.js";
 
-function buildProfileQuery(profile?: string): string {
-  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
-}
-
-function withBaseUrl(baseUrl: string | undefined, path: string): string {
-  const trimmed = baseUrl?.trim();
-  if (!trimmed) {
-    return path;
-  }
-  return `${trimmed.replace(/\/$/, "")}${path}`;
-}
-
 export async function browserConsoleMessages(
   baseUrl: string | undefined,
   opts: { level?: string; targetId?: string; profile?: string } = {},
diff --git a/src/browser/client-actions-state.ts b/src/browser/client-actions-state.ts
index b2f351b33d1..ad04b652c76 100644
--- a/src/browser/client-actions-state.ts
+++ b/src/browser/client-actions-state.ts
@@ -1,18 +1,7 @@
 import type { BrowserActionOk, BrowserActionTargetOk } from "./client-actions-types.js";
+import { buildProfileQuery, withBaseUrl } from "./client-actions-url.js";
 import { fetchBrowserJson } from "./client-fetch.js";
 
-function buildProfileQuery(profile?: string): string {
-  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
-}
-
-function withBaseUrl(baseUrl: string | undefined, path: string): string {
-  const trimmed = baseUrl?.trim();
-  if (!trimmed) {
-    return path;
-  }
-  return `${trimmed.replace(/\/$/, "")}${path}`;
-}
-
 export async function browserCookies(
   baseUrl: string | undefined,
   opts: { targetId?: string; profile?: string } = {},
diff --git a/src/browser/client-actions-url.ts b/src/browser/client-actions-url.ts
new file mode 100644
index 00000000000..25c47fa6dba
--- /dev/null
+++ b/src/browser/client-actions-url.ts
@@ -0,0 +1,11 @@
+export function buildProfileQuery(profile?: string): string {
+  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+
+export function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) {
+    return path;
+  }
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
diff --git a/src/browser/client-fetch.bridge-auth-registry.test.ts b/src/browser/client-fetch.bridge-auth-registry.test.ts
deleted file mode 100644
index 8e8ef5848b6..00000000000
--- a/src/browser/client-fetch.bridge-auth-registry.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { __test } from "./client-fetch.js";
-
-describe("fetchBrowserJson loopback auth (bridge auth registry)", () => {
-  it("falls back to per-port bridge auth when config auth is not available", async () => {
-    const port = 18765;
-    const getBridgeAuthForPort = vi.fn((candidate: number) =>
-      candidate === port ? { token: "registry-token" } : undefined,
-    );
-    const init = __test.withLoopbackBrowserAuth(`http://127.0.0.1:${port}/`, undefined, {
-      loadConfig: () => ({}),
-      resolveBrowserControlAuth: () => ({}),
-      getBridgeAuthForPort,
-    });
-    const headers = new Headers(init.headers ?? {});
-    expect(headers.get("authorization")).toBe("Bearer registry-token");
-    expect(getBridgeAuthForPort).toHaveBeenCalledWith(port);
-  });
-});
diff --git a/src/browser/client-fetch.ts b/src/browser/client-fetch.ts
index 3fe71934b3e..c8617d0f79c 100644
--- a/src/browser/client-fetch.ts
+++ b/src/browser/client-fetch.ts
@@ -90,9 +90,16 @@ function withLoopbackBrowserAuth(
 }
 
 function enhanceBrowserFetchError(url: string, err: unknown, timeoutMs: number): Error {
-  const hint = isAbsoluteHttp(url)
-    ? "If this is a sandboxed session, ensure the sandbox browser is running and try again."
-    : `Start (or restart) the OpenClaw gateway (OpenClaw.app menubar, or \`${formatCliCommand("openclaw gateway")}\`) and try again.`;
+  const isLocal = !isAbsoluteHttp(url);
+  // Human-facing hint for logs/diagnostics.
+  const operatorHint = isLocal
+    ? `Restart the OpenClaw gateway (OpenClaw.app menubar, or \`${formatCliCommand("openclaw gateway")}\`).`
+    : "If this is a sandboxed session, ensure the sandbox browser is running.";
+  // Model-facing suffix: explicitly tell the LLM NOT to retry.
+  // Without this, models see "try again" and enter an infinite tool-call loop.
+  const modelHint =
+    "Do NOT retry the browser tool — it will keep failing. " +
+    "Use an alternative approach or inform the user that the browser is currently unavailable.";
   const msg = String(err);
   const msgLower = msg.toLowerCase();
   const looksLikeTimeout =
@@ -103,10 +110,12 @@ function enhanceBrowserFetchError(url: string, err: unknown, timeoutMs: number):
     msgLower.includes("aborterror");
   if (looksLikeTimeout) {
     return new Error(
-      `Can't reach the OpenClaw browser control service (timed out after ${timeoutMs}ms). ${hint}`,
+      `Can't reach the OpenClaw browser control service (timed out after ${timeoutMs}ms). ${operatorHint} ${modelHint}`,
     );
   }
-  return new Error(`Can't reach the OpenClaw browser control service. ${hint} (${msg})`);
+  return new Error(
+    `Can't reach the OpenClaw browser control service. ${operatorHint} ${modelHint} (${msg})`,
+  );
 }
 
 async function fetchHttpJson<T>(
diff --git a/src/browser/csrf.test.ts b/src/browser/csrf.test.ts
deleted file mode 100644
index 6f4bedd692f..00000000000
--- a/src/browser/csrf.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { shouldRejectBrowserMutation } from "./csrf.js";
-
-describe("browser CSRF loopback mutation guard", () => {
-  it("rejects mutating methods from non-loopback origin", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        origin: "https://evil.example",
-      }),
-    ).toBe(true);
-  });
-
-  it("allows mutating methods from loopback origin", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        origin: "http://127.0.0.1:18789",
-      }),
-    ).toBe(false);
-
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        origin: "http://localhost:18789",
-      }),
-    ).toBe(false);
-  });
-
-  it("allows mutating methods without origin/referer (non-browser clients)", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-      }),
-    ).toBe(false);
-  });
-
-  it("rejects mutating methods with origin=null", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        origin: "null",
-      }),
-    ).toBe(true);
-  });
-
-  it("rejects mutating methods from non-loopback referer", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        referer: "https://evil.example/attack",
-      }),
-    ).toBe(true);
-  });
-
-  it("rejects cross-site mutations via Sec-Fetch-Site when present", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "POST",
-        secFetchSite: "cross-site",
-      }),
-    ).toBe(true);
-  });
-
-  it("does not reject non-mutating methods", () => {
-    expect(
-      shouldRejectBrowserMutation({
-        method: "GET",
-        origin: "https://evil.example",
-      }),
-    ).toBe(false);
-
-    expect(
-      shouldRejectBrowserMutation({
-        method: "OPTIONS",
-        origin: "https://evil.example",
-      }),
-    ).toBe(false);
-  });
-});
diff --git a/src/browser/profiles.test.ts b/src/browser/profiles.test.ts
index bc1ff087600..b5b4d0fdbaa 100644
--- a/src/browser/profiles.test.ts
+++ b/src/browser/profiles.test.ts
@@ -102,10 +102,6 @@ describe("getUsedPorts", () => {
     expect(getUsedPorts(undefined)).toEqual(new Set());
   });
 
-  it("returns empty set for empty profiles object", () => {
-    expect(getUsedPorts({})).toEqual(new Set());
-  });
-
   it("extracts ports from profile configs", () => {
     const profiles = {
       openclaw: { cdpPort: 18792 },
@@ -227,10 +223,6 @@ describe("getUsedColors", () => {
     expect(getUsedColors(undefined)).toEqual(new Set());
   });
 
-  it("returns empty set for empty profiles object", () => {
-    expect(getUsedColors({})).toEqual(new Set());
-  });
-
   it("extracts and uppercases colors from profile configs", () => {
     const profiles = {
       openclaw: { color: "#ff4500" },
diff --git a/src/browser/routes/utils.test.ts b/src/browser/routes/utils.test.ts
deleted file mode 100644
index 4f7762a944e..00000000000
--- a/src/browser/routes/utils.test.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { toBoolean } from "./utils.js";
-
-describe("toBoolean", () => {
-  it("parses yes/no and 1/0", () => {
-    expect(toBoolean("yes")).toBe(true);
-    expect(toBoolean("1")).toBe(true);
-    expect(toBoolean("no")).toBe(false);
-    expect(toBoolean("0")).toBe(false);
-  });
-
-  it("returns undefined for on/off strings", () => {
-    expect(toBoolean("on")).toBeUndefined();
-    expect(toBoolean("off")).toBeUndefined();
-  });
-
-  it("passes through boolean values", () => {
-    expect(toBoolean(true)).toBe(true);
-    expect(toBoolean(false)).toBe(false);
-  });
-});
diff --git a/src/browser/server-context.list-known-profile-names.test.ts b/src/browser/server-context.list-known-profile-names.test.ts
deleted file mode 100644
index 04c897563e9..00000000000
--- a/src/browser/server-context.list-known-profile-names.test.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { BrowserServerState } from "./server-context.js";
-import { resolveBrowserConfig, resolveProfile } from "./config.js";
-import { listKnownProfileNames } from "./server-context.js";
-
-describe("browser server-context listKnownProfileNames", () => {
-  it("includes configured and runtime-only profile names", () => {
-    const resolved = resolveBrowserConfig({
-      defaultProfile: "openclaw",
-      profiles: {
-        openclaw: { cdpPort: 18800, color: "#FF4500" },
-      },
-    });
-    const openclaw = resolveProfile(resolved, "openclaw");
-    if (!openclaw) {
-      throw new Error("expected openclaw profile");
-    }
-
-    const state: BrowserServerState = {
-      server: null as unknown as BrowserServerState["server"],
-      port: 18791,
-      resolved,
-      profiles: new Map([
-        [
-          "stale-removed",
-          {
-            profile: { ...openclaw, name: "stale-removed" },
-            running: null,
-          },
-        ],
-      ]),
-    };
-
-    expect(listKnownProfileNames(state).toSorted()).toEqual([
-      "chrome",
-      "openclaw",
-      "stale-removed",
-    ]);
-  });
-});
diff --git a/src/browser/server-context.ts b/src/browser/server-context.ts
index 61698f6e701..6e5a60a1420 100644
--- a/src/browser/server-context.ts
+++ b/src/browser/server-context.ts
@@ -10,7 +10,8 @@ import type {
   ProfileRuntimeState,
   ProfileStatus,
 } from "./server-context.types.js";
-import { appendCdpPath, createTargetViaCdp, getHeadersWithAuth, normalizeCdpWsUrl } from "./cdp.js";
+import { fetchJson, fetchOk } from "./cdp.helpers.js";
+import { appendCdpPath, createTargetViaCdp, normalizeCdpWsUrl } from "./cdp.js";
 import {
   isChromeCdpReady,
   isChromeReachable,
@@ -62,35 +63,6 @@ function normalizeWsUrl(raw: string | undefined, cdpBaseUrl: string): string | u
   }
 }
 
-async function fetchJson<T>(url: string, timeoutMs = 1500, init?: RequestInit): Promise<T> {
-  const ctrl = new AbortController();
-  const t = setTimeout(ctrl.abort.bind(ctrl), timeoutMs);
-  try {
-    const headers = getHeadersWithAuth(url, (init?.headers as Record<string, string>) || {});
-    const res = await fetch(url, { ...init, headers, signal: ctrl.signal });
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}`);
-    }
-    return (await res.json()) as T;
-  } finally {
-    clearTimeout(t);
-  }
-}
-
-async function fetchOk(url: string, timeoutMs = 1500, init?: RequestInit): Promise<void> {
-  const ctrl = new AbortController();
-  const t = setTimeout(ctrl.abort.bind(ctrl), timeoutMs);
-  try {
-    const headers = getHeadersWithAuth(url, (init?.headers as Record<string, string>) || {});
-    const res = await fetch(url, { ...init, headers, signal: ctrl.signal });
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}`);
-    }
-  } finally {
-    clearTimeout(t);
-  }
-}
-
 /**
  * Create a profile-scoped context for browser operations.
  */
diff --git a/src/browser/target-id.test.ts b/src/browser/target-id.test.ts
deleted file mode 100644
index a63b6aedbf3..00000000000
--- a/src/browser/target-id.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveTargetIdFromTabs } from "./target-id.js";
-
-describe("browser target id resolution", () => {
-  it("resolves exact ids", () => {
-    const res = resolveTargetIdFromTabs("FULL", [{ targetId: "AAA" }, { targetId: "FULL" }]);
-    expect(res).toEqual({ ok: true, targetId: "FULL" });
-  });
-
-  it("resolves unique prefixes (case-insensitive)", () => {
-    const res = resolveTargetIdFromTabs("57a01309", [
-      { targetId: "57A01309E14B5DEE0FB41F908515A2FC" },
-    ]);
-    expect(res).toEqual({
-      ok: true,
-      targetId: "57A01309E14B5DEE0FB41F908515A2FC",
-    });
-  });
-
-  it("fails on ambiguous prefixes", () => {
-    const res = resolveTargetIdFromTabs("57A0", [
-      { targetId: "57A01309E14B5DEE0FB41F908515A2FC" },
-      { targetId: "57A0BEEF000000000000000000000000" },
-    ]);
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.reason).toBe("ambiguous");
-      expect(res.matches?.length).toBe(2);
-    }
-  });
-
-  it("fails when no tab matches", () => {
-    const res = resolveTargetIdFromTabs("NOPE", [{ targetId: "AAA" }]);
-    expect(res).toEqual({ ok: false, reason: "not_found" });
-  });
-});
diff --git a/src/channel-web.barrel.test.ts b/src/channel-web.barrel.test.ts
deleted file mode 100644
index 0c52598c3e2..00000000000
--- a/src/channel-web.barrel.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { describe, expect, it } from "vitest";
-import * as mod from "./channel-web.js";
-
-describe("channel-web barrel", () => {
-  it("exports the expected web helpers", () => {
-    expect(mod.createWaSocket).toBeTypeOf("function");
-    expect(mod.loginWeb).toBeTypeOf("function");
-    expect(mod.monitorWebChannel).toBeTypeOf("function");
-    expect(mod.sendMessageWhatsApp).toBeTypeOf("function");
-    expect(mod.monitorWebInbox).toBeTypeOf("function");
-    expect(mod.pickWebChannel).toBeTypeOf("function");
-    expect(mod.WA_WEB_AUTH_DIR).toBeTruthy();
-  });
-});
diff --git a/src/channels/ack-reactions.test.ts b/src/channels/ack-reactions.test.ts
index bd8698ef1a3..73891720867 100644
--- a/src/channels/ack-reactions.test.ts
+++ b/src/channels/ack-reactions.test.ts
@@ -1,11 +1,14 @@
 import { describe, expect, it, vi } from "vitest";
-import { sleep } from "../utils.ts";
 import {
   removeAckReactionAfterReply,
   shouldAckReaction,
   shouldAckReactionForWhatsApp,
 } from "./ack-reactions.js";
 
+const flushMicrotasks = async () => {
+  await Promise.resolve();
+};
+
 describe("shouldAckReaction", () => {
   it("honors direct and group-all scopes", () => {
     expect(
@@ -33,7 +36,7 @@ describe("shouldAckReaction", () => {
     ).toBe(true);
   });
 
-  it("skips when scope is off or none", () => {
+  it("skips when scope is off", () => {
     expect(
       shouldAckReaction({
         scope: "off",
@@ -45,18 +48,6 @@ describe("shouldAckReaction", () => {
         effectiveWasMentioned: true,
       }),
     ).toBe(false);
-
-    expect(
-      shouldAckReaction({
-        scope: "none",
-        isDirect: true,
-        isGroup: true,
-        isMentionableGroup: true,
-        requireMention: true,
-        canDetectMention: true,
-        effectiveWasMentioned: true,
-      }),
-    ).toBe(false);
   });
 
   it("defaults to group-mentions gating", () => {
@@ -139,18 +130,6 @@ describe("shouldAckReaction", () => {
 
 describe("shouldAckReactionForWhatsApp", () => {
   it("respects direct and group modes", () => {
-    expect(
-      shouldAckReactionForWhatsApp({
-        emoji: "👀",
-        isDirect: true,
-        isGroup: false,
-        directEnabled: true,
-        groupMode: "mentions",
-        wasMentioned: false,
-        groupActivated: false,
-      }),
-    ).toBe(true);
-
     expect(
       shouldAckReactionForWhatsApp({
         emoji: "👀",
@@ -189,18 +168,6 @@ describe("shouldAckReactionForWhatsApp", () => {
   });
 
   it("honors mentions or activation for group-mentions", () => {
-    expect(
-      shouldAckReactionForWhatsApp({
-        emoji: "👀",
-        isDirect: false,
-        isGroup: true,
-        directEnabled: true,
-        groupMode: "mentions",
-        wasMentioned: true,
-        groupActivated: false,
-      }),
-    ).toBe(true);
-
     expect(
       shouldAckReactionForWhatsApp({
         emoji: "👀",
@@ -238,7 +205,7 @@ describe("removeAckReactionAfterReply", () => {
       remove,
       onError,
     });
-    await sleep(0);
+    await flushMicrotasks();
     expect(remove).toHaveBeenCalledTimes(1);
     expect(onError).not.toHaveBeenCalled();
   });
@@ -251,19 +218,7 @@ describe("removeAckReactionAfterReply", () => {
       ackReactionValue: "👀",
       remove,
     });
-    await sleep(0);
-    expect(remove).not.toHaveBeenCalled();
-  });
-
-  it("skips when not configured", async () => {
-    const remove = vi.fn().mockResolvedValue(undefined);
-    removeAckReactionAfterReply({
-      removeAfterReply: false,
-      ackReactionPromise: Promise.resolve(true),
-      ackReactionValue: "👀",
-      remove,
-    });
-    await sleep(0);
+    await flushMicrotasks();
     expect(remove).not.toHaveBeenCalled();
   });
 });
diff --git a/src/channels/allowlists/resolve-utils.test.ts b/src/channels/allowlists/resolve-utils.test.ts
new file mode 100644
index 00000000000..7d8cc212345
--- /dev/null
+++ b/src/channels/allowlists/resolve-utils.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import {
+  addAllowlistUserEntriesFromConfigEntry,
+  buildAllowlistResolutionSummary,
+} from "./resolve-utils.js";
+
+describe("buildAllowlistResolutionSummary", () => {
+  it("returns mapping, additions, and unresolved (including missing ids)", () => {
+    const resolvedUsers = [
+      { input: "a", resolved: true, id: "1" },
+      { input: "b", resolved: false },
+      { input: "c", resolved: true },
+    ];
+    const result = buildAllowlistResolutionSummary(resolvedUsers);
+    expect(result.mapping).toEqual(["a→1"]);
+    expect(result.additions).toEqual(["1"]);
+    expect(result.unresolved).toEqual(["b", "c"]);
+  });
+
+  it("supports custom resolved formatting", () => {
+    const resolvedUsers = [{ input: "a", resolved: true, id: "1", note: "x" }];
+    const result = buildAllowlistResolutionSummary(resolvedUsers, {
+      formatResolved: (entry) =>
+        `${entry.input}→${entry.id}${(entry as { note?: string }).note ? " (note)" : ""}`,
+    });
+    expect(result.mapping).toEqual(["a→1 (note)"]);
+  });
+});
+
+describe("addAllowlistUserEntriesFromConfigEntry", () => {
+  it("adds trimmed users and skips '*' and blanks", () => {
+    const target = new Set<string>();
+    addAllowlistUserEntriesFromConfigEntry(target, { users: ["  a  ", "*", "", "b"] });
+    expect(Array.from(target).toSorted()).toEqual(["a", "b"]);
+  });
+
+  it("ignores non-objects", () => {
+    const target = new Set<string>(["a"]);
+    addAllowlistUserEntriesFromConfigEntry(target, null);
+    expect(Array.from(target)).toEqual(["a"]);
+  });
+});
diff --git a/src/channels/allowlists/resolve-utils.ts b/src/channels/allowlists/resolve-utils.ts
index a4a747f77dd..46b439093c9 100644
--- a/src/channels/allowlists/resolve-utils.ts
+++ b/src/channels/allowlists/resolve-utils.ts
@@ -35,17 +35,25 @@ export function mergeAllowlist(params: {
 
 export function buildAllowlistResolutionSummary<T extends AllowlistUserResolutionLike>(
   resolvedUsers: T[],
+  opts?: { formatResolved?: (entry: T) => string },
 ): {
   resolvedMap: Map<string, T>;
   mapping: string[];
   unresolved: string[];
+  additions: string[];
 } {
   const resolvedMap = new Map(resolvedUsers.map((entry) => [entry.input, entry]));
-  const mapping = resolvedUsers
-    .filter((entry) => entry.resolved && entry.id)
-    .map((entry) => `${entry.input}→${entry.id}`);
-  const unresolved = resolvedUsers.filter((entry) => !entry.resolved).map((entry) => entry.input);
-  return { resolvedMap, mapping, unresolved };
+  const resolvedOk = (entry: T) => Boolean(entry.resolved && entry.id);
+  const formatResolved = opts?.formatResolved ?? ((entry: T) => `${entry.input}→${entry.id}`);
+  const mapping = resolvedUsers.filter(resolvedOk).map(formatResolved);
+  const additions = resolvedUsers
+    .filter(resolvedOk)
+    .map((entry) => entry.id)
+    .filter((entry): entry is string => Boolean(entry));
+  const unresolved = resolvedUsers
+    .filter((entry) => !resolvedOk(entry))
+    .map((entry) => entry.input);
+  return { resolvedMap, mapping, unresolved, additions };
 }
 
 export function resolveAllowlistIdAdditions<T extends AllowlistUserResolutionLike>(params: {
@@ -88,6 +96,22 @@ export function patchAllowlistUsersInConfigEntries<
   return nextEntries as TEntries;
 }
 
+export function addAllowlistUserEntriesFromConfigEntry(target: Set<string>, entry: unknown): void {
+  if (!entry || typeof entry !== "object") {
+    return;
+  }
+  const users = (entry as { users?: Array<string | number> }).users;
+  if (!Array.isArray(users)) {
+    return;
+  }
+  for (const value of users) {
+    const trimmed = String(value).trim();
+    if (trimmed && trimmed !== "*") {
+      target.add(trimmed);
+    }
+  }
+}
+
 export function summarizeMapping(
   label: string,
   mapping: string[],
diff --git a/src/channels/channel-config.test.ts b/src/channels/channel-config.test.ts
index 9af6cedc135..807a254e62b 100644
--- a/src/channels/channel-config.test.ts
+++ b/src/channels/channel-config.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import type { MsgContext } from "../auto-reply/templating.js";
 import {
   buildChannelKeyCandidates,
   normalizeChannelSlug,
@@ -8,6 +9,7 @@ import {
   applyChannelMatchMeta,
   resolveChannelMatchConfig,
 } from "./channel-config.js";
+import { validateSenderIdentity } from "./sender-identity.js";
 
 describe("buildChannelKeyCandidates", () => {
   it("dedupes and trims keys", () => {
@@ -118,6 +120,33 @@ describe("resolveChannelMatchConfig", () => {
   });
 });
 
+describe("validateSenderIdentity", () => {
+  it("allows direct messages without sender fields", () => {
+    const ctx: MsgContext = { ChatType: "direct" };
+    expect(validateSenderIdentity(ctx)).toEqual([]);
+  });
+
+  it("requires some sender identity for non-direct chats", () => {
+    const ctx: MsgContext = { ChatType: "group" };
+    expect(validateSenderIdentity(ctx)).toContain(
+      "missing sender identity (SenderId/SenderName/SenderUsername/SenderE164)",
+    );
+  });
+
+  it("validates SenderE164 and SenderUsername shape", () => {
+    const ctx: MsgContext = {
+      ChatType: "group",
+      SenderE164: "123",
+      SenderUsername: "@ada lovelace",
+    };
+    expect(validateSenderIdentity(ctx)).toEqual([
+      "invalid SenderE164: 123",
+      'SenderUsername should not include "@": @ada lovelace',
+      "SenderUsername should not include whitespace: @ada lovelace",
+    ]);
+  });
+});
+
 describe("resolveNestedAllowlistDecision", () => {
   it("allows when outer allowlist is disabled", () => {
     expect(
diff --git a/src/channels/channel-helpers.test.ts b/src/channels/channel-helpers.test.ts
new file mode 100644
index 00000000000..89837fe42ec
--- /dev/null
+++ b/src/channels/channel-helpers.test.ts
@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MsgContext } from "../auto-reply/templating.js";
+import { resolveConversationLabel } from "./conversation-label.js";
+import {
+  formatChannelSelectionLine,
+  listChatChannels,
+  normalizeChatChannelId,
+} from "./registry.js";
+import { buildMessagingTarget, ensureTargetId, requireTargetKind } from "./targets.js";
+import { createTypingCallbacks } from "./typing.js";
+
+const flushMicrotasks = async () => {
+  await Promise.resolve();
+  await Promise.resolve();
+};
+
+describe("channel registry helpers", () => {
+  it("normalizes aliases + trims whitespace", () => {
+    expect(normalizeChatChannelId(" imsg ")).toBe("imessage");
+    expect(normalizeChatChannelId("gchat")).toBe("googlechat");
+    expect(normalizeChatChannelId("google-chat")).toBe("googlechat");
+    expect(normalizeChatChannelId("internet-relay-chat")).toBe("irc");
+    expect(normalizeChatChannelId("telegram")).toBe("telegram");
+    expect(normalizeChatChannelId("web")).toBeNull();
+    expect(normalizeChatChannelId("nope")).toBeNull();
+  });
+
+  it("keeps Telegram first in the default order", () => {
+    const channels = listChatChannels();
+    expect(channels[0]?.id).toBe("telegram");
+  });
+
+  it("does not include MS Teams by default", () => {
+    const channels = listChatChannels();
+    expect(channels.some((channel) => channel.id === "msteams")).toBe(false);
+  });
+
+  it("formats selection lines with docs labels + website extras", () => {
+    const channels = listChatChannels();
+    const first = channels[0];
+    if (!first) {
+      throw new Error("Missing channel metadata.");
+    }
+    const line = formatChannelSelectionLine(first, (path, label) =>
+      [label, path].filter(Boolean).join(":"),
+    );
+    expect(line).not.toContain("Docs:");
+    expect(line).toContain("/channels/telegram");
+    expect(line).toContain("https://openclaw.ai");
+  });
+});
+
+describe("channel targets", () => {
+  it("ensureTargetId returns the candidate when it matches", () => {
+    expect(
+      ensureTargetId({
+        candidate: "U123",
+        pattern: /^[A-Z0-9]+$/i,
+        errorMessage: "bad",
+      }),
+    ).toBe("U123");
+  });
+
+  it("ensureTargetId throws with the provided message on mismatch", () => {
+    expect(() =>
+      ensureTargetId({
+        candidate: "not-ok",
+        pattern: /^[A-Z0-9]+$/i,
+        errorMessage: "Bad target",
+      }),
+    ).toThrow(/Bad target/);
+  });
+
+  it("requireTargetKind returns the target id when the kind matches", () => {
+    const target = buildMessagingTarget("channel", "C123", "C123");
+    expect(requireTargetKind({ platform: "Slack", target, kind: "channel" })).toBe("C123");
+  });
+
+  it("requireTargetKind throws when the kind is missing or mismatched", () => {
+    expect(() =>
+      requireTargetKind({ platform: "Slack", target: undefined, kind: "channel" }),
+    ).toThrow(/Slack channel id is required/);
+    const target = buildMessagingTarget("user", "U123", "U123");
+    expect(() => requireTargetKind({ platform: "Slack", target, kind: "channel" })).toThrow(
+      /Slack channel id is required/,
+    );
+  });
+});
+
+describe("resolveConversationLabel", () => {
+  it("prefers ConversationLabel when present", () => {
+    const ctx: MsgContext = { ConversationLabel: "Pinned Label", ChatType: "group" };
+    expect(resolveConversationLabel(ctx)).toBe("Pinned Label");
+  });
+
+  it("prefers ThreadLabel over derived chat labels", () => {
+    const ctx: MsgContext = {
+      ThreadLabel: "Thread Alpha",
+      ChatType: "group",
+      GroupSubject: "Ops",
+      From: "telegram:group:42",
+    };
+    expect(resolveConversationLabel(ctx)).toBe("Thread Alpha");
+  });
+
+  it("uses SenderName for direct chats when available", () => {
+    const ctx: MsgContext = { ChatType: "direct", SenderName: "Ada", From: "telegram:99" };
+    expect(resolveConversationLabel(ctx)).toBe("Ada");
+  });
+
+  it("falls back to From for direct chats when SenderName is missing", () => {
+    const ctx: MsgContext = { ChatType: "direct", From: "telegram:99" };
+    expect(resolveConversationLabel(ctx)).toBe("telegram:99");
+  });
+
+  it("derives Telegram-like group labels with numeric id suffix", () => {
+    const ctx: MsgContext = { ChatType: "group", GroupSubject: "Ops", From: "telegram:group:42" };
+    expect(resolveConversationLabel(ctx)).toBe("Ops id:42");
+  });
+
+  it("does not append ids for #rooms/channels", () => {
+    const ctx: MsgContext = {
+      ChatType: "channel",
+      GroupSubject: "#general",
+      From: "slack:channel:C123",
+    };
+    expect(resolveConversationLabel(ctx)).toBe("#general");
+  });
+
+  it("does not append ids when the base already contains the id", () => {
+    const ctx: MsgContext = {
+      ChatType: "group",
+      GroupSubject: "Family id:123@g.us",
+      From: "whatsapp:group:123@g.us",
+    };
+    expect(resolveConversationLabel(ctx)).toBe("Family id:123@g.us");
+  });
+
+  it("appends ids for WhatsApp-like group ids when a subject exists", () => {
+    const ctx: MsgContext = {
+      ChatType: "group",
+      GroupSubject: "Family",
+      From: "whatsapp:group:123@g.us",
+    };
+    expect(resolveConversationLabel(ctx)).toBe("Family id:123@g.us");
+  });
+});
+
+describe("createTypingCallbacks", () => {
+  it("invokes start on reply start", async () => {
+    const start = vi.fn().mockResolvedValue(undefined);
+    const onStartError = vi.fn();
+    const callbacks = createTypingCallbacks({ start, onStartError });
+
+    await callbacks.onReplyStart();
+
+    expect(start).toHaveBeenCalledTimes(1);
+    expect(onStartError).not.toHaveBeenCalled();
+  });
+
+  it("reports start errors", async () => {
+    const start = vi.fn().mockRejectedValue(new Error("fail"));
+    const onStartError = vi.fn();
+    const callbacks = createTypingCallbacks({ start, onStartError });
+
+    await callbacks.onReplyStart();
+
+    expect(onStartError).toHaveBeenCalledTimes(1);
+  });
+
+  it("invokes stop on idle and reports stop errors", async () => {
+    const start = vi.fn().mockResolvedValue(undefined);
+    const stop = vi.fn().mockRejectedValue(new Error("stop"));
+    const onStartError = vi.fn();
+    const onStopError = vi.fn();
+    const callbacks = createTypingCallbacks({ start, stop, onStartError, onStopError });
+
+    callbacks.onIdle?.();
+    await flushMicrotasks();
+
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(onStopError).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/channels/channels-misc.test.ts b/src/channels/channels-misc.test.ts
new file mode 100644
index 00000000000..3eb51c509ac
--- /dev/null
+++ b/src/channels/channels-misc.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import * as channelWeb from "../channel-web.js";
+import { normalizeChatType } from "./chat-type.js";
+import * as webEntry from "./web/index.js";
+
+describe("channel-web barrel", () => {
+  it("exports the expected web helpers", () => {
+    expect(channelWeb.createWaSocket).toBeTypeOf("function");
+    expect(channelWeb.loginWeb).toBeTypeOf("function");
+    expect(channelWeb.monitorWebChannel).toBeTypeOf("function");
+    expect(channelWeb.sendMessageWhatsApp).toBeTypeOf("function");
+    expect(channelWeb.monitorWebInbox).toBeTypeOf("function");
+    expect(channelWeb.pickWebChannel).toBeTypeOf("function");
+    expect(channelWeb.WA_WEB_AUTH_DIR).toBeTruthy();
+  });
+});
+
+describe("normalizeChatType", () => {
+  it("normalizes common inputs", () => {
+    expect(normalizeChatType("direct")).toBe("direct");
+    expect(normalizeChatType("dm")).toBe("direct");
+    expect(normalizeChatType("group")).toBe("group");
+    expect(normalizeChatType("channel")).toBe("channel");
+  });
+
+  it("returns undefined for empty/unknown values", () => {
+    expect(normalizeChatType(undefined)).toBeUndefined();
+    expect(normalizeChatType("")).toBeUndefined();
+    expect(normalizeChatType("nope")).toBeUndefined();
+    expect(normalizeChatType("room")).toBeUndefined();
+  });
+
+  describe("backward compatibility", () => {
+    it("accepts legacy 'dm' value and normalizes to 'direct'", () => {
+      // Legacy config/input may use "dm" - ensure smooth upgrade path
+      expect(normalizeChatType("dm")).toBe("direct");
+      expect(normalizeChatType("DM")).toBe("direct");
+      expect(normalizeChatType(" dm ")).toBe("direct");
+    });
+  });
+});
+
+describe("channels/web entrypoint", () => {
+  it("re-exports web channel helpers", () => {
+    expect(webEntry.createWaSocket).toBe(channelWeb.createWaSocket);
+    expect(webEntry.loginWeb).toBe(channelWeb.loginWeb);
+    expect(webEntry.logWebSelfId).toBe(channelWeb.logWebSelfId);
+    expect(webEntry.monitorWebInbox).toBe(channelWeb.monitorWebInbox);
+    expect(webEntry.monitorWebChannel).toBe(channelWeb.monitorWebChannel);
+    expect(webEntry.pickWebChannel).toBe(channelWeb.pickWebChannel);
+    expect(webEntry.sendMessageWhatsApp).toBe(channelWeb.sendMessageWhatsApp);
+    expect(webEntry.WA_WEB_AUTH_DIR).toBe(channelWeb.WA_WEB_AUTH_DIR);
+    expect(webEntry.waitForWaConnection).toBe(channelWeb.waitForWaConnection);
+    expect(webEntry.webAuthExists).toBe(channelWeb.webAuthExists);
+  });
+});
diff --git a/src/channels/chat-type.test.ts b/src/channels/chat-type.test.ts
deleted file mode 100644
index 6775c8cac8e..00000000000
--- a/src/channels/chat-type.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeChatType } from "./chat-type.js";
-
-describe("normalizeChatType", () => {
-  it("normalizes common inputs", () => {
-    expect(normalizeChatType("direct")).toBe("direct");
-    expect(normalizeChatType("dm")).toBe("direct");
-    expect(normalizeChatType("group")).toBe("group");
-    expect(normalizeChatType("channel")).toBe("channel");
-  });
-
-  it("returns undefined for empty/unknown values", () => {
-    expect(normalizeChatType(undefined)).toBeUndefined();
-    expect(normalizeChatType("")).toBeUndefined();
-    expect(normalizeChatType("nope")).toBeUndefined();
-    expect(normalizeChatType("room")).toBeUndefined();
-  });
-
-  describe("backward compatibility", () => {
-    it("accepts legacy 'dm' value and normalizes to 'direct'", () => {
-      // Legacy config/input may use "dm" - ensure smooth upgrade path
-      expect(normalizeChatType("dm")).toBe("direct");
-      expect(normalizeChatType("DM")).toBe("direct");
-      expect(normalizeChatType(" dm ")).toBe("direct");
-    });
-  });
-});
diff --git a/src/channels/conversation-label.test.ts b/src/channels/conversation-label.test.ts
deleted file mode 100644
index 7e261e1c55a..00000000000
--- a/src/channels/conversation-label.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { MsgContext } from "../auto-reply/templating.js";
-import { resolveConversationLabel } from "./conversation-label.js";
-
-describe("resolveConversationLabel", () => {
-  it("prefers ConversationLabel when present", () => {
-    const ctx: MsgContext = { ConversationLabel: "Pinned Label", ChatType: "group" };
-    expect(resolveConversationLabel(ctx)).toBe("Pinned Label");
-  });
-
-  it("uses SenderName for direct chats when available", () => {
-    const ctx: MsgContext = { ChatType: "direct", SenderName: "Ada", From: "telegram:99" };
-    expect(resolveConversationLabel(ctx)).toBe("Ada");
-  });
-
-  it("derives Telegram-like group labels with numeric id suffix", () => {
-    const ctx: MsgContext = { ChatType: "group", GroupSubject: "Ops", From: "telegram:group:42" };
-    expect(resolveConversationLabel(ctx)).toBe("Ops id:42");
-  });
-
-  it("does not append ids for #rooms/channels", () => {
-    const ctx: MsgContext = {
-      ChatType: "channel",
-      GroupSubject: "#general",
-      From: "slack:channel:C123",
-    };
-    expect(resolveConversationLabel(ctx)).toBe("#general");
-  });
-
-  it("appends ids for WhatsApp-like group ids when a subject exists", () => {
-    const ctx: MsgContext = {
-      ChatType: "group",
-      GroupSubject: "Family",
-      From: "whatsapp:group:123@g.us",
-    };
-    expect(resolveConversationLabel(ctx)).toBe("Family id:123@g.us");
-  });
-});
diff --git a/src/channels/dock.ts b/src/channels/dock.ts
index e0aec226964..fa872a21620 100644
--- a/src/channels/dock.ts
+++ b/src/channels/dock.ts
@@ -8,7 +8,9 @@ import type {
   ChannelAgentPromptAdapter,
   ChannelMentionAdapter,
   ChannelPlugin,
+  ChannelThreadingContext,
   ChannelThreadingAdapter,
+  ChannelThreadingToolContext,
 } from "./plugins/types.js";
 import {
   resolveChannelGroupRequireMention,
@@ -79,6 +81,21 @@ const formatLower = (allowFrom: Array<string | number>) =>
     .map((entry) => String(entry).trim())
     .filter(Boolean)
     .map((entry) => entry.toLowerCase());
+
+function buildDirectOrGroupThreadToolContext(params: {
+  context: ChannelThreadingContext;
+  hasRepliedRef: ChannelThreadingToolContext["hasRepliedRef"];
+}): ChannelThreadingToolContext {
+  const isDirect = params.context.ChatType?.toLowerCase() === "direct";
+  const channelId =
+    (isDirect ? (params.context.From ?? params.context.To) : params.context.To)?.trim() ||
+    undefined;
+  return {
+    currentChannelId: channelId,
+    currentThreadTs: params.context.ReplyToId,
+    hasRepliedRef: params.hasRepliedRef,
+  };
+}
 // Channel docks: lightweight channel metadata/behavior for shared code paths.
 //
 // Rules:
@@ -404,16 +421,8 @@ const DOCKS: Record<ChatChannelId, ChannelDock> = {
           .filter(Boolean),
     },
     threading: {
-      buildToolContext: ({ context, hasRepliedRef }) => {
-        const isDirect = context.ChatType?.toLowerCase() === "direct";
-        const channelId =
-          (isDirect ? (context.From ?? context.To) : context.To)?.trim() || undefined;
-        return {
-          currentChannelId: channelId,
-          currentThreadTs: context.ReplyToId,
-          hasRepliedRef,
-        };
-      },
+      buildToolContext: ({ context, hasRepliedRef }) =>
+        buildDirectOrGroupThreadToolContext({ context, hasRepliedRef }),
     },
   },
   imessage: {
@@ -437,16 +446,8 @@ const DOCKS: Record<ChatChannelId, ChannelDock> = {
       resolveToolPolicy: resolveIMessageGroupToolPolicy,
     },
     threading: {
-      buildToolContext: ({ context, hasRepliedRef }) => {
-        const isDirect = context.ChatType?.toLowerCase() === "direct";
-        const channelId =
-          (isDirect ? (context.From ?? context.To) : context.To)?.trim() || undefined;
-        return {
-          currentChannelId: channelId,
-          currentThreadTs: context.ReplyToId,
-          hasRepliedRef,
-        };
-      },
+      buildToolContext: ({ context, hasRepliedRef }) =>
+        buildDirectOrGroupThreadToolContext({ context, hasRepliedRef }),
     },
   },
 };
diff --git a/src/channels/plugins/actions/actions.test.ts b/src/channels/plugins/actions/actions.test.ts
new file mode 100644
index 00000000000..1b33f41377c
--- /dev/null
+++ b/src/channels/plugins/actions/actions.test.ts
@@ -0,0 +1,529 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../../config/config.js";
+
+const handleDiscordAction = vi.fn(async () => ({ details: { ok: true } }));
+const handleTelegramAction = vi.fn(async () => ({ ok: true }));
+const sendReactionSignal = vi.fn(async () => ({ ok: true }));
+const removeReactionSignal = vi.fn(async () => ({ ok: true }));
+const handleSlackAction = vi.fn(async () => ({ details: { ok: true } }));
+
+vi.mock("../../../agents/tools/discord-actions.js", () => ({
+  handleDiscordAction: (...args: unknown[]) => handleDiscordAction(...args),
+}));
+
+vi.mock("../../../agents/tools/telegram-actions.js", () => ({
+  handleTelegramAction: (...args: unknown[]) => handleTelegramAction(...args),
+}));
+
+vi.mock("../../../signal/send-reactions.js", () => ({
+  sendReactionSignal: (...args: unknown[]) => sendReactionSignal(...args),
+  removeReactionSignal: (...args: unknown[]) => removeReactionSignal(...args),
+}));
+
+vi.mock("../../../agents/tools/slack-actions.js", () => ({
+  handleSlackAction: (...args: unknown[]) => handleSlackAction(...args),
+}));
+
+const { discordMessageActions } = await import("./discord.js");
+const { handleDiscordMessageAction } = await import("./discord/handle-action.js");
+const { telegramMessageActions } = await import("./telegram.js");
+const { signalMessageActions } = await import("./signal.js");
+const { createSlackActions } = await import("../slack.actions.js");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("discord message actions", () => {
+  it("lists channel and upload actions by default", async () => {
+    const cfg = { channels: { discord: { token: "d0" } } } as OpenClawConfig;
+    const actions = discordMessageActions.listActions?.({ cfg }) ?? [];
+
+    expect(actions).toContain("emoji-upload");
+    expect(actions).toContain("sticker-upload");
+    expect(actions).toContain("channel-create");
+  });
+
+  it("respects disabled channel actions", async () => {
+    const cfg = {
+      channels: { discord: { token: "d0", actions: { channels: false } } },
+    } as OpenClawConfig;
+    const actions = discordMessageActions.listActions?.({ cfg }) ?? [];
+
+    expect(actions).not.toContain("channel-create");
+  });
+});
+
+describe("handleDiscordMessageAction", () => {
+  it("forwards context accountId for send", async () => {
+    await handleDiscordMessageAction({
+      action: "send",
+      params: {
+        to: "channel:123",
+        message: "hi",
+      },
+      cfg: {} as OpenClawConfig,
+      accountId: "ops",
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        accountId: "ops",
+        to: "channel:123",
+        content: "hi",
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("forwards legacy embeds for send", async () => {
+    const embeds = [{ title: "Legacy", description: "Use components v2." }];
+
+    await handleDiscordMessageAction({
+      action: "send",
+      params: {
+        to: "channel:123",
+        message: "hi",
+        embeds,
+      },
+      cfg: {} as OpenClawConfig,
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "channel:123",
+        content: "hi",
+        embeds,
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("falls back to params accountId when context missing", async () => {
+    await handleDiscordMessageAction({
+      action: "poll",
+      params: {
+        to: "channel:123",
+        pollQuestion: "Ready?",
+        pollOption: ["Yes", "No"],
+        accountId: "marve",
+      },
+      cfg: {} as OpenClawConfig,
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "poll",
+        accountId: "marve",
+        to: "channel:123",
+        question: "Ready?",
+        answers: ["Yes", "No"],
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("forwards accountId for thread replies", async () => {
+    await handleDiscordMessageAction({
+      action: "thread-reply",
+      params: {
+        channelId: "123",
+        message: "hi",
+      },
+      cfg: {} as OpenClawConfig,
+      accountId: "ops",
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "threadReply",
+        accountId: "ops",
+        channelId: "123",
+        content: "hi",
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("accepts threadId for thread replies (tool compatibility)", async () => {
+    await handleDiscordMessageAction({
+      action: "thread-reply",
+      params: {
+        // The `message` tool uses `threadId`.
+        threadId: "999",
+        // Include a conflicting channelId to ensure threadId takes precedence.
+        channelId: "123",
+        message: "hi",
+      },
+      cfg: {} as OpenClawConfig,
+      accountId: "ops",
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "threadReply",
+        accountId: "ops",
+        channelId: "999",
+        content: "hi",
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("forwards thread-create message as content", async () => {
+    await handleDiscordMessageAction({
+      action: "thread-create",
+      params: {
+        to: "channel:123456789",
+        threadName: "Forum thread",
+        message: "Initial forum post body",
+      },
+      cfg: {} as OpenClawConfig,
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "threadCreate",
+        channelId: "123456789",
+        name: "Forum thread",
+        content: "Initial forum post body",
+      }),
+      expect.any(Object),
+    );
+  });
+
+  it("forwards thread edit fields for channel-edit", async () => {
+    await handleDiscordMessageAction({
+      action: "channel-edit",
+      params: {
+        channelId: "123456789",
+        archived: true,
+        locked: false,
+        autoArchiveDuration: 1440,
+      },
+      cfg: {} as OpenClawConfig,
+    });
+
+    expect(handleDiscordAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "channelEdit",
+        channelId: "123456789",
+        archived: true,
+        locked: false,
+        autoArchiveDuration: 1440,
+      }),
+      expect.any(Object),
+    );
+  });
+});
+
+describe("telegramMessageActions", () => {
+  it("excludes sticker actions when not enabled", () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+    const actions = telegramMessageActions.listActions({ cfg });
+    expect(actions).not.toContain("sticker");
+    expect(actions).not.toContain("sticker-search");
+  });
+
+  it("allows media-only sends and passes asVoice", async () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+
+    await telegramMessageActions.handleAction({
+      action: "send",
+      params: {
+        to: "123",
+        media: "https://example.com/voice.ogg",
+        asVoice: true,
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(handleTelegramAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "123",
+        content: "",
+        mediaUrl: "https://example.com/voice.ogg",
+        asVoice: true,
+      }),
+      cfg,
+    );
+  });
+
+  it("passes silent flag for silent sends", async () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+
+    await telegramMessageActions.handleAction({
+      action: "send",
+      params: {
+        to: "456",
+        message: "Silent notification test",
+        silent: true,
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(handleTelegramAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "456",
+        content: "Silent notification test",
+        silent: true,
+      }),
+      cfg,
+    );
+  });
+
+  it("maps edit action params into editMessage", async () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+
+    await telegramMessageActions.handleAction({
+      action: "edit",
+      params: {
+        chatId: "123",
+        messageId: 42,
+        message: "Updated",
+        buttons: [],
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(handleTelegramAction).toHaveBeenCalledWith(
+      {
+        action: "editMessage",
+        chatId: "123",
+        messageId: 42,
+        content: "Updated",
+        buttons: [],
+        accountId: undefined,
+      },
+      cfg,
+    );
+  });
+
+  it("rejects non-integer messageId for edit before reaching telegram-actions", async () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+
+    await expect(
+      telegramMessageActions.handleAction({
+        action: "edit",
+        params: {
+          chatId: "123",
+          messageId: "nope",
+          message: "Updated",
+        },
+        cfg,
+        accountId: undefined,
+      }),
+    ).rejects.toThrow();
+
+    expect(handleTelegramAction).not.toHaveBeenCalled();
+  });
+
+  it("accepts numeric messageId and channelId for reactions", async () => {
+    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
+
+    await telegramMessageActions.handleAction({
+      action: "react",
+      params: {
+        channelId: 123,
+        messageId: 456,
+        emoji: "ok",
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(handleTelegramAction).toHaveBeenCalledTimes(1);
+    const call = handleTelegramAction.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(call.action).toBe("react");
+    expect(String(call.chatId)).toBe("123");
+    expect(String(call.messageId)).toBe("456");
+    expect(call.emoji).toBe("ok");
+  });
+});
+
+describe("signalMessageActions", () => {
+  it("returns no actions when no configured accounts exist", () => {
+    const cfg = {} as OpenClawConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual([]);
+  });
+
+  it("hides react when reactions are disabled", () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
+    } as OpenClawConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual(["send"]);
+  });
+
+  it("enables react when at least one account allows reactions", () => {
+    const cfg = {
+      channels: {
+        signal: {
+          actions: { reactions: false },
+          accounts: {
+            work: { account: "+15550001111", actions: { reactions: true } },
+          },
+        },
+      },
+    } as OpenClawConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual(["send", "react"]);
+  });
+
+  it("skips send for plugin dispatch", () => {
+    expect(signalMessageActions.supportsAction?.({ action: "send" })).toBe(false);
+    expect(signalMessageActions.supportsAction?.({ action: "react" })).toBe(true);
+  });
+
+  it("blocks reactions when action gate is disabled", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
+    } as OpenClawConfig;
+
+    await expect(
+      signalMessageActions.handleAction({
+        action: "react",
+        params: { to: "+15550001111", messageId: "123", emoji: "✅" },
+        cfg,
+        accountId: undefined,
+      }),
+    ).rejects.toThrow(/actions\.reactions/);
+  });
+
+  it("uses account-level actions when enabled", async () => {
+    const cfg = {
+      channels: {
+        signal: {
+          actions: { reactions: false },
+          accounts: {
+            work: { account: "+15550001111", actions: { reactions: true } },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: { to: "+15550001111", messageId: "123", emoji: "👍" },
+      cfg,
+      accountId: "work",
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith("+15550001111", 123, "👍", {
+      accountId: "work",
+    });
+  });
+
+  it("normalizes uuid recipients", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as OpenClawConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: {
+        recipient: "uuid:123e4567-e89b-12d3-a456-426614174000",
+        messageId: "123",
+        emoji: "🔥",
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith(
+      "123e4567-e89b-12d3-a456-426614174000",
+      123,
+      "🔥",
+      { accountId: undefined },
+    );
+  });
+
+  it("requires targetAuthor for group reactions", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as OpenClawConfig;
+
+    await expect(
+      signalMessageActions.handleAction({
+        action: "react",
+        params: { to: "signal:group:group-id", messageId: "123", emoji: "✅" },
+        cfg,
+        accountId: undefined,
+      }),
+    ).rejects.toThrow(/targetAuthor/);
+  });
+
+  it("passes groupId and targetAuthor for group reactions", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as OpenClawConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: {
+        to: "signal:group:group-id",
+        targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
+        messageId: "123",
+        emoji: "✅",
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith("", 123, "✅", {
+      accountId: undefined,
+      groupId: "group-id",
+      targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
+      targetAuthorUuid: undefined,
+    });
+  });
+});
+
+describe("slack actions adapter", () => {
+  it("forwards threadId for read", async () => {
+    const cfg = { channels: { slack: { botToken: "tok" } } } as OpenClawConfig;
+    const actions = createSlackActions("slack");
+
+    await actions.handleAction?.({
+      channel: "slack",
+      action: "read",
+      cfg,
+      params: {
+        channelId: "C1",
+        threadId: "171234.567",
+      },
+    });
+
+    const [params] = handleSlackAction.mock.calls[0] ?? [];
+    expect(params).toMatchObject({
+      action: "readMessages",
+      channelId: "C1",
+      threadId: "171234.567",
+    });
+  });
+
+  it("forwards normalized limit for emoji-list", async () => {
+    const cfg = { channels: { slack: { botToken: "tok" } } } as OpenClawConfig;
+    const actions = createSlackActions("slack");
+
+    await actions.handleAction?.({
+      channel: "slack",
+      action: "emoji-list",
+      cfg,
+      params: {
+        limit: "2.9",
+      },
+    });
+
+    const [params] = handleSlackAction.mock.calls[0] ?? [];
+    expect(params).toMatchObject({
+      action: "emojiList",
+      limit: 2,
+    });
+  });
+});
diff --git a/src/channels/plugins/actions/discord.test.ts b/src/channels/plugins/actions/discord.test.ts
deleted file mode 100644
index fc30a0a7566..00000000000
--- a/src/channels/plugins/actions/discord.test.ts
+++ /dev/null
@@ -1,142 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../../config/config.js";
-type SendMessageDiscord = typeof import("../../../discord/send.js").sendMessageDiscord;
-type SendPollDiscord = typeof import("../../../discord/send.js").sendPollDiscord;
-
-const sendMessageDiscord = vi.fn<Parameters<SendMessageDiscord>, ReturnType<SendMessageDiscord>>(
-  async () => ({ ok: true }) as Awaited<ReturnType<SendMessageDiscord>>,
-);
-const sendPollDiscord = vi.fn<Parameters<SendPollDiscord>, ReturnType<SendPollDiscord>>(
-  async () => ({ ok: true }) as Awaited<ReturnType<SendPollDiscord>>,
-);
-
-vi.mock("../../../discord/send.js", async () => {
-  const actual = await vi.importActual<typeof import("../../../discord/send.js")>(
-    "../../../discord/send.js",
-  );
-  return {
-    ...actual,
-    sendMessageDiscord: (...args: Parameters<SendMessageDiscord>) => sendMessageDiscord(...args),
-    sendPollDiscord: (...args: Parameters<SendPollDiscord>) => sendPollDiscord(...args),
-  };
-});
-
-const { handleDiscordMessageAction } = await import("./discord/handle-action.js");
-const { discordMessageActions } = await import("./discord.js");
-
-describe("discord message actions", () => {
-  it("lists channel and upload actions by default", async () => {
-    const cfg = { channels: { discord: { token: "d0" } } } as OpenClawConfig;
-    const actions = discordMessageActions.listActions?.({ cfg }) ?? [];
-
-    expect(actions).toContain("emoji-upload");
-    expect(actions).toContain("sticker-upload");
-    expect(actions).toContain("channel-create");
-  });
-
-  it("respects disabled channel actions", async () => {
-    const cfg = {
-      channels: { discord: { token: "d0", actions: { channels: false } } },
-    } as OpenClawConfig;
-    const actions = discordMessageActions.listActions?.({ cfg }) ?? [];
-
-    expect(actions).not.toContain("channel-create");
-  });
-});
-
-describe("handleDiscordMessageAction", () => {
-  it("forwards context accountId for send", async () => {
-    sendMessageDiscord.mockClear();
-
-    await handleDiscordMessageAction({
-      action: "send",
-      params: {
-        to: "channel:123",
-        message: "hi",
-      },
-      cfg: {} as OpenClawConfig,
-      accountId: "ops",
-    });
-
-    expect(sendMessageDiscord).toHaveBeenCalledWith(
-      "channel:123",
-      "hi",
-      expect.objectContaining({
-        accountId: "ops",
-      }),
-    );
-  });
-
-  it("falls back to params accountId when context missing", async () => {
-    sendPollDiscord.mockClear();
-
-    await handleDiscordMessageAction({
-      action: "poll",
-      params: {
-        to: "channel:123",
-        pollQuestion: "Ready?",
-        pollOption: ["Yes", "No"],
-        accountId: "marve",
-      },
-      cfg: {} as OpenClawConfig,
-    });
-
-    expect(sendPollDiscord).toHaveBeenCalledWith(
-      "channel:123",
-      expect.objectContaining({
-        question: "Ready?",
-        options: ["Yes", "No"],
-      }),
-      expect.objectContaining({
-        accountId: "marve",
-      }),
-    );
-  });
-
-  it("forwards accountId for thread replies", async () => {
-    sendMessageDiscord.mockClear();
-
-    await handleDiscordMessageAction({
-      action: "thread-reply",
-      params: {
-        channelId: "123",
-        message: "hi",
-      },
-      cfg: {} as OpenClawConfig,
-      accountId: "ops",
-    });
-
-    expect(sendMessageDiscord).toHaveBeenCalledWith(
-      "channel:123",
-      "hi",
-      expect.objectContaining({
-        accountId: "ops",
-      }),
-    );
-  });
-
-  it("accepts threadId for thread replies (tool compatibility)", async () => {
-    sendMessageDiscord.mockClear();
-
-    await handleDiscordMessageAction({
-      action: "thread-reply",
-      params: {
-        // The `message` tool uses `threadId`.
-        threadId: "999",
-        // Include a conflicting channelId to ensure threadId takes precedence.
-        channelId: "123",
-        message: "hi",
-      },
-      cfg: {} as OpenClawConfig,
-      accountId: "ops",
-    });
-
-    expect(sendMessageDiscord).toHaveBeenCalledWith(
-      "channel:999",
-      "hi",
-      expect.objectContaining({
-        accountId: "ops",
-      }),
-    );
-  });
-});
diff --git a/src/channels/plugins/actions/discord/handle-action.test.ts b/src/channels/plugins/actions/discord/handle-action.test.ts
deleted file mode 100644
index 425c7d5a50e..00000000000
--- a/src/channels/plugins/actions/discord/handle-action.test.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { handleDiscordMessageAction } from "./handle-action.js";
-
-const handleDiscordAction = vi.fn(async () => ({ details: { ok: true } }));
-
-vi.mock("../../../../agents/tools/discord-actions.js", () => ({
-  handleDiscordAction: (...args: unknown[]) => handleDiscordAction(...args),
-}));
-
-describe("handleDiscordMessageAction", () => {
-  beforeEach(() => {
-    handleDiscordAction.mockClear();
-  });
-
-  it("forwards thread-create message as content", async () => {
-    await handleDiscordMessageAction({
-      action: "thread-create",
-      params: {
-        to: "channel:123456789",
-        threadName: "Forum thread",
-        message: "Initial forum post body",
-      },
-      cfg: {},
-    });
-    expect(handleDiscordAction).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "threadCreate",
-        channelId: "123456789",
-        name: "Forum thread",
-        content: "Initial forum post body",
-      }),
-      expect.any(Object),
-    );
-  });
-
-  it("forwards thread edit fields for channel-edit", async () => {
-    await handleDiscordMessageAction({
-      action: "channel-edit",
-      params: {
-        channelId: "123456789",
-        archived: true,
-        locked: false,
-        autoArchiveDuration: 1440,
-      },
-      cfg: {},
-    });
-    expect(handleDiscordAction).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "channelEdit",
-        channelId: "123456789",
-        archived: true,
-        locked: false,
-        autoArchiveDuration: 1440,
-      }),
-      expect.any(Object),
-    );
-  });
-});
diff --git a/src/channels/plugins/actions/discord/handle-action.ts b/src/channels/plugins/actions/discord/handle-action.ts
index a5797440af9..6c867d81c87 100644
--- a/src/channels/plugins/actions/discord/handle-action.ts
+++ b/src/channels/plugins/actions/discord/handle-action.ts
@@ -34,8 +34,14 @@ export async function handleDiscordMessageAction(
 
   if (action === "send") {
     const to = readStringParam(params, "to", { required: true });
+    const asVoice = params.asVoice === true;
+    const rawComponents = params.components;
+    const hasComponents =
+      Boolean(rawComponents) &&
+      (typeof rawComponents === "function" || typeof rawComponents === "object");
+    const components = hasComponents ? rawComponents : undefined;
     const content = readStringParam(params, "message", {
-      required: true,
+      required: !asVoice && !hasComponents,
       allowEmpty: true,
     });
     // Support media, path, and filePath for media URL
@@ -43,10 +49,13 @@ export async function handleDiscordMessageAction(
       readStringParam(params, "media", { trim: false }) ??
       readStringParam(params, "path", { trim: false }) ??
       readStringParam(params, "filePath", { trim: false });
+    const filename = readStringParam(params, "filename");
     const replyTo = readStringParam(params, "replyTo");
-    const embeds = Array.isArray(params.embeds) ? params.embeds : undefined;
-    const asVoice = params.asVoice === true;
+    const rawEmbeds = params.embeds;
+    const embeds = Array.isArray(rawEmbeds) ? rawEmbeds : undefined;
     const silent = params.silent === true;
+    const sessionKey = readStringParam(params, "__sessionKey");
+    const agentId = readStringParam(params, "__agentId");
     return await handleDiscordAction(
       {
         action: "sendMessage",
@@ -54,10 +63,14 @@ export async function handleDiscordMessageAction(
         to,
         content,
         mediaUrl: mediaUrl ?? undefined,
+        filename: filename ?? undefined,
         replyTo: replyTo ?? undefined,
+        components,
         embeds,
         asVoice,
         silent,
+        __sessionKey: sessionKey ?? undefined,
+        __agentId: agentId ?? undefined,
       },
       cfg,
     );
diff --git a/src/channels/plugins/actions/signal.test.ts b/src/channels/plugins/actions/signal.test.ts
deleted file mode 100644
index 613b725f77a..00000000000
--- a/src/channels/plugins/actions/signal.test.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../../config/config.js";
-import { signalMessageActions } from "./signal.js";
-
-const sendReactionSignal = vi.fn(async () => ({ ok: true }));
-const removeReactionSignal = vi.fn(async () => ({ ok: true }));
-
-vi.mock("../../../signal/send-reactions.js", () => ({
-  sendReactionSignal: (...args: unknown[]) => sendReactionSignal(...args),
-  removeReactionSignal: (...args: unknown[]) => removeReactionSignal(...args),
-}));
-
-describe("signalMessageActions", () => {
-  it("returns no actions when no configured accounts exist", () => {
-    const cfg = {} as OpenClawConfig;
-    expect(signalMessageActions.listActions({ cfg })).toEqual([]);
-  });
-
-  it("hides react when reactions are disabled", () => {
-    const cfg = {
-      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
-    } as OpenClawConfig;
-    expect(signalMessageActions.listActions({ cfg })).toEqual(["send"]);
-  });
-
-  it("enables react when at least one account allows reactions", () => {
-    const cfg = {
-      channels: {
-        signal: {
-          actions: { reactions: false },
-          accounts: {
-            work: { account: "+15550001111", actions: { reactions: true } },
-          },
-        },
-      },
-    } as OpenClawConfig;
-    expect(signalMessageActions.listActions({ cfg })).toEqual(["send", "react"]);
-  });
-
-  it("skips send for plugin dispatch", () => {
-    expect(signalMessageActions.supportsAction?.({ action: "send" })).toBe(false);
-    expect(signalMessageActions.supportsAction?.({ action: "react" })).toBe(true);
-  });
-
-  it("blocks reactions when action gate is disabled", async () => {
-    const cfg = {
-      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
-    } as OpenClawConfig;
-
-    await expect(
-      signalMessageActions.handleAction({
-        action: "react",
-        params: { to: "+15550001111", messageId: "123", emoji: "✅" },
-        cfg,
-        accountId: undefined,
-      }),
-    ).rejects.toThrow(/actions\.reactions/);
-  });
-
-  it("uses account-level actions when enabled", async () => {
-    sendReactionSignal.mockClear();
-    const cfg = {
-      channels: {
-        signal: {
-          actions: { reactions: false },
-          accounts: {
-            work: { account: "+15550001111", actions: { reactions: true } },
-          },
-        },
-      },
-    } as OpenClawConfig;
-
-    await signalMessageActions.handleAction({
-      action: "react",
-      params: { to: "+15550001111", messageId: "123", emoji: "👍" },
-      cfg,
-      accountId: "work",
-    });
-
-    expect(sendReactionSignal).toHaveBeenCalledWith("+15550001111", 123, "👍", {
-      accountId: "work",
-    });
-  });
-
-  it("normalizes uuid recipients", async () => {
-    sendReactionSignal.mockClear();
-    const cfg = {
-      channels: { signal: { account: "+15550001111" } },
-    } as OpenClawConfig;
-
-    await signalMessageActions.handleAction({
-      action: "react",
-      params: {
-        recipient: "uuid:123e4567-e89b-12d3-a456-426614174000",
-        messageId: "123",
-        emoji: "🔥",
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(sendReactionSignal).toHaveBeenCalledWith(
-      "123e4567-e89b-12d3-a456-426614174000",
-      123,
-      "🔥",
-      { accountId: undefined },
-    );
-  });
-
-  it("requires targetAuthor for group reactions", async () => {
-    const cfg = {
-      channels: { signal: { account: "+15550001111" } },
-    } as OpenClawConfig;
-
-    await expect(
-      signalMessageActions.handleAction({
-        action: "react",
-        params: { to: "signal:group:group-id", messageId: "123", emoji: "✅" },
-        cfg,
-        accountId: undefined,
-      }),
-    ).rejects.toThrow(/targetAuthor/);
-  });
-
-  it("passes groupId and targetAuthor for group reactions", async () => {
-    sendReactionSignal.mockClear();
-    const cfg = {
-      channels: { signal: { account: "+15550001111" } },
-    } as OpenClawConfig;
-
-    await signalMessageActions.handleAction({
-      action: "react",
-      params: {
-        to: "signal:group:group-id",
-        targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
-        messageId: "123",
-        emoji: "✅",
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(sendReactionSignal).toHaveBeenCalledWith("", 123, "✅", {
-      accountId: undefined,
-      groupId: "group-id",
-      targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
-      targetAuthorUuid: undefined,
-    });
-  });
-});
diff --git a/src/channels/plugins/actions/telegram.test.ts b/src/channels/plugins/actions/telegram.test.ts
deleted file mode 100644
index 21922905e53..00000000000
--- a/src/channels/plugins/actions/telegram.test.ts
+++ /dev/null
@@ -1,143 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../../config/config.js";
-import { telegramMessageActions } from "./telegram.js";
-
-const handleTelegramAction = vi.fn(async () => ({ ok: true }));
-
-vi.mock("../../../agents/tools/telegram-actions.js", () => ({
-  handleTelegramAction: (...args: unknown[]) => handleTelegramAction(...args),
-}));
-
-describe("telegramMessageActions", () => {
-  it("excludes sticker actions when not enabled", () => {
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-    const actions = telegramMessageActions.listActions({ cfg });
-    expect(actions).not.toContain("sticker");
-    expect(actions).not.toContain("sticker-search");
-  });
-
-  it("allows media-only sends and passes asVoice", async () => {
-    handleTelegramAction.mockClear();
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-
-    await telegramMessageActions.handleAction({
-      action: "send",
-      params: {
-        to: "123",
-        media: "https://example.com/voice.ogg",
-        asVoice: true,
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(handleTelegramAction).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "sendMessage",
-        to: "123",
-        content: "",
-        mediaUrl: "https://example.com/voice.ogg",
-        asVoice: true,
-      }),
-      cfg,
-    );
-  });
-
-  it("passes silent flag for silent sends", async () => {
-    handleTelegramAction.mockClear();
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-
-    await telegramMessageActions.handleAction({
-      action: "send",
-      params: {
-        to: "456",
-        message: "Silent notification test",
-        silent: true,
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(handleTelegramAction).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "sendMessage",
-        to: "456",
-        content: "Silent notification test",
-        silent: true,
-      }),
-      cfg,
-    );
-  });
-
-  it("maps edit action params into editMessage", async () => {
-    handleTelegramAction.mockClear();
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-
-    await telegramMessageActions.handleAction({
-      action: "edit",
-      params: {
-        chatId: "123",
-        messageId: 42,
-        message: "Updated",
-        buttons: [],
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(handleTelegramAction).toHaveBeenCalledWith(
-      {
-        action: "editMessage",
-        chatId: "123",
-        messageId: 42,
-        content: "Updated",
-        buttons: [],
-        accountId: undefined,
-      },
-      cfg,
-    );
-  });
-
-  it("rejects non-integer messageId for edit before reaching telegram-actions", async () => {
-    handleTelegramAction.mockClear();
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-
-    await expect(
-      telegramMessageActions.handleAction({
-        action: "edit",
-        params: {
-          chatId: "123",
-          messageId: "nope",
-          message: "Updated",
-        },
-        cfg,
-        accountId: undefined,
-      }),
-    ).rejects.toThrow();
-
-    expect(handleTelegramAction).not.toHaveBeenCalled();
-  });
-
-  it("accepts numeric messageId and channelId for reactions", async () => {
-    handleTelegramAction.mockClear();
-    const cfg = { channels: { telegram: { botToken: "tok" } } } as OpenClawConfig;
-
-    await telegramMessageActions.handleAction({
-      action: "react",
-      params: {
-        channelId: 123,
-        messageId: 456,
-        emoji: "ok",
-      },
-      cfg,
-      accountId: undefined,
-    });
-
-    expect(handleTelegramAction).toHaveBeenCalledTimes(1);
-    const call = handleTelegramAction.mock.calls[0]?.[0] as Record<string, unknown>;
-    expect(call.action).toBe("react");
-    expect(String(call.chatId)).toBe("123");
-    expect(String(call.messageId)).toBe("456");
-    expect(call.emoji).toBe("ok");
-  });
-});
diff --git a/src/channels/plugins/catalog.test.ts b/src/channels/plugins/catalog.test.ts
deleted file mode 100644
index d62fac8a8fc..00000000000
--- a/src/channels/plugins/catalog.test.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { getChannelPluginCatalogEntry, listChannelPluginCatalogEntries } from "./catalog.js";
-
-describe("channel plugin catalog", () => {
-  it("includes Microsoft Teams", () => {
-    const entry = getChannelPluginCatalogEntry("msteams");
-    expect(entry?.install.npmSpec).toBe("@openclaw/msteams");
-    expect(entry?.meta.aliases).toContain("teams");
-  });
-
-  it("lists plugin catalog entries", () => {
-    const ids = listChannelPluginCatalogEntries().map((entry) => entry.id);
-    expect(ids).toContain("msteams");
-  });
-
-  it("includes external catalog entries", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-catalog-"));
-    const catalogPath = path.join(dir, "catalog.json");
-    fs.writeFileSync(
-      catalogPath,
-      JSON.stringify({
-        entries: [
-          {
-            name: "@openclaw/demo-channel",
-            openclaw: {
-              channel: {
-                id: "demo-channel",
-                label: "Demo Channel",
-                selectionLabel: "Demo Channel",
-                docsPath: "/channels/demo-channel",
-                blurb: "Demo entry",
-                order: 999,
-              },
-              install: {
-                npmSpec: "@openclaw/demo-channel",
-              },
-            },
-          },
-        ],
-      }),
-    );
-
-    const ids = listChannelPluginCatalogEntries({ catalogPaths: [catalogPath] }).map(
-      (entry) => entry.id,
-    );
-    expect(ids).toContain("demo-channel");
-  });
-});
diff --git a/src/channels/plugins/config-writes.test.ts b/src/channels/plugins/config-writes.test.ts
deleted file mode 100644
index 00fe9164f8e..00000000000
--- a/src/channels/plugins/config-writes.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveChannelConfigWrites } from "./config-writes.js";
-
-describe("resolveChannelConfigWrites", () => {
-  it("defaults to allow when unset", () => {
-    const cfg = {};
-    expect(resolveChannelConfigWrites({ cfg, channelId: "slack" })).toBe(true);
-  });
-
-  it("blocks when channel config disables writes", () => {
-    const cfg = { channels: { slack: { configWrites: false } } };
-    expect(resolveChannelConfigWrites({ cfg, channelId: "slack" })).toBe(false);
-  });
-
-  it("account override wins over channel default", () => {
-    const cfg = {
-      channels: {
-        slack: {
-          configWrites: true,
-          accounts: {
-            work: { configWrites: false },
-          },
-        },
-      },
-    };
-    expect(resolveChannelConfigWrites({ cfg, channelId: "slack", accountId: "work" })).toBe(false);
-  });
-
-  it("matches account ids case-insensitively", () => {
-    const cfg = {
-      channels: {
-        slack: {
-          configWrites: true,
-          accounts: {
-            Work: { configWrites: false },
-          },
-        },
-      },
-    };
-    expect(resolveChannelConfigWrites({ cfg, channelId: "slack", accountId: "work" })).toBe(false);
-  });
-});
diff --git a/src/channels/plugins/directory-config.test.ts b/src/channels/plugins/directory-config.test.ts
deleted file mode 100644
index ab043e1b36d..00000000000
--- a/src/channels/plugins/directory-config.test.ts
+++ /dev/null
@@ -1,146 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  listDiscordDirectoryGroupsFromConfig,
-  listDiscordDirectoryPeersFromConfig,
-  listSlackDirectoryGroupsFromConfig,
-  listSlackDirectoryPeersFromConfig,
-  listTelegramDirectoryGroupsFromConfig,
-  listTelegramDirectoryPeersFromConfig,
-  listWhatsAppDirectoryGroupsFromConfig,
-  listWhatsAppDirectoryPeersFromConfig,
-} from "./directory-config.js";
-
-describe("directory (config-backed)", () => {
-  it("lists Slack peers/groups from config", async () => {
-    const cfg = {
-      channels: {
-        slack: {
-          botToken: "xoxb-test",
-          appToken: "xapp-test",
-          dm: { allowFrom: ["U123", "user:U999"] },
-          dms: { U234: {} },
-          channels: { C111: { users: ["U777"] } },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    const peers = await listSlackDirectoryPeersFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(peers?.map((e) => e.id).toSorted()).toEqual([
-      "user:u123",
-      "user:u234",
-      "user:u777",
-      "user:u999",
-    ]);
-
-    const groups = await listSlackDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(groups?.map((e) => e.id)).toEqual(["channel:c111"]);
-  });
-
-  it("lists Discord peers/groups from config (numeric ids only)", async () => {
-    const cfg = {
-      channels: {
-        discord: {
-          token: "discord-test",
-          dm: { allowFrom: ["<@111>", "nope"] },
-          dms: { "222": {} },
-          guilds: {
-            "123": {
-              users: ["<@12345>", "not-an-id"],
-              channels: {
-                "555": {},
-                "channel:666": {},
-                general: {},
-              },
-            },
-          },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    const peers = await listDiscordDirectoryPeersFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(peers?.map((e) => e.id).toSorted()).toEqual(["user:111", "user:12345", "user:222"]);
-
-    const groups = await listDiscordDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(groups?.map((e) => e.id).toSorted()).toEqual(["channel:555", "channel:666"]);
-  });
-
-  it("lists Telegram peers/groups from config", async () => {
-    const cfg = {
-      channels: {
-        telegram: {
-          botToken: "telegram-test",
-          allowFrom: ["123", "alice", "tg:@bob"],
-          dms: { "456": {} },
-          groups: { "-1001": {}, "*": {} },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    const peers = await listTelegramDirectoryPeersFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(peers?.map((e) => e.id).toSorted()).toEqual(["123", "456", "@alice", "@bob"]);
-
-    const groups = await listTelegramDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(groups?.map((e) => e.id)).toEqual(["-1001"]);
-  });
-
-  it("lists WhatsApp peers/groups from config", async () => {
-    const cfg = {
-      channels: {
-        whatsapp: {
-          allowFrom: ["+15550000000", "*", "123@g.us"],
-          groups: { "999@g.us": { requireMention: true }, "*": {} },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    const peers = await listWhatsAppDirectoryPeersFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(peers?.map((e) => e.id)).toEqual(["+15550000000"]);
-
-    const groups = await listWhatsAppDirectoryGroupsFromConfig({
-      cfg,
-      accountId: "default",
-      query: null,
-      limit: null,
-    });
-    expect(groups?.map((e) => e.id)).toEqual(["999@g.us"]);
-  });
-});
diff --git a/src/channels/plugins/directory-config.ts b/src/channels/plugins/directory-config.ts
index 3b57bd082c9..2593878d204 100644
--- a/src/channels/plugins/directory-config.ts
+++ b/src/channels/plugins/directory-config.ts
@@ -14,6 +14,26 @@ export type DirectoryConfigParams = {
   limit?: number | null;
 };
 
+function addAllowFromAndDmsIds(
+  ids: Set<string>,
+  allowFrom: readonly unknown[] | undefined,
+  dms: Record<string, unknown> | undefined,
+) {
+  for (const entry of allowFrom ?? []) {
+    const raw = String(entry).trim();
+    if (!raw || raw === "*") {
+      continue;
+    }
+    ids.add(raw);
+  }
+  for (const id of Object.keys(dms ?? {})) {
+    const trimmed = id.trim();
+    if (trimmed) {
+      ids.add(trimmed);
+    }
+  }
+}
+
 export async function listSlackDirectoryPeersFromConfig(
   params: DirectoryConfigParams,
 ): Promise<ChannelDirectoryEntry[]> {
@@ -21,19 +41,7 @@ export async function listSlackDirectoryPeersFromConfig(
   const q = params.query?.trim().toLowerCase() || "";
   const ids = new Set<string>();
 
-  for (const entry of account.config.allowFrom ?? account.dm?.allowFrom ?? []) {
-    const raw = String(entry).trim();
-    if (!raw || raw === "*") {
-      continue;
-    }
-    ids.add(raw);
-  }
-  for (const id of Object.keys(account.config.dms ?? {})) {
-    const trimmed = id.trim();
-    if (trimmed) {
-      ids.add(trimmed);
-    }
-  }
+  addAllowFromAndDmsIds(ids, account.config.allowFrom ?? account.dm?.allowFrom, account.config.dms);
   for (const channel of Object.values(account.config.channels ?? {})) {
     for (const user of channel.users ?? []) {
       const raw = String(user).trim();
@@ -84,19 +92,11 @@ export async function listDiscordDirectoryPeersFromConfig(
   const q = params.query?.trim().toLowerCase() || "";
   const ids = new Set<string>();
 
-  for (const entry of account.config.allowFrom ?? account.config.dm?.allowFrom ?? []) {
-    const raw = String(entry).trim();
-    if (!raw || raw === "*") {
-      continue;
-    }
-    ids.add(raw);
-  }
-  for (const id of Object.keys(account.config.dms ?? {})) {
-    const trimmed = id.trim();
-    if (trimmed) {
-      ids.add(trimmed);
-    }
-  }
+  addAllowFromAndDmsIds(
+    ids,
+    account.config.allowFrom ?? account.config.dm?.allowFrom,
+    account.config.dms,
+  );
   for (const guild of Object.values(account.config.guilds ?? {})) {
     for (const entry of guild.users ?? []) {
       const raw = String(entry).trim();
diff --git a/src/channels/plugins/group-mentions.ts b/src/channels/plugins/group-mentions.ts
index 708b4d3c190..e7369146480 100644
--- a/src/channels/plugins/group-mentions.ts
+++ b/src/channels/plugins/group-mentions.ts
@@ -120,6 +120,24 @@ function resolveDiscordGuildEntry(guilds: DiscordConfig["guilds"], groupSpace?:
   return guilds["*"] ?? null;
 }
 
+function resolveDiscordChannelEntry<TEntry>(
+  channelEntries: Record<string, TEntry> | undefined,
+  params: { groupId?: string | null; groupChannel?: string | null },
+): TEntry | undefined {
+  if (!channelEntries || Object.keys(channelEntries).length === 0) {
+    return undefined;
+  }
+  const groupChannel = params.groupChannel;
+  const channelSlug = normalizeDiscordSlug(groupChannel);
+  return (
+    (params.groupId ? channelEntries[params.groupId] : undefined) ??
+    (channelSlug
+      ? (channelEntries[channelSlug] ?? channelEntries[`#${channelSlug}`])
+      : undefined) ??
+    (groupChannel ? channelEntries[normalizeDiscordSlug(groupChannel)] : undefined)
+  );
+}
+
 export function resolveTelegramGroupRequireMention(
   params: GroupMentionParams,
 ): boolean | undefined {
@@ -165,14 +183,7 @@ export function resolveDiscordGroupRequireMention(params: GroupMentionParams): b
   );
   const channelEntries = guildEntry?.channels;
   if (channelEntries && Object.keys(channelEntries).length > 0) {
-    const groupChannel = params.groupChannel;
-    const channelSlug = normalizeDiscordSlug(groupChannel);
-    const entry =
-      (params.groupId ? channelEntries[params.groupId] : undefined) ??
-      (channelSlug
-        ? (channelEntries[channelSlug] ?? channelEntries[`#${channelSlug}`])
-        : undefined) ??
-      (groupChannel ? channelEntries[normalizeDiscordSlug(groupChannel)] : undefined);
+    const entry = resolveDiscordChannelEntry(channelEntries, params);
     if (entry && typeof entry.requireMention === "boolean") {
       return entry.requireMention;
     }
@@ -306,14 +317,7 @@ export function resolveDiscordGroupToolPolicy(
   );
   const channelEntries = guildEntry?.channels;
   if (channelEntries && Object.keys(channelEntries).length > 0) {
-    const groupChannel = params.groupChannel;
-    const channelSlug = normalizeDiscordSlug(groupChannel);
-    const entry =
-      (params.groupId ? channelEntries[params.groupId] : undefined) ??
-      (channelSlug
-        ? (channelEntries[channelSlug] ?? channelEntries[`#${channelSlug}`])
-        : undefined) ??
-      (groupChannel ? channelEntries[normalizeDiscordSlug(groupChannel)] : undefined);
+    const entry = resolveDiscordChannelEntry(channelEntries, params);
     const senderPolicy = resolveToolsBySender({
       toolsBySender: entry?.toolsBySender,
       senderId: params.senderId,
diff --git a/src/channels/plugins/index.test.ts b/src/channels/plugins/index.test.ts
deleted file mode 100644
index 63162f09018..00000000000
--- a/src/channels/plugins/index.test.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import type { ChannelPlugin } from "./types.js";
-import { setActivePluginRegistry } from "../../plugins/runtime.js";
-import { createTestRegistry } from "../../test-utils/channel-plugins.js";
-import { listChannelPlugins } from "./index.js";
-
-describe("channel plugin registry", () => {
-  const emptyRegistry = createTestRegistry([]);
-
-  const createPlugin = (id: string): ChannelPlugin => ({
-    id,
-    meta: {
-      id,
-      label: id,
-      selectionLabel: id,
-      docsPath: `/channels/${id}`,
-      blurb: "test",
-    },
-    capabilities: { chatTypes: ["direct"] },
-    config: {
-      listAccountIds: () => [],
-      resolveAccount: () => ({}),
-    },
-  });
-
-  beforeEach(() => {
-    setActivePluginRegistry(emptyRegistry);
-  });
-
-  afterEach(() => {
-    setActivePluginRegistry(emptyRegistry);
-  });
-
-  it("sorts channel plugins by configured order", () => {
-    const registry = createTestRegistry(
-      ["slack", "telegram", "signal"].map((id) => ({
-        pluginId: id,
-        plugin: createPlugin(id),
-        source: "test",
-      })),
-    );
-    setActivePluginRegistry(registry);
-    const pluginIds = listChannelPlugins().map((plugin) => plugin.id);
-    expect(pluginIds).toEqual(["telegram", "slack", "signal"]);
-  });
-});
diff --git a/src/channels/plugins/load.test.ts b/src/channels/plugins/load.test.ts
deleted file mode 100644
index f3daf0543c7..00000000000
--- a/src/channels/plugins/load.test.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import type { PluginRegistry } from "../../plugins/registry.js";
-import type { ChannelOutboundAdapter, ChannelPlugin } from "./types.js";
-import { setActivePluginRegistry } from "../../plugins/runtime.js";
-import { loadChannelPlugin } from "./load.js";
-import { loadChannelOutboundAdapter } from "./outbound/load.js";
-
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
-const emptyRegistry = createRegistry([]);
-
-const msteamsOutbound: ChannelOutboundAdapter = {
-  deliveryMode: "direct",
-  sendText: async () => ({ channel: "msteams", messageId: "m1" }),
-  sendMedia: async () => ({ channel: "msteams", messageId: "m2" }),
-};
-
-const msteamsPlugin: ChannelPlugin = {
-  id: "msteams",
-  meta: {
-    id: "msteams",
-    label: "Microsoft Teams",
-    selectionLabel: "Microsoft Teams (Bot Framework)",
-    docsPath: "/channels/msteams",
-    blurb: "Bot Framework; enterprise support.",
-    aliases: ["teams"],
-  },
-  capabilities: { chatTypes: ["direct"] },
-  config: {
-    listAccountIds: () => [],
-    resolveAccount: () => ({}),
-  },
-  outbound: msteamsOutbound,
-};
-
-const registryWithMSTeams = createRegistry([
-  { pluginId: "msteams", plugin: msteamsPlugin, source: "test" },
-]);
-
-describe("channel plugin loader", () => {
-  beforeEach(() => {
-    setActivePluginRegistry(emptyRegistry);
-  });
-
-  afterEach(() => {
-    setActivePluginRegistry(emptyRegistry);
-  });
-
-  it("loads channel plugins from the active registry", async () => {
-    setActivePluginRegistry(registryWithMSTeams);
-    const plugin = await loadChannelPlugin("msteams");
-    expect(plugin).toBe(msteamsPlugin);
-  });
-
-  it("loads outbound adapters from registered plugins", async () => {
-    setActivePluginRegistry(registryWithMSTeams);
-    const outbound = await loadChannelOutboundAdapter("msteams");
-    expect(outbound).toBe(msteamsOutbound);
-  });
-});
diff --git a/src/channels/plugins/normalize/imessage.test.ts b/src/channels/plugins/normalize/imessage.test.ts
deleted file mode 100644
index a3cbf0501eb..00000000000
--- a/src/channels/plugins/normalize/imessage.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeIMessageMessagingTarget } from "./imessage.js";
-
-describe("imessage target normalization", () => {
-  it("preserves service prefixes for handles", () => {
-    expect(normalizeIMessageMessagingTarget("sms:+1 (555) 222-3333")).toBe("sms:+15552223333");
-  });
-
-  it("drops service prefixes for chat targets", () => {
-    expect(normalizeIMessageMessagingTarget("sms:chat_id:123")).toBe("chat_id:123");
-    expect(normalizeIMessageMessagingTarget("imessage:CHAT_GUID:abc")).toBe("chat_guid:abc");
-    expect(normalizeIMessageMessagingTarget("auto:ChatIdentifier:foo")).toBe("chat_identifier:foo");
-  });
-});
diff --git a/src/channels/plugins/normalize/signal.test.ts b/src/channels/plugins/normalize/signal.test.ts
deleted file mode 100644
index 547a8f30d91..00000000000
--- a/src/channels/plugins/normalize/signal.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { looksLikeSignalTargetId, normalizeSignalMessagingTarget } from "./signal.js";
-
-describe("signal target normalization", () => {
-  it("normalizes uuid targets by stripping uuid:", () => {
-    expect(normalizeSignalMessagingTarget("uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
-      "123e4567-e89b-12d3-a456-426614174000",
-    );
-  });
-
-  it("normalizes signal:uuid targets", () => {
-    expect(normalizeSignalMessagingTarget("signal:uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
-      "123e4567-e89b-12d3-a456-426614174000",
-    );
-  });
-
-  it("preserves case for group targets", () => {
-    expect(
-      normalizeSignalMessagingTarget("signal:group:VWATOdKF2hc8zdOS76q9tb0+5BI522e03QLDAq/9yPg="),
-    ).toBe("group:VWATOdKF2hc8zdOS76q9tb0+5BI522e03QLDAq/9yPg=");
-  });
-
-  it("accepts uuid prefixes for target detection", () => {
-    expect(looksLikeSignalTargetId("uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
-    expect(looksLikeSignalTargetId("signal:uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
-  });
-
-  it("accepts compact UUIDs for target detection", () => {
-    expect(looksLikeSignalTargetId("123e4567e89b12d3a456426614174000")).toBe(true);
-    expect(looksLikeSignalTargetId("uuid:123e4567e89b12d3a456426614174000")).toBe(true);
-  });
-
-  it("rejects invalid uuid prefixes", () => {
-    expect(looksLikeSignalTargetId("uuid:")).toBe(false);
-    expect(looksLikeSignalTargetId("uuid:not-a-uuid")).toBe(false);
-  });
-});
diff --git a/src/channels/plugins/onboarding/signal.test.ts b/src/channels/plugins/onboarding/signal.test.ts
deleted file mode 100644
index 23f218bd4c4..00000000000
--- a/src/channels/plugins/onboarding/signal.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeSignalAccountInput } from "./signal.js";
-
-describe("normalizeSignalAccountInput", () => {
-  it("accepts already normalized numbers", () => {
-    expect(normalizeSignalAccountInput("+15555550123")).toBe("+15555550123");
-  });
-
-  it("normalizes formatted input", () => {
-    expect(normalizeSignalAccountInput("  +1 (555) 000-1234 ")).toBe("+15550001234");
-  });
-
-  it("rejects empty input", () => {
-    expect(normalizeSignalAccountInput("   ")).toBeNull();
-  });
-
-  it("rejects non-numeric input", () => {
-    expect(normalizeSignalAccountInput("ok")).toBeNull();
-    expect(normalizeSignalAccountInput("++--")).toBeNull();
-  });
-
-  it("rejects inputs with stray + characters", () => {
-    expect(normalizeSignalAccountInput("++12345")).toBeNull();
-    expect(normalizeSignalAccountInput("+1+2345")).toBeNull();
-  });
-
-  it("rejects numbers that are too short or too long", () => {
-    expect(normalizeSignalAccountInput("+1234")).toBeNull();
-    expect(normalizeSignalAccountInput("+1234567890123456")).toBeNull();
-  });
-});
diff --git a/src/channels/plugins/onboarding/slack.ts b/src/channels/plugins/onboarding/slack.ts
index daacc66fede..f1aa29b7c11 100644
--- a/src/channels/plugins/onboarding/slack.ts
+++ b/src/channels/plugins/onboarding/slack.ts
@@ -124,6 +124,25 @@ async function noteSlackTokenHelp(prompter: WizardPrompter, botName: string): Pr
   );
 }
 
+async function promptSlackTokens(prompter: WizardPrompter): Promise<{
+  botToken: string;
+  appToken: string;
+}> {
+  const botToken = String(
+    await prompter.text({
+      message: "Enter Slack bot token (xoxb-...)",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  const appToken = String(
+    await prompter.text({
+      message: "Enter Slack app token (xapp-...)",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    }),
+  ).trim();
+  return { botToken, appToken };
+}
+
 function patchSlackConfigForAccount(
   cfg: OpenClawConfig,
   accountId: string,
@@ -370,18 +389,7 @@ export const slackOnboardingAdapter: ChannelOnboardingAdapter = {
           },
         };
       } else {
-        botToken = String(
-          await prompter.text({
-            message: "Enter Slack bot token (xoxb-...)",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appToken = String(
-          await prompter.text({
-            message: "Enter Slack app token (xapp-...)",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        ({ botToken, appToken } = await promptSlackTokens(prompter));
       }
     } else if (hasConfigTokens) {
       const keep = await prompter.confirm({
@@ -389,32 +397,10 @@ export const slackOnboardingAdapter: ChannelOnboardingAdapter = {
         initialValue: true,
       });
       if (!keep) {
-        botToken = String(
-          await prompter.text({
-            message: "Enter Slack bot token (xoxb-...)",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
-        appToken = String(
-          await prompter.text({
-            message: "Enter Slack app token (xapp-...)",
-            validate: (value) => (value?.trim() ? undefined : "Required"),
-          }),
-        ).trim();
+        ({ botToken, appToken } = await promptSlackTokens(prompter));
       }
     } else {
-      botToken = String(
-        await prompter.text({
-          message: "Enter Slack bot token (xoxb-...)",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
-      appToken = String(
-        await prompter.text({
-          message: "Enter Slack app token (xapp-...)",
-          validate: (value) => (value?.trim() ? undefined : "Required"),
-        }),
-      ).trim();
+      ({ botToken, appToken } = await promptSlackTokens(prompter));
     }
 
     if (botToken && appToken) {
diff --git a/src/channels/plugins/onboarding/whatsapp.ts b/src/channels/plugins/onboarding/whatsapp.ts
index 3a140ee49d7..e640c8a3989 100644
--- a/src/channels/plugins/onboarding/whatsapp.ts
+++ b/src/channels/plugins/onboarding/whatsapp.ts
@@ -79,6 +79,27 @@ async function promptWhatsAppOwnerAllowFrom(params: {
   return { normalized, allowFrom };
 }
 
+async function applyWhatsAppOwnerAllowlist(params: {
+  cfg: OpenClawConfig;
+  prompter: WizardPrompter;
+  existingAllowFrom: string[];
+  title: string;
+  messageLines: string[];
+}): Promise<OpenClawConfig> {
+  const { normalized, allowFrom } = await promptWhatsAppOwnerAllowFrom({
+    prompter: params.prompter,
+    existingAllowFrom: params.existingAllowFrom,
+  });
+  let next = setWhatsAppSelfChatMode(params.cfg, true);
+  next = setWhatsAppDmPolicy(next, "allowlist");
+  next = setWhatsAppAllowFrom(next, allowFrom);
+  await params.prompter.note(
+    [...params.messageLines, `- allowFrom includes ${normalized}`].join("\n"),
+    params.title,
+  );
+  return next;
+}
+
 async function promptWhatsAppAllowFrom(
   cfg: OpenClawConfig,
   _runtime: RuntimeEnv,
@@ -90,18 +111,13 @@ async function promptWhatsAppAllowFrom(
   const existingLabel = existingAllowFrom.length > 0 ? existingAllowFrom.join(", ") : "unset";
 
   if (options?.forceAllowlist) {
-    const { normalized, allowFrom } = await promptWhatsAppOwnerAllowFrom({
+    return await applyWhatsAppOwnerAllowlist({
+      cfg,
       prompter,
       existingAllowFrom,
+      title: "WhatsApp allowlist",
+      messageLines: ["Allowlist mode enabled."],
     });
-    let next = setWhatsAppSelfChatMode(cfg, true);
-    next = setWhatsAppDmPolicy(next, "allowlist");
-    next = setWhatsAppAllowFrom(next, allowFrom);
-    await prompter.note(
-      ["Allowlist mode enabled.", `- allowFrom includes ${normalized}`].join("\n"),
-      "WhatsApp allowlist",
-    );
-    return next;
   }
 
   await prompter.note(
@@ -127,22 +143,16 @@ async function promptWhatsAppAllowFrom(
   });
 
   if (phoneMode === "personal") {
-    const { normalized, allowFrom } = await promptWhatsAppOwnerAllowFrom({
+    return await applyWhatsAppOwnerAllowlist({
+      cfg,
       prompter,
       existingAllowFrom,
-    });
-    let next = setWhatsAppSelfChatMode(cfg, true);
-    next = setWhatsAppDmPolicy(next, "allowlist");
-    next = setWhatsAppAllowFrom(next, allowFrom);
-    await prompter.note(
-      [
+      title: "WhatsApp personal phone",
+      messageLines: [
         "Personal phone mode enabled.",
         "- dmPolicy set to allowlist (pairing skipped)",
-        `- allowFrom includes ${normalized}`,
-      ].join("\n"),
-      "WhatsApp personal phone",
-    );
-    return next;
+      ],
+    });
   }
 
   const policy = (await prompter.select({
diff --git a/src/channels/plugins/outbound/imessage.ts b/src/channels/plugins/outbound/imessage.ts
index 8aab8c5f916..13d79849f12 100644
--- a/src/channels/plugins/outbound/imessage.ts
+++ b/src/channels/plugins/outbound/imessage.ts
@@ -3,6 +3,19 @@ import { chunkText } from "../../../auto-reply/chunk.js";
 import { sendMessageIMessage } from "../../../imessage/send.js";
 import { resolveChannelMediaMaxBytes } from "../media-limits.js";
 
+function resolveIMessageMaxBytes(params: {
+  cfg: Parameters<typeof resolveChannelMediaMaxBytes>[0]["cfg"];
+  accountId?: string | null;
+}) {
+  return resolveChannelMediaMaxBytes({
+    cfg: params.cfg,
+    resolveChannelLimitMb: ({ cfg, accountId }) =>
+      cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
+      cfg.channels?.imessage?.mediaMaxMb,
+    accountId: params.accountId,
+  });
+}
+
 export const imessageOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunker: chunkText,
@@ -10,13 +23,7 @@ export const imessageOutbound: ChannelOutboundAdapter = {
   textChunkLimit: 4000,
   sendText: async ({ cfg, to, text, accountId, deps }) => {
     const send = deps?.sendIMessage ?? sendMessageIMessage;
-    const maxBytes = resolveChannelMediaMaxBytes({
-      cfg,
-      resolveChannelLimitMb: ({ cfg, accountId }) =>
-        cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
-        cfg.channels?.imessage?.mediaMaxMb,
-      accountId,
-    });
+    const maxBytes = resolveIMessageMaxBytes({ cfg, accountId });
     const result = await send(to, text, {
       maxBytes,
       accountId: accountId ?? undefined,
@@ -25,13 +32,7 @@ export const imessageOutbound: ChannelOutboundAdapter = {
   },
   sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId, deps }) => {
     const send = deps?.sendIMessage ?? sendMessageIMessage;
-    const maxBytes = resolveChannelMediaMaxBytes({
-      cfg,
-      resolveChannelLimitMb: ({ cfg, accountId }) =>
-        cfg.channels?.imessage?.accounts?.[accountId]?.mediaMaxMb ??
-        cfg.channels?.imessage?.mediaMaxMb,
-      accountId,
-    });
+    const maxBytes = resolveIMessageMaxBytes({ cfg, accountId });
     const result = await send(to, text, {
       mediaUrl,
       maxBytes,
diff --git a/src/channels/plugins/outbound/signal.ts b/src/channels/plugins/outbound/signal.ts
index 45544b417da..b96615b1486 100644
--- a/src/channels/plugins/outbound/signal.ts
+++ b/src/channels/plugins/outbound/signal.ts
@@ -3,6 +3,18 @@ import { chunkText } from "../../../auto-reply/chunk.js";
 import { sendMessageSignal } from "../../../signal/send.js";
 import { resolveChannelMediaMaxBytes } from "../media-limits.js";
 
+function resolveSignalMaxBytes(params: {
+  cfg: Parameters<typeof resolveChannelMediaMaxBytes>[0]["cfg"];
+  accountId?: string | null;
+}) {
+  return resolveChannelMediaMaxBytes({
+    cfg: params.cfg,
+    resolveChannelLimitMb: ({ cfg, accountId }) =>
+      cfg.channels?.signal?.accounts?.[accountId]?.mediaMaxMb ?? cfg.channels?.signal?.mediaMaxMb,
+    accountId: params.accountId,
+  });
+}
+
 export const signalOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunker: chunkText,
@@ -10,12 +22,7 @@ export const signalOutbound: ChannelOutboundAdapter = {
   textChunkLimit: 4000,
   sendText: async ({ cfg, to, text, accountId, deps }) => {
     const send = deps?.sendSignal ?? sendMessageSignal;
-    const maxBytes = resolveChannelMediaMaxBytes({
-      cfg,
-      resolveChannelLimitMb: ({ cfg, accountId }) =>
-        cfg.channels?.signal?.accounts?.[accountId]?.mediaMaxMb ?? cfg.channels?.signal?.mediaMaxMb,
-      accountId,
-    });
+    const maxBytes = resolveSignalMaxBytes({ cfg, accountId });
     const result = await send(to, text, {
       maxBytes,
       accountId: accountId ?? undefined,
@@ -24,12 +31,7 @@ export const signalOutbound: ChannelOutboundAdapter = {
   },
   sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots, accountId, deps }) => {
     const send = deps?.sendSignal ?? sendMessageSignal;
-    const maxBytes = resolveChannelMediaMaxBytes({
-      cfg,
-      resolveChannelLimitMb: ({ cfg, accountId }) =>
-        cfg.channels?.signal?.accounts?.[accountId]?.mediaMaxMb ?? cfg.channels?.signal?.mediaMaxMb,
-      accountId,
-    });
+    const maxBytes = resolveSignalMaxBytes({ cfg, accountId });
     const result = await send(to, text, {
       mediaUrl,
       maxBytes,
diff --git a/src/channels/plugins/outbound/slack.ts b/src/channels/plugins/outbound/slack.ts
index d7c05ea8d7f..b5bd4273fbd 100644
--- a/src/channels/plugins/outbound/slack.ts
+++ b/src/channels/plugins/outbound/slack.ts
@@ -46,36 +46,63 @@ async function applySlackMessageSendingHooks(params: {
   return { cancelled: false, text: hookResult?.content ?? params.text };
 }
 
+async function sendSlackOutboundMessage(params: {
+  to: string;
+  text: string;
+  mediaUrl?: string;
+  mediaLocalRoots?: readonly string[];
+  accountId?: string | null;
+  deps?: { sendSlack?: typeof sendMessageSlack } | null;
+  replyToId?: string | null;
+  threadId?: string | number | null;
+  identity?: OutboundIdentity;
+}) {
+  const send = params.deps?.sendSlack ?? sendMessageSlack;
+  // Use threadId fallback so routed tool notifications stay in the Slack thread.
+  const threadTs =
+    params.replyToId ?? (params.threadId != null ? String(params.threadId) : undefined);
+  const hookResult = await applySlackMessageSendingHooks({
+    to: params.to,
+    text: params.text,
+    threadTs,
+    mediaUrl: params.mediaUrl,
+    accountId: params.accountId ?? undefined,
+  });
+  if (hookResult.cancelled) {
+    return {
+      channel: "slack" as const,
+      messageId: "cancelled-by-hook",
+      channelId: params.to,
+      meta: { cancelled: true },
+    };
+  }
+
+  const slackIdentity = resolveSlackSendIdentity(params.identity);
+  const result = await send(params.to, hookResult.text, {
+    threadTs,
+    accountId: params.accountId ?? undefined,
+    ...(params.mediaUrl
+      ? { mediaUrl: params.mediaUrl, mediaLocalRoots: params.mediaLocalRoots }
+      : {}),
+    ...(slackIdentity ? { identity: slackIdentity } : {}),
+  });
+  return { channel: "slack" as const, ...result };
+}
+
 export const slackOutbound: ChannelOutboundAdapter = {
   deliveryMode: "direct",
   chunker: null,
   textChunkLimit: 4000,
   sendText: async ({ to, text, accountId, deps, replyToId, threadId, identity }) => {
-    const send = deps?.sendSlack ?? sendMessageSlack;
-    // Use threadId fallback so routed tool notifications stay in the Slack thread.
-    const threadTs = replyToId ?? (threadId != null ? String(threadId) : undefined);
-    const hookResult = await applySlackMessageSendingHooks({
+    return await sendSlackOutboundMessage({
       to,
       text,
-      threadTs,
-      accountId: accountId ?? undefined,
+      accountId,
+      deps,
+      replyToId,
+      threadId,
+      identity,
     });
-    if (hookResult.cancelled) {
-      return {
-        channel: "slack",
-        messageId: "cancelled-by-hook",
-        channelId: to,
-        meta: { cancelled: true },
-      };
-    }
-
-    const slackIdentity = resolveSlackSendIdentity(identity);
-    const result = await send(to, hookResult.text, {
-      threadTs,
-      accountId: accountId ?? undefined,
-      ...(slackIdentity ? { identity: slackIdentity } : {}),
-    });
-    return { channel: "slack", ...result };
   },
   sendMedia: async ({
     to,
@@ -88,33 +115,16 @@ export const slackOutbound: ChannelOutboundAdapter = {
     threadId,
     identity,
   }) => {
-    const send = deps?.sendSlack ?? sendMessageSlack;
-    // Use threadId fallback so routed tool notifications stay in the Slack thread.
-    const threadTs = replyToId ?? (threadId != null ? String(threadId) : undefined);
-    const hookResult = await applySlackMessageSendingHooks({
+    return await sendSlackOutboundMessage({
       to,
       text,
-      threadTs,
-      mediaUrl,
-      accountId: accountId ?? undefined,
-    });
-    if (hookResult.cancelled) {
-      return {
-        channel: "slack",
-        messageId: "cancelled-by-hook",
-        channelId: to,
-        meta: { cancelled: true },
-      };
-    }
-
-    const slackIdentity = resolveSlackSendIdentity(identity);
-    const result = await send(to, hookResult.text, {
       mediaUrl,
       mediaLocalRoots,
-      threadTs,
-      accountId: accountId ?? undefined,
-      ...(slackIdentity ? { identity: slackIdentity } : {}),
+      accountId,
+      deps,
+      replyToId,
+      threadId,
+      identity,
     });
-    return { channel: "slack", ...result };
   },
 };
diff --git a/src/channels/plugins/outbound/telegram.test.ts b/src/channels/plugins/outbound/telegram.test.ts
deleted file mode 100644
index 7981addf566..00000000000
--- a/src/channels/plugins/outbound/telegram.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../../config/config.js";
-import { telegramOutbound } from "./telegram.js";
-
-describe("telegramOutbound.sendPayload", () => {
-  it("sends text payload with buttons", async () => {
-    const sendTelegram = vi.fn(async () => ({ messageId: "m1", chatId: "c1" }));
-
-    const result = await telegramOutbound.sendPayload?.({
-      cfg: {} as OpenClawConfig,
-      to: "telegram:123",
-      text: "ignored",
-      payload: {
-        text: "Hello",
-        channelData: {
-          telegram: {
-            buttons: [[{ text: "Option", callback_data: "/option" }]],
-          },
-        },
-      },
-      deps: { sendTelegram },
-    });
-
-    expect(sendTelegram).toHaveBeenCalledTimes(1);
-    expect(sendTelegram).toHaveBeenCalledWith(
-      "telegram:123",
-      "Hello",
-      expect.objectContaining({
-        buttons: [[{ text: "Option", callback_data: "/option" }]],
-        textMode: "html",
-      }),
-    );
-    expect(result).toEqual({ channel: "telegram", messageId: "m1", chatId: "c1" });
-  });
-
-  it("sends media payloads and attaches buttons only to first", async () => {
-    const sendTelegram = vi
-      .fn()
-      .mockResolvedValueOnce({ messageId: "m1", chatId: "c1" })
-      .mockResolvedValueOnce({ messageId: "m2", chatId: "c1" });
-
-    const result = await telegramOutbound.sendPayload?.({
-      cfg: {} as OpenClawConfig,
-      to: "telegram:123",
-      text: "ignored",
-      payload: {
-        text: "Caption",
-        mediaUrls: ["https://example.com/a.png", "https://example.com/b.png"],
-        channelData: {
-          telegram: {
-            buttons: [[{ text: "Go", callback_data: "/go" }]],
-          },
-        },
-      },
-      deps: { sendTelegram },
-    });
-
-    expect(sendTelegram).toHaveBeenCalledTimes(2);
-    expect(sendTelegram).toHaveBeenNthCalledWith(
-      1,
-      "telegram:123",
-      "Caption",
-      expect.objectContaining({
-        mediaUrl: "https://example.com/a.png",
-        buttons: [[{ text: "Go", callback_data: "/go" }]],
-      }),
-    );
-    const secondOpts = sendTelegram.mock.calls[1]?.[2] as { buttons?: unknown } | undefined;
-    expect(sendTelegram).toHaveBeenNthCalledWith(
-      2,
-      "telegram:123",
-      "",
-      expect.objectContaining({
-        mediaUrl: "https://example.com/b.png",
-      }),
-    );
-    expect(secondOpts?.buttons).toBeUndefined();
-    expect(result).toEqual({ channel: "telegram", messageId: "m2", chatId: "c1" });
-  });
-});
diff --git a/src/channels/plugins/outbound/whatsapp.test.ts b/src/channels/plugins/outbound/whatsapp.test.ts
deleted file mode 100644
index 7922ed00795..00000000000
--- a/src/channels/plugins/outbound/whatsapp.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { whatsappOutbound } from "./whatsapp.js";
-
-describe("whatsappOutbound.resolveTarget", () => {
-  it("returns error when no target is provided even with allowFrom", () => {
-    const result = whatsappOutbound.resolveTarget?.({
-      to: undefined,
-      allowFrom: ["+15551234567"],
-      mode: "implicit",
-    });
-
-    expect(result).toEqual({
-      ok: false,
-      error: expect.any(Error),
-    });
-  });
-
-  it("returns error when implicit target is not in allowFrom", () => {
-    const result = whatsappOutbound.resolveTarget?.({
-      to: "+15550000000",
-      allowFrom: ["+15551234567"],
-      mode: "implicit",
-    });
-
-    expect(result).toEqual({
-      ok: false,
-      error: expect.any(Error),
-    });
-  });
-
-  it("keeps group JID targets even when allowFrom does not contain them", () => {
-    const result = whatsappOutbound.resolveTarget?.({
-      to: "120363401234567890@g.us",
-      allowFrom: ["+15551234567"],
-      mode: "implicit",
-    });
-
-    expect(result).toEqual({
-      ok: true,
-      to: "120363401234567890@g.us",
-    });
-  });
-});
diff --git a/src/channels/plugins/plugins-channel.test.ts b/src/channels/plugins/plugins-channel.test.ts
new file mode 100644
index 00000000000..91277158d2e
--- /dev/null
+++ b/src/channels/plugins/plugins-channel.test.ts
@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import { normalizeIMessageMessagingTarget } from "./normalize/imessage.js";
+import { looksLikeSignalTargetId, normalizeSignalMessagingTarget } from "./normalize/signal.js";
+import { normalizeSignalAccountInput } from "./onboarding/signal.js";
+import { telegramOutbound } from "./outbound/telegram.js";
+import { whatsappOutbound } from "./outbound/whatsapp.js";
+
+describe("imessage target normalization", () => {
+  it("preserves service prefixes for handles", () => {
+    expect(normalizeIMessageMessagingTarget("sms:+1 (555) 222-3333")).toBe("sms:+15552223333");
+  });
+
+  it("drops service prefixes for chat targets", () => {
+    expect(normalizeIMessageMessagingTarget("sms:chat_id:123")).toBe("chat_id:123");
+    expect(normalizeIMessageMessagingTarget("imessage:CHAT_GUID:abc")).toBe("chat_guid:abc");
+    expect(normalizeIMessageMessagingTarget("auto:ChatIdentifier:foo")).toBe("chat_identifier:foo");
+  });
+});
+
+describe("signal target normalization", () => {
+  it("normalizes uuid targets by stripping uuid:", () => {
+    expect(normalizeSignalMessagingTarget("uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
+      "123e4567-e89b-12d3-a456-426614174000",
+    );
+  });
+
+  it("normalizes signal:uuid targets", () => {
+    expect(normalizeSignalMessagingTarget("signal:uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
+      "123e4567-e89b-12d3-a456-426614174000",
+    );
+  });
+
+  it("preserves case for group targets", () => {
+    expect(
+      normalizeSignalMessagingTarget("signal:group:VWATOdKF2hc8zdOS76q9tb0+5BI522e03QLDAq/9yPg="),
+    ).toBe("group:VWATOdKF2hc8zdOS76q9tb0+5BI522e03QLDAq/9yPg=");
+  });
+
+  it("accepts uuid prefixes for target detection", () => {
+    expect(looksLikeSignalTargetId("uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
+    expect(looksLikeSignalTargetId("signal:uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
+  });
+
+  it("accepts compact UUIDs for target detection", () => {
+    expect(looksLikeSignalTargetId("123e4567e89b12d3a456426614174000")).toBe(true);
+    expect(looksLikeSignalTargetId("uuid:123e4567e89b12d3a456426614174000")).toBe(true);
+  });
+
+  it("rejects invalid uuid prefixes", () => {
+    expect(looksLikeSignalTargetId("uuid:")).toBe(false);
+    expect(looksLikeSignalTargetId("uuid:not-a-uuid")).toBe(false);
+  });
+});
+
+describe("telegramOutbound.sendPayload", () => {
+  it("sends text payload with buttons", async () => {
+    const sendTelegram = vi.fn(async () => ({ messageId: "m1", chatId: "c1" }));
+
+    const result = await telegramOutbound.sendPayload?.({
+      cfg: {} as OpenClawConfig,
+      to: "telegram:123",
+      text: "ignored",
+      payload: {
+        text: "Hello",
+        channelData: {
+          telegram: {
+            buttons: [[{ text: "Option", callback_data: "/option" }]],
+          },
+        },
+      },
+      deps: { sendTelegram },
+    });
+
+    expect(sendTelegram).toHaveBeenCalledTimes(1);
+    expect(sendTelegram).toHaveBeenCalledWith(
+      "telegram:123",
+      "Hello",
+      expect.objectContaining({
+        buttons: [[{ text: "Option", callback_data: "/option" }]],
+        textMode: "html",
+      }),
+    );
+    expect(result).toEqual({ channel: "telegram", messageId: "m1", chatId: "c1" });
+  });
+
+  it("sends media payloads and attaches buttons only to first", async () => {
+    const sendTelegram = vi
+      .fn()
+      .mockResolvedValueOnce({ messageId: "m1", chatId: "c1" })
+      .mockResolvedValueOnce({ messageId: "m2", chatId: "c1" });
+
+    const result = await telegramOutbound.sendPayload?.({
+      cfg: {} as OpenClawConfig,
+      to: "telegram:123",
+      text: "ignored",
+      payload: {
+        text: "Caption",
+        mediaUrls: ["https://example.com/a.png", "https://example.com/b.png"],
+        channelData: {
+          telegram: {
+            buttons: [[{ text: "Go", callback_data: "/go" }]],
+          },
+        },
+      },
+      deps: { sendTelegram },
+    });
+
+    expect(sendTelegram).toHaveBeenCalledTimes(2);
+    expect(sendTelegram).toHaveBeenNthCalledWith(
+      1,
+      "telegram:123",
+      "Caption",
+      expect.objectContaining({
+        mediaUrl: "https://example.com/a.png",
+        buttons: [[{ text: "Go", callback_data: "/go" }]],
+      }),
+    );
+    const secondOpts = sendTelegram.mock.calls[1]?.[2] as { buttons?: unknown } | undefined;
+    expect(sendTelegram).toHaveBeenNthCalledWith(
+      2,
+      "telegram:123",
+      "",
+      expect.objectContaining({
+        mediaUrl: "https://example.com/b.png",
+      }),
+    );
+    expect(secondOpts?.buttons).toBeUndefined();
+    expect(result).toEqual({ channel: "telegram", messageId: "m2", chatId: "c1" });
+  });
+});
+
+describe("whatsappOutbound.resolveTarget", () => {
+  it("returns error when no target is provided even with allowFrom", () => {
+    const result = whatsappOutbound.resolveTarget?.({
+      to: undefined,
+      allowFrom: ["+15551234567"],
+      mode: "implicit",
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: expect.any(Error),
+    });
+  });
+
+  it("returns error when implicit target is not in allowFrom", () => {
+    const result = whatsappOutbound.resolveTarget?.({
+      to: "+15550000000",
+      allowFrom: ["+15551234567"],
+      mode: "implicit",
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: expect.any(Error),
+    });
+  });
+
+  it("keeps group JID targets even when allowFrom does not contain them", () => {
+    const result = whatsappOutbound.resolveTarget?.({
+      to: "120363401234567890@g.us",
+      allowFrom: ["+15551234567"],
+      mode: "implicit",
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      to: "120363401234567890@g.us",
+    });
+  });
+});
+
+describe("normalizeSignalAccountInput", () => {
+  it("accepts already normalized numbers", () => {
+    expect(normalizeSignalAccountInput("+15555550123")).toBe("+15555550123");
+  });
+
+  it("normalizes formatted input", () => {
+    expect(normalizeSignalAccountInput("  +1 (555) 000-1234 ")).toBe("+15550001234");
+  });
+
+  it("rejects empty input", () => {
+    expect(normalizeSignalAccountInput("   ")).toBeNull();
+  });
+
+  it("rejects non-numeric input", () => {
+    expect(normalizeSignalAccountInput("ok")).toBeNull();
+    expect(normalizeSignalAccountInput("++--")).toBeNull();
+  });
+
+  it("rejects inputs with stray + characters", () => {
+    expect(normalizeSignalAccountInput("++12345")).toBeNull();
+    expect(normalizeSignalAccountInput("+1+2345")).toBeNull();
+  });
+
+  it("rejects numbers that are too short or too long", () => {
+    expect(normalizeSignalAccountInput("+1234")).toBeNull();
+    expect(normalizeSignalAccountInput("+1234567890123456")).toBeNull();
+  });
+});
diff --git a/src/channels/plugins/plugins-core.test.ts b/src/channels/plugins/plugins-core.test.ts
new file mode 100644
index 00000000000..64daeb574a2
--- /dev/null
+++ b/src/channels/plugins/plugins-core.test.ts
@@ -0,0 +1,395 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it } from "vitest";
+import type { DiscordProbe } from "../../discord/probe.js";
+import type { DiscordTokenResolution } from "../../discord/token.js";
+import type { IMessageProbe } from "../../imessage/probe.js";
+import type { LineProbeResult } from "../../line/types.js";
+import type { PluginRegistry } from "../../plugins/registry.js";
+import type { SignalProbe } from "../../signal/probe.js";
+import type { SlackProbe } from "../../slack/probe.js";
+import type { TelegramProbe } from "../../telegram/probe.js";
+import type { TelegramTokenResolution } from "../../telegram/token.js";
+import type { ChannelOutboundAdapter, ChannelPlugin } from "./types.js";
+import type { BaseProbeResult, BaseTokenResolution } from "./types.js";
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
+import { getChannelPluginCatalogEntry, listChannelPluginCatalogEntries } from "./catalog.js";
+import { resolveChannelConfigWrites } from "./config-writes.js";
+import {
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryPeersFromConfig,
+  listSlackDirectoryGroupsFromConfig,
+  listSlackDirectoryPeersFromConfig,
+  listTelegramDirectoryGroupsFromConfig,
+  listTelegramDirectoryPeersFromConfig,
+  listWhatsAppDirectoryGroupsFromConfig,
+  listWhatsAppDirectoryPeersFromConfig,
+} from "./directory-config.js";
+import { listChannelPlugins } from "./index.js";
+import { loadChannelPlugin } from "./load.js";
+import { loadChannelOutboundAdapter } from "./outbound/load.js";
+
+describe("channel plugin registry", () => {
+  const emptyRegistry = createTestRegistry([]);
+
+  const createPlugin = (id: string): ChannelPlugin => ({
+    id,
+    meta: {
+      id,
+      label: id,
+      selectionLabel: id,
+      docsPath: `/channels/${id}`,
+      blurb: "test",
+    },
+    capabilities: { chatTypes: ["direct"] },
+    config: {
+      listAccountIds: () => [],
+      resolveAccount: () => ({}),
+    },
+  });
+
+  beforeEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  it("sorts channel plugins by configured order", () => {
+    const registry = createTestRegistry(
+      ["slack", "telegram", "signal"].map((id) => ({
+        pluginId: id,
+        plugin: createPlugin(id),
+        source: "test",
+      })),
+    );
+    setActivePluginRegistry(registry);
+    const pluginIds = listChannelPlugins().map((plugin) => plugin.id);
+    expect(pluginIds).toEqual(["telegram", "slack", "signal"]);
+  });
+});
+
+describe("channel plugin catalog", () => {
+  it("includes Microsoft Teams", () => {
+    const entry = getChannelPluginCatalogEntry("msteams");
+    expect(entry?.install.npmSpec).toBe("@openclaw/msteams");
+    expect(entry?.meta.aliases).toContain("teams");
+  });
+
+  it("lists plugin catalog entries", () => {
+    const ids = listChannelPluginCatalogEntries().map((entry) => entry.id);
+    expect(ids).toContain("msteams");
+  });
+
+  it("includes external catalog entries", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-catalog-"));
+    const catalogPath = path.join(dir, "catalog.json");
+    fs.writeFileSync(
+      catalogPath,
+      JSON.stringify({
+        entries: [
+          {
+            name: "@openclaw/demo-channel",
+            openclaw: {
+              channel: {
+                id: "demo-channel",
+                label: "Demo Channel",
+                selectionLabel: "Demo Channel",
+                docsPath: "/channels/demo-channel",
+                blurb: "Demo entry",
+                order: 999,
+              },
+              install: {
+                npmSpec: "@openclaw/demo-channel",
+              },
+            },
+          },
+        ],
+      }),
+    );
+
+    const ids = listChannelPluginCatalogEntries({ catalogPaths: [catalogPath] }).map(
+      (entry) => entry.id,
+    );
+    expect(ids).toContain("demo-channel");
+  });
+});
+
+const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
+  plugins: [],
+  tools: [],
+  channels,
+  providers: [],
+  gatewayHandlers: {},
+  httpHandlers: [],
+  httpRoutes: [],
+  cliRegistrars: [],
+  services: [],
+  diagnostics: [],
+});
+
+const emptyRegistry = createRegistry([]);
+
+const msteamsOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  sendText: async () => ({ channel: "msteams", messageId: "m1" }),
+  sendMedia: async () => ({ channel: "msteams", messageId: "m2" }),
+};
+
+const msteamsPlugin: ChannelPlugin = {
+  id: "msteams",
+  meta: {
+    id: "msteams",
+    label: "Microsoft Teams",
+    selectionLabel: "Microsoft Teams (Bot Framework)",
+    docsPath: "/channels/msteams",
+    blurb: "Bot Framework; enterprise support.",
+    aliases: ["teams"],
+  },
+  capabilities: { chatTypes: ["direct"] },
+  config: {
+    listAccountIds: () => [],
+    resolveAccount: () => ({}),
+  },
+  outbound: msteamsOutbound,
+};
+
+const registryWithMSTeams = createRegistry([
+  { pluginId: "msteams", plugin: msteamsPlugin, source: "test" },
+]);
+
+describe("channel plugin loader", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(emptyRegistry);
+  });
+
+  it("loads channel plugins from the active registry", async () => {
+    setActivePluginRegistry(registryWithMSTeams);
+    const plugin = await loadChannelPlugin("msteams");
+    expect(plugin).toBe(msteamsPlugin);
+  });
+
+  it("loads outbound adapters from registered plugins", async () => {
+    setActivePluginRegistry(registryWithMSTeams);
+    const outbound = await loadChannelOutboundAdapter("msteams");
+    expect(outbound).toBe(msteamsOutbound);
+  });
+});
+
+describe("BaseProbeResult assignability", () => {
+  it("TelegramProbe satisfies BaseProbeResult", () => {
+    expectTypeOf<TelegramProbe>().toMatchTypeOf<BaseProbeResult>();
+  });
+
+  it("DiscordProbe satisfies BaseProbeResult", () => {
+    expectTypeOf<DiscordProbe>().toMatchTypeOf<BaseProbeResult>();
+  });
+
+  it("SlackProbe satisfies BaseProbeResult", () => {
+    expectTypeOf<SlackProbe>().toMatchTypeOf<BaseProbeResult>();
+  });
+
+  it("SignalProbe satisfies BaseProbeResult", () => {
+    expectTypeOf<SignalProbe>().toMatchTypeOf<BaseProbeResult>();
+  });
+
+  it("IMessageProbe satisfies BaseProbeResult", () => {
+    expectTypeOf<IMessageProbe>().toMatchTypeOf<BaseProbeResult>();
+  });
+
+  it("LineProbeResult satisfies BaseProbeResult", () => {
+    expectTypeOf<LineProbeResult>().toMatchTypeOf<BaseProbeResult>();
+  });
+});
+
+describe("BaseTokenResolution assignability", () => {
+  it("TelegramTokenResolution satisfies BaseTokenResolution", () => {
+    expectTypeOf<TelegramTokenResolution>().toMatchTypeOf<BaseTokenResolution>();
+  });
+
+  it("DiscordTokenResolution satisfies BaseTokenResolution", () => {
+    expectTypeOf<DiscordTokenResolution>().toMatchTypeOf<BaseTokenResolution>();
+  });
+});
+
+describe("resolveChannelConfigWrites", () => {
+  it("defaults to allow when unset", () => {
+    const cfg = {};
+    expect(resolveChannelConfigWrites({ cfg, channelId: "slack" })).toBe(true);
+  });
+
+  it("blocks when channel config disables writes", () => {
+    const cfg = { channels: { slack: { configWrites: false } } };
+    expect(resolveChannelConfigWrites({ cfg, channelId: "slack" })).toBe(false);
+  });
+
+  it("account override wins over channel default", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          configWrites: true,
+          accounts: {
+            work: { configWrites: false },
+          },
+        },
+      },
+    };
+    expect(resolveChannelConfigWrites({ cfg, channelId: "slack", accountId: "work" })).toBe(false);
+  });
+
+  it("matches account ids case-insensitively", () => {
+    const cfg = {
+      channels: {
+        slack: {
+          configWrites: true,
+          accounts: {
+            Work: { configWrites: false },
+          },
+        },
+      },
+    };
+    expect(resolveChannelConfigWrites({ cfg, channelId: "slack", accountId: "work" })).toBe(false);
+  });
+});
+
+describe("directory (config-backed)", () => {
+  it("lists Slack peers/groups from config", async () => {
+    const cfg = {
+      channels: {
+        slack: {
+          botToken: "xoxb-test",
+          appToken: "xapp-test",
+          dm: { allowFrom: ["U123", "user:U999"] },
+          dms: { U234: {} },
+          channels: { C111: { users: ["U777"] } },
+        },
+      },
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any;
+
+    const peers = await listSlackDirectoryPeersFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(peers?.map((e) => e.id).toSorted()).toEqual([
+      "user:u123",
+      "user:u234",
+      "user:u777",
+      "user:u999",
+    ]);
+
+    const groups = await listSlackDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(groups?.map((e) => e.id)).toEqual(["channel:c111"]);
+  });
+
+  it("lists Discord peers/groups from config (numeric ids only)", async () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: "discord-test",
+          dm: { allowFrom: ["<@111>", "nope"] },
+          dms: { "222": {} },
+          guilds: {
+            "123": {
+              users: ["<@12345>", "not-an-id"],
+              channels: {
+                "555": {},
+                "channel:666": {},
+                general: {},
+              },
+            },
+          },
+        },
+      },
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any;
+
+    const peers = await listDiscordDirectoryPeersFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(peers?.map((e) => e.id).toSorted()).toEqual(["user:111", "user:12345", "user:222"]);
+
+    const groups = await listDiscordDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(groups?.map((e) => e.id).toSorted()).toEqual(["channel:555", "channel:666"]);
+  });
+
+  it("lists Telegram peers/groups from config", async () => {
+    const cfg = {
+      channels: {
+        telegram: {
+          botToken: "telegram-test",
+          allowFrom: ["123", "alice", "tg:@bob"],
+          dms: { "456": {} },
+          groups: { "-1001": {}, "*": {} },
+        },
+      },
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any;
+
+    const peers = await listTelegramDirectoryPeersFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(peers?.map((e) => e.id).toSorted()).toEqual(["123", "456", "@alice", "@bob"]);
+
+    const groups = await listTelegramDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(groups?.map((e) => e.id)).toEqual(["-1001"]);
+  });
+
+  it("lists WhatsApp peers/groups from config", async () => {
+    const cfg = {
+      channels: {
+        whatsapp: {
+          allowFrom: ["+15550000000", "*", "123@g.us"],
+          groups: { "999@g.us": { requireMention: true }, "*": {} },
+        },
+      },
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any;
+
+    const peers = await listWhatsAppDirectoryPeersFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(peers?.map((e) => e.id)).toEqual(["+15550000000"]);
+
+    const groups = await listWhatsAppDirectoryGroupsFromConfig({
+      cfg,
+      accountId: "default",
+      query: null,
+      limit: null,
+    });
+    expect(groups?.map((e) => e.id)).toEqual(["999@g.us"]);
+  });
+});
diff --git a/src/channels/plugins/slack.actions.test.ts b/src/channels/plugins/slack.actions.test.ts
deleted file mode 100644
index 844da4f09ad..00000000000
--- a/src/channels/plugins/slack.actions.test.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { createSlackActions } from "./slack.actions.js";
-
-const handleSlackAction = vi.fn(async () => ({ details: { ok: true } }));
-
-vi.mock("../../agents/tools/slack-actions.js", () => ({
-  handleSlackAction: (...args: unknown[]) => handleSlackAction(...args),
-}));
-
-describe("slack actions adapter", () => {
-  beforeEach(() => {
-    handleSlackAction.mockClear();
-  });
-
-  it("forwards threadId for read", async () => {
-    const cfg = { channels: { slack: { botToken: "tok" } } } as OpenClawConfig;
-    const actions = createSlackActions("slack");
-
-    await actions.handleAction?.({
-      channel: "slack",
-      action: "read",
-      cfg,
-      params: {
-        channelId: "C1",
-        threadId: "171234.567",
-      },
-    });
-
-    const [params] = handleSlackAction.mock.calls[0] ?? [];
-    expect(params).toMatchObject({
-      action: "readMessages",
-      channelId: "C1",
-      threadId: "171234.567",
-    });
-  });
-
-  it("forwards normalized limit for emoji-list", async () => {
-    const cfg = { channels: { slack: { botToken: "tok" } } } as OpenClawConfig;
-    const actions = createSlackActions("slack");
-
-    await actions.handleAction?.({
-      channel: "slack",
-      action: "emoji-list",
-      cfg,
-      params: {
-        limit: "2.9",
-      },
-    });
-
-    const [params] = handleSlackAction.mock.calls[0] ?? [];
-    expect(params).toMatchObject({
-      action: "emojiList",
-      limit: 2,
-    });
-  });
-});
diff --git a/src/channels/plugins/status-issues/discord.ts b/src/channels/plugins/status-issues/discord.ts
index d3e6b795ca0..f3e8765093f 100644
--- a/src/channels/plugins/status-issues/discord.ts
+++ b/src/channels/plugins/status-issues/discord.ts
@@ -1,5 +1,10 @@
 import type { ChannelAccountSnapshot, ChannelStatusIssue } from "../types.js";
-import { appendMatchMetadata, asString, isRecord } from "./shared.js";
+import {
+  appendMatchMetadata,
+  asString,
+  isRecord,
+  resolveEnabledConfiguredAccountId,
+} from "./shared.js";
 
 type DiscordIntentSummary = {
   messageContent?: "enabled" | "limited" | "disabled";
@@ -111,10 +116,8 @@ export function collectDiscordStatusIssues(
     if (!account) {
       continue;
     }
-    const accountId = asString(account.accountId) ?? "default";
-    const enabled = account.enabled !== false;
-    const configured = account.configured === true;
-    if (!enabled || !configured) {
+    const accountId = resolveEnabledConfiguredAccountId(account);
+    if (!accountId) {
       continue;
     }
 
diff --git a/src/channels/plugins/status-issues/shared.ts b/src/channels/plugins/status-issues/shared.ts
index da3606c2e9f..d4f5be878c1 100644
--- a/src/channels/plugins/status-issues/shared.ts
+++ b/src/channels/plugins/status-issues/shared.ts
@@ -30,3 +30,14 @@ export function appendMatchMetadata(
   const meta = formatMatchMetadata(params);
   return meta ? `${message} (${meta})` : message;
 }
+
+export function resolveEnabledConfiguredAccountId(account: {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+}): string | null {
+  const accountId = asString(account.accountId) ?? "default";
+  const enabled = account.enabled !== false;
+  const configured = account.configured === true;
+  return enabled && configured ? accountId : null;
+}
diff --git a/src/channels/plugins/status-issues/telegram.ts b/src/channels/plugins/status-issues/telegram.ts
index 8853bf4b1c8..97998eb4da4 100644
--- a/src/channels/plugins/status-issues/telegram.ts
+++ b/src/channels/plugins/status-issues/telegram.ts
@@ -1,5 +1,10 @@
 import type { ChannelAccountSnapshot, ChannelStatusIssue } from "../types.js";
-import { appendMatchMetadata, asString, isRecord } from "./shared.js";
+import {
+  appendMatchMetadata,
+  asString,
+  isRecord,
+  resolveEnabledConfiguredAccountId,
+} from "./shared.js";
 
 type TelegramAccountStatus = {
   accountId?: unknown;
@@ -81,10 +86,8 @@ export function collectTelegramStatusIssues(
     if (!account) {
       continue;
     }
-    const accountId = asString(account.accountId) ?? "default";
-    const enabled = account.enabled !== false;
-    const configured = account.configured === true;
-    if (!enabled || !configured) {
+    const accountId = resolveEnabledConfiguredAccountId(account);
+    if (!accountId) {
       continue;
     }
 
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
index a2195597e0c..2178acd5eee 100644
--- a/src/channels/plugins/types.core.ts
+++ b/src/channels/plugins/types.core.ts
@@ -347,3 +347,15 @@ export type ChannelPollContext = {
   silent?: boolean;
   isAnonymous?: boolean;
 };
+
+/** Minimal base for all channel probe results. Channel-specific probes extend this. */
+export type BaseProbeResult<TError = string | null> = {
+  ok: boolean;
+  error?: TError;
+};
+
+/** Minimal base for token resolution results. */
+export type BaseTokenResolution = {
+  token: string;
+  source: string;
+};
diff --git a/src/channels/plugins/types.ts b/src/channels/plugins/types.ts
index d7175f1765b..d3028e9970d 100644
--- a/src/channels/plugins/types.ts
+++ b/src/channels/plugins/types.ts
@@ -58,6 +58,8 @@ export type {
   ChannelThreadingContext,
   ChannelThreadingToolContext,
   ChannelToolSend,
+  BaseProbeResult,
+  BaseTokenResolution,
 } from "./types.core.js";
 
 export type { ChannelPlugin } from "./types.plugin.js";
diff --git a/src/channels/registry.test.ts b/src/channels/registry.test.ts
deleted file mode 100644
index cee891be70c..00000000000
--- a/src/channels/registry.test.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  formatChannelSelectionLine,
-  listChatChannels,
-  normalizeChatChannelId,
-} from "./registry.js";
-
-describe("channel registry", () => {
-  it("normalizes aliases", () => {
-    expect(normalizeChatChannelId("imsg")).toBe("imessage");
-    expect(normalizeChatChannelId("gchat")).toBe("googlechat");
-    expect(normalizeChatChannelId("google-chat")).toBe("googlechat");
-    expect(normalizeChatChannelId("internet-relay-chat")).toBe("irc");
-    expect(normalizeChatChannelId("web")).toBeNull();
-  });
-
-  it("keeps Telegram first in the default order", () => {
-    const channels = listChatChannels();
-    expect(channels[0]?.id).toBe("telegram");
-  });
-
-  it("does not include MS Teams by default", () => {
-    const channels = listChatChannels();
-    expect(channels.some((channel) => channel.id === "msteams")).toBe(false);
-  });
-
-  it("formats selection lines with docs labels", () => {
-    const channels = listChatChannels();
-    const first = channels[0];
-    if (!first) {
-      throw new Error("Missing channel metadata.");
-    }
-    const line = formatChannelSelectionLine(first, (path, label) =>
-      [label, path].filter(Boolean).join(":"),
-    );
-    expect(line).not.toContain("Docs:");
-    expect(line).toContain("/channels/telegram");
-    expect(line).toContain("https://openclaw.ai");
-  });
-});
diff --git a/src/channels/sender-identity.test.ts b/src/channels/sender-identity.test.ts
deleted file mode 100644
index 7c93821efbe..00000000000
--- a/src/channels/sender-identity.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { MsgContext } from "../auto-reply/templating.js";
-import { validateSenderIdentity } from "./sender-identity.js";
-
-describe("validateSenderIdentity", () => {
-  it("allows direct messages without sender fields", () => {
-    const ctx: MsgContext = { ChatType: "direct" };
-    expect(validateSenderIdentity(ctx)).toEqual([]);
-  });
-
-  it("requires some sender identity for non-direct chats", () => {
-    const ctx: MsgContext = { ChatType: "group" };
-    expect(validateSenderIdentity(ctx)).toContain(
-      "missing sender identity (SenderId/SenderName/SenderUsername/SenderE164)",
-    );
-  });
-
-  it("validates SenderE164 and SenderUsername shape", () => {
-    const ctx: MsgContext = {
-      ChatType: "group",
-      SenderE164: "123",
-      SenderUsername: "@ada lovelace",
-    };
-    expect(validateSenderIdentity(ctx)).toEqual([
-      "invalid SenderE164: 123",
-      'SenderUsername should not include "@": @ada lovelace',
-      "SenderUsername should not include whitespace: @ada lovelace",
-    ]);
-  });
-});
diff --git a/src/channels/targets.test.ts b/src/channels/targets.test.ts
deleted file mode 100644
index 256c60bc435..00000000000
--- a/src/channels/targets.test.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildMessagingTarget, ensureTargetId, requireTargetKind } from "./targets.js";
-
-describe("ensureTargetId", () => {
-  it("returns the candidate when it matches", () => {
-    expect(
-      ensureTargetId({
-        candidate: "U123",
-        pattern: /^[A-Z0-9]+$/i,
-        errorMessage: "bad",
-      }),
-    ).toBe("U123");
-  });
-
-  it("throws with the provided message on mismatch", () => {
-    expect(() =>
-      ensureTargetId({
-        candidate: "not-ok",
-        pattern: /^[A-Z0-9]+$/i,
-        errorMessage: "Bad target",
-      }),
-    ).toThrow(/Bad target/);
-  });
-});
-
-describe("requireTargetKind", () => {
-  it("returns the target id when the kind matches", () => {
-    const target = buildMessagingTarget("channel", "C123", "C123");
-    expect(requireTargetKind({ platform: "Slack", target, kind: "channel" })).toBe("C123");
-  });
-
-  it("throws when the kind is missing or mismatched", () => {
-    expect(() =>
-      requireTargetKind({ platform: "Slack", target: undefined, kind: "channel" }),
-    ).toThrow(/Slack channel id is required/);
-    const target = buildMessagingTarget("user", "U123", "U123");
-    expect(() => requireTargetKind({ platform: "Slack", target, kind: "channel" })).toThrow(
-      /Slack channel id is required/,
-    );
-  });
-});
diff --git a/src/channels/telegram/allow-from.ts b/src/channels/telegram/allow-from.ts
new file mode 100644
index 00000000000..d1e0209bc23
--- /dev/null
+++ b/src/channels/telegram/allow-from.ts
@@ -0,0 +1,11 @@
+export function normalizeTelegramAllowFromEntry(raw: unknown): string {
+  const base = typeof raw === "string" ? raw : typeof raw === "number" ? String(raw) : "";
+  return base
+    .trim()
+    .replace(/^(telegram|tg):/i, "")
+    .trim();
+}
+
+export function isNumericTelegramUserId(raw: string): boolean {
+  return /^\d+$/.test(raw);
+}
diff --git a/src/channels/typing.test.ts b/src/channels/typing.test.ts
deleted file mode 100644
index 5df7e02aa0b..00000000000
--- a/src/channels/typing.test.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { createTypingCallbacks } from "./typing.js";
-
-const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
-
-describe("createTypingCallbacks", () => {
-  it("invokes start on reply start", async () => {
-    const start = vi.fn().mockResolvedValue(undefined);
-    const onStartError = vi.fn();
-    const callbacks = createTypingCallbacks({ start, onStartError });
-
-    await callbacks.onReplyStart();
-
-    expect(start).toHaveBeenCalledTimes(1);
-    expect(onStartError).not.toHaveBeenCalled();
-  });
-
-  it("reports start errors", async () => {
-    const start = vi.fn().mockRejectedValue(new Error("fail"));
-    const onStartError = vi.fn();
-    const callbacks = createTypingCallbacks({ start, onStartError });
-
-    await callbacks.onReplyStart();
-
-    expect(onStartError).toHaveBeenCalledTimes(1);
-  });
-
-  it("invokes stop on idle and reports stop errors", async () => {
-    const start = vi.fn().mockResolvedValue(undefined);
-    const stop = vi.fn().mockRejectedValue(new Error("stop"));
-    const onStartError = vi.fn();
-    const onStopError = vi.fn();
-    const callbacks = createTypingCallbacks({ start, stop, onStartError, onStopError });
-
-    callbacks.onIdle?.();
-    await flush();
-
-    expect(stop).toHaveBeenCalledTimes(1);
-    expect(onStopError).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/channels/web/index.test.ts b/src/channels/web/index.test.ts
deleted file mode 100644
index 8f628495798..00000000000
--- a/src/channels/web/index.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it } from "vitest";
-import * as impl from "../../channel-web.js";
-import * as entry from "./index.js";
-
-describe("channels/web entrypoint", () => {
-  it("re-exports web channel helpers", () => {
-    expect(entry.createWaSocket).toBe(impl.createWaSocket);
-    expect(entry.loginWeb).toBe(impl.loginWeb);
-    expect(entry.logWebSelfId).toBe(impl.logWebSelfId);
-    expect(entry.monitorWebInbox).toBe(impl.monitorWebInbox);
-    expect(entry.monitorWebChannel).toBe(impl.monitorWebChannel);
-    expect(entry.pickWebChannel).toBe(impl.pickWebChannel);
-    expect(entry.sendMessageWhatsApp).toBe(impl.sendMessageWhatsApp);
-    expect(entry.WA_WEB_AUTH_DIR).toBe(impl.WA_WEB_AUTH_DIR);
-    expect(entry.waitForWaConnection).toBe(impl.waitForWaConnection);
-    expect(entry.webAuthExists).toBe(impl.webAuthExists);
-  });
-});
diff --git a/src/cli/browser-cli-actions-input/register.navigation.ts b/src/cli/browser-cli-actions-input/register.navigation.ts
index ca632dbd528..393ffb7e56f 100644
--- a/src/cli/browser-cli-actions-input/register.navigation.ts
+++ b/src/cli/browser-cli-actions-input/register.navigation.ts
@@ -1,11 +1,8 @@
 import type { Command } from "commander";
 import { danger } from "../../globals.js";
 import { defaultRuntime } from "../../runtime.js";
-import {
-  callBrowserRequest,
-  callBrowserResize,
-  type BrowserParentOpts,
-} from "../browser-cli-shared.js";
+import { runBrowserResizeWithOutput } from "../browser-cli-resize.js";
+import { callBrowserRequest, type BrowserParentOpts } from "../browser-cli-shared.js";
 import { requireRef, resolveBrowserActionContext } from "./shared.js";
 
 export function registerBrowserNavigationCommands(
@@ -52,27 +49,16 @@ export function registerBrowserNavigationCommands(
     .option("--target-id <id>", "CDP target id (or unique prefix)")
     .action(async (width: number, height: number, opts, cmd) => {
       const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
-      if (!Number.isFinite(width) || !Number.isFinite(height)) {
-        defaultRuntime.error(danger("width and height must be numbers"));
-        defaultRuntime.exit(1);
-        return;
-      }
       try {
-        const result = await callBrowserResize(
+        await runBrowserResizeWithOutput({
           parent,
-          {
-            profile,
-            width,
-            height,
-            targetId: opts.targetId,
-          },
-          { timeoutMs: 20000 },
-        );
-        if (parent?.json) {
-          defaultRuntime.log(JSON.stringify(result, null, 2));
-          return;
-        }
-        defaultRuntime.log(`resized to ${width}x${height}`);
+          profile,
+          width,
+          height,
+          targetId: opts.targetId,
+          timeoutMs: 20000,
+          successMessage: `resized to ${width}x${height}`,
+        });
       } catch (err) {
         defaultRuntime.error(danger(String(err)));
         defaultRuntime.exit(1);
diff --git a/src/cli/browser-cli-extension.test.ts b/src/cli/browser-cli-extension.test.ts
index 19b994d56c9..be5957f3141 100644
--- a/src/cli/browser-cli-extension.test.ts
+++ b/src/cli/browser-cli-extension.test.ts
@@ -1,7 +1,5 @@
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const copyToClipboard = vi.fn();
 const runtime = {
@@ -10,6 +8,91 @@ const runtime = {
   exit: vi.fn(),
 };
 
+type FakeFsEntry = { kind: "file"; content: string } | { kind: "dir" };
+
+const state = vi.hoisted(() => ({
+  entries: new Map<string, FakeFsEntry>(),
+  counter: 0,
+}));
+
+const abs = (p: string) => path.resolve(p);
+
+function setFile(p: string, content = "") {
+  const resolved = abs(p);
+  state.entries.set(resolved, { kind: "file", content });
+  setDir(path.dirname(resolved));
+}
+
+function setDir(p: string) {
+  const resolved = abs(p);
+  if (!state.entries.has(resolved)) {
+    state.entries.set(resolved, { kind: "dir" });
+  }
+}
+
+function copyTree(src: string, dest: string) {
+  const srcAbs = abs(src);
+  const destAbs = abs(dest);
+  const srcPrefix = `${srcAbs}${path.sep}`;
+  for (const [key, entry] of state.entries.entries()) {
+    if (key === srcAbs || key.startsWith(srcPrefix)) {
+      const rel = key === srcAbs ? "" : key.slice(srcPrefix.length);
+      const next = rel ? path.join(destAbs, rel) : destAbs;
+      state.entries.set(next, entry);
+    }
+  }
+}
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+
+  const wrapped = {
+    ...actual,
+    existsSync: (p: string) => state.entries.has(absInMock(p)),
+    mkdirSync: (p: string, _opts?: unknown) => {
+      setDir(p);
+    },
+    writeFileSync: (p: string, content: string) => {
+      setFile(p, content);
+    },
+    renameSync: (from: string, to: string) => {
+      const fromAbs = absInMock(from);
+      const toAbs = absInMock(to);
+      const entry = state.entries.get(fromAbs);
+      if (!entry) {
+        throw new Error(`ENOENT: no such file or directory, rename '${from}' -> '${to}'`);
+      }
+      state.entries.delete(fromAbs);
+      state.entries.set(toAbs, entry);
+    },
+    rmSync: (p: string) => {
+      const root = absInMock(p);
+      const prefix = `${root}${pathMod.sep}`;
+      const keys = Array.from(state.entries.keys());
+      for (const key of keys) {
+        if (key === root || key.startsWith(prefix)) {
+          state.entries.delete(key);
+        }
+      }
+    },
+    mkdtempSync: (prefix: string) => {
+      const dir = `${prefix}${state.counter++}`;
+      setDir(dir);
+      return dir;
+    },
+    promises: {
+      ...actual.promises,
+      cp: async (src: string, dest: string, _opts?: unknown) => {
+        copyTree(src, dest);
+      },
+    },
+  };
+
+  return { ...wrapped, default: wrapped };
+});
+
 vi.mock("../infra/clipboard.js", () => ({
   copyToClipboard,
 }));
@@ -18,86 +101,83 @@ vi.mock("../runtime.js", () => ({
   defaultRuntime: runtime,
 }));
 
+let resolveBundledExtensionRootDir: typeof import("./browser-cli-extension.js").resolveBundledExtensionRootDir;
+let installChromeExtension: typeof import("./browser-cli-extension.js").installChromeExtension;
+let registerBrowserExtensionCommands: typeof import("./browser-cli-extension.js").registerBrowserExtensionCommands;
+
+beforeAll(async () => {
+  ({ resolveBundledExtensionRootDir, installChromeExtension, registerBrowserExtensionCommands } =
+    await import("./browser-cli-extension.js"));
+});
+
+beforeEach(() => {
+  state.entries.clear();
+  state.counter = 0;
+  copyToClipboard.mockReset();
+  runtime.log.mockReset();
+  runtime.error.mockReset();
+  runtime.exit.mockReset();
+  vi.clearAllMocks();
+});
+
 function writeManifest(dir: string) {
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, "manifest.json"), JSON.stringify({ manifest_version: 3 }));
+  setDir(dir);
+  setFile(path.join(dir, "manifest.json"), JSON.stringify({ manifest_version: 3 }));
 }
 
-describe("bundled extension resolver", () => {
-  it("walks up to find the assets directory", async () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-ext-root-"));
+describe("bundled extension resolver (fs-mocked)", () => {
+  it("walks up to find the assets directory", () => {
+    const root = abs("/tmp/openclaw-ext-root");
     const here = path.join(root, "dist", "cli");
     const assets = path.join(root, "assets", "chrome-extension");
 
-    try {
-      writeManifest(assets);
-      fs.mkdirSync(here, { recursive: true });
+    writeManifest(assets);
+    setDir(here);
 
-      const { resolveBundledExtensionRootDir } = await import("./browser-cli-extension.js");
-      expect(resolveBundledExtensionRootDir(here)).toBe(assets);
-    } finally {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
+    expect(resolveBundledExtensionRootDir(here)).toBe(assets);
   });
 
-  it("prefers the nearest assets directory", async () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-ext-root-"));
+  it("prefers the nearest assets directory", () => {
+    const root = abs("/tmp/openclaw-ext-root-nearest");
     const here = path.join(root, "dist", "cli");
     const distAssets = path.join(root, "dist", "assets", "chrome-extension");
     const rootAssets = path.join(root, "assets", "chrome-extension");
 
-    try {
-      writeManifest(distAssets);
-      writeManifest(rootAssets);
-      fs.mkdirSync(here, { recursive: true });
+    writeManifest(distAssets);
+    writeManifest(rootAssets);
+    setDir(here);
 
-      const { resolveBundledExtensionRootDir } = await import("./browser-cli-extension.js");
-      expect(resolveBundledExtensionRootDir(here)).toBe(distAssets);
-    } finally {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
+    expect(resolveBundledExtensionRootDir(here)).toBe(distAssets);
   });
 });
 
-describe("browser extension install", () => {
+describe("browser extension install (fs-mocked)", () => {
   it("installs into the state dir (never node_modules)", async () => {
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-ext-"));
+    const tmp = abs("/tmp/openclaw-ext-install");
+    const sourceDir = path.join(tmp, "source-ext");
+    writeManifest(sourceDir);
+    setFile(path.join(sourceDir, "test.txt"), "ok");
 
-    try {
-      const { installChromeExtension } = await import("./browser-cli-extension.js");
-      // Keep this test hermetic + fast: use a tiny fixture instead of copying the
-      // full repo assets tree.
-      const sourceDir = path.join(tmp, "source-ext");
-      writeManifest(sourceDir);
-      fs.writeFileSync(path.join(sourceDir, "test.txt"), "ok");
-      const result = await installChromeExtension({ stateDir: tmp, sourceDir });
+    const result = await installChromeExtension({ stateDir: tmp, sourceDir });
 
-      expect(result.path).toBe(path.join(tmp, "browser", "chrome-extension"));
-      expect(fs.existsSync(path.join(result.path, "manifest.json"))).toBe(true);
-      expect(fs.existsSync(path.join(result.path, "test.txt"))).toBe(true);
-      expect(result.path.includes("node_modules")).toBe(false);
-    } finally {
-      fs.rmSync(tmp, { recursive: true, force: true });
-    }
+    expect(result.path).toBe(path.join(tmp, "browser", "chrome-extension"));
+    expect(state.entries.has(abs(path.join(result.path, "manifest.json")))).toBe(true);
+    expect(state.entries.has(abs(path.join(result.path, "test.txt")))).toBe(true);
+    expect(result.path.includes("node_modules")).toBe(false);
   });
 
   it("copies extension path to clipboard", async () => {
     const prev = process.env.OPENCLAW_STATE_DIR;
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-ext-path-"));
+    const tmp = abs("/tmp/openclaw-ext-path");
     process.env.OPENCLAW_STATE_DIR = tmp;
 
     try {
-      copyToClipboard.mockReset();
       copyToClipboard.mockResolvedValue(true);
-      runtime.log.mockReset();
-      runtime.error.mockReset();
-      runtime.exit.mockReset();
 
       const dir = path.join(tmp, "browser", "chrome-extension");
       writeManifest(dir);
 
       const { Command } = await import("commander");
-      const { registerBrowserExtensionCommands } = await import("./browser-cli-extension.js");
 
       const program = new Command();
       const browser = program.command("browser").option("--json", false);
@@ -107,7 +187,6 @@ describe("browser extension install", () => {
       );
 
       await program.parseAsync(["browser", "extension", "path"], { from: "user" });
-
       expect(copyToClipboard).toHaveBeenCalledWith(dir);
     } finally {
       if (prev === undefined) {
diff --git a/src/cli/browser-cli-resize.ts b/src/cli/browser-cli-resize.ts
new file mode 100644
index 00000000000..1ba31cb29f2
--- /dev/null
+++ b/src/cli/browser-cli-resize.ts
@@ -0,0 +1,37 @@
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+import { callBrowserResize, type BrowserParentOpts } from "./browser-cli-shared.js";
+
+export async function runBrowserResizeWithOutput(params: {
+  parent: BrowserParentOpts;
+  profile?: string;
+  width: number;
+  height: number;
+  targetId?: string;
+  timeoutMs?: number;
+  successMessage: string;
+}): Promise<void> {
+  const { width, height } = params;
+  if (!Number.isFinite(width) || !Number.isFinite(height)) {
+    defaultRuntime.error(danger("width and height must be numbers"));
+    defaultRuntime.exit(1);
+    return;
+  }
+
+  const result = await callBrowserResize(
+    params.parent,
+    {
+      profile: params.profile,
+      width,
+      height,
+      targetId: params.targetId,
+    },
+    { timeoutMs: params.timeoutMs ?? 20000 },
+  );
+
+  if (params.parent?.json) {
+    defaultRuntime.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  defaultRuntime.log(params.successMessage);
+}
diff --git a/src/cli/browser-cli-state.ts b/src/cli/browser-cli-state.ts
index e2e19503ac1..ace701bd236 100644
--- a/src/cli/browser-cli-state.ts
+++ b/src/cli/browser-cli-state.ts
@@ -2,11 +2,8 @@ import type { Command } from "commander";
 import { danger } from "../globals.js";
 import { defaultRuntime } from "../runtime.js";
 import { parseBooleanValue } from "../utils/boolean.js";
-import {
-  callBrowserRequest,
-  callBrowserResize,
-  type BrowserParentOpts,
-} from "./browser-cli-shared.js";
+import { runBrowserResizeWithOutput } from "./browser-cli-resize.js";
+import { callBrowserRequest, type BrowserParentOpts } from "./browser-cli-shared.js";
 import { registerBrowserCookiesAndStorageCommands } from "./browser-cli-state.cookies-storage.js";
 import { runCommandWithRuntime } from "./cli-utils.js";
 
@@ -39,27 +36,16 @@ export function registerBrowserStateCommands(
     .action(async (width: number, height: number, opts, cmd) => {
       const parent = parentOpts(cmd);
       const profile = parent?.browserProfile;
-      if (!Number.isFinite(width) || !Number.isFinite(height)) {
-        defaultRuntime.error(danger("width and height must be numbers"));
-        defaultRuntime.exit(1);
-        return;
-      }
       await runBrowserCommand(async () => {
-        const result = await callBrowserResize(
+        await runBrowserResizeWithOutput({
           parent,
-          {
-            profile,
-            width,
-            height,
-            targetId: opts.targetId,
-          },
-          { timeoutMs: 20000 },
-        );
-        if (parent?.json) {
-          defaultRuntime.log(JSON.stringify(result, null, 2));
-          return;
-        }
-        defaultRuntime.log(`viewport set: ${width}x${height}`);
+          profile,
+          width,
+          height,
+          targetId: opts.targetId,
+          timeoutMs: 20000,
+          successMessage: `viewport set: ${width}x${height}`,
+        });
       });
     });
 
diff --git a/src/cli/cli-utils.test.ts b/src/cli/cli-utils.test.ts
new file mode 100644
index 00000000000..5e8bfee99dd
--- /dev/null
+++ b/src/cli/cli-utils.test.ts
@@ -0,0 +1,110 @@
+import { Command } from "commander";
+import { describe, expect, it, vi } from "vitest";
+import { parseCanvasSnapshotPayload } from "./nodes-canvas.js";
+import { parseByteSize } from "./parse-bytes.js";
+import { parseDurationMs } from "./parse-duration.js";
+import { shouldSkipRespawnForArgv } from "./respawn-policy.js";
+import { waitForever } from "./wait.js";
+
+const { registerDnsCli } = await import("./dns-cli.js");
+
+describe("waitForever", () => {
+  it("creates an unref'ed interval and returns a pending promise", () => {
+    const setIntervalSpy = vi.spyOn(global, "setInterval");
+    const promise = waitForever();
+    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 1_000_000);
+    expect(promise).toBeInstanceOf(Promise);
+    setIntervalSpy.mockRestore();
+  });
+});
+
+describe("shouldSkipRespawnForArgv", () => {
+  it("skips respawn for help/version calls", () => {
+    expect(shouldSkipRespawnForArgv(["node", "openclaw", "--help"])).toBe(true);
+    expect(shouldSkipRespawnForArgv(["node", "openclaw", "-V"])).toBe(true);
+  });
+
+  it("keeps respawn path for normal commands", () => {
+    expect(shouldSkipRespawnForArgv(["node", "openclaw", "status"])).toBe(false);
+  });
+});
+
+describe("nodes canvas helpers", () => {
+  it("parses canvas.snapshot payload", () => {
+    expect(parseCanvasSnapshotPayload({ format: "png", base64: "aGk=" })).toEqual({
+      format: "png",
+      base64: "aGk=",
+    });
+  });
+
+  it("rejects invalid canvas.snapshot payload", () => {
+    expect(() => parseCanvasSnapshotPayload({ format: "png" })).toThrow(
+      /invalid canvas\.snapshot payload/i,
+    );
+  });
+});
+
+describe("dns cli", () => {
+  it("prints setup info (no apply)", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const program = new Command();
+      registerDnsCli(program);
+      await program.parseAsync(["dns", "setup", "--domain", "openclaw.internal"], { from: "user" });
+      const output = log.mock.calls.map((call) => call.join(" ")).join("\\n");
+      expect(output).toContain("DNS setup");
+      expect(output).toContain("openclaw.internal");
+    } finally {
+      log.mockRestore();
+    }
+  });
+});
+
+describe("parseByteSize", () => {
+  it("parses bytes with units", () => {
+    expect(parseByteSize("10kb")).toBe(10 * 1024);
+    expect(parseByteSize("1mb")).toBe(1024 * 1024);
+    expect(parseByteSize("2gb")).toBe(2 * 1024 * 1024 * 1024);
+  });
+
+  it("parses shorthand units", () => {
+    expect(parseByteSize("5k")).toBe(5 * 1024);
+    expect(parseByteSize("1m")).toBe(1024 * 1024);
+  });
+
+  it("uses default unit when omitted", () => {
+    expect(parseByteSize("123")).toBe(123);
+  });
+
+  it("rejects invalid values", () => {
+    expect(() => parseByteSize("")).toThrow();
+    expect(() => parseByteSize("nope")).toThrow();
+    expect(() => parseByteSize("-5kb")).toThrow();
+  });
+});
+
+describe("parseDurationMs", () => {
+  it("parses bare ms", () => {
+    expect(parseDurationMs("10000")).toBe(10_000);
+  });
+
+  it("parses seconds suffix", () => {
+    expect(parseDurationMs("10s")).toBe(10_000);
+  });
+
+  it("parses minutes suffix", () => {
+    expect(parseDurationMs("1m")).toBe(60_000);
+  });
+
+  it("parses hours suffix", () => {
+    expect(parseDurationMs("2h")).toBe(7_200_000);
+  });
+
+  it("parses days suffix", () => {
+    expect(parseDurationMs("2d")).toBe(172_800_000);
+  });
+
+  it("supports decimals", () => {
+    expect(parseDurationMs("0.5s")).toBe(500);
+  });
+});
diff --git a/src/cli/daemon-cli/install.ts b/src/cli/daemon-cli/install.ts
index 112b4fa2743..c29462d4eca 100644
--- a/src/cli/daemon-cli/install.ts
+++ b/src/cli/daemon-cli/install.ts
@@ -16,7 +16,11 @@ import { resolveGatewayService } from "../../daemon/service.js";
 import { resolveGatewayAuth } from "../../gateway/auth.js";
 import { defaultRuntime } from "../../runtime.js";
 import { formatCliCommand } from "../command-format.js";
-import { buildDaemonServiceSnapshot, createDaemonActionContext } from "./response.js";
+import {
+  buildDaemonServiceSnapshot,
+  createDaemonActionContext,
+  installDaemonServiceAndEmit,
+} from "./response.js";
 import { parsePort } from "./shared.js";
 
 export async function runDaemonInstall(opts: DaemonInstallOptions) {
@@ -154,29 +158,20 @@ export async function runDaemonInstall(opts: DaemonInstallOptions) {
     config: cfg,
   });
 
-  try {
-    await service.install({
-      env: process.env,
-      stdout,
-      programArguments,
-      workingDirectory,
-      environment,
-    });
-  } catch (err) {
-    fail(`Gateway install failed: ${String(err)}`);
-    return;
-  }
-
-  let installed = true;
-  try {
-    installed = await service.isLoaded({ env: process.env });
-  } catch {
-    installed = true;
-  }
-  emit({
-    ok: true,
-    result: "installed",
-    service: buildDaemonServiceSnapshot(service, installed),
-    warnings: warnings.length ? warnings : undefined,
+  await installDaemonServiceAndEmit({
+    serviceNoun: "Gateway",
+    service,
+    warnings,
+    emit,
+    fail,
+    install: async () => {
+      await service.install({
+        env: process.env,
+        stdout,
+        programArguments,
+        workingDirectory,
+        environment,
+      });
+    },
   });
 }
diff --git a/src/cli/daemon-cli/response.ts b/src/cli/daemon-cli/response.ts
index 13dd4f2606d..7b6f6d2a07e 100644
--- a/src/cli/daemon-cli/response.ts
+++ b/src/cli/daemon-cli/response.ts
@@ -79,3 +79,32 @@ export function createDaemonActionContext(params: { action: DaemonAction; json:
 
   return { stdout, warnings, emit, fail };
 }
+
+export async function installDaemonServiceAndEmit(params: {
+  serviceNoun: string;
+  service: GatewayService;
+  warnings: string[];
+  emit: (payload: Omit<DaemonActionResponse, "action">) => void;
+  fail: (message: string, hints?: string[]) => void;
+  install: () => Promise<void>;
+}) {
+  try {
+    await params.install();
+  } catch (err) {
+    params.fail(`${params.serviceNoun} install failed: ${String(err)}`);
+    return;
+  }
+
+  let installed = true;
+  try {
+    installed = await params.service.isLoaded({ env: process.env });
+  } catch {
+    installed = true;
+  }
+  params.emit({
+    ok: true,
+    result: "installed",
+    service: buildDaemonServiceSnapshot(params.service, installed),
+    warnings: params.warnings.length ? params.warnings : undefined,
+  });
+}
diff --git a/src/cli/daemon-cli/shared.ts b/src/cli/daemon-cli/shared.ts
index 4c07458fb2d..ef37e855b24 100644
--- a/src/cli/daemon-cli/shared.ts
+++ b/src/cli/daemon-cli/shared.ts
@@ -7,12 +7,26 @@ import { resolveGatewayLogPaths } from "../../daemon/launchd.js";
 import { formatRuntimeStatus } from "../../daemon/runtime-format.js";
 import { pickPrimaryLanIPv4 } from "../../gateway/net.js";
 import { getResolvedLoggerSettings } from "../../logging.js";
+import { colorize, isRich, theme } from "../../terminal/theme.js";
 import { formatCliCommand } from "../command-format.js";
 import { parsePort } from "../shared/parse-port.js";
 
 export { formatRuntimeStatus };
 export { parsePort };
 
+export function createCliStatusTextStyles() {
+  const rich = isRich();
+  return {
+    rich,
+    label: (value: string) => colorize(rich, theme.muted, value),
+    accent: (value: string) => colorize(rich, theme.accent, value),
+    infoText: (value: string) => colorize(rich, theme.info, value),
+    okText: (value: string) => colorize(rich, theme.success, value),
+    warnText: (value: string) => colorize(rich, theme.warn, value),
+    errorText: (value: string) => colorize(rich, theme.error, value),
+  };
+}
+
 export function parsePortFromArgs(programArguments: string[] | undefined): number | null {
   if (!programArguments?.length) {
     return null;
diff --git a/src/cli/daemon-cli/status.print.ts b/src/cli/daemon-cli/status.print.ts
index 24249ab1dc1..bfa0cfa69c2 100644
--- a/src/cli/daemon-cli/status.print.ts
+++ b/src/cli/daemon-cli/status.print.ts
@@ -12,10 +12,11 @@ import {
 import { isWSLEnv } from "../../infra/wsl.js";
 import { getResolvedLoggerSettings } from "../../logging.js";
 import { defaultRuntime } from "../../runtime.js";
-import { colorize, isRich, theme } from "../../terminal/theme.js";
+import { colorize, theme } from "../../terminal/theme.js";
 import { shortenHomePath } from "../../utils.js";
 import { formatCliCommand } from "../command-format.js";
 import {
+  createCliStatusTextStyles,
   filterDaemonEnv,
   formatRuntimeStatus,
   renderRuntimeHints,
@@ -53,13 +54,8 @@ export function printDaemonStatus(status: DaemonStatus, opts: { json: boolean })
     return;
   }
 
-  const rich = isRich();
-  const label = (value: string) => colorize(rich, theme.muted, value);
-  const accent = (value: string) => colorize(rich, theme.accent, value);
-  const infoText = (value: string) => colorize(rich, theme.info, value);
-  const okText = (value: string) => colorize(rich, theme.success, value);
-  const warnText = (value: string) => colorize(rich, theme.warn, value);
-  const errorText = (value: string) => colorize(rich, theme.error, value);
+  const { rich, label, accent, infoText, okText, warnText, errorText } =
+    createCliStatusTextStyles();
   const spacer = () => defaultRuntime.log("");
 
   const { service, rpc, extraServices } = status;
diff --git a/src/cli/dns-cli.test.ts b/src/cli/dns-cli.test.ts
deleted file mode 100644
index 69d63dd28b1..00000000000
--- a/src/cli/dns-cli.test.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { Command } from "commander";
-import { describe, expect, it, vi } from "vitest";
-
-const { registerDnsCli } = await import("./dns-cli.js");
-
-describe("dns cli", () => {
-  it("prints setup info (no apply)", async () => {
-    const log = vi.spyOn(console, "log").mockImplementation(() => {});
-    try {
-      const program = new Command();
-      registerDnsCli(program);
-      await program.parseAsync(["dns", "setup", "--domain", "openclaw.internal"], { from: "user" });
-      const output = log.mock.calls.map((call) => call.join(" ")).join("\n");
-      expect(output).toContain("DNS setup");
-      expect(output).toContain("openclaw.internal");
-    } finally {
-      log.mockRestore();
-    }
-  });
-});
diff --git a/src/cli/gateway-cli/discover.test.ts b/src/cli/gateway-cli/discover.test.ts
deleted file mode 100644
index bda8b70920b..00000000000
--- a/src/cli/gateway-cli/discover.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { GatewayBonjourBeacon } from "../../infra/bonjour-discovery.js";
-import { pickBeaconHost, pickGatewayPort } from "./discover.js";
-
-describe("gateway discover routing helpers", () => {
-  it("prefers resolved service host over TXT hints", () => {
-    const beacon: GatewayBonjourBeacon = {
-      instanceName: "Test",
-      host: "10.0.0.2",
-      lanHost: "evil.example.com",
-      tailnetDns: "evil.example.com",
-    };
-    expect(pickBeaconHost(beacon)).toBe("10.0.0.2");
-  });
-
-  it("prefers resolved service port over TXT gatewayPort", () => {
-    const beacon: GatewayBonjourBeacon = {
-      instanceName: "Test",
-      host: "10.0.0.2",
-      port: 18789,
-      gatewayPort: 12345,
-    };
-    expect(pickGatewayPort(beacon)).toBe(18789);
-  });
-
-  it("falls back to TXT host/port when resolve data is missing", () => {
-    const beacon: GatewayBonjourBeacon = {
-      instanceName: "Test",
-      lanHost: "test-host.local",
-      gatewayPort: 18789,
-    };
-    expect(pickBeaconHost(beacon)).toBe("test-host.local");
-    expect(pickGatewayPort(beacon)).toBe(18789);
-  });
-});
diff --git a/src/cli/gateway-cli/run-loop.test.ts b/src/cli/gateway-cli/run-loop.test.ts
index 5bd0f73e480..3bea291e24f 100644
--- a/src/cli/gateway-cli/run-loop.test.ts
+++ b/src/cli/gateway-cli/run-loop.test.ts
@@ -1,4 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
+import type { GatewayBonjourBeacon } from "../../infra/bonjour-discovery.js";
+import { pickBeaconHost, pickGatewayPort } from "./discover.js";
 
 const acquireGatewayLock = vi.fn(async () => ({
   release: vi.fn(async () => {}),
@@ -64,11 +66,27 @@ describe("runGatewayLoop", () => {
 
     const closeFirst = vi.fn(async () => {});
     const closeSecond = vi.fn(async () => {});
-    const start = vi
-      .fn<StartServer>()
-      .mockResolvedValueOnce({ close: closeFirst })
-      .mockResolvedValueOnce({ close: closeSecond })
-      .mockRejectedValueOnce(new Error("stop-loop"));
+
+    const start = vi.fn<StartServer>();
+    let resolveFirst: (() => void) | null = null;
+    const startedFirst = new Promise<void>((resolve) => {
+      resolveFirst = resolve;
+    });
+    start.mockImplementationOnce(async () => {
+      resolveFirst?.();
+      return { close: closeFirst };
+    });
+
+    let resolveSecond: (() => void) | null = null;
+    const startedSecond = new Promise<void>((resolve) => {
+      resolveSecond = resolve;
+    });
+    start.mockImplementationOnce(async () => {
+      resolveSecond?.();
+      return { close: closeSecond };
+    });
+
+    start.mockRejectedValueOnce(new Error("stop-loop"));
 
     const beforeSigterm = new Set(
       process.listeners("SIGTERM") as Array<(...args: unknown[]) => void>,
@@ -80,25 +98,24 @@ describe("runGatewayLoop", () => {
       process.listeners("SIGUSR1") as Array<(...args: unknown[]) => void>,
     );
 
-    const loopPromise = import("./run-loop.js").then(({ runGatewayLoop }) =>
-      runGatewayLoop({
-        start,
-        runtime: {
-          exit: vi.fn(),
-        } as { exit: (code: number) => never },
-      }),
-    );
+    const { runGatewayLoop } = await import("./run-loop.js");
+    const loopPromise = runGatewayLoop({
+      start,
+      runtime: {
+        exit: vi.fn(),
+      } as { exit: (code: number) => never },
+    });
 
     try {
-      await vi.waitFor(() => {
-        expect(start).toHaveBeenCalledTimes(1);
-      });
+      await startedFirst;
+      expect(start).toHaveBeenCalledTimes(1);
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       process.emit("SIGUSR1");
 
-      await vi.waitFor(() => {
-        expect(start).toHaveBeenCalledTimes(2);
-      });
+      await startedSecond;
+      expect(start).toHaveBeenCalledTimes(2);
+      await new Promise<void>((resolve) => setImmediate(resolve));
 
       expect(waitForActiveTasks).toHaveBeenCalledWith(30_000);
       expect(gatewayLog.warn).toHaveBeenCalledWith(DRAIN_TIMEOUT_LOG);
@@ -125,3 +142,35 @@ describe("runGatewayLoop", () => {
     }
   });
 });
+
+describe("gateway discover routing helpers", () => {
+  it("prefers resolved service host over TXT hints", () => {
+    const beacon: GatewayBonjourBeacon = {
+      instanceName: "Test",
+      host: "10.0.0.2",
+      lanHost: "evil.example.com",
+      tailnetDns: "evil.example.com",
+    };
+    expect(pickBeaconHost(beacon)).toBe("10.0.0.2");
+  });
+
+  it("prefers resolved service port over TXT gatewayPort", () => {
+    const beacon: GatewayBonjourBeacon = {
+      instanceName: "Test",
+      host: "10.0.0.2",
+      port: 18789,
+      gatewayPort: 12345,
+    };
+    expect(pickGatewayPort(beacon)).toBe(18789);
+  });
+
+  it("falls back to TXT host/port when resolve data is missing", () => {
+    const beacon: GatewayBonjourBeacon = {
+      instanceName: "Test",
+      lanHost: "test-host.local",
+      gatewayPort: 18789,
+    };
+    expect(pickBeaconHost(beacon)).toBe("test-host.local");
+    expect(pickGatewayPort(beacon)).toBe(18789);
+  });
+});
diff --git a/src/cli/hooks-cli.ts b/src/cli/hooks-cli.ts
index 7f7b0e9eb0a..42bb391e223 100644
--- a/src/cli/hooks-cli.ts
+++ b/src/cli/hooks-cli.ts
@@ -66,6 +66,50 @@ function buildHooksReport(config: OpenClawConfig): HookStatusReport {
   return buildWorkspaceHookStatus(workspaceDir, { config, entries });
 }
 
+function resolveHookForToggle(
+  report: HookStatusReport,
+  hookName: string,
+  opts?: { requireEligible?: boolean },
+): HookStatusEntry {
+  const hook = report.hooks.find((h) => h.name === hookName);
+  if (!hook) {
+    throw new Error(`Hook "${hookName}" not found`);
+  }
+  if (hook.managedByPlugin) {
+    throw new Error(
+      `Hook "${hookName}" is managed by plugin "${hook.pluginId ?? "unknown"}" and cannot be enabled/disabled.`,
+    );
+  }
+  if (opts?.requireEligible && !hook.eligible) {
+    throw new Error(`Hook "${hookName}" is not eligible (missing requirements)`);
+  }
+  return hook;
+}
+
+function buildConfigWithHookEnabled(params: {
+  config: OpenClawConfig;
+  hookName: string;
+  enabled: boolean;
+  ensureHooksEnabled?: boolean;
+}): OpenClawConfig {
+  const entries = { ...params.config.hooks?.internal?.entries };
+  entries[params.hookName] = { ...entries[params.hookName], enabled: params.enabled };
+
+  const internal = {
+    ...params.config.hooks?.internal,
+    ...(params.ensureHooksEnabled ? { enabled: true } : {}),
+    entries,
+  };
+
+  return {
+    ...params.config,
+    hooks: {
+      ...params.config.hooks,
+      internal,
+    },
+  };
+}
+
 function formatHookStatus(hook: HookStatusEntry): string {
   if (hook.eligible) {
     return theme.success("✓ ready");
@@ -384,38 +428,13 @@ export function formatHooksCheck(report: HookStatusReport, opts: HooksCheckOptio
 
 export async function enableHook(hookName: string): Promise<void> {
   const config = loadConfig();
-  const report = buildHooksReport(config);
-  const hook = report.hooks.find((h) => h.name === hookName);
-
-  if (!hook) {
-    throw new Error(`Hook "${hookName}" not found`);
-  }
-
-  if (hook.managedByPlugin) {
-    throw new Error(
-      `Hook "${hookName}" is managed by plugin "${hook.pluginId ?? "unknown"}" and cannot be enabled/disabled.`,
-    );
-  }
-
-  if (!hook.eligible) {
-    throw new Error(`Hook "${hookName}" is not eligible (missing requirements)`);
-  }
-
-  // Update config
-  const entries = { ...config.hooks?.internal?.entries };
-  entries[hookName] = { ...entries[hookName], enabled: true };
-
-  const nextConfig = {
-    ...config,
-    hooks: {
-      ...config.hooks,
-      internal: {
-        ...config.hooks?.internal,
-        enabled: true,
-        entries,
-      },
-    },
-  };
+  const hook = resolveHookForToggle(buildHooksReport(config), hookName, { requireEligible: true });
+  const nextConfig = buildConfigWithHookEnabled({
+    config,
+    hookName,
+    enabled: true,
+    ensureHooksEnabled: true,
+  });
 
   await writeConfigFile(nextConfig);
   defaultRuntime.log(
@@ -425,33 +444,8 @@ export async function enableHook(hookName: string): Promise<void> {
 
 export async function disableHook(hookName: string): Promise<void> {
   const config = loadConfig();
-  const report = buildHooksReport(config);
-  const hook = report.hooks.find((h) => h.name === hookName);
-
-  if (!hook) {
-    throw new Error(`Hook "${hookName}" not found`);
-  }
-
-  if (hook.managedByPlugin) {
-    throw new Error(
-      `Hook "${hookName}" is managed by plugin "${hook.pluginId ?? "unknown"}" and cannot be enabled/disabled.`,
-    );
-  }
-
-  // Update config
-  const entries = { ...config.hooks?.internal?.entries };
-  entries[hookName] = { ...entries[hookName], enabled: false };
-
-  const nextConfig = {
-    ...config,
-    hooks: {
-      ...config.hooks,
-      internal: {
-        ...config.hooks?.internal,
-        entries,
-      },
-    },
-  };
+  const hook = resolveHookForToggle(buildHooksReport(config), hookName);
+  const nextConfig = buildConfigWithHookEnabled({ config, hookName, enabled: false });
 
   await writeConfigFile(nextConfig);
   defaultRuntime.log(
diff --git a/src/cli/logs-cli.ts b/src/cli/logs-cli.ts
index 073bc03ddee..2fa8345814a 100644
--- a/src/cli/logs-cli.ts
+++ b/src/cli/logs-cli.ts
@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import { setTimeout as delay } from "node:timers/promises";
 import { buildGatewayConnectionDetails } from "../gateway/call.js";
 import { parseLogLine } from "../logging/parse-log-line.js";
+import { formatLocalIsoWithOffset } from "../logging/timestamps.js";
 import { formatDocsLink } from "../terminal/links.js";
 import { clearActiveProgressLine } from "../terminal/progress-line.js";
 import { createSafeStreamWriter } from "../terminal/stream-writer.js";
@@ -73,21 +74,6 @@ export function formatLogTimestamp(
     return value;
   }
 
-  const formatLocalIsoWithOffset = (now: Date) => {
-    const year = now.getFullYear();
-    const month = String(now.getMonth() + 1).padStart(2, "0");
-    const day = String(now.getDate()).padStart(2, "0");
-    const h = String(now.getHours()).padStart(2, "0");
-    const m = String(now.getMinutes()).padStart(2, "0");
-    const s = String(now.getSeconds()).padStart(2, "0");
-    const ms = String(now.getMilliseconds()).padStart(3, "0");
-    const tzOffset = now.getTimezoneOffset();
-    const tzSign = tzOffset <= 0 ? "+" : "-";
-    const tzHours = String(Math.floor(Math.abs(tzOffset) / 60)).padStart(2, "0");
-    const tzMinutes = String(Math.abs(tzOffset) % 60).padStart(2, "0");
-    return `${year}-${month}-${day}T${h}:${m}:${s}.${ms}${tzSign}${tzHours}:${tzMinutes}`;
-  };
-
   let timeString: string;
   if (localTime) {
     timeString = formatLocalIsoWithOffset(parsed);
diff --git a/src/cli/models-cli.test.ts b/src/cli/models-cli.test.ts
index 72aa073bd8c..fb34e421fda 100644
--- a/src/cli/models-cli.test.ts
+++ b/src/cli/models-cli.test.ts
@@ -99,6 +99,10 @@ describe("models cli", () => {
   it("shows help for models auth without error exit", async () => {
     const program = new Command();
     program.exitOverride();
+    program.configureOutput({
+      writeOut: () => {},
+      writeErr: () => {},
+    });
     registerModelsCli(program);
 
     try {
diff --git a/src/cli/node-cli/daemon.ts b/src/cli/node-cli/daemon.ts
index 2c2418fb246..9c53af76178 100644
--- a/src/cli/node-cli/daemon.ts
+++ b/src/cli/node-cli/daemon.ts
@@ -14,7 +14,7 @@ import { resolveGatewayLogPaths } from "../../daemon/launchd.js";
 import { resolveNodeService } from "../../daemon/node-service.js";
 import { loadNodeHostConfig } from "../../node-host/config.js";
 import { defaultRuntime } from "../../runtime.js";
-import { colorize, isRich, theme } from "../../terminal/theme.js";
+import { colorize, theme } from "../../terminal/theme.js";
 import { formatCliCommand } from "../command-format.js";
 import {
   runServiceRestart,
@@ -22,8 +22,12 @@ import {
   runServiceStop,
   runServiceUninstall,
 } from "../daemon-cli/lifecycle-core.js";
-import { buildDaemonServiceSnapshot, createDaemonActionContext } from "../daemon-cli/response.js";
-import { formatRuntimeStatus, parsePort } from "../daemon-cli/shared.js";
+import {
+  buildDaemonServiceSnapshot,
+  createDaemonActionContext,
+  installDaemonServiceAndEmit,
+} from "../daemon-cli/response.js";
+import { createCliStatusTextStyles, formatRuntimeStatus, parsePort } from "../daemon-cli/shared.js";
 
 type NodeDaemonInstallOptions = {
   host?: string;
@@ -160,31 +164,22 @@ export async function runNodeDaemonInstall(opts: NodeDaemonInstallOptions) {
       },
     });
 
-  try {
-    await service.install({
-      env: process.env,
-      stdout,
-      programArguments,
-      workingDirectory,
-      environment,
-      description,
-    });
-  } catch (err) {
-    fail(`Node install failed: ${String(err)}`);
-    return;
-  }
-
-  let installed = true;
-  try {
-    installed = await service.isLoaded({ env: process.env });
-  } catch {
-    installed = true;
-  }
-  emit({
-    ok: true,
-    result: "installed",
-    service: buildDaemonServiceSnapshot(service, installed),
-    warnings: warnings.length ? warnings : undefined,
+  await installDaemonServiceAndEmit({
+    serviceNoun: "Node",
+    service,
+    warnings,
+    emit,
+    fail,
+    install: async () => {
+      await service.install({
+        env: process.env,
+        stdout,
+        programArguments,
+        workingDirectory,
+        environment,
+        description,
+      });
+    },
   });
 }
 
@@ -248,13 +243,8 @@ export async function runNodeDaemonStatus(opts: NodeDaemonStatusOptions = {}) {
     return;
   }
 
-  const rich = isRich();
-  const label = (value: string) => colorize(rich, theme.muted, value);
-  const accent = (value: string) => colorize(rich, theme.accent, value);
-  const infoText = (value: string) => colorize(rich, theme.info, value);
-  const okText = (value: string) => colorize(rich, theme.success, value);
-  const warnText = (value: string) => colorize(rich, theme.warn, value);
-  const errorText = (value: string) => colorize(rich, theme.error, value);
+  const { rich, label, accent, infoText, okText, warnText, errorText } =
+    createCliStatusTextStyles();
 
   const serviceStatus = loaded ? okText(service.loadedText) : warnText(service.notLoadedText);
   defaultRuntime.log(`${label("Service:")} ${accent(service.label)} (${serviceStatus})`);
diff --git a/src/cli/nodes-camera.test.ts b/src/cli/nodes-camera.test.ts
index 63e1b1a4da8..e4a05f66f30 100644
--- a/src/cli/nodes-camera.test.ts
+++ b/src/cli/nodes-camera.test.ts
@@ -9,6 +9,7 @@ import {
   writeBase64ToFile,
   writeUrlToFile,
 } from "./nodes-camera.js";
+import { parseScreenRecordPayload, screenRecordTempPath } from "./nodes-screen.js";
 
 describe("nodes camera helpers", () => {
   it("parses camera.snap payload", () => {
@@ -104,3 +105,52 @@ describe("nodes camera helpers", () => {
     );
   });
 });
+
+describe("nodes screen helpers", () => {
+  it("parses screen.record payload", () => {
+    const payload = parseScreenRecordPayload({
+      format: "mp4",
+      base64: "Zm9v",
+      durationMs: 1000,
+      fps: 12,
+      screenIndex: 0,
+      hasAudio: true,
+    });
+    expect(payload.format).toBe("mp4");
+    expect(payload.base64).toBe("Zm9v");
+    expect(payload.durationMs).toBe(1000);
+    expect(payload.fps).toBe(12);
+    expect(payload.screenIndex).toBe(0);
+    expect(payload.hasAudio).toBe(true);
+  });
+
+  it("drops invalid optional fields instead of throwing", () => {
+    const payload = parseScreenRecordPayload({
+      format: "mp4",
+      base64: "Zm9v",
+      durationMs: "nope",
+      fps: null,
+      screenIndex: "0",
+      hasAudio: 1,
+    });
+    expect(payload.durationMs).toBeUndefined();
+    expect(payload.fps).toBeUndefined();
+    expect(payload.screenIndex).toBeUndefined();
+    expect(payload.hasAudio).toBeUndefined();
+  });
+
+  it("rejects invalid screen.record payload", () => {
+    expect(() => parseScreenRecordPayload({ format: "mp4" })).toThrow(
+      /invalid screen\.record payload/i,
+    );
+  });
+
+  it("builds screen record temp path", () => {
+    const p = screenRecordTempPath({
+      ext: "mp4",
+      tmpDir: "/tmp",
+      id: "id1",
+    });
+    expect(p).toBe(path.join("/tmp", "openclaw-screen-record-id1.mp4"));
+  });
+});
diff --git a/src/cli/nodes-canvas.test.ts b/src/cli/nodes-canvas.test.ts
deleted file mode 100644
index a3b7a394582..00000000000
--- a/src/cli/nodes-canvas.test.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseCanvasSnapshotPayload } from "./nodes-canvas.js";
-
-describe("nodes canvas helpers", () => {
-  it("parses canvas.snapshot payload", () => {
-    expect(parseCanvasSnapshotPayload({ format: "png", base64: "aGk=" })).toEqual({
-      format: "png",
-      base64: "aGk=",
-    });
-  });
-
-  it("rejects invalid canvas.snapshot payload", () => {
-    expect(() => parseCanvasSnapshotPayload({ format: "png" })).toThrow(
-      /invalid canvas\.snapshot payload/i,
-    );
-  });
-});
diff --git a/src/cli/nodes-cli/pairing-render.ts b/src/cli/nodes-cli/pairing-render.ts
new file mode 100644
index 00000000000..a24561912ee
--- /dev/null
+++ b/src/cli/nodes-cli/pairing-render.ts
@@ -0,0 +1,38 @@
+import type { PendingRequest } from "./types.js";
+import { formatTimeAgo } from "../../infra/format-time/format-relative.ts";
+import { renderTable } from "../../terminal/table.js";
+
+export function renderPendingPairingRequestsTable(params: {
+  pending: PendingRequest[];
+  now: number;
+  tableWidth: number;
+  theme: {
+    heading: (text: string) => string;
+    warn: (text: string) => string;
+    muted: (text: string) => string;
+  };
+}) {
+  const { pending, now, tableWidth, theme } = params;
+  const rows = pending.map((r) => ({
+    Request: r.requestId,
+    Node: r.displayName?.trim() ? r.displayName.trim() : r.nodeId,
+    IP: r.remoteIp ?? "",
+    Requested:
+      typeof r.ts === "number" ? formatTimeAgo(Math.max(0, now - r.ts)) : theme.muted("unknown"),
+    Repair: r.isRepair ? theme.warn("yes") : "",
+  }));
+  return {
+    heading: theme.heading("Pending"),
+    table: renderTable({
+      width: tableWidth,
+      columns: [
+        { key: "Request", header: "Request", minWidth: 8 },
+        { key: "Node", header: "Node", minWidth: 14, flex: true },
+        { key: "IP", header: "IP", minWidth: 10 },
+        { key: "Requested", header: "Requested", minWidth: 12 },
+        { key: "Repair", header: "Repair", minWidth: 6 },
+      ],
+      rows,
+    }).trimEnd(),
+  };
+}
diff --git a/src/cli/nodes-cli/register.camera.ts b/src/cli/nodes-cli/register.camera.ts
index 76f839f6a74..3039189f0ff 100644
--- a/src/cli/nodes-cli/register.camera.ts
+++ b/src/cli/nodes-cli/register.camera.ts
@@ -1,6 +1,5 @@
 import type { Command } from "commander";
 import type { NodesRpcOpts } from "./types.js";
-import { randomIdempotencyKey } from "../../gateway/call.js";
 import { defaultRuntime } from "../../runtime.js";
 import { renderTable } from "../../terminal/table.js";
 import { shortenHomePath } from "../../utils.js";
@@ -14,7 +13,7 @@ import {
 } from "../nodes-camera.js";
 import { parseDurationMs } from "../parse-duration.js";
 import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
-import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
+import { buildNodeInvokeParams, callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 
 const parseFacing = (value: string): CameraFacing => {
   const v = String(value ?? "")
@@ -37,12 +36,15 @@ export function registerNodesCameraCommands(nodes: Command) {
       .action(async (opts: NodesRpcOpts) => {
         await runNodesCommand("camera list", async () => {
           const nodeId = await resolveNodeId(opts, String(opts.node ?? ""));
-          const raw = await callGatewayCli("node.invoke", opts, {
-            nodeId,
-            command: "camera.list",
-            params: {},
-            idempotencyKey: randomIdempotencyKey(),
-          });
+          const raw = await callGatewayCli(
+            "node.invoke",
+            opts,
+            buildNodeInvokeParams({
+              nodeId,
+              command: "camera.list",
+              params: {},
+            }),
+          );
 
           const res = typeof raw === "object" && raw !== null ? (raw as { payload?: unknown }) : {};
           const payload =
@@ -130,7 +132,7 @@ export function registerNodesCameraCommands(nodes: Command) {
           }> = [];
 
           for (const facing of facings) {
-            const invokeParams: Record<string, unknown> = {
+            const invokeParams = buildNodeInvokeParams({
               nodeId,
               command: "camera.snap",
               params: {
@@ -141,11 +143,8 @@ export function registerNodesCameraCommands(nodes: Command) {
                 delayMs: Number.isFinite(delayMs) ? delayMs : undefined,
                 deviceId: deviceId || undefined,
               },
-              idempotencyKey: randomIdempotencyKey(),
-            };
-            if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-              invokeParams.timeoutMs = timeoutMs;
-            }
+              timeoutMs,
+            });
 
             const raw = await callGatewayCli("node.invoke", opts, invokeParams);
             const res =
@@ -204,7 +203,7 @@ export function registerNodesCameraCommands(nodes: Command) {
             : undefined;
           const deviceId = opts.deviceId ? String(opts.deviceId).trim() : undefined;
 
-          const invokeParams: Record<string, unknown> = {
+          const invokeParams = buildNodeInvokeParams({
             nodeId,
             command: "camera.clip",
             params: {
@@ -214,11 +213,8 @@ export function registerNodesCameraCommands(nodes: Command) {
               format: "mp4",
               deviceId: deviceId || undefined,
             },
-            idempotencyKey: randomIdempotencyKey(),
-          };
-          if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-            invokeParams.timeoutMs = timeoutMs;
-          }
+            timeoutMs,
+          });
 
           const raw = await callGatewayCli("node.invoke", opts, invokeParams);
           const res = typeof raw === "object" && raw !== null ? (raw as { payload?: unknown }) : {};
diff --git a/src/cli/nodes-cli/register.canvas.ts b/src/cli/nodes-cli/register.canvas.ts
index 5883953eb47..d9877f8ad15 100644
--- a/src/cli/nodes-cli/register.canvas.ts
+++ b/src/cli/nodes-cli/register.canvas.ts
@@ -1,7 +1,6 @@
 import type { Command } from "commander";
 import fs from "node:fs/promises";
 import type { NodesRpcOpts } from "./types.js";
-import { randomIdempotencyKey } from "../../gateway/call.js";
 import { defaultRuntime } from "../../runtime.js";
 import { shortenHomePath } from "../../utils.js";
 import { writeBase64ToFile } from "../nodes-camera.js";
@@ -9,21 +8,21 @@ import { canvasSnapshotTempPath, parseCanvasSnapshotPayload } from "../nodes-can
 import { parseTimeoutMs } from "../nodes-run.js";
 import { buildA2UITextJsonl, validateA2UIJsonl } from "./a2ui-jsonl.js";
 import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
-import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
+import { buildNodeInvokeParams, callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 
 async function invokeCanvas(opts: NodesRpcOpts, command: string, params?: Record<string, unknown>) {
   const nodeId = await resolveNodeId(opts, String(opts.node ?? ""));
-  const invokeParams: Record<string, unknown> = {
-    nodeId,
-    command,
-    params,
-    idempotencyKey: randomIdempotencyKey(),
-  };
   const timeoutMs = parseTimeoutMs(opts.invokeTimeout);
-  if (typeof timeoutMs === "number") {
-    invokeParams.timeoutMs = timeoutMs;
-  }
-  return await callGatewayCli("node.invoke", opts, invokeParams);
+  return await callGatewayCli(
+    "node.invoke",
+    opts,
+    buildNodeInvokeParams({
+      nodeId,
+      command,
+      params,
+      timeoutMs: typeof timeoutMs === "number" ? timeoutMs : undefined,
+    }),
+  );
 }
 
 export function registerNodesCanvasCommands(nodes: Command) {
@@ -42,7 +41,6 @@ export function registerNodesCanvasCommands(nodes: Command) {
       .option("--invoke-timeout <ms>", "Node invoke timeout in ms (default 20000)", "20000")
       .action(async (opts: NodesRpcOpts) => {
         await runNodesCommand("canvas snapshot", async () => {
-          const nodeId = await resolveNodeId(opts, String(opts.node ?? ""));
           const formatOpt = String(opts.format ?? "jpg")
             .trim()
             .toLowerCase();
@@ -54,25 +52,11 @@ export function registerNodesCanvasCommands(nodes: Command) {
 
           const maxWidth = opts.maxWidth ? Number.parseInt(String(opts.maxWidth), 10) : undefined;
           const quality = opts.quality ? Number.parseFloat(String(opts.quality)) : undefined;
-          const timeoutMs = opts.invokeTimeout
-            ? Number.parseInt(String(opts.invokeTimeout), 10)
-            : undefined;
-
-          const invokeParams: Record<string, unknown> = {
-            nodeId,
-            command: "canvas.snapshot",
-            params: {
-              format: formatForParams,
-              maxWidth: Number.isFinite(maxWidth) ? maxWidth : undefined,
-              quality: Number.isFinite(quality) ? quality : undefined,
-            },
-            idempotencyKey: randomIdempotencyKey(),
-          };
-          if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-            invokeParams.timeoutMs = timeoutMs;
-          }
-
-          const raw = await callGatewayCli("node.invoke", opts, invokeParams);
+          const raw = await invokeCanvas(opts, "canvas.snapshot", {
+            format: formatForParams,
+            maxWidth: Number.isFinite(maxWidth) ? maxWidth : undefined,
+            quality: Number.isFinite(quality) ? quality : undefined,
+          });
           const res = typeof raw === "object" && raw !== null ? (raw as { payload?: unknown }) : {};
           const payload = parseCanvasSnapshotPayload(res.payload);
           const filePath = canvasSnapshotTempPath({
diff --git a/src/cli/nodes-cli/register.pairing.ts b/src/cli/nodes-cli/register.pairing.ts
index 9241aeff782..daab00bdf32 100644
--- a/src/cli/nodes-cli/register.pairing.ts
+++ b/src/cli/nodes-cli/register.pairing.ts
@@ -1,10 +1,9 @@
 import type { Command } from "commander";
 import type { NodesRpcOpts } from "./types.js";
-import { formatTimeAgo } from "../../infra/format-time/format-relative.ts";
 import { defaultRuntime } from "../../runtime.js";
-import { renderTable } from "../../terminal/table.js";
 import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
 import { parsePairingList } from "./format.js";
+import { renderPendingPairingRequestsTable } from "./pairing-render.js";
 import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 
 export function registerNodesPairingCommands(nodes: Command) {
@@ -28,28 +27,14 @@ export function registerNodesPairingCommands(nodes: Command) {
           const { heading, warn, muted } = getNodesTheme();
           const tableWidth = Math.max(60, (process.stdout.columns ?? 120) - 1);
           const now = Date.now();
-          const rows = pending.map((r) => ({
-            Request: r.requestId,
-            Node: r.displayName?.trim() ? r.displayName.trim() : r.nodeId,
-            IP: r.remoteIp ?? "",
-            Requested:
-              typeof r.ts === "number" ? formatTimeAgo(Math.max(0, now - r.ts)) : muted("unknown"),
-            Repair: r.isRepair ? warn("yes") : "",
-          }));
-          defaultRuntime.log(heading("Pending"));
-          defaultRuntime.log(
-            renderTable({
-              width: tableWidth,
-              columns: [
-                { key: "Request", header: "Request", minWidth: 8 },
-                { key: "Node", header: "Node", minWidth: 14, flex: true },
-                { key: "IP", header: "IP", minWidth: 10 },
-                { key: "Requested", header: "Requested", minWidth: 12 },
-                { key: "Repair", header: "Repair", minWidth: 6 },
-              ],
-              rows,
-            }).trimEnd(),
-          );
+          const rendered = renderPendingPairingRequestsTable({
+            pending,
+            now,
+            tableWidth,
+            theme: { heading, warn, muted },
+          });
+          defaultRuntime.log(rendered.heading);
+          defaultRuntime.log(rendered.table);
         });
       }),
   );
diff --git a/src/cli/nodes-cli/register.screen.ts b/src/cli/nodes-cli/register.screen.ts
index 60ff4ec9716..e2034be1699 100644
--- a/src/cli/nodes-cli/register.screen.ts
+++ b/src/cli/nodes-cli/register.screen.ts
@@ -1,6 +1,5 @@
 import type { Command } from "commander";
 import type { NodesRpcOpts } from "./types.js";
-import { randomIdempotencyKey } from "../../gateway/call.js";
 import { defaultRuntime } from "../../runtime.js";
 import { shortenHomePath } from "../../utils.js";
 import {
@@ -10,7 +9,7 @@ import {
 } from "../nodes-screen.js";
 import { parseDurationMs } from "../parse-duration.js";
 import { runNodesCommand } from "./cli-utils.js";
-import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
+import { buildNodeInvokeParams, callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 
 export function registerNodesScreenCommands(nodes: Command) {
   const screen = nodes
@@ -38,7 +37,7 @@ export function registerNodesScreenCommands(nodes: Command) {
             ? Number.parseInt(String(opts.invokeTimeout), 10)
             : undefined;
 
-          const invokeParams: Record<string, unknown> = {
+          const invokeParams = buildNodeInvokeParams({
             nodeId,
             command: "screen.record",
             params: {
@@ -48,11 +47,8 @@ export function registerNodesScreenCommands(nodes: Command) {
               format: "mp4",
               includeAudio: opts.audio !== false,
             },
-            idempotencyKey: randomIdempotencyKey(),
-          };
-          if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-            invokeParams.timeoutMs = timeoutMs;
-          }
+            timeoutMs,
+          });
 
           const raw = await callGatewayCli("node.invoke", opts, invokeParams);
           const res = typeof raw === "object" && raw !== null ? (raw as { payload?: unknown }) : {};
diff --git a/src/cli/nodes-cli/register.status.ts b/src/cli/nodes-cli/register.status.ts
index e29b79d0699..414106f130b 100644
--- a/src/cli/nodes-cli/register.status.ts
+++ b/src/cli/nodes-cli/register.status.ts
@@ -7,6 +7,7 @@ import { shortenHomeInString } from "../../utils.js";
 import { parseDurationMs } from "../parse-duration.js";
 import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
 import { formatPermissions, parseNodeList, parsePairingList } from "./format.js";
+import { renderPendingPairingRequestsTable } from "./pairing-render.js";
 import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 
 function formatVersionLabel(raw: string) {
@@ -356,31 +357,15 @@ export function registerNodesStatusCommands(nodes: Command) {
           }
 
           if (pendingRows.length > 0) {
-            const pendingRowsRendered = pendingRows.map((r) => ({
-              Request: r.requestId,
-              Node: r.displayName?.trim() ? r.displayName.trim() : r.nodeId,
-              IP: r.remoteIp ?? "",
-              Requested:
-                typeof r.ts === "number"
-                  ? formatTimeAgo(Math.max(0, now - r.ts))
-                  : muted("unknown"),
-              Repair: r.isRepair ? warn("yes") : "",
-            }));
+            const rendered = renderPendingPairingRequestsTable({
+              pending: pendingRows,
+              now,
+              tableWidth,
+              theme: { heading, warn, muted },
+            });
             defaultRuntime.log("");
-            defaultRuntime.log(heading("Pending"));
-            defaultRuntime.log(
-              renderTable({
-                width: tableWidth,
-                columns: [
-                  { key: "Request", header: "Request", minWidth: 8 },
-                  { key: "Node", header: "Node", minWidth: 14, flex: true },
-                  { key: "IP", header: "IP", minWidth: 10 },
-                  { key: "Requested", header: "Requested", minWidth: 12 },
-                  { key: "Repair", header: "Repair", minWidth: 6 },
-                ],
-                rows: pendingRowsRendered,
-              }).trimEnd(),
-            );
+            defaultRuntime.log(rendered.heading);
+            defaultRuntime.log(rendered.table);
           }
 
           if (filteredPaired.length > 0) {
diff --git a/src/cli/nodes-cli/rpc.ts b/src/cli/nodes-cli/rpc.ts
index a51e0fa2a9a..691da4dd7fa 100644
--- a/src/cli/nodes-cli/rpc.ts
+++ b/src/cli/nodes-cli/rpc.ts
@@ -1,6 +1,6 @@
 import type { Command } from "commander";
 import type { NodeListNode, NodesRpcOpts } from "./types.js";
-import { callGateway } from "../../gateway/call.js";
+import { callGateway, randomIdempotencyKey } from "../../gateway/call.js";
 import { resolveNodeIdFromCandidates } from "../../shared/node-match.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
 import { withProgress } from "../progress.js";
@@ -37,6 +37,25 @@ export const callGatewayCli = async (
       }),
   );
 
+export function buildNodeInvokeParams(params: {
+  nodeId: string;
+  command: string;
+  params?: Record<string, unknown>;
+  timeoutMs?: number;
+  idempotencyKey?: string;
+}): Record<string, unknown> {
+  const invokeParams: Record<string, unknown> = {
+    nodeId: params.nodeId,
+    command: params.command,
+    params: params.params,
+    idempotencyKey: params.idempotencyKey ?? randomIdempotencyKey(),
+  };
+  if (typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs)) {
+    invokeParams.timeoutMs = params.timeoutMs;
+  }
+  return invokeParams;
+}
+
 export function unauthorizedHintForMessage(message: string): string | null {
   const haystack = message.toLowerCase();
   if (
diff --git a/src/cli/nodes-screen.test.ts b/src/cli/nodes-screen.test.ts
deleted file mode 100644
index 5aa6dfe8361..00000000000
--- a/src/cli/nodes-screen.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { parseScreenRecordPayload, screenRecordTempPath } from "./nodes-screen.js";
-
-describe("nodes screen helpers", () => {
-  it("parses screen.record payload", () => {
-    const payload = parseScreenRecordPayload({
-      format: "mp4",
-      base64: "Zm9v",
-      durationMs: 1000,
-      fps: 12,
-      screenIndex: 0,
-      hasAudio: true,
-    });
-    expect(payload.format).toBe("mp4");
-    expect(payload.base64).toBe("Zm9v");
-    expect(payload.durationMs).toBe(1000);
-    expect(payload.fps).toBe(12);
-    expect(payload.screenIndex).toBe(0);
-    expect(payload.hasAudio).toBe(true);
-  });
-
-  it("rejects invalid screen.record payload", () => {
-    expect(() => parseScreenRecordPayload({ format: "mp4" })).toThrow(
-      /invalid screen\.record payload/i,
-    );
-  });
-
-  it("builds screen record temp path", () => {
-    const p = screenRecordTempPath({
-      ext: "mp4",
-      tmpDir: "/tmp",
-      id: "id1",
-    });
-    expect(p).toBe(path.join("/tmp", "openclaw-screen-record-id1.mp4"));
-  });
-});
diff --git a/src/cli/pairing-cli.test.ts b/src/cli/pairing-cli.test.ts
index 5efb7f729d6..73b81386a0c 100644
--- a/src/cli/pairing-cli.test.ts
+++ b/src/cli/pairing-cli.test.ts
@@ -94,6 +94,20 @@ describe("pairing cli", () => {
     expect(listChannelPairingRequests).toHaveBeenCalledWith("telegram");
   });
 
+  it("forwards --account for list", async () => {
+    const { registerPairingCli } = await import("./pairing-cli.js");
+    listChannelPairingRequests.mockResolvedValueOnce([]);
+
+    const program = new Command();
+    program.name("test");
+    registerPairingCli(program);
+    await program.parseAsync(["pairing", "list", "--channel", "telegram", "--account", "yy"], {
+      from: "user",
+    });
+
+    expect(listChannelPairingRequests).toHaveBeenCalledWith("telegram", process.env, "yy");
+  });
+
   it("normalizes channel aliases", async () => {
     const { registerPairingCli } = await import("./pairing-cli.js");
     listChannelPairingRequests.mockResolvedValueOnce([]);
@@ -170,4 +184,33 @@ describe("pairing cli", () => {
     });
     expect(log).toHaveBeenCalledWith(expect.stringContaining("Approved"));
   });
+
+  it("forwards --account for approve", async () => {
+    const { registerPairingCli } = await import("./pairing-cli.js");
+    approveChannelPairingCode.mockResolvedValueOnce({
+      id: "123",
+      entry: {
+        id: "123",
+        code: "ABCDEFGH",
+        createdAt: "2026-01-08T00:00:00Z",
+        lastSeenAt: "2026-01-08T00:00:00Z",
+      },
+    });
+
+    const program = new Command();
+    program.name("test");
+    registerPairingCli(program);
+    await program.parseAsync(
+      ["pairing", "approve", "--channel", "telegram", "--account", "yy", "ABCDEFGH"],
+      {
+        from: "user",
+      },
+    );
+
+    expect(approveChannelPairingCode).toHaveBeenCalledWith({
+      channel: "telegram",
+      code: "ABCDEFGH",
+      accountId: "yy",
+    });
+  });
 });
diff --git a/src/cli/pairing-cli.ts b/src/cli/pairing-cli.ts
index e576d1b5723..f028b08fc33 100644
--- a/src/cli/pairing-cli.ts
+++ b/src/cli/pairing-cli.ts
@@ -64,6 +64,7 @@ export function registerPairingCli(program: Command) {
     .command("list")
     .description("List pending pairing requests")
     .option("--channel <channel>", `Channel (${channels.join(", ")})`)
+    .option("--account <accountId>", "Account id (for multi-account channels)")
     .argument("[channel]", `Channel (${channels.join(", ")})`)
     .option("--json", "Print JSON", false)
     .action(async (channelArg, opts) => {
@@ -74,7 +75,10 @@ export function registerPairingCli(program: Command) {
         );
       }
       const channel = parseChannel(channelRaw, channels);
-      const requests = await listChannelPairingRequests(channel);
+      const accountId = String(opts.account ?? "").trim();
+      const requests = accountId
+        ? await listChannelPairingRequests(channel, process.env, accountId)
+        : await listChannelPairingRequests(channel);
       if (opts.json) {
         defaultRuntime.log(JSON.stringify({ channel, requests }, null, 2));
         return;
@@ -111,6 +115,7 @@ export function registerPairingCli(program: Command) {
     .command("approve")
     .description("Approve a pairing code and allow that sender")
     .option("--channel <channel>", `Channel (${channels.join(", ")})`)
+    .option("--account <accountId>", "Account id (for multi-account channels)")
     .argument("<codeOrChannel>", "Pairing code (or channel when using 2 args)")
     .argument("[code]", "Pairing code (when channel is passed as the 1st arg)")
     .option("--notify", "Notify the requester on the same channel", false)
@@ -128,10 +133,17 @@ export function registerPairingCli(program: Command) {
         );
       }
       const channel = parseChannel(channelRaw, channels);
-      const approved = await approveChannelPairingCode({
-        channel,
-        code: String(resolvedCode),
-      });
+      const accountId = String(opts.account ?? "").trim();
+      const approved = accountId
+        ? await approveChannelPairingCode({
+            channel,
+            code: String(resolvedCode),
+            accountId,
+          })
+        : await approveChannelPairingCode({
+            channel,
+            code: String(resolvedCode),
+          });
       if (!approved) {
         throw new Error(`No pending pairing request found for code: ${String(resolvedCode)}`);
       }
diff --git a/src/cli/parse-bytes.test.ts b/src/cli/parse-bytes.test.ts
deleted file mode 100644
index a0c1abcb0b0..00000000000
--- a/src/cli/parse-bytes.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseByteSize } from "./parse-bytes.js";
-
-describe("parseByteSize", () => {
-  it("parses bytes with units", () => {
-    expect(parseByteSize("10kb")).toBe(10 * 1024);
-    expect(parseByteSize("1mb")).toBe(1024 * 1024);
-    expect(parseByteSize("2gb")).toBe(2 * 1024 * 1024 * 1024);
-  });
-
-  it("parses shorthand units", () => {
-    expect(parseByteSize("5k")).toBe(5 * 1024);
-    expect(parseByteSize("1m")).toBe(1024 * 1024);
-  });
-
-  it("uses default unit when omitted", () => {
-    expect(parseByteSize("123")).toBe(123);
-  });
-
-  it("rejects invalid values", () => {
-    expect(() => parseByteSize("")).toThrow();
-    expect(() => parseByteSize("nope")).toThrow();
-    expect(() => parseByteSize("-5kb")).toThrow();
-  });
-});
diff --git a/src/cli/parse-duration.test.ts b/src/cli/parse-duration.test.ts
deleted file mode 100644
index ad9d6a3a60c..00000000000
--- a/src/cli/parse-duration.test.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseDurationMs } from "./parse-duration.js";
-
-describe("parseDurationMs", () => {
-  it("parses bare ms", () => {
-    expect(parseDurationMs("10000")).toBe(10_000);
-  });
-
-  it("parses seconds suffix", () => {
-    expect(parseDurationMs("10s")).toBe(10_000);
-  });
-
-  it("parses minutes suffix", () => {
-    expect(parseDurationMs("1m")).toBe(60_000);
-  });
-
-  it("parses hours suffix", () => {
-    expect(parseDurationMs("2h")).toBe(7_200_000);
-  });
-
-  it("parses days suffix", () => {
-    expect(parseDurationMs("2d")).toBe(172_800_000);
-  });
-
-  it("supports decimals", () => {
-    expect(parseDurationMs("0.5s")).toBe(500);
-  });
-});
diff --git a/src/cli/plugins-cli.ts b/src/cli/plugins-cli.ts
index 3d3a3341115..5f897351c5f 100644
--- a/src/cli/plugins-cli.ts
+++ b/src/cli/plugins-cli.ts
@@ -9,6 +9,7 @@ import { resolveStateDir } from "../config/paths.js";
 import { resolveArchiveKind } from "../infra/archive.js";
 import { installPluginFromNpmSpec, installPluginFromPath } from "../plugins/install.js";
 import { recordPluginInstall } from "../plugins/installs.js";
+import { clearPluginManifestRegistryCache } from "../plugins/manifest-registry.js";
 import { applyExclusiveSlotSelection } from "../plugins/slots.js";
 import { resolvePluginSourceRoots, formatPluginSourceForTable } from "../plugins/source-display.js";
 import { buildPluginStatusReport } from "../plugins/status.js";
@@ -591,6 +592,9 @@ export function registerPluginsCli(program: Command) {
           defaultRuntime.error(result.error);
           process.exit(1);
         }
+        // Plugin CLI registrars may have warmed the manifest registry cache before install;
+        // force a rescan so config validation sees the freshly installed plugin.
+        clearPluginManifestRegistryCache();
 
         let next = enablePluginInConfig(cfg, result.pluginId);
         const source: "archive" | "path" = resolveArchiveKind(resolved) ? "archive" : "path";
@@ -640,6 +644,8 @@ export function registerPluginsCli(program: Command) {
         defaultRuntime.error(result.error);
         process.exit(1);
       }
+      // Ensure config validation sees newly installed plugin(s) even if the cache was warmed at startup.
+      clearPluginManifestRegistryCache();
 
       let next = enablePluginInConfig(cfg, result.pluginId);
       next = recordPluginInstall(next, {
diff --git a/src/cli/program.test-mocks.ts b/src/cli/program.test-mocks.ts
index 524c6b3a88e..ab0d6b497bf 100644
--- a/src/cli/program.test-mocks.ts
+++ b/src/cli/program.test-mocks.ts
@@ -43,6 +43,13 @@ export function installBaseProgramMocks() {
     ],
     configureCommand,
     configureCommandWithSections,
+    configureCommandFromSectionsArg: (sections: unknown, runtime: unknown) => {
+      const resolved = Array.isArray(sections) ? sections : [];
+      if (resolved.length > 0) {
+        return configureCommandWithSections(resolved, runtime);
+      }
+      return configureCommand({}, runtime);
+    },
   }));
   vi.mock("../commands/setup.js", () => ({ setupCommand }));
   vi.mock("../commands/onboard.js", () => ({ onboardCommand }));
diff --git a/src/cli/respawn-policy.test.ts b/src/cli/respawn-policy.test.ts
deleted file mode 100644
index 25e026b0a56..00000000000
--- a/src/cli/respawn-policy.test.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { shouldSkipRespawnForArgv } from "./respawn-policy.js";
-
-describe("shouldSkipRespawnForArgv", () => {
-  it("skips respawn for help/version calls", () => {
-    expect(shouldSkipRespawnForArgv(["node", "openclaw", "--help"])).toBe(true);
-    expect(shouldSkipRespawnForArgv(["node", "openclaw", "-V"])).toBe(true);
-  });
-
-  it("keeps respawn path for normal commands", () => {
-    expect(shouldSkipRespawnForArgv(["node", "openclaw", "status"])).toBe(false);
-  });
-});
diff --git a/src/cli/skills-cli.e2e.test.ts b/src/cli/skills-cli.e2e.test.ts
new file mode 100644
index 00000000000..51b1640af1e
--- /dev/null
+++ b/src/cli/skills-cli.e2e.test.ts
@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { SkillEntry } from "../agents/skills.js";
+import { buildWorkspaceSkillStatus } from "../agents/skills-status.js";
+import { captureEnv } from "../test-utils/env.js";
+import { formatSkillInfo, formatSkillsCheck, formatSkillsList } from "./skills-cli.format.js";
+
+describe("skills-cli (e2e)", () => {
+  let tempWorkspaceDir = "";
+  let tempBundledDir = "";
+  let envSnapshot: ReturnType<typeof captureEnv>;
+
+  beforeAll(() => {
+    envSnapshot = captureEnv(["OPENCLAW_BUNDLED_SKILLS_DIR"]);
+    tempWorkspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-skills-test-"));
+    tempBundledDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-bundled-skills-test-"));
+    process.env.OPENCLAW_BUNDLED_SKILLS_DIR = tempBundledDir;
+  });
+
+  afterAll(() => {
+    if (tempWorkspaceDir) {
+      fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
+    }
+    if (tempBundledDir) {
+      fs.rmSync(tempBundledDir, { recursive: true, force: true });
+    }
+    envSnapshot.restore();
+  });
+
+  function createEntries(): SkillEntry[] {
+    const baseDir = path.join(tempWorkspaceDir, "peekaboo");
+    return [
+      {
+        skill: {
+          name: "peekaboo",
+          description: "Capture UI screenshots",
+          source: "openclaw-bundled",
+          filePath: path.join(baseDir, "SKILL.md"),
+          baseDir,
+        } as SkillEntry["skill"],
+        frontmatter: {},
+        metadata: { emoji: "📸" },
+      },
+    ];
+  }
+
+  it("loads bundled skills and formats them", () => {
+    const entries = createEntries();
+    const report = buildWorkspaceSkillStatus(tempWorkspaceDir, {
+      managedSkillsDir: "/nonexistent",
+      entries,
+    });
+
+    expect(report.skills.length).toBeGreaterThan(0);
+
+    const listOutput = formatSkillsList(report, {});
+    expect(listOutput).toContain("Skills");
+
+    const checkOutput = formatSkillsCheck(report, {});
+    expect(checkOutput).toContain("Total:");
+
+    const jsonOutput = formatSkillsList(report, { json: true });
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.skills).toBeInstanceOf(Array);
+  });
+
+  it("formats info for a real bundled skill (peekaboo)", () => {
+    const entries = createEntries();
+    const report = buildWorkspaceSkillStatus(tempWorkspaceDir, {
+      managedSkillsDir: "/nonexistent",
+      entries,
+    });
+
+    const peekaboo = report.skills.find((s) => s.name === "peekaboo");
+    if (!peekaboo) {
+      throw new Error("peekaboo fixture skill missing");
+    }
+
+    const output = formatSkillInfo(report, "peekaboo", {});
+    expect(output).toContain("peekaboo");
+    expect(output).toContain("Details:");
+  });
+});
diff --git a/src/cli/skills-cli.format.ts b/src/cli/skills-cli.format.ts
index 97f77a3530e..5f6dcfdcd2a 100644
--- a/src/cli/skills-cli.format.ts
+++ b/src/cli/skills-cli.format.ts
@@ -292,23 +292,8 @@ export function formatSkillsCheck(report: SkillStatusReport, opts: SkillsCheckOp
     lines.push(theme.heading("Missing requirements:"));
     for (const skill of missingReqs) {
       const emoji = skill.emoji ?? "📦";
-      const missing: string[] = [];
-      if (skill.missing.bins.length > 0) {
-        missing.push(`bins: ${skill.missing.bins.join(", ")}`);
-      }
-      if (skill.missing.anyBins.length > 0) {
-        missing.push(`anyBins: ${skill.missing.anyBins.join(", ")}`);
-      }
-      if (skill.missing.env.length > 0) {
-        missing.push(`env: ${skill.missing.env.join(", ")}`);
-      }
-      if (skill.missing.config.length > 0) {
-        missing.push(`config: ${skill.missing.config.join(", ")}`);
-      }
-      if (skill.missing.os.length > 0) {
-        missing.push(`os: ${skill.missing.os.join(", ")}`);
-      }
-      lines.push(`  ${emoji} ${skill.name} ${theme.muted(`(${missing.join("; ")})`)}`);
+      const missing = formatSkillMissingSummary(skill);
+      lines.push(`  ${emoji} ${skill.name} ${theme.muted(`(${missing})`)}`);
     }
   }
 
diff --git a/src/cli/skills-cli.test.ts b/src/cli/skills-cli.test.ts
index afc9336786d..b539caada9d 100644
--- a/src/cli/skills-cli.test.ts
+++ b/src/cli/skills-cli.test.ts
@@ -1,9 +1,5 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { SkillStatusEntry, SkillStatusReport } from "../agents/skills-status.js";
-import type { SkillEntry } from "../agents/skills.js";
 import { formatSkillInfo, formatSkillsCheck, formatSkillsList } from "./skills-cli.format.js";
 
 // Unit tests: don't pay the runtime cost of loading/parsing the real skills loader.
@@ -215,78 +211,4 @@ describe("skills-cli", () => {
       expect(parsed.summary.total).toBe(2);
     });
   });
-
-  describe("integration: loads real skills from bundled directory", () => {
-    let tempWorkspaceDir = "";
-
-    beforeAll(() => {
-      tempWorkspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-skills-test-"));
-    });
-
-    afterAll(() => {
-      if (tempWorkspaceDir) {
-        fs.rmSync(tempWorkspaceDir, { recursive: true, force: true });
-      }
-    });
-
-    const createEntries = (): SkillEntry[] => {
-      const baseDir = path.join(tempWorkspaceDir, "peekaboo");
-      return [
-        {
-          skill: {
-            name: "peekaboo",
-            description: "Capture UI screenshots",
-            source: "openclaw-bundled",
-            filePath: path.join(baseDir, "SKILL.md"),
-            baseDir,
-          } as SkillEntry["skill"],
-          frontmatter: {},
-          metadata: { emoji: "📸" },
-        },
-      ];
-    };
-
-    it("loads bundled skills and formats them", async () => {
-      const { buildWorkspaceSkillStatus } = await import("../agents/skills-status.js");
-      const entries = createEntries();
-      const report = buildWorkspaceSkillStatus(tempWorkspaceDir, {
-        managedSkillsDir: "/nonexistent",
-        entries,
-      });
-
-      // Should have loaded some skills
-      expect(report.skills.length).toBeGreaterThan(0);
-
-      // Format should work without errors
-      const listOutput = formatSkillsList(report, {});
-      expect(listOutput).toContain("Skills");
-
-      const checkOutput = formatSkillsCheck(report, {});
-      expect(checkOutput).toContain("Total:");
-
-      // JSON output should be valid
-      const jsonOutput = formatSkillsList(report, { json: true });
-      const parsed = JSON.parse(jsonOutput);
-      expect(parsed.skills).toBeInstanceOf(Array);
-    });
-
-    it("formats info for a real bundled skill (peekaboo)", async () => {
-      const { buildWorkspaceSkillStatus } = await import("../agents/skills-status.js");
-      const entries = createEntries();
-      const report = buildWorkspaceSkillStatus(tempWorkspaceDir, {
-        managedSkillsDir: "/nonexistent",
-        entries,
-      });
-
-      // peekaboo is a bundled skill that should always exist
-      const peekaboo = report.skills.find((s) => s.name === "peekaboo");
-      if (!peekaboo) {
-        throw new Error("peekaboo fixture skill missing");
-      }
-
-      const output = formatSkillInfo(report, "peekaboo", {});
-      expect(output).toContain("peekaboo");
-      expect(output).toContain("Details:");
-    });
-  });
 });
diff --git a/src/cli/update-cli.test.ts b/src/cli/update-cli.test.ts
index 20b935e7ecf..550bbbf43ec 100644
--- a/src/cli/update-cli.test.ts
+++ b/src/cli/update-cli.test.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { UpdateRunResult } from "../infra/update-runner.js";
+import { captureEnv } from "../test-utils/env.js";
 
 const confirm = vi.fn();
 const select = vi.fn();
@@ -144,7 +145,7 @@ describe("update-cli", () => {
 
   const createCaseDir = async (prefix: string) => {
     const dir = path.join(fixtureRoot, `${prefix}-${fixtureCount++}`);
-    await fs.mkdir(dir, { recursive: true });
+    // Tests only need a stable path; the directory does not have to exist because all I/O is mocked.
     return dir;
   };
 
@@ -597,7 +598,7 @@ describe("update-cli", () => {
 
   it("updateWizardCommand offers dev checkout and forwards selections", async () => {
     const tempDir = await createCaseDir("openclaw-update-wizard");
-    const previousGitDir = process.env.OPENCLAW_GIT_DIR;
+    const envSnapshot = captureEnv(["OPENCLAW_GIT_DIR"]);
     try {
       setTty(true);
       process.env.OPENCLAW_GIT_DIR = tempDir;
@@ -627,7 +628,7 @@ describe("update-cli", () => {
       const call = vi.mocked(runGatewayUpdate).mock.calls[0]?.[0];
       expect(call?.channel).toBe("dev");
     } finally {
-      process.env.OPENCLAW_GIT_DIR = previousGitDir;
+      envSnapshot.restore();
     }
   });
 });
diff --git a/src/cli/update-cli/shared.ts b/src/cli/update-cli/shared.ts
index 507df6edc50..b137248f0b8 100644
--- a/src/cli/update-cli/shared.ts
+++ b/src/cli/update-cli/shared.ts
@@ -5,6 +5,7 @@ import path from "node:path";
 import type { UpdateStepProgress, UpdateStepResult } from "../../infra/update-runner.js";
 import { resolveStateDir } from "../../config/paths.js";
 import { resolveOpenClawPackageRoot } from "../../infra/openclaw-root.js";
+import { readPackageName, readPackageVersion } from "../../infra/package-json.js";
 import { trimLogTail } from "../../infra/restart-sentinel.js";
 import { parseSemver } from "../../infra/runtime-guard.js";
 import { fetchNpmTagVersion } from "../../infra/update-check.js";
@@ -68,15 +69,7 @@ export function normalizeVersionTag(tag: string): string | null {
   return parseSemver(cleaned) ? cleaned : null;
 }
 
-export async function readPackageVersion(root: string): Promise<string | null> {
-  try {
-    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    return typeof parsed.version === "string" ? parsed.version : null;
-  } catch {
-    return null;
-  }
-}
+export { readPackageName, readPackageVersion };
 
 export async function resolveTargetVersion(
   tag: string,
@@ -99,17 +92,6 @@ export async function isGitCheckout(root: string): Promise<boolean> {
   }
 }
 
-export async function readPackageName(root: string): Promise<string | null> {
-  try {
-    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { name?: string };
-    const name = parsed?.name?.trim();
-    return name ? name : null;
-  } catch {
-    return null;
-  }
-}
-
 export async function isCorePackage(root: string): Promise<boolean> {
   const name = await readPackageName(root);
   return Boolean(name && CORE_PACKAGE_NAMES.has(name));
diff --git a/src/cli/wait.test.ts b/src/cli/wait.test.ts
deleted file mode 100644
index 5af1ba32a64..00000000000
--- a/src/cli/wait.test.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { waitForever } from "./wait.js";
-
-describe("waitForever", () => {
-  it("creates an unref'ed interval and returns a pending promise", () => {
-    const setIntervalSpy = vi.spyOn(global, "setInterval");
-    const promise = waitForever();
-    expect(setIntervalSpy).toHaveBeenCalledWith(expect.any(Function), 1_000_000);
-    expect(promise).toBeInstanceOf(Promise);
-    setIntervalSpy.mockRestore();
-  });
-});
diff --git a/src/cli/webhooks-cli.ts b/src/cli/webhooks-cli.ts
index c9c49a2b1ba..c5a551afd8f 100644
--- a/src/cli/webhooks-cli.ts
+++ b/src/cli/webhooks-cli.ts
@@ -110,32 +110,54 @@ function parseGmailSetupOptions(raw: Record<string, unknown>): GmailSetupOptions
   if (!account) {
     throw new Error("--account is required");
   }
+  const common = parseGmailCommonOptions(raw);
   return {
     account,
     project: stringOption(raw.project),
-    topic: stringOption(raw.topic),
-    subscription: stringOption(raw.subscription),
-    label: stringOption(raw.label),
-    hookUrl: stringOption(raw.hookUrl),
-    hookToken: stringOption(raw.hookToken),
-    pushToken: stringOption(raw.pushToken),
-    bind: stringOption(raw.bind),
-    port: numberOption(raw.port),
-    path: stringOption(raw.path),
-    includeBody: booleanOption(raw.includeBody),
-    maxBytes: numberOption(raw.maxBytes),
-    renewEveryMinutes: numberOption(raw.renewMinutes),
-    tailscale: stringOption(raw.tailscale) as GmailSetupOptions["tailscale"],
-    tailscalePath: stringOption(raw.tailscalePath),
-    tailscaleTarget: stringOption(raw.tailscaleTarget),
+    topic: common.topic,
+    subscription: common.subscription,
+    label: common.label,
+    hookUrl: common.hookUrl,
+    hookToken: common.hookToken,
+    pushToken: common.pushToken,
+    bind: common.bind,
+    port: common.port,
+    path: common.path,
+    includeBody: common.includeBody,
+    maxBytes: common.maxBytes,
+    renewEveryMinutes: common.renewEveryMinutes,
+    tailscale: common.tailscaleRaw as GmailSetupOptions["tailscale"],
+    tailscalePath: common.tailscalePath,
+    tailscaleTarget: common.tailscaleTarget,
     pushEndpoint: stringOption(raw.pushEndpoint),
     json: Boolean(raw.json),
   };
 }
 
 function parseGmailRunOptions(raw: Record<string, unknown>): GmailRunOptions {
+  const common = parseGmailCommonOptions(raw);
   return {
     account: stringOption(raw.account),
+    topic: common.topic,
+    subscription: common.subscription,
+    label: common.label,
+    hookUrl: common.hookUrl,
+    hookToken: common.hookToken,
+    pushToken: common.pushToken,
+    bind: common.bind,
+    port: common.port,
+    path: common.path,
+    includeBody: common.includeBody,
+    maxBytes: common.maxBytes,
+    renewEveryMinutes: common.renewEveryMinutes,
+    tailscale: common.tailscaleRaw as GmailRunOptions["tailscale"],
+    tailscalePath: common.tailscalePath,
+    tailscaleTarget: common.tailscaleTarget,
+  };
+}
+
+function parseGmailCommonOptions(raw: Record<string, unknown>) {
+  return {
     topic: stringOption(raw.topic),
     subscription: stringOption(raw.subscription),
     label: stringOption(raw.label),
@@ -148,7 +170,7 @@ function parseGmailRunOptions(raw: Record<string, unknown>): GmailRunOptions {
     includeBody: booleanOption(raw.includeBody),
     maxBytes: numberOption(raw.maxBytes),
     renewEveryMinutes: numberOption(raw.renewMinutes),
-    tailscale: stringOption(raw.tailscale) as GmailRunOptions["tailscale"],
+    tailscaleRaw: stringOption(raw.tailscale),
     tailscalePath: stringOption(raw.tailscalePath),
     tailscaleTarget: stringOption(raw.tailscaleTarget),
   };
diff --git a/src/commands/agent.ts b/src/commands/agent.ts
index adeaf865ad9..e8de4b4d86d 100644
--- a/src/commands/agent.ts
+++ b/src/commands/agent.ts
@@ -2,7 +2,7 @@ import type { AgentCommandOpts } from "./agent/types.js";
 import {
   listAgentIds,
   resolveAgentDir,
-  resolveAgentModelFallbacksOverride,
+  resolveEffectiveModelFallbacks,
   resolveAgentModelPrimary,
   resolveAgentSkillsFilter,
   resolveAgentWorkspaceDir,
@@ -63,6 +63,124 @@ import { resolveAgentRunContext } from "./agent/run-context.js";
 import { updateSessionStoreAfterAgentRun } from "./agent/session-store.js";
 import { resolveSession } from "./agent/session.js";
 
+type PersistSessionEntryParams = {
+  sessionStore: Record<string, SessionEntry>;
+  sessionKey: string;
+  storePath: string;
+  entry: SessionEntry;
+};
+
+async function persistSessionEntry(params: PersistSessionEntryParams): Promise<void> {
+  params.sessionStore[params.sessionKey] = params.entry;
+  await updateSessionStore(params.storePath, (store) => {
+    store[params.sessionKey] = params.entry;
+  });
+}
+
+function resolveFallbackRetryPrompt(params: { body: string; isFallbackRetry: boolean }): string {
+  if (!params.isFallbackRetry) {
+    return params.body;
+  }
+  return "Continue where you left off. The previous model attempt failed or timed out.";
+}
+
+function runAgentAttempt(params: {
+  providerOverride: string;
+  modelOverride: string;
+  cfg: ReturnType<typeof loadConfig>;
+  sessionEntry: SessionEntry | undefined;
+  sessionId: string;
+  sessionKey: string | undefined;
+  sessionAgentId: string;
+  sessionFile: string;
+  workspaceDir: string;
+  body: string;
+  isFallbackRetry: boolean;
+  resolvedThinkLevel: ThinkLevel;
+  timeoutMs: number;
+  runId: string;
+  opts: AgentCommandOpts;
+  runContext: ReturnType<typeof resolveAgentRunContext>;
+  spawnedBy: string | undefined;
+  messageChannel: ReturnType<typeof resolveMessageChannel>;
+  skillsSnapshot: ReturnType<typeof buildWorkspaceSkillSnapshot> | undefined;
+  resolvedVerboseLevel: VerboseLevel | undefined;
+  agentDir: string;
+  onAgentEvent: (evt: { stream: string; data?: Record<string, unknown> }) => void;
+  primaryProvider: string;
+}) {
+  const effectivePrompt = resolveFallbackRetryPrompt({
+    body: params.body,
+    isFallbackRetry: params.isFallbackRetry,
+  });
+  if (isCliProvider(params.providerOverride, params.cfg)) {
+    const cliSessionId = getCliSessionId(params.sessionEntry, params.providerOverride);
+    return runCliAgent({
+      sessionId: params.sessionId,
+      sessionKey: params.sessionKey,
+      agentId: params.sessionAgentId,
+      sessionFile: params.sessionFile,
+      workspaceDir: params.workspaceDir,
+      config: params.cfg,
+      prompt: effectivePrompt,
+      provider: params.providerOverride,
+      model: params.modelOverride,
+      thinkLevel: params.resolvedThinkLevel,
+      timeoutMs: params.timeoutMs,
+      runId: params.runId,
+      extraSystemPrompt: params.opts.extraSystemPrompt,
+      cliSessionId,
+      images: params.isFallbackRetry ? undefined : params.opts.images,
+      streamParams: params.opts.streamParams,
+    });
+  }
+
+  const authProfileId =
+    params.providerOverride === params.primaryProvider
+      ? params.sessionEntry?.authProfileOverride
+      : undefined;
+  return runEmbeddedPiAgent({
+    sessionId: params.sessionId,
+    sessionKey: params.sessionKey,
+    agentId: params.sessionAgentId,
+    messageChannel: params.messageChannel,
+    agentAccountId: params.runContext.accountId,
+    messageTo: params.opts.replyTo ?? params.opts.to,
+    messageThreadId: params.opts.threadId,
+    groupId: params.runContext.groupId,
+    groupChannel: params.runContext.groupChannel,
+    groupSpace: params.runContext.groupSpace,
+    spawnedBy: params.spawnedBy,
+    currentChannelId: params.runContext.currentChannelId,
+    currentThreadTs: params.runContext.currentThreadTs,
+    replyToMode: params.runContext.replyToMode,
+    hasRepliedRef: params.runContext.hasRepliedRef,
+    senderIsOwner: true,
+    sessionFile: params.sessionFile,
+    workspaceDir: params.workspaceDir,
+    config: params.cfg,
+    skillsSnapshot: params.skillsSnapshot,
+    prompt: effectivePrompt,
+    images: params.isFallbackRetry ? undefined : params.opts.images,
+    clientTools: params.opts.clientTools,
+    provider: params.providerOverride,
+    model: params.modelOverride,
+    authProfileId,
+    authProfileIdSource: authProfileId ? params.sessionEntry?.authProfileOverrideSource : undefined,
+    thinkLevel: params.resolvedThinkLevel,
+    verboseLevel: params.resolvedVerboseLevel,
+    timeoutMs: params.timeoutMs,
+    runId: params.runId,
+    lane: params.opts.lane,
+    abortSignal: params.opts.abortSignal,
+    extraSystemPrompt: params.opts.extraSystemPrompt,
+    inputProvenance: params.opts.inputProvenance,
+    streamParams: params.opts.streamParams,
+    agentDir: params.agentDir,
+    onAgentEvent: params.onAgentEvent,
+  });
+}
+
 export async function agentCommand(
   opts: AgentCommandOpts,
   runtime: RuntimeEnv = defaultRuntime,
@@ -217,9 +335,11 @@ export async function agentCommand(
         updatedAt: Date.now(),
         skillsSnapshot,
       };
-      sessionStore[sessionKey] = next;
-      await updateSessionStore(storePath, (store) => {
-        store[sessionKey] = next;
+      await persistSessionEntry({
+        sessionStore,
+        sessionKey,
+        storePath,
+        entry: next,
       });
       sessionEntry = next;
     }
@@ -233,9 +353,11 @@ export async function agentCommand(
         next.thinkingLevel = thinkOverride;
       }
       applyVerboseOverride(next, verboseOverride);
-      sessionStore[sessionKey] = next;
-      await updateSessionStore(storePath, (store) => {
-        store[sessionKey] = next;
+      await persistSessionEntry({
+        sessionStore,
+        sessionKey,
+        storePath,
+        entry: next,
       });
     }
 
@@ -307,9 +429,11 @@ export async function agentCommand(
             selection: { provider: defaultProvider, model: defaultModel, isDefault: true },
           });
           if (updated) {
-            sessionStore[sessionKey] = entry;
-            await updateSessionStore(storePath, (store) => {
-              store[sessionKey] = entry;
+            await persistSessionEntry({
+              sessionStore,
+              sessionKey,
+              storePath,
+              entry,
             });
           }
         }
@@ -373,9 +497,11 @@ export async function agentCommand(
         const entry = sessionEntry;
         entry.thinkingLevel = "high";
         entry.updatedAt = Date.now();
-        sessionStore[sessionKey] = entry;
-        await updateSessionStore(storePath, (store) => {
-          store[sessionKey] = entry;
+        await persistSessionEntry({
+          sessionStore,
+          sessionKey,
+          storePath,
+          entry,
         });
       }
     }
@@ -396,18 +522,13 @@ export async function agentCommand(
         opts.replyChannel ?? opts.channel,
       );
       const spawnedBy = opts.spawnedBy ?? sessionEntry?.spawnedBy;
-      // When a session has an explicit model override, keep the candidate chain
-      // anchored to that override (no implicit configured-primary append), while
-      // still preserving configured fallback lists unless the agent explicitly
-      // overrides fallbacks with its own list (including an empty list to disable).
-      const agentFallbacksOverride = resolveAgentModelFallbacksOverride(cfg, sessionAgentId);
-      const defaultFallbacks =
-        typeof cfg.agents?.defaults?.model === "object"
-          ? (cfg.agents.defaults.model.fallbacks ?? [])
-          : [];
-      const effectiveFallbacksOverride = storedModelOverride
-        ? (agentFallbacksOverride ?? defaultFallbacks)
-        : agentFallbacksOverride;
+      // Keep fallback candidate resolution centralized so session model overrides,
+      // per-agent overrides, and default fallbacks stay consistent across callers.
+      const effectiveFallbacksOverride = resolveEffectiveModelFallbacks({
+        cfg,
+        agentId: sessionAgentId,
+        hasSessionModelOverride: Boolean(storedModelOverride),
+      });
 
       // Track model fallback attempts so retries on an existing session don't
       // re-inject the original prompt as a duplicate user message.
@@ -421,76 +542,29 @@ export async function agentCommand(
         run: (providerOverride, modelOverride) => {
           const isFallbackRetry = fallbackAttemptIndex > 0;
           fallbackAttemptIndex += 1;
-          // On fallback retries the session file already contains the original
-          // prompt from the first attempt.  Re-injecting the full prompt would
-          // create a duplicate user message.  Use a short continuation hint
-          // instead so the model picks up where it left off.
-          const effectivePrompt = isFallbackRetry
-            ? "Continue where you left off. The previous model attempt failed or timed out."
-            : body;
-          if (isCliProvider(providerOverride, cfg)) {
-            const cliSessionId = getCliSessionId(sessionEntry, providerOverride);
-            return runCliAgent({
-              sessionId,
-              sessionKey,
-              agentId: sessionAgentId,
-              sessionFile,
-              workspaceDir,
-              config: cfg,
-              prompt: effectivePrompt,
-              provider: providerOverride,
-              model: modelOverride,
-              thinkLevel: resolvedThinkLevel,
-              timeoutMs,
-              runId,
-              extraSystemPrompt: opts.extraSystemPrompt,
-              cliSessionId,
-              images: isFallbackRetry ? undefined : opts.images,
-              streamParams: opts.streamParams,
-            });
-          }
-          const authProfileId =
-            providerOverride === provider ? sessionEntry?.authProfileOverride : undefined;
-          return runEmbeddedPiAgent({
+          return runAgentAttempt({
+            providerOverride,
+            modelOverride,
+            cfg,
+            sessionEntry,
             sessionId,
             sessionKey,
-            agentId: sessionAgentId,
-            messageChannel,
-            agentAccountId: runContext.accountId,
-            messageTo: opts.replyTo ?? opts.to,
-            messageThreadId: opts.threadId,
-            groupId: runContext.groupId,
-            groupChannel: runContext.groupChannel,
-            groupSpace: runContext.groupSpace,
-            spawnedBy,
-            currentChannelId: runContext.currentChannelId,
-            currentThreadTs: runContext.currentThreadTs,
-            replyToMode: runContext.replyToMode,
-            hasRepliedRef: runContext.hasRepliedRef,
-            senderIsOwner: true,
+            sessionAgentId,
             sessionFile,
             workspaceDir,
-            config: cfg,
-            skillsSnapshot,
-            prompt: effectivePrompt,
-            images: isFallbackRetry ? undefined : opts.images,
-            clientTools: opts.clientTools,
-            provider: providerOverride,
-            model: modelOverride,
-            authProfileId,
-            authProfileIdSource: authProfileId
-              ? sessionEntry?.authProfileOverrideSource
-              : undefined,
-            thinkLevel: resolvedThinkLevel,
-            verboseLevel: resolvedVerboseLevel,
+            body,
+            isFallbackRetry,
+            resolvedThinkLevel,
             timeoutMs,
             runId,
-            lane: opts.lane,
-            abortSignal: opts.abortSignal,
-            extraSystemPrompt: opts.extraSystemPrompt,
-            inputProvenance: opts.inputProvenance,
-            streamParams: opts.streamParams,
+            opts,
+            runContext,
+            spawnedBy,
+            messageChannel,
+            skillsSnapshot,
+            resolvedVerboseLevel,
             agentDir,
+            primaryProvider: provider,
             onAgentEvent: (evt) => {
               // Track lifecycle end for fallback emission below.
               if (
diff --git a/src/commands/auth-choice.apply.huggingface.test.ts b/src/commands/auth-choice.apply.huggingface.test.ts
index 3f6d995a908..aa0e2115235 100644
--- a/src/commands/auth-choice.apply.huggingface.test.ts
+++ b/src/commands/auth-choice.apply.huggingface.test.ts
@@ -4,6 +4,7 @@ import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
+import { captureEnv } from "../test-utils/env.js";
 import { applyAuthChoiceHuggingface } from "./auth-choice.apply.huggingface.js";
 
 const noopAsync = async () => {};
@@ -11,9 +12,7 @@ const noop = () => {};
 const authProfilePathFor = (agentDir: string) => path.join(agentDir, "auth-profiles.json");
 
 describe("applyAuthChoiceHuggingface", () => {
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousHfToken = process.env.HF_TOKEN;
-  const previousHubToken = process.env.HUGGINGFACE_HUB_TOKEN;
+  const envSnapshot = captureEnv(["OPENCLAW_AGENT_DIR", "HF_TOKEN", "HUGGINGFACE_HUB_TOKEN"]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -21,21 +20,7 @@ describe("applyAuthChoiceHuggingface", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousHfToken === undefined) {
-      delete process.env.HF_TOKEN;
-    } else {
-      process.env.HF_TOKEN = previousHfToken;
-    }
-    if (previousHubToken === undefined) {
-      delete process.env.HUGGINGFACE_HUB_TOKEN;
-    } else {
-      process.env.HUGGINGFACE_HUB_TOKEN = previousHubToken;
-    }
+    envSnapshot.restore();
   });
 
   it("returns null when authChoice is not huggingface-api-key", async () => {
diff --git a/src/commands/auth-choice.e2e.test.ts b/src/commands/auth-choice.e2e.test.ts
index c58494792b5..2977b750e50 100644
--- a/src/commands/auth-choice.e2e.test.ts
+++ b/src/commands/auth-choice.e2e.test.ts
@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
 import type { AuthChoice } from "./onboard-types.js";
+import { captureEnv } from "../test-utils/env.js";
 import { applyAuthChoice, resolvePreferredProviderForAuthChoice } from "./auth-choice.js";
 import {
   MINIMAX_CN_API_BASE_URL,
@@ -38,18 +39,20 @@ const requireAgentDir = () => {
 };
 
 describe("applyAuthChoice", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
-  const previousAnthropicKey = process.env.ANTHROPIC_API_KEY;
-  const previousOpenrouterKey = process.env.OPENROUTER_API_KEY;
-  const previousHfToken = process.env.HF_TOKEN;
-  const previousHfHubToken = process.env.HUGGINGFACE_HUB_TOKEN;
-  const previousLitellmKey = process.env.LITELLM_API_KEY;
-  const previousAiGatewayKey = process.env.AI_GATEWAY_API_KEY;
-  const previousCloudflareGatewayKey = process.env.CLOUDFLARE_AI_GATEWAY_API_KEY;
-  const previousSshTty = process.env.SSH_TTY;
-  const previousChutesClientId = process.env.CHUTES_CLIENT_ID;
+  const envSnapshot = captureEnv([
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+    "ANTHROPIC_API_KEY",
+    "OPENROUTER_API_KEY",
+    "HF_TOKEN",
+    "HUGGINGFACE_HUB_TOKEN",
+    "LITELLM_API_KEY",
+    "AI_GATEWAY_API_KEY",
+    "CLOUDFLARE_AI_GATEWAY_API_KEY",
+    "SSH_TTY",
+    "CHUTES_CLIENT_ID",
+  ]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -61,66 +64,7 @@ describe("applyAuthChoice", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
-    if (previousAnthropicKey === undefined) {
-      delete process.env.ANTHROPIC_API_KEY;
-    } else {
-      process.env.ANTHROPIC_API_KEY = previousAnthropicKey;
-    }
-    if (previousOpenrouterKey === undefined) {
-      delete process.env.OPENROUTER_API_KEY;
-    } else {
-      process.env.OPENROUTER_API_KEY = previousOpenrouterKey;
-    }
-    if (previousHfToken === undefined) {
-      delete process.env.HF_TOKEN;
-    } else {
-      process.env.HF_TOKEN = previousHfToken;
-    }
-    if (previousHfHubToken === undefined) {
-      delete process.env.HUGGINGFACE_HUB_TOKEN;
-    } else {
-      process.env.HUGGINGFACE_HUB_TOKEN = previousHfHubToken;
-    }
-    if (previousLitellmKey === undefined) {
-      delete process.env.LITELLM_API_KEY;
-    } else {
-      process.env.LITELLM_API_KEY = previousLitellmKey;
-    }
-    if (previousAiGatewayKey === undefined) {
-      delete process.env.AI_GATEWAY_API_KEY;
-    } else {
-      process.env.AI_GATEWAY_API_KEY = previousAiGatewayKey;
-    }
-    if (previousCloudflareGatewayKey === undefined) {
-      delete process.env.CLOUDFLARE_AI_GATEWAY_API_KEY;
-    } else {
-      process.env.CLOUDFLARE_AI_GATEWAY_API_KEY = previousCloudflareGatewayKey;
-    }
-    if (previousSshTty === undefined) {
-      delete process.env.SSH_TTY;
-    } else {
-      process.env.SSH_TTY = previousSshTty;
-    }
-    if (previousChutesClientId === undefined) {
-      delete process.env.CHUTES_CLIENT_ID;
-    } else {
-      process.env.CHUTES_CLIENT_ID = previousChutesClientId;
-    }
+    envSnapshot.restore();
   });
 
   it("does not throw when openai-codex oauth fails", async () => {
diff --git a/src/commands/auth-choice.moonshot.e2e.test.ts b/src/commands/auth-choice.moonshot.e2e.test.ts
index 8bddbd7a6f6..d215125f357 100644
--- a/src/commands/auth-choice.moonshot.e2e.test.ts
+++ b/src/commands/auth-choice.moonshot.e2e.test.ts
@@ -4,6 +4,7 @@ import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "../wizard/prompts.js";
+import { captureEnv } from "../test-utils/env.js";
 import { applyAuthChoice } from "./auth-choice.js";
 
 const noopAsync = async () => {};
@@ -17,65 +18,61 @@ const requireAgentDir = () => {
   return agentDir;
 };
 
+function createRuntime(): RuntimeEnv {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: vi.fn((code: number) => {
+      throw new Error(`exit:${code}`);
+    }),
+  };
+}
+
+function createPrompter(overrides: Partial<WizardPrompter>): WizardPrompter {
+  return {
+    intro: vi.fn(noopAsync),
+    outro: vi.fn(noopAsync),
+    note: vi.fn(noopAsync),
+    select: vi.fn(async () => "" as never),
+    multiselect: vi.fn(async () => []),
+    text: vi.fn(async () => "") as unknown as WizardPrompter["text"],
+    confirm: vi.fn(async () => false),
+    progress: vi.fn(() => ({ update: noop, stop: noop })),
+    ...overrides,
+  };
+}
+
 describe("applyAuthChoice (moonshot)", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
-  const previousMoonshotKey = process.env.MOONSHOT_API_KEY;
+  const envSnapshot = captureEnv([
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+    "MOONSHOT_API_KEY",
+  ]);
   let tempStateDir: string | null = null;
 
+  async function setupTempState() {
+    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-auth-"));
+    process.env.OPENCLAW_STATE_DIR = tempStateDir;
+    process.env.OPENCLAW_AGENT_DIR = path.join(tempStateDir, "agent");
+    process.env.PI_CODING_AGENT_DIR = process.env.OPENCLAW_AGENT_DIR;
+    delete process.env.MOONSHOT_API_KEY;
+  }
+
   afterEach(async () => {
     if (tempStateDir) {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
-    if (previousMoonshotKey === undefined) {
-      delete process.env.MOONSHOT_API_KEY;
-    } else {
-      process.env.MOONSHOT_API_KEY = previousMoonshotKey;
-    }
+    envSnapshot.restore();
   });
 
   it("keeps the .cn baseUrl when setDefaultModel is false", async () => {
-    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-auth-"));
-    process.env.OPENCLAW_STATE_DIR = tempStateDir;
-    process.env.OPENCLAW_AGENT_DIR = path.join(tempStateDir, "agent");
-    process.env.PI_CODING_AGENT_DIR = process.env.OPENCLAW_AGENT_DIR;
-    delete process.env.MOONSHOT_API_KEY;
+    await setupTempState();
 
     const text = vi.fn().mockResolvedValue("sk-moonshot-cn-test");
-    const prompter: WizardPrompter = {
-      intro: vi.fn(noopAsync),
-      outro: vi.fn(noopAsync),
-      note: vi.fn(noopAsync),
-      select: vi.fn(async () => "" as never),
-      multiselect: vi.fn(async () => []),
-      text,
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: noop, stop: noop })),
-    };
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const prompter = createPrompter({ text: text as unknown as WizardPrompter["text"] });
+    const runtime = createRuntime();
 
     const result = await applyAuthChoice({
       authChoice: "moonshot-api-key-cn",
@@ -107,30 +104,11 @@ describe("applyAuthChoice (moonshot)", () => {
   });
 
   it("sets the default model when setDefaultModel is true", async () => {
-    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-auth-"));
-    process.env.OPENCLAW_STATE_DIR = tempStateDir;
-    process.env.OPENCLAW_AGENT_DIR = path.join(tempStateDir, "agent");
-    process.env.PI_CODING_AGENT_DIR = process.env.OPENCLAW_AGENT_DIR;
-    delete process.env.MOONSHOT_API_KEY;
+    await setupTempState();
 
     const text = vi.fn().mockResolvedValue("sk-moonshot-cn-test");
-    const prompter: WizardPrompter = {
-      intro: vi.fn(noopAsync),
-      outro: vi.fn(noopAsync),
-      note: vi.fn(noopAsync),
-      select: vi.fn(async () => "" as never),
-      multiselect: vi.fn(async () => []),
-      text,
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: noop, stop: noop })),
-    };
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const prompter = createPrompter({ text: text as unknown as WizardPrompter["text"] });
+    const runtime = createRuntime();
 
     const result = await applyAuthChoice({
       authChoice: "moonshot-api-key-cn",
diff --git a/src/commands/channels/status.ts b/src/commands/channels/status.ts
index be1e3bb9fac..28debb7e411 100644
--- a/src/commands/channels/status.ts
+++ b/src/commands/channels/status.ts
@@ -18,21 +18,49 @@ export type ChannelsStatusOptions = {
   timeout?: string;
 };
 
+function appendEnabledConfiguredLinkedBits(bits: string[], account: Record<string, unknown>) {
+  if (typeof account.enabled === "boolean") {
+    bits.push(account.enabled ? "enabled" : "disabled");
+  }
+  if (typeof account.configured === "boolean") {
+    bits.push(account.configured ? "configured" : "not configured");
+  }
+  if (typeof account.linked === "boolean") {
+    bits.push(account.linked ? "linked" : "not linked");
+  }
+}
+
+function appendModeBit(bits: string[], account: Record<string, unknown>) {
+  if (typeof account.mode === "string" && account.mode.length > 0) {
+    bits.push(`mode:${account.mode}`);
+  }
+}
+
+function appendTokenSourceBits(bits: string[], account: Record<string, unknown>) {
+  if (typeof account.tokenSource === "string" && account.tokenSource) {
+    bits.push(`token:${account.tokenSource}`);
+  }
+  if (typeof account.botTokenSource === "string" && account.botTokenSource) {
+    bits.push(`bot:${account.botTokenSource}`);
+  }
+  if (typeof account.appTokenSource === "string" && account.appTokenSource) {
+    bits.push(`app:${account.appTokenSource}`);
+  }
+}
+
+function appendBaseUrlBit(bits: string[], account: Record<string, unknown>) {
+  if (typeof account.baseUrl === "string" && account.baseUrl) {
+    bits.push(`url:${account.baseUrl}`);
+  }
+}
+
 export function formatGatewayChannelsStatusLines(payload: Record<string, unknown>): string[] {
   const lines: string[] = [];
   lines.push(theme.success("Gateway reachable."));
   const accountLines = (provider: ChatChannel, accounts: Array<Record<string, unknown>>) =>
     accounts.map((account) => {
       const bits: string[] = [];
-      if (typeof account.enabled === "boolean") {
-        bits.push(account.enabled ? "enabled" : "disabled");
-      }
-      if (typeof account.configured === "boolean") {
-        bits.push(account.configured ? "configured" : "not configured");
-      }
-      if (typeof account.linked === "boolean") {
-        bits.push(account.linked ? "linked" : "not linked");
-      }
+      appendEnabledConfiguredLinkedBits(bits, account);
       if (typeof account.running === "boolean") {
         bits.push(account.running ? "running" : "stopped");
       }
@@ -53,9 +81,7 @@ export function formatGatewayChannelsStatusLines(payload: Record<string, unknown
       if (outboundAt) {
         bits.push(`out:${formatTimeAgo(Date.now() - outboundAt)}`);
       }
-      if (typeof account.mode === "string" && account.mode.length > 0) {
-        bits.push(`mode:${account.mode}`);
-      }
+      appendModeBit(bits, account);
       const botUsername = (() => {
         const bot = account.bot as { username?: string | null } | undefined;
         const probeBot = (account.probe as { bot?: { username?: string | null } } | undefined)?.bot;
@@ -78,15 +104,7 @@ export function formatGatewayChannelsStatusLines(payload: Record<string, unknown
       if (Array.isArray(account.allowFrom) && account.allowFrom.length > 0) {
         bits.push(`allow:${account.allowFrom.slice(0, 2).join(",")}`);
       }
-      if (typeof account.tokenSource === "string" && account.tokenSource) {
-        bits.push(`token:${account.tokenSource}`);
-      }
-      if (typeof account.botTokenSource === "string" && account.botTokenSource) {
-        bits.push(`bot:${account.botTokenSource}`);
-      }
-      if (typeof account.appTokenSource === "string" && account.appTokenSource) {
-        bits.push(`app:${account.appTokenSource}`);
-      }
+      appendTokenSourceBits(bits, account);
       const application = account.application as
         | { intents?: { messageContent?: string } }
         | undefined;
@@ -101,9 +119,7 @@ export function formatGatewayChannelsStatusLines(payload: Record<string, unknown
       if (account.allowUnmentionedGroups === true) {
         bits.push("groups:unmentioned");
       }
-      if (typeof account.baseUrl === "string" && account.baseUrl) {
-        bits.push(`url:${account.baseUrl}`);
-      }
+      appendBaseUrlBit(bits, account);
       const probe = account.probe as { ok?: boolean } | undefined;
       if (probe && typeof probe.ok === "boolean") {
         bits.push(probe.ok ? "works" : "probe failed");
@@ -179,30 +195,10 @@ async function formatConfigChannelsStatusLines(
   const accountLines = (provider: ChatChannel, accounts: Array<Record<string, unknown>>) =>
     accounts.map((account) => {
       const bits: string[] = [];
-      if (typeof account.enabled === "boolean") {
-        bits.push(account.enabled ? "enabled" : "disabled");
-      }
-      if (typeof account.configured === "boolean") {
-        bits.push(account.configured ? "configured" : "not configured");
-      }
-      if (typeof account.linked === "boolean") {
-        bits.push(account.linked ? "linked" : "not linked");
-      }
-      if (typeof account.mode === "string" && account.mode.length > 0) {
-        bits.push(`mode:${account.mode}`);
-      }
-      if (typeof account.tokenSource === "string" && account.tokenSource) {
-        bits.push(`token:${account.tokenSource}`);
-      }
-      if (typeof account.botTokenSource === "string" && account.botTokenSource) {
-        bits.push(`bot:${account.botTokenSource}`);
-      }
-      if (typeof account.appTokenSource === "string" && account.appTokenSource) {
-        bits.push(`app:${account.appTokenSource}`);
-      }
-      if (typeof account.baseUrl === "string" && account.baseUrl) {
-        bits.push(`url:${account.baseUrl}`);
-      }
+      appendEnabledConfiguredLinkedBits(bits, account);
+      appendModeBit(bits, account);
+      appendTokenSourceBits(bits, account);
+      appendBaseUrlBit(bits, account);
       const accountId = typeof account.accountId === "string" ? account.accountId : "default";
       const name = typeof account.name === "string" ? account.name.trim() : "";
       const labelText = formatChannelAccountLabel({
diff --git a/src/commands/cleanup-plan.ts b/src/commands/cleanup-plan.ts
new file mode 100644
index 00000000000..534db21482c
--- /dev/null
+++ b/src/commands/cleanup-plan.ts
@@ -0,0 +1,25 @@
+import type { OpenClawConfig } from "../config/config.js";
+import {
+  loadConfig,
+  resolveConfigPath,
+  resolveOAuthDir,
+  resolveStateDir,
+} from "../config/config.js";
+import { buildCleanupPlan } from "./cleanup-utils.js";
+
+export function resolveCleanupPlanFromDisk(): {
+  cfg: OpenClawConfig;
+  stateDir: string;
+  configPath: string;
+  oauthDir: string;
+  configInsideState: boolean;
+  oauthInsideState: boolean;
+  workspaceDirs: string[];
+} {
+  const cfg = loadConfig();
+  const stateDir = resolveStateDir();
+  const configPath = resolveConfigPath();
+  const oauthDir = resolveOAuthDir();
+  const plan = buildCleanupPlan({ cfg, stateDir, configPath, oauthDir });
+  return { cfg, stateDir, configPath, oauthDir, ...plan };
+}
diff --git a/src/commands/cleanup-utils.test.ts b/src/commands/cleanup-utils.test.ts
new file mode 100644
index 00000000000..2d82753cca2
--- /dev/null
+++ b/src/commands/cleanup-utils.test.ts
@@ -0,0 +1,52 @@
+import path from "node:path";
+import { describe, expect, it, test } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import { buildCleanupPlan } from "./cleanup-utils.js";
+import { applyAgentDefaultPrimaryModel } from "./model-default.js";
+
+describe("buildCleanupPlan", () => {
+  test("resolves inside-state flags and workspace dirs", () => {
+    const tmpRoot = path.join(path.parse(process.cwd()).root, "tmp");
+    const cfg = {
+      agents: {
+        defaults: { workspace: path.join(tmpRoot, "openclaw-workspace-1") },
+        list: [{ workspace: path.join(tmpRoot, "openclaw-workspace-2") }],
+      },
+    };
+    const plan = buildCleanupPlan({
+      cfg: cfg as unknown as OpenClawConfig,
+      stateDir: path.join(tmpRoot, "openclaw-state"),
+      configPath: path.join(tmpRoot, "openclaw-state", "openclaw.json"),
+      oauthDir: path.join(tmpRoot, "openclaw-oauth"),
+    });
+
+    expect(plan.configInsideState).toBe(true);
+    expect(plan.oauthInsideState).toBe(false);
+    expect(new Set(plan.workspaceDirs)).toEqual(
+      new Set([
+        path.join(tmpRoot, "openclaw-workspace-1"),
+        path.join(tmpRoot, "openclaw-workspace-2"),
+      ]),
+    );
+  });
+});
+
+describe("applyAgentDefaultPrimaryModel", () => {
+  it("does not mutate when already set", () => {
+    const cfg = { agents: { defaults: { model: { primary: "a/b" } } } } as OpenClawConfig;
+    const result = applyAgentDefaultPrimaryModel({ cfg, model: "a/b" });
+    expect(result.changed).toBe(false);
+    expect(result.next).toBe(cfg);
+  });
+
+  it("normalizes legacy models", () => {
+    const cfg = { agents: { defaults: { model: { primary: "legacy" } } } } as OpenClawConfig;
+    const result = applyAgentDefaultPrimaryModel({
+      cfg,
+      model: "a/b",
+      legacyModels: new Set(["legacy"]),
+    });
+    expect(result.changed).toBe(false);
+    expect(result.next).toBe(cfg);
+  });
+});
diff --git a/src/commands/cleanup-utils.ts b/src/commands/cleanup-utils.ts
index a1c8dbb7c50..edca7757daa 100644
--- a/src/commands/cleanup-utils.ts
+++ b/src/commands/cleanup-utils.ts
@@ -29,6 +29,23 @@ export function collectWorkspaceDirs(cfg: OpenClawConfig | undefined): string[]
   return [...dirs];
 }
 
+export function buildCleanupPlan(params: {
+  cfg: OpenClawConfig | undefined;
+  stateDir: string;
+  configPath: string;
+  oauthDir: string;
+}): {
+  configInsideState: boolean;
+  oauthInsideState: boolean;
+  workspaceDirs: string[];
+} {
+  return {
+    configInsideState: isPathWithin(params.configPath, params.stateDir),
+    oauthInsideState: isPathWithin(params.oauthDir, params.stateDir),
+    workspaceDirs: collectWorkspaceDirs(params.cfg),
+  };
+}
+
 export function isPathWithin(child: string, parent: string): boolean {
   const relative = path.relative(parent, child);
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
diff --git a/src/commands/configure.gateway.ts b/src/commands/configure.gateway.ts
index 84db572eb26..b0676f311a3 100644
--- a/src/commands/configure.gateway.ts
+++ b/src/commands/configure.gateway.ts
@@ -1,6 +1,11 @@
 import type { OpenClawConfig } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { resolveGatewayPort } from "../config/config.js";
+import {
+  TAILSCALE_DOCS_LINES,
+  TAILSCALE_EXPOSURE_OPTIONS,
+  TAILSCALE_MISSING_BIN_NOTE_LINES,
+} from "../gateway/gateway-config-prompts.shared.js";
 import { findTailscaleBinary } from "../infra/tailscale.js";
 import { validateIPv4AddressInput } from "../shared/net/ipv4.js";
 import { note } from "../terminal/note.js";
@@ -100,19 +105,7 @@ export async function promptGatewayConfig(
   let tailscaleMode = guardCancel(
     await select({
       message: "Tailscale exposure",
-      options: [
-        { value: "off", label: "Off", hint: "No Tailscale exposure" },
-        {
-          value: "serve",
-          label: "Serve",
-          hint: "Private HTTPS for your tailnet (devices on Tailscale)",
-        },
-        {
-          value: "funnel",
-          label: "Funnel",
-          hint: "Public HTTPS via Tailscale Funnel (internet)",
-        },
-      ],
+      options: [...TAILSCALE_EXPOSURE_OPTIONS],
     }),
     runtime,
   );
@@ -121,27 +114,13 @@ export async function promptGatewayConfig(
   if (tailscaleMode !== "off") {
     const tailscaleBin = await findTailscaleBinary();
     if (!tailscaleBin) {
-      note(
-        [
-          "Tailscale binary not found in PATH or /Applications.",
-          "Ensure Tailscale is installed from:",
-          "  https://tailscale.com/download/mac",
-          "",
-          "You can continue setup, but serve/funnel will fail at runtime.",
-        ].join("\n"),
-        "Tailscale Warning",
-      );
+      note(TAILSCALE_MISSING_BIN_NOTE_LINES.join("\n"), "Tailscale Warning");
     }
   }
 
   let tailscaleResetOnExit = false;
   if (tailscaleMode !== "off") {
-    note(
-      ["Docs:", "https://docs.openclaw.ai/gateway/tailscale", "https://docs.openclaw.ai/web"].join(
-        "\n",
-      ),
-      "Tailscale",
-    );
+    note(TAILSCALE_DOCS_LINES.join("\n"), "Tailscale");
     tailscaleResetOnExit = Boolean(
       guardCancel(
         await confirm({
diff --git a/src/commands/doctor-config-flow.ts b/src/commands/doctor-config-flow.ts
index 511141e366d..287a2ac8ca6 100644
--- a/src/commands/doctor-config-flow.ts
+++ b/src/commands/doctor-config-flow.ts
@@ -3,6 +3,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
 import type { DoctorOptions } from "./doctor-prompter.js";
+import {
+  isNumericTelegramUserId,
+  normalizeTelegramAllowFromEntry,
+} from "../channels/telegram/allow-from.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import {
   OpenClawSchema,
@@ -143,18 +147,6 @@ function noteOpencodeProviderOverrides(cfg: OpenClawConfig) {
   note(lines.join("\n"), "OpenCode Zen");
 }
 
-function normalizeTelegramAllowFromEntry(raw: unknown): string {
-  const base = typeof raw === "string" ? raw : typeof raw === "number" ? String(raw) : "";
-  return base
-    .trim()
-    .replace(/^(telegram|tg):/i, "")
-    .trim();
-}
-
-function isNumericTelegramUserId(raw: string): boolean {
-  return /^\d+$/.test(raw);
-}
-
 type TelegramAllowFromUsernameHit = { path: string; entry: string };
 
 function scanTelegramAllowFromUsernameEntries(cfg: OpenClawConfig): TelegramAllowFromUsernameHit[] {
diff --git a/src/commands/doctor-memory-search.test.ts b/src/commands/doctor-memory-search.test.ts
index 334e0518214..9db631a6fe1 100644
--- a/src/commands/doctor-memory-search.test.ts
+++ b/src/commands/doctor-memory-search.test.ts
@@ -1,3 +1,4 @@
+import path from "node:path";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 
@@ -25,6 +26,7 @@ vi.mock("../agents/model-auth.js", () => ({
 }));
 
 import { noteMemorySearchHealth } from "./doctor-memory-search.js";
+import { detectLegacyWorkspaceDirs } from "./doctor-workspace.js";
 
 describe("noteMemorySearchHealth", () => {
   const cfg = {} as OpenClawConfig;
@@ -85,3 +87,12 @@ describe("noteMemorySearchHealth", () => {
     expect(note).not.toHaveBeenCalled();
   });
 });
+
+describe("detectLegacyWorkspaceDirs", () => {
+  it("returns active workspace and no legacy dirs", () => {
+    const workspaceDir = "/home/user/openclaw";
+    const detection = detectLegacyWorkspaceDirs({ workspaceDir });
+    expect(detection.activeWorkspace).toBe(path.resolve(workspaceDir));
+    expect(detection.legacyDirs).toEqual([]);
+  });
+});
diff --git a/src/commands/doctor-state-migrations.e2e.test.ts b/src/commands/doctor-state-migrations.e2e.test.ts
index ce8474f5468..5d43859173c 100644
--- a/src/commands/doctor-state-migrations.e2e.test.ts
+++ b/src/commands/doctor-state-migrations.e2e.test.ts
@@ -178,6 +178,42 @@ describe("doctor legacy state migrations", () => {
     expect(fs.existsSync(path.join(oauthDir, "creds.json"))).toBe(false);
   });
 
+  it("migrates legacy Telegram pairing allowFrom store to account-scoped default file", async () => {
+    const root = await makeTempRoot();
+    const cfg: OpenClawConfig = {};
+
+    const oauthDir = path.join(root, "credentials");
+    fs.mkdirSync(oauthDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(oauthDir, "telegram-allowFrom.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          allowFrom: ["123456"],
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf-8",
+    );
+
+    const detected = await detectLegacyStateMigrations({
+      cfg,
+      env: { OPENCLAW_STATE_DIR: root } as NodeJS.ProcessEnv,
+    });
+    expect(detected.pairingAllowFrom.hasLegacyTelegram).toBe(true);
+
+    const result = await runLegacyStateMigrations({ detected, now: () => 123 });
+    expect(result.warnings).toEqual([]);
+
+    const target = path.join(oauthDir, "telegram-default-allowFrom.json");
+    expect(fs.existsSync(target)).toBe(true);
+    expect(JSON.parse(fs.readFileSync(target, "utf-8"))).toEqual({
+      version: 1,
+      allowFrom: ["123456"],
+    });
+  });
+
   it("no-ops when nothing detected", async () => {
     const root = await makeTempRoot();
     const cfg: OpenClawConfig = {};
diff --git a/src/commands/doctor-workspace.e2e.test.ts b/src/commands/doctor-workspace.e2e.test.ts
deleted file mode 100644
index fb0d46a56e8..00000000000
--- a/src/commands/doctor-workspace.e2e.test.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { detectLegacyWorkspaceDirs } from "./doctor-workspace.js";
-
-describe("detectLegacyWorkspaceDirs", () => {
-  it("returns active workspace and no legacy dirs", () => {
-    const workspaceDir = "/home/user/openclaw";
-    const detection = detectLegacyWorkspaceDirs({ workspaceDir });
-    expect(detection.activeWorkspace).toBe(path.resolve(workspaceDir));
-    expect(detection.legacyDirs).toEqual([]);
-  });
-});
diff --git a/src/commands/doctor.e2e-harness.ts b/src/commands/doctor.e2e-harness.ts
index beb20a8180d..126d912f486 100644
--- a/src/commands/doctor.e2e-harness.ts
+++ b/src/commands/doctor.e2e-harness.ts
@@ -116,6 +116,11 @@ export const detectLegacyStateMigrations = vi.fn().mockResolvedValue({
     targetDir: "/tmp/oauth/whatsapp/default",
     hasLegacy: false,
   },
+  pairingAllowFrom: {
+    legacyTelegramPath: "/tmp/oauth/telegram-allowFrom.json",
+    targetTelegramPath: "/tmp/oauth/telegram-default-allowFrom.json",
+    hasLegacyTelegram: false,
+  },
   preview: [],
 }) as unknown as MockFn;
 
@@ -306,6 +311,11 @@ export async function arrangeLegacyStateMigrationTest(): Promise<{
       targetDir: "/tmp/oauth/whatsapp/default",
       hasLegacy: false,
     },
+    pairingAllowFrom: {
+      legacyTelegramPath: "/tmp/oauth/telegram-allowFrom.json",
+      targetTelegramPath: "/tmp/oauth/telegram-default-allowFrom.json",
+      hasLegacyTelegram: false,
+    },
     preview: ["- Legacy sessions detected"],
   });
   runLegacyStateMigrations.mockResolvedValueOnce({
diff --git a/src/commands/doctor.falls-back-legacy-sandbox-image-missing.e2e.test.ts b/src/commands/doctor.falls-back-legacy-sandbox-image-missing.e2e.test.ts
deleted file mode 100644
index 79c3b3ec1e1..00000000000
--- a/src/commands/doctor.falls-back-legacy-sandbox-image-missing.e2e.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { arrangeLegacyStateMigrationTest, confirm } from "./doctor.e2e-harness.js";
-
-describe("doctor command", () => {
-  it("runs legacy state migrations in non-interactive mode without prompting", async () => {
-    const { doctorCommand, runtime, runLegacyStateMigrations } =
-      await arrangeLegacyStateMigrationTest();
-
-    await doctorCommand(runtime, { nonInteractive: true });
-
-    expect(runLegacyStateMigrations).toHaveBeenCalledTimes(1);
-    expect(confirm).not.toHaveBeenCalled();
-  }, 30_000);
-});
diff --git a/src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts b/src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts
index 635cf8a05f7..1df276f3da6 100644
--- a/src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts
+++ b/src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts
@@ -20,6 +20,16 @@ describe("doctor command", () => {
     expect(confirm).not.toHaveBeenCalled();
   }, 30_000);
 
+  it("runs legacy state migrations in non-interactive mode without prompting", async () => {
+    const { doctorCommand, runtime, runLegacyStateMigrations } =
+      await arrangeLegacyStateMigrationTest();
+
+    await doctorCommand(runtime, { nonInteractive: true });
+
+    expect(runLegacyStateMigrations).toHaveBeenCalledTimes(1);
+    expect(confirm).not.toHaveBeenCalled();
+  }, 30_000);
+
   it("skips gateway restarts in non-interactive mode", async () => {
     readConfigFileSnapshot.mockResolvedValue({
       path: "/tmp/openclaw.json",
diff --git a/src/commands/google-gemini-model-default.ts b/src/commands/google-gemini-model-default.ts
index a343a29fb3b..385f1cc849d 100644
--- a/src/commands/google-gemini-model-default.ts
+++ b/src/commands/google-gemini-model-default.ts
@@ -1,44 +1,11 @@
 import type { OpenClawConfig } from "../config/config.js";
-import type { AgentModelListConfig } from "../config/types.js";
+import { applyAgentDefaultPrimaryModel } from "./model-default.js";
 
 export const GOOGLE_GEMINI_DEFAULT_MODEL = "google/gemini-3-pro-preview";
 
-function resolvePrimaryModel(model?: AgentModelListConfig | string): string | undefined {
-  if (typeof model === "string") {
-    return model;
-  }
-  if (model && typeof model === "object" && typeof model.primary === "string") {
-    return model.primary;
-  }
-  return undefined;
-}
-
 export function applyGoogleGeminiModelDefault(cfg: OpenClawConfig): {
   next: OpenClawConfig;
   changed: boolean;
 } {
-  const current = resolvePrimaryModel(cfg.agents?.defaults?.model)?.trim();
-  if (current === GOOGLE_GEMINI_DEFAULT_MODEL) {
-    return { next: cfg, changed: false };
-  }
-
-  return {
-    next: {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model:
-            cfg.agents?.defaults?.model && typeof cfg.agents.defaults.model === "object"
-              ? {
-                  ...cfg.agents.defaults.model,
-                  primary: GOOGLE_GEMINI_DEFAULT_MODEL,
-                }
-              : { primary: GOOGLE_GEMINI_DEFAULT_MODEL },
-        },
-      },
-    },
-    changed: true,
-  };
+  return applyAgentDefaultPrimaryModel({ cfg, model: GOOGLE_GEMINI_DEFAULT_MODEL });
 }
diff --git a/src/commands/health-format.e2e.test.ts b/src/commands/health-format.e2e.test.ts
deleted file mode 100644
index 7381743f1f2..00000000000
--- a/src/commands/health-format.e2e.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { stripAnsi } from "../terminal/ansi.js";
-import { formatHealthCheckFailure } from "./health-format.js";
-
-describe("formatHealthCheckFailure", () => {
-  it("keeps non-rich output stable", () => {
-    const err = new Error("gateway closed (1006 abnormal closure): no close reason");
-    expect(formatHealthCheckFailure(err, { rich: false })).toBe(
-      `Health check failed: ${String(err)}`,
-    );
-  });
-
-  it("formats gateway connection details as indented key/value lines", () => {
-    const err = new Error(
-      [
-        "gateway closed (1006 abnormal closure (no close frame)): no close reason",
-        "Gateway target: ws://127.0.0.1:19001",
-        "Source: local loopback",
-        "Config: /Users/steipete/.openclaw-dev/openclaw.json",
-        "Bind: loopback",
-      ].join("\n"),
-    );
-
-    expect(stripAnsi(formatHealthCheckFailure(err, { rich: true }))).toBe(
-      [
-        "Health check failed: gateway closed (1006 abnormal closure (no close frame)): no close reason",
-        "  Gateway target: ws://127.0.0.1:19001",
-        "  Source: local loopback",
-        "  Config: /Users/steipete/.openclaw-dev/openclaw.json",
-        "  Bind: loopback",
-      ].join("\n"),
-    );
-  });
-});
diff --git a/src/commands/health.e2e.test.ts b/src/commands/health.e2e.test.ts
index 289af11bb79..e452b1389a8 100644
--- a/src/commands/health.e2e.test.ts
+++ b/src/commands/health.e2e.test.ts
@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { HealthSummary } from "./health.js";
+import { stripAnsi } from "../terminal/ansi.js";
+import { formatHealthCheckFailure } from "./health-format.js";
 import { formatHealthChannelLines, healthCommand } from "./health.js";
 
 const runtime = {
@@ -173,3 +175,34 @@ describe("healthCommand", () => {
     );
   });
 });
+
+describe("formatHealthCheckFailure", () => {
+  it("keeps non-rich output stable", () => {
+    const err = new Error("gateway closed (1006 abnormal closure): no close reason");
+    expect(formatHealthCheckFailure(err, { rich: false })).toBe(
+      `Health check failed: ${String(err)}`,
+    );
+  });
+
+  it("formats gateway connection details as indented key/value lines", () => {
+    const err = new Error(
+      [
+        "gateway closed (1006 abnormal closure (no close frame)): no close reason",
+        "Gateway target: ws://127.0.0.1:19001",
+        "Source: local loopback",
+        "Config: /Users/steipete/.openclaw-dev/openclaw.json",
+        "Bind: loopback",
+      ].join("\n"),
+    );
+
+    expect(stripAnsi(formatHealthCheckFailure(err, { rich: true }))).toBe(
+      [
+        "Health check failed: gateway closed (1006 abnormal closure (no close frame)): no close reason",
+        "  Gateway target: ws://127.0.0.1:19001",
+        "  Source: local loopback",
+        "  Config: /Users/steipete/.openclaw-dev/openclaw.json",
+        "  Bind: loopback",
+      ].join("\n"),
+    );
+  });
+});
diff --git a/src/commands/model-default.ts b/src/commands/model-default.ts
new file mode 100644
index 00000000000..ce121973da3
--- /dev/null
+++ b/src/commands/model-default.ts
@@ -0,0 +1,45 @@
+import type { OpenClawConfig } from "../config/config.js";
+import type { AgentModelListConfig } from "../config/types.js";
+
+export function resolvePrimaryModel(model?: AgentModelListConfig | string): string | undefined {
+  if (typeof model === "string") {
+    return model;
+  }
+  if (model && typeof model === "object" && typeof model.primary === "string") {
+    return model.primary;
+  }
+  return undefined;
+}
+
+export function applyAgentDefaultPrimaryModel(params: {
+  cfg: OpenClawConfig;
+  model: string;
+  legacyModels?: Set<string>;
+}): { next: OpenClawConfig; changed: boolean } {
+  const current = resolvePrimaryModel(params.cfg.agents?.defaults?.model)?.trim();
+  const normalizedCurrent = current && params.legacyModels?.has(current) ? params.model : current;
+  if (normalizedCurrent === params.model) {
+    return { next: params.cfg, changed: false };
+  }
+
+  return {
+    next: {
+      ...params.cfg,
+      agents: {
+        ...params.cfg.agents,
+        defaults: {
+          ...params.cfg.agents?.defaults,
+          model:
+            params.cfg.agents?.defaults?.model &&
+            typeof params.cfg.agents.defaults.model === "object"
+              ? {
+                  ...params.cfg.agents.defaults.model,
+                  primary: params.model,
+                }
+              : { primary: params.model },
+        },
+      },
+    },
+    changed: true,
+  };
+}
diff --git a/src/commands/model-picker.ts b/src/commands/model-picker.ts
index 0afd7b2e6f2..22956dcec61 100644
--- a/src/commands/model-picker.ts
+++ b/src/commands/model-picker.ts
@@ -57,6 +57,25 @@ function hasAuthForProvider(
   return false;
 }
 
+function createProviderAuthChecker(params: {
+  cfg: OpenClawConfig;
+  agentDir?: string;
+}): (provider: string) => boolean {
+  const authStore = ensureAuthProfileStore(params.agentDir, {
+    allowKeychainPrompt: false,
+  });
+  const authCache = new Map<string, boolean>();
+  return (provider: string) => {
+    const cached = authCache.get(provider);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const value = hasAuthForProvider(provider, params.cfg, authStore);
+    authCache.set(provider, value);
+    return value;
+  };
+}
+
 function resolveConfiguredModelRaw(cfg: OpenClawConfig): string {
   const raw = cfg.agents?.defaults?.model as { primary?: string } | string | undefined;
   if (typeof raw === "string") {
@@ -235,19 +254,7 @@ export async function promptDefaultModel(
   }
 
   const agentDir = params.agentDir;
-  const authStore = ensureAuthProfileStore(agentDir, {
-    allowKeychainPrompt: false,
-  });
-  const authCache = new Map<string, boolean>();
-  const hasAuth = (provider: string) => {
-    const cached = authCache.get(provider);
-    if (cached !== undefined) {
-      return cached;
-    }
-    const value = hasAuthForProvider(provider, cfg, authStore);
-    authCache.set(provider, value);
-    return value;
-  };
+  const hasAuth = createProviderAuthChecker({ cfg, agentDir });
 
   const options: WizardSelectOption[] = [];
   if (allowKeep) {
@@ -383,19 +390,7 @@ export async function promptModelAllowlist(params: {
     cfg,
     defaultProvider: DEFAULT_PROVIDER,
   });
-  const authStore = ensureAuthProfileStore(params.agentDir, {
-    allowKeychainPrompt: false,
-  });
-  const authCache = new Map<string, boolean>();
-  const hasAuth = (provider: string) => {
-    const cached = authCache.get(provider);
-    if (cached !== undefined) {
-      return cached;
-    }
-    const value = hasAuthForProvider(provider, cfg, authStore);
-    authCache.set(provider, value);
-    return value;
-  };
+  const hasAuth = createProviderAuthChecker({ cfg, agentDir: params.agentDir });
 
   const options: WizardSelectOption[] = [];
   const seen = new Set<string>();
diff --git a/src/commands/models.list.test.ts b/src/commands/models.list.test.ts
index 27e2b1af0f4..932ccec7a03 100644
--- a/src/commands/models.list.test.ts
+++ b/src/commands/models.list.test.ts
@@ -153,30 +153,6 @@ describe("models list/status", () => {
     ({ modelsListCommand } = await import("./models/list.list-command.js"));
   });
 
-  it("models list outputs canonical zai key for configured z.ai model", async () => {
-    loadConfig.mockReturnValue({
-      agents: { defaults: { model: "z.ai/glm-4.7" } },
-    });
-    const runtime = makeRuntime();
-
-    const model = {
-      provider: "zai",
-      id: "glm-4.7",
-      name: "GLM-4.7",
-      input: ["text"],
-      baseUrl: "https://api.z.ai/v1",
-      contextWindow: 128000,
-    };
-
-    modelRegistryState.models = [model];
-    modelRegistryState.available = [model];
-    await modelsListCommand({ json: true }, runtime);
-
-    expect(runtime.log).toHaveBeenCalledTimes(1);
-    const payload = JSON.parse(String(runtime.log.mock.calls[0]?.[0]));
-    expect(payload.models[0]?.key).toBe("zai/glm-4.7");
-  });
-
   it("models list plain outputs canonical zai key", async () => {
     loadConfig.mockReturnValue({
       agents: { defaults: { model: "z.ai/glm-4.7" } },
@@ -200,18 +176,10 @@ describe("models list/status", () => {
     expect(runtime.log.mock.calls[0]?.[0]).toBe("zai/glm-4.7");
   });
 
-  it("models list provider filter normalizes z.ai alias", async () => {
-    await expectZaiProviderFilter("z.ai");
-  });
-
   it("models list provider filter normalizes Z.AI alias casing", async () => {
     await expectZaiProviderFilter("Z.AI");
   });
 
-  it("models list provider filter normalizes z-ai alias", async () => {
-    await expectZaiProviderFilter("z-ai");
-  });
-
   it("models list marks auth as unavailable when ZAI key is missing", async () => {
     loadConfig.mockReturnValue({
       agents: { defaults: { model: "z.ai/glm-4.7" } },
@@ -348,42 +316,6 @@ describe("models list/status", () => {
     expect(payload.models[0]?.available).toBe(true);
   });
 
-  it("models list marks synthesized antigravity opus 4.6 (non-thinking) as available when template is available", async () => {
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          model: "google-antigravity/claude-opus-4-6",
-          models: {
-            "google-antigravity/claude-opus-4-6": {},
-          },
-        },
-      },
-    });
-    const runtime = makeRuntime();
-
-    const template = {
-      provider: "google-antigravity",
-      id: "claude-opus-4-5",
-      name: "Claude Opus 4.5",
-      api: "google-gemini-cli",
-      input: ["text", "image"],
-      baseUrl: "https://daily-cloudcode-pa.sandbox.googleapis.com",
-      contextWindow: 200000,
-      maxTokens: 64000,
-      reasoning: true,
-      cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-    };
-    modelRegistryState.models = [template];
-    modelRegistryState.available = [template];
-    await modelsListCommand({ json: true }, runtime);
-
-    expect(runtime.log).toHaveBeenCalledTimes(1);
-    const payload = JSON.parse(String(runtime.log.mock.calls[0]?.[0]));
-    expect(payload.models[0]?.key).toBe("google-antigravity/claude-opus-4-6");
-    expect(payload.models[0]?.missing).toBe(false);
-    expect(payload.models[0]?.available).toBe(true);
-  });
-
   it("models list prefers registry availability over provider auth heuristics", async () => {
     loadConfig.mockReturnValue({
       agents: {
@@ -426,55 +358,6 @@ describe("models list/status", () => {
     listProfilesForProvider.mockReturnValue([]);
   });
 
-  it("models list falls back to auth heuristics when registry availability is unavailable", async () => {
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          model: "google-antigravity/claude-opus-4-6-thinking",
-          models: {
-            "google-antigravity/claude-opus-4-6-thinking": {},
-          },
-        },
-      },
-    });
-    listProfilesForProvider.mockImplementation((_: unknown, provider: string) =>
-      provider === "google-antigravity"
-        ? ([{ id: "profile-1" }] as Array<Record<string, unknown>>)
-        : [],
-    );
-    modelRegistryState.getAvailableError = Object.assign(
-      new Error("availability unsupported: getAvailable failed"),
-      { code: "MODEL_AVAILABILITY_UNAVAILABLE" },
-    );
-    const runtime = makeRuntime();
-
-    modelRegistryState.models = [
-      {
-        provider: "google-antigravity",
-        id: "claude-opus-4-5-thinking",
-        name: "Claude Opus 4.5 Thinking",
-        api: "google-gemini-cli",
-        input: ["text", "image"],
-        baseUrl: "https://daily-cloudcode-pa.sandbox.googleapis.com",
-        contextWindow: 200000,
-        maxTokens: 64000,
-        reasoning: true,
-        cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-      },
-    ];
-    modelRegistryState.available = [];
-    await modelsListCommand({ json: true }, runtime);
-
-    expect(runtime.error).toHaveBeenCalledTimes(1);
-    expect(runtime.error.mock.calls[0]?.[0]).toContain("falling back to auth heuristics");
-    expect(runtime.error.mock.calls[0]?.[0]).toContain("getAvailable failed");
-    expect(runtime.log).toHaveBeenCalledTimes(1);
-    const payload = JSON.parse(String(runtime.log.mock.calls[0]?.[0]));
-    expect(payload.models[0]?.key).toBe("google-antigravity/claude-opus-4-6-thinking");
-    expect(payload.models[0]?.missing).toBe(false);
-    expect(payload.models[0]?.available).toBe(true);
-  });
-
   it("models list falls back to auth heuristics when getAvailable returns invalid shape", async () => {
     loadConfig.mockReturnValue({
       agents: {
@@ -627,29 +510,6 @@ describe("models list/status", () => {
     expect(process.exitCode).toBe(1);
   });
 
-  it("loadModelRegistry throws when model discovery is unavailable", async () => {
-    modelRegistryState.getAllError = Object.assign(new Error("model discovery unavailable"), {
-      code: "MODEL_DISCOVERY_UNAVAILABLE",
-    });
-    modelRegistryState.available = [
-      {
-        provider: "google-antigravity",
-        id: "claude-opus-4-5-thinking",
-        name: "Claude Opus 4.5 Thinking",
-        api: "google-gemini-cli",
-        input: ["text", "image"],
-        baseUrl: "https://daily-cloudcode-pa.sandbox.googleapis.com",
-        contextWindow: 200000,
-        maxTokens: 64000,
-        reasoning: true,
-        cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
-      },
-    ];
-
-    const { loadModelRegistry } = await import("./models/list.registry.js");
-    await expect(loadModelRegistry({})).rejects.toThrow("model discovery unavailable");
-  });
-
   it("toModelRow does not crash without cfg/authStore when availability is undefined", async () => {
     const { toModelRow } = await import("./models/list.registry.js");
 
diff --git a/src/commands/models/auth-order.ts b/src/commands/models/auth-order.ts
index b8f373eaaa3..9dc820c8e9e 100644
--- a/src/commands/models/auth-order.ts
+++ b/src/commands/models/auth-order.ts
@@ -28,18 +28,22 @@ function describeOrder(store: AuthProfileStore, provider: string): string[] {
   return Array.isArray(order) ? order : [];
 }
 
-export async function modelsAuthOrderGetCommand(
-  opts: { provider: string; agent?: string; json?: boolean },
-  runtime: RuntimeEnv,
-) {
+function resolveAuthOrderContext(opts: { provider: string; agent?: string }) {
   const rawProvider = opts.provider?.trim();
   if (!rawProvider) {
     throw new Error("Missing --provider.");
   }
   const provider = normalizeProviderId(rawProvider);
-
   const cfg = loadConfig();
   const { agentId, agentDir } = resolveTargetAgent(cfg, opts.agent);
+  return { cfg, agentId, agentDir, provider };
+}
+
+export async function modelsAuthOrderGetCommand(
+  opts: { provider: string; agent?: string; json?: boolean },
+  runtime: RuntimeEnv,
+) {
+  const { agentId, agentDir, provider } = resolveAuthOrderContext(opts);
   const store = ensureAuthProfileStore(agentDir, {
     allowKeychainPrompt: false,
   });
@@ -72,14 +76,7 @@ export async function modelsAuthOrderClearCommand(
   opts: { provider: string; agent?: string },
   runtime: RuntimeEnv,
 ) {
-  const rawProvider = opts.provider?.trim();
-  if (!rawProvider) {
-    throw new Error("Missing --provider.");
-  }
-  const provider = normalizeProviderId(rawProvider);
-
-  const cfg = loadConfig();
-  const { agentId, agentDir } = resolveTargetAgent(cfg, opts.agent);
+  const { agentId, agentDir, provider } = resolveAuthOrderContext(opts);
   const updated = await setAuthProfileOrder({
     agentDir,
     provider,
@@ -98,19 +95,12 @@ export async function modelsAuthOrderSetCommand(
   opts: { provider: string; agent?: string; order: string[] },
   runtime: RuntimeEnv,
 ) {
-  const rawProvider = opts.provider?.trim();
-  if (!rawProvider) {
-    throw new Error("Missing --provider.");
-  }
-  const provider = normalizeProviderId(rawProvider);
-
-  const cfg = loadConfig();
-  const { agentId, agentDir } = resolveTargetAgent(cfg, opts.agent);
+  const { agentId, agentDir, provider } = resolveAuthOrderContext(opts);
 
   const store = ensureAuthProfileStore(agentDir, {
     allowKeychainPrompt: false,
   });
-  const providerKey = normalizeProviderId(provider);
+  const providerKey = provider;
   const requested = (opts.order ?? []).map((entry) => String(entry).trim()).filter(Boolean);
   if (requested.length === 0) {
     throw new Error("Missing profile ids. Provide one or more profile ids.");
diff --git a/src/commands/models/fallbacks-shared.ts b/src/commands/models/fallbacks-shared.ts
new file mode 100644
index 00000000000..1070249ddd5
--- /dev/null
+++ b/src/commands/models/fallbacks-shared.ts
@@ -0,0 +1,158 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { RuntimeEnv } from "../../runtime.js";
+import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/model-selection.js";
+import { loadConfig } from "../../config/config.js";
+import { logConfigUpdated } from "../../config/logging.js";
+import {
+  DEFAULT_PROVIDER,
+  ensureFlagCompatibility,
+  mergePrimaryFallbackConfig,
+  type PrimaryFallbackConfig,
+  modelKey,
+  resolveModelTarget,
+  resolveModelKeysFromEntries,
+  updateConfig,
+} from "./shared.js";
+
+type DefaultsFallbackKey = "model" | "imageModel";
+
+function getFallbacks(cfg: OpenClawConfig, key: DefaultsFallbackKey): string[] {
+  const entry = cfg.agents?.defaults?.[key] as unknown as PrimaryFallbackConfig | undefined;
+  return entry?.fallbacks ?? [];
+}
+
+function patchDefaultsFallbacks(
+  cfg: OpenClawConfig,
+  params: { key: DefaultsFallbackKey; fallbacks: string[]; models?: Record<string, unknown> },
+): OpenClawConfig {
+  const existing = cfg.agents?.defaults?.[params.key] as unknown as
+    | PrimaryFallbackConfig
+    | undefined;
+  return {
+    ...cfg,
+    agents: {
+      ...cfg.agents,
+      defaults: {
+        ...cfg.agents?.defaults,
+        [params.key]: mergePrimaryFallbackConfig(existing, { fallbacks: params.fallbacks }),
+        ...(params.models ? { models: params.models as never } : undefined),
+      },
+    },
+  };
+}
+
+export async function listFallbacksCommand(
+  params: { label: string; key: DefaultsFallbackKey },
+  opts: { json?: boolean; plain?: boolean },
+  runtime: RuntimeEnv,
+) {
+  ensureFlagCompatibility(opts);
+  const cfg = loadConfig();
+  const fallbacks = getFallbacks(cfg, params.key);
+
+  if (opts.json) {
+    runtime.log(JSON.stringify({ fallbacks }, null, 2));
+    return;
+  }
+  if (opts.plain) {
+    for (const entry of fallbacks) {
+      runtime.log(entry);
+    }
+    return;
+  }
+
+  runtime.log(`${params.label} (${fallbacks.length}):`);
+  if (fallbacks.length === 0) {
+    runtime.log("- none");
+    return;
+  }
+  for (const entry of fallbacks) {
+    runtime.log(`- ${entry}`);
+  }
+}
+
+export async function addFallbackCommand(
+  params: {
+    label: string;
+    key: DefaultsFallbackKey;
+    logPrefix: string;
+  },
+  modelRaw: string,
+  runtime: RuntimeEnv,
+) {
+  const updated = await updateConfig((cfg) => {
+    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+    const targetKey = modelKey(resolved.provider, resolved.model);
+    const nextModels = { ...cfg.agents?.defaults?.models } as Record<string, unknown>;
+    if (!nextModels[targetKey]) {
+      nextModels[targetKey] = {};
+    }
+    const existing = getFallbacks(cfg, params.key);
+    const existingKeys = resolveModelKeysFromEntries({ cfg, entries: existing });
+    if (existingKeys.includes(targetKey)) {
+      return cfg;
+    }
+
+    return patchDefaultsFallbacks(cfg, {
+      key: params.key,
+      fallbacks: [...existing, targetKey],
+      models: nextModels,
+    });
+  });
+
+  logConfigUpdated(runtime);
+  runtime.log(`${params.logPrefix}: ${getFallbacks(updated, params.key).join(", ")}`);
+}
+
+export async function removeFallbackCommand(
+  params: {
+    label: string;
+    key: DefaultsFallbackKey;
+    notFoundLabel: string;
+    logPrefix: string;
+  },
+  modelRaw: string,
+  runtime: RuntimeEnv,
+) {
+  const updated = await updateConfig((cfg) => {
+    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
+    const targetKey = modelKey(resolved.provider, resolved.model);
+    const aliasIndex = buildModelAliasIndex({
+      cfg,
+      defaultProvider: DEFAULT_PROVIDER,
+    });
+    const existing = getFallbacks(cfg, params.key);
+    const filtered = existing.filter((entry) => {
+      const resolvedEntry = resolveModelRefFromString({
+        raw: String(entry ?? ""),
+        defaultProvider: DEFAULT_PROVIDER,
+        aliasIndex,
+      });
+      if (!resolvedEntry) {
+        return true;
+      }
+      return modelKey(resolvedEntry.ref.provider, resolvedEntry.ref.model) !== targetKey;
+    });
+
+    if (filtered.length === existing.length) {
+      throw new Error(`${params.notFoundLabel} not found: ${targetKey}`);
+    }
+
+    return patchDefaultsFallbacks(cfg, { key: params.key, fallbacks: filtered });
+  });
+
+  logConfigUpdated(runtime);
+  runtime.log(`${params.logPrefix}: ${getFallbacks(updated, params.key).join(", ")}`);
+}
+
+export async function clearFallbacksCommand(
+  params: { key: DefaultsFallbackKey; clearedMessage: string },
+  runtime: RuntimeEnv,
+) {
+  await updateConfig((cfg) => {
+    return patchDefaultsFallbacks(cfg, { key: params.key, fallbacks: [] });
+  });
+
+  logConfigUpdated(runtime);
+  runtime.log(params.clearedMessage);
+}
diff --git a/src/commands/models/fallbacks.ts b/src/commands/models/fallbacks.ts
index afd14667b21..f588dbc2452 100644
--- a/src/commands/models/fallbacks.ts
+++ b/src/commands/models/fallbacks.ts
@@ -1,164 +1,42 @@
 import type { RuntimeEnv } from "../../runtime.js";
-import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/model-selection.js";
-import { loadConfig } from "../../config/config.js";
-import { logConfigUpdated } from "../../config/logging.js";
 import {
-  DEFAULT_PROVIDER,
-  ensureFlagCompatibility,
-  modelKey,
-  resolveModelTarget,
-  updateConfig,
-} from "./shared.js";
+  addFallbackCommand,
+  clearFallbacksCommand,
+  listFallbacksCommand,
+  removeFallbackCommand,
+} from "./fallbacks-shared.js";
 
 export async function modelsFallbacksListCommand(
   opts: { json?: boolean; plain?: boolean },
   runtime: RuntimeEnv,
 ) {
-  ensureFlagCompatibility(opts);
-  const cfg = loadConfig();
-  const fallbacks = cfg.agents?.defaults?.model?.fallbacks ?? [];
-
-  if (opts.json) {
-    runtime.log(JSON.stringify({ fallbacks }, null, 2));
-    return;
-  }
-  if (opts.plain) {
-    for (const entry of fallbacks) {
-      runtime.log(entry);
-    }
-    return;
-  }
-
-  runtime.log(`Fallbacks (${fallbacks.length}):`);
-  if (fallbacks.length === 0) {
-    runtime.log("- none");
-    return;
-  }
-  for (const entry of fallbacks) {
-    runtime.log(`- ${entry}`);
-  }
+  return await listFallbacksCommand({ label: "Fallbacks", key: "model" }, opts, runtime);
 }
 
 export async function modelsFallbacksAddCommand(modelRaw: string, runtime: RuntimeEnv) {
-  const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const targetKey = modelKey(resolved.provider, resolved.model);
-    const nextModels = { ...cfg.agents?.defaults?.models };
-    if (!nextModels[targetKey]) {
-      nextModels[targetKey] = {};
-    }
-    const aliasIndex = buildModelAliasIndex({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    const existing = cfg.agents?.defaults?.model?.fallbacks ?? [];
-    const existingKeys = existing
-      .map((entry) =>
-        resolveModelRefFromString({
-          raw: String(entry ?? ""),
-          defaultProvider: DEFAULT_PROVIDER,
-          aliasIndex,
-        }),
-      )
-      .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
-      .map((entry) => modelKey(entry.ref.provider, entry.ref.model));
-
-    if (existingKeys.includes(targetKey)) {
-      return cfg;
-    }
-
-    const existingModel = cfg.agents?.defaults?.model as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: [...existing, targetKey],
-          },
-          models: nextModels,
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log(`Fallbacks: ${(updated.agents?.defaults?.model?.fallbacks ?? []).join(", ")}`);
+  return await addFallbackCommand(
+    { label: "Fallbacks", key: "model", logPrefix: "Fallbacks" },
+    modelRaw,
+    runtime,
+  );
 }
 
 export async function modelsFallbacksRemoveCommand(modelRaw: string, runtime: RuntimeEnv) {
-  const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const targetKey = modelKey(resolved.provider, resolved.model);
-    const aliasIndex = buildModelAliasIndex({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    const existing = cfg.agents?.defaults?.model?.fallbacks ?? [];
-    const filtered = existing.filter((entry) => {
-      const resolvedEntry = resolveModelRefFromString({
-        raw: String(entry ?? ""),
-        defaultProvider: DEFAULT_PROVIDER,
-        aliasIndex,
-      });
-      if (!resolvedEntry) {
-        return true;
-      }
-      return modelKey(resolvedEntry.ref.provider, resolvedEntry.ref.model) !== targetKey;
-    });
-
-    if (filtered.length === existing.length) {
-      throw new Error(`Fallback not found: ${targetKey}`);
-    }
-
-    const existingModel = cfg.agents?.defaults?.model as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: filtered,
-          },
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log(`Fallbacks: ${(updated.agents?.defaults?.model?.fallbacks ?? []).join(", ")}`);
+  return await removeFallbackCommand(
+    {
+      label: "Fallbacks",
+      key: "model",
+      notFoundLabel: "Fallback",
+      logPrefix: "Fallbacks",
+    },
+    modelRaw,
+    runtime,
+  );
 }
 
 export async function modelsFallbacksClearCommand(runtime: RuntimeEnv) {
-  await updateConfig((cfg) => {
-    const existingModel = cfg.agents?.defaults?.model as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: [],
-          },
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log("Fallback list cleared.");
+  return await clearFallbacksCommand(
+    { key: "model", clearedMessage: "Fallback list cleared." },
+    runtime,
+  );
 }
diff --git a/src/commands/models/image-fallbacks.ts b/src/commands/models/image-fallbacks.ts
index e4beb1adf26..99ae401972b 100644
--- a/src/commands/models/image-fallbacks.ts
+++ b/src/commands/models/image-fallbacks.ts
@@ -1,168 +1,42 @@
 import type { RuntimeEnv } from "../../runtime.js";
-import { buildModelAliasIndex, resolveModelRefFromString } from "../../agents/model-selection.js";
-import { loadConfig } from "../../config/config.js";
-import { logConfigUpdated } from "../../config/logging.js";
 import {
-  DEFAULT_PROVIDER,
-  ensureFlagCompatibility,
-  modelKey,
-  resolveModelTarget,
-  updateConfig,
-} from "./shared.js";
+  addFallbackCommand,
+  clearFallbacksCommand,
+  listFallbacksCommand,
+  removeFallbackCommand,
+} from "./fallbacks-shared.js";
 
 export async function modelsImageFallbacksListCommand(
   opts: { json?: boolean; plain?: boolean },
   runtime: RuntimeEnv,
 ) {
-  ensureFlagCompatibility(opts);
-  const cfg = loadConfig();
-  const fallbacks = cfg.agents?.defaults?.imageModel?.fallbacks ?? [];
-
-  if (opts.json) {
-    runtime.log(JSON.stringify({ fallbacks }, null, 2));
-    return;
-  }
-  if (opts.plain) {
-    for (const entry of fallbacks) {
-      runtime.log(entry);
-    }
-    return;
-  }
-
-  runtime.log(`Image fallbacks (${fallbacks.length}):`);
-  if (fallbacks.length === 0) {
-    runtime.log("- none");
-    return;
-  }
-  for (const entry of fallbacks) {
-    runtime.log(`- ${entry}`);
-  }
+  return await listFallbacksCommand({ label: "Image fallbacks", key: "imageModel" }, opts, runtime);
 }
 
 export async function modelsImageFallbacksAddCommand(modelRaw: string, runtime: RuntimeEnv) {
-  const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const targetKey = modelKey(resolved.provider, resolved.model);
-    const nextModels = { ...cfg.agents?.defaults?.models };
-    if (!nextModels[targetKey]) {
-      nextModels[targetKey] = {};
-    }
-    const aliasIndex = buildModelAliasIndex({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    const existing = cfg.agents?.defaults?.imageModel?.fallbacks ?? [];
-    const existingKeys = existing
-      .map((entry) =>
-        resolveModelRefFromString({
-          raw: String(entry ?? ""),
-          defaultProvider: DEFAULT_PROVIDER,
-          aliasIndex,
-        }),
-      )
-      .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
-      .map((entry) => modelKey(entry.ref.provider, entry.ref.model));
-
-    if (existingKeys.includes(targetKey)) {
-      return cfg;
-    }
-
-    const existingModel = cfg.agents?.defaults?.imageModel as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          imageModel: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: [...existing, targetKey],
-          },
-          models: nextModels,
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log(
-    `Image fallbacks: ${(updated.agents?.defaults?.imageModel?.fallbacks ?? []).join(", ")}`,
+  return await addFallbackCommand(
+    { label: "Image fallbacks", key: "imageModel", logPrefix: "Image fallbacks" },
+    modelRaw,
+    runtime,
   );
 }
 
 export async function modelsImageFallbacksRemoveCommand(modelRaw: string, runtime: RuntimeEnv) {
-  const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const targetKey = modelKey(resolved.provider, resolved.model);
-    const aliasIndex = buildModelAliasIndex({
-      cfg,
-      defaultProvider: DEFAULT_PROVIDER,
-    });
-    const existing = cfg.agents?.defaults?.imageModel?.fallbacks ?? [];
-    const filtered = existing.filter((entry) => {
-      const resolvedEntry = resolveModelRefFromString({
-        raw: String(entry ?? ""),
-        defaultProvider: DEFAULT_PROVIDER,
-        aliasIndex,
-      });
-      if (!resolvedEntry) {
-        return true;
-      }
-      return modelKey(resolvedEntry.ref.provider, resolvedEntry.ref.model) !== targetKey;
-    });
-
-    if (filtered.length === existing.length) {
-      throw new Error(`Image fallback not found: ${targetKey}`);
-    }
-
-    const existingModel = cfg.agents?.defaults?.imageModel as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          imageModel: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: filtered,
-          },
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log(
-    `Image fallbacks: ${(updated.agents?.defaults?.imageModel?.fallbacks ?? []).join(", ")}`,
+  return await removeFallbackCommand(
+    {
+      label: "Image fallbacks",
+      key: "imageModel",
+      notFoundLabel: "Image fallback",
+      logPrefix: "Image fallbacks",
+    },
+    modelRaw,
+    runtime,
   );
 }
 
 export async function modelsImageFallbacksClearCommand(runtime: RuntimeEnv) {
-  await updateConfig((cfg) => {
-    const existingModel = cfg.agents?.defaults?.imageModel as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          imageModel: {
-            ...(existingModel?.primary ? { primary: existingModel.primary } : undefined),
-            fallbacks: [],
-          },
-        },
-      },
-    };
-  });
-
-  logConfigUpdated(runtime);
-  runtime.log("Image fallback list cleared.");
+  return await clearFallbacksCommand(
+    { key: "imageModel", clearedMessage: "Image fallback list cleared." },
+    runtime,
+  );
 }
diff --git a/src/commands/models/list.list-command.ts b/src/commands/models/list.list-command.ts
index c371e85a308..cdad37bbd21 100644
--- a/src/commands/models/list.list-command.ts
+++ b/src/commands/models/list.list-command.ts
@@ -2,11 +2,8 @@ import type { Api, Model } from "@mariozechner/pi-ai";
 import type { ModelRegistry } from "../../agents/pi-model-discovery.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import type { ModelRow } from "./list.types.js";
-import { ensureAuthProfileStore } from "../../agents/auth-profiles.js";
 import { resolveForwardCompatModel } from "../../agents/model-forward-compat.js";
 import { parseModelRef } from "../../agents/model-selection.js";
-import { resolveModel } from "../../agents/pi-embedded-runner/model.js";
-import { loadConfig } from "../../config/config.js";
 import { resolveConfiguredEntries } from "./list.configured.js";
 import { formatErrorWithStack } from "./list.errors.js";
 import { loadModelRegistry, toModelRow } from "./list.registry.js";
@@ -24,6 +21,8 @@ export async function modelsListCommand(
   runtime: RuntimeEnv,
 ) {
   ensureFlagCompatibility(opts);
+  const { loadConfig } = await import("../../config/config.js");
+  const { ensureAuthProfileStore } = await import("../../agents/auth-profiles.js");
   const cfg = loadConfig();
   const authStore = ensureAuthProfileStore();
   const providerFilter = (() => {
@@ -111,6 +110,7 @@ export async function modelsListCommand(
         }
       }
       if (!model) {
+        const { resolveModel } = await import("../../agents/pi-embedded-runner/model.js");
         model = resolveModel(entry.ref.provider, entry.ref.model, undefined, cfg).model;
       }
       if (opts.local && model && !isLocalBaseUrl(model.baseUrl)) {
diff --git a/src/commands/models/set-image.ts b/src/commands/models/set-image.ts
index 82531414ef2..920418e4f89 100644
--- a/src/commands/models/set-image.ts
+++ b/src/commands/models/set-image.ts
@@ -1,32 +1,10 @@
 import type { RuntimeEnv } from "../../runtime.js";
 import { logConfigUpdated } from "../../config/logging.js";
-import { resolveModelTarget, updateConfig } from "./shared.js";
+import { applyDefaultModelPrimaryUpdate, updateConfig } from "./shared.js";
 
 export async function modelsSetImageCommand(modelRaw: string, runtime: RuntimeEnv) {
   const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const key = `${resolved.provider}/${resolved.model}`;
-    const nextModels = { ...cfg.agents?.defaults?.models };
-    if (!nextModels[key]) {
-      nextModels[key] = {};
-    }
-    const existingModel = cfg.agents?.defaults?.imageModel as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          imageModel: {
-            ...(existingModel?.fallbacks ? { fallbacks: existingModel.fallbacks } : undefined),
-            primary: key,
-          },
-          models: nextModels,
-        },
-      },
-    };
+    return applyDefaultModelPrimaryUpdate({ cfg, modelRaw, field: "imageModel" });
   });
 
   logConfigUpdated(runtime);
diff --git a/src/commands/models/set.ts b/src/commands/models/set.ts
index 83db6723fbd..d0506acbdf6 100644
--- a/src/commands/models/set.ts
+++ b/src/commands/models/set.ts
@@ -1,32 +1,10 @@
 import type { RuntimeEnv } from "../../runtime.js";
 import { logConfigUpdated } from "../../config/logging.js";
-import { resolveModelTarget, updateConfig } from "./shared.js";
+import { applyDefaultModelPrimaryUpdate, updateConfig } from "./shared.js";
 
 export async function modelsSetCommand(modelRaw: string, runtime: RuntimeEnv) {
   const updated = await updateConfig((cfg) => {
-    const resolved = resolveModelTarget({ raw: modelRaw, cfg });
-    const key = `${resolved.provider}/${resolved.model}`;
-    const nextModels = { ...cfg.agents?.defaults?.models };
-    if (!nextModels[key]) {
-      nextModels[key] = {};
-    }
-    const existingModel = cfg.agents?.defaults?.model as
-      | { primary?: string; fallbacks?: string[] }
-      | undefined;
-    return {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model: {
-            ...(existingModel?.fallbacks ? { fallbacks: existingModel.fallbacks } : undefined),
-            primary: key,
-          },
-          models: nextModels,
-        },
-      },
-    };
+    return applyDefaultModelPrimaryUpdate({ cfg, modelRaw, field: "model" });
   });
 
   logConfigUpdated(runtime);
diff --git a/src/commands/models/shared.ts b/src/commands/models/shared.ts
index b25be3a8926..64439ef60c7 100644
--- a/src/commands/models/shared.ts
+++ b/src/commands/models/shared.ts
@@ -91,6 +91,26 @@ export function resolveModelTarget(params: { raw: string; cfg: OpenClawConfig })
   return resolved.ref;
 }
 
+export function resolveModelKeysFromEntries(params: {
+  cfg: OpenClawConfig;
+  entries: readonly string[];
+}): string[] {
+  const aliasIndex = buildModelAliasIndex({
+    cfg: params.cfg,
+    defaultProvider: DEFAULT_PROVIDER,
+  });
+  return params.entries
+    .map((entry) =>
+      resolveModelRefFromString({
+        raw: entry,
+        defaultProvider: DEFAULT_PROVIDER,
+        aliasIndex,
+      }),
+    )
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .map((entry) => modelKey(entry.ref.provider, entry.ref.model));
+}
+
 export function buildAllowlistSet(cfg: OpenClawConfig): Set<string> {
   const allowed = new Set<string>();
   const models = cfg.agents?.defaults?.models ?? {};
@@ -133,6 +153,53 @@ export function resolveKnownAgentId(params: {
   return agentId;
 }
 
+export type PrimaryFallbackConfig = { primary?: string; fallbacks?: string[] };
+
+export function mergePrimaryFallbackConfig(
+  existing: PrimaryFallbackConfig | undefined,
+  patch: { primary?: string; fallbacks?: string[] },
+): PrimaryFallbackConfig {
+  const next: PrimaryFallbackConfig = { ...existing };
+  if (patch.primary !== undefined) {
+    next.primary = patch.primary;
+  }
+  if (patch.fallbacks !== undefined) {
+    next.fallbacks = patch.fallbacks;
+  }
+  return next;
+}
+
+export function applyDefaultModelPrimaryUpdate(params: {
+  cfg: OpenClawConfig;
+  modelRaw: string;
+  field: "model" | "imageModel";
+}): OpenClawConfig {
+  const resolved = resolveModelTarget({ raw: params.modelRaw, cfg: params.cfg });
+  const key = `${resolved.provider}/${resolved.model}`;
+
+  const nextModels = { ...params.cfg.agents?.defaults?.models };
+  if (!nextModels[key]) {
+    nextModels[key] = {};
+  }
+
+  const defaults = params.cfg.agents?.defaults ?? {};
+  const existing = (defaults as Record<string, unknown>)[params.field] as
+    | PrimaryFallbackConfig
+    | undefined;
+
+  return {
+    ...params.cfg,
+    agents: {
+      ...params.cfg.agents,
+      defaults: {
+        ...defaults,
+        [params.field]: mergePrimaryFallbackConfig(existing, { primary: key }),
+        models: nextModels,
+      },
+    },
+  };
+}
+
 export { modelKey };
 export { DEFAULT_MODEL, DEFAULT_PROVIDER };
 
diff --git a/src/commands/onboard-auth.config-core.ts b/src/commands/onboard-auth.config-core.ts
index 037c28e3721..4db007191b4 100644
--- a/src/commands/onboard-auth.config-core.ts
+++ b/src/commands/onboard-auth.config-core.ts
@@ -135,25 +135,7 @@ export function applyZaiConfig(
   const modelId = params?.modelId?.trim() || ZAI_DEFAULT_MODEL_ID;
   const modelRef = modelId === ZAI_DEFAULT_MODEL_ID ? ZAI_DEFAULT_MODEL_REF : `zai/${modelId}`;
   const next = applyZaiProviderConfig(cfg, params);
-
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: modelRef,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, modelRef);
 }
 
 export function applyOpenrouterProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
@@ -177,24 +159,7 @@ export function applyOpenrouterProviderConfig(cfg: OpenClawConfig): OpenClawConf
 
 export function applyOpenrouterConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyOpenrouterProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: OPENROUTER_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, OPENROUTER_DEFAULT_MODEL_REF);
 }
 
 export function applyMoonshotProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
@@ -258,24 +223,7 @@ export function applyKimiCodeProviderConfig(cfg: OpenClawConfig): OpenClawConfig
 
 export function applyKimiCodeConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyKimiCodeProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: KIMI_CODING_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, KIMI_CODING_MODEL_REF);
 }
 
 export function applySyntheticProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
@@ -314,24 +262,7 @@ export function applySyntheticProviderConfig(cfg: OpenClawConfig): OpenClawConfi
 
 export function applySyntheticConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applySyntheticProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: SYNTHETIC_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, SYNTHETIC_DEFAULT_MODEL_REF);
 }
 
 export function applyXiaomiProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
@@ -354,24 +285,7 @@ export function applyXiaomiProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
 
 export function applyXiaomiConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyXiaomiProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: XIAOMI_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, XIAOMI_DEFAULT_MODEL_REF);
 }
 
 /**
@@ -401,24 +315,7 @@ export function applyVeniceProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
  */
 export function applyVeniceConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyVeniceProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: VENICE_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, VENICE_DEFAULT_MODEL_REF);
 }
 
 /**
@@ -448,24 +345,7 @@ export function applyTogetherProviderConfig(cfg: OpenClawConfig): OpenClawConfig
  */
 export function applyTogetherConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyTogetherProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: TOGETHER_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, TOGETHER_DEFAULT_MODEL_REF);
 }
 
 /**
@@ -493,24 +373,7 @@ export function applyHuggingfaceProviderConfig(cfg: OpenClawConfig): OpenClawCon
  */
 export function applyHuggingfaceConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyHuggingfaceProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: HUGGINGFACE_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, HUGGINGFACE_DEFAULT_MODEL_REF);
 }
 
 export function applyXaiProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
@@ -534,24 +397,7 @@ export function applyXaiProviderConfig(cfg: OpenClawConfig): OpenClawConfig {
 
 export function applyXaiConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyXaiProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: XAI_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, XAI_DEFAULT_MODEL_REF);
 }
 
 export function applyAuthProfileConfig(
@@ -636,22 +482,5 @@ export function applyQianfanProviderConfig(cfg: OpenClawConfig): OpenClawConfig
 
 export function applyQianfanConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyQianfanProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: QIANFAN_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, QIANFAN_DEFAULT_MODEL_REF);
 }
diff --git a/src/commands/onboard-auth.config-gateways.ts b/src/commands/onboard-auth.config-gateways.ts
index 1e4ffc62cfa..b89acca00f0 100644
--- a/src/commands/onboard-auth.config-gateways.ts
+++ b/src/commands/onboard-auth.config-gateways.ts
@@ -3,7 +3,10 @@ import {
   buildCloudflareAiGatewayModelDefinition,
   resolveCloudflareAiGatewayBaseUrl,
 } from "../agents/cloudflare-ai-gateway.js";
-import { applyProviderConfigWithDefaultModel } from "./onboard-auth.config-shared.js";
+import {
+  applyAgentDefaultModelPrimary,
+  applyProviderConfigWithDefaultModel,
+} from "./onboard-auth.config-shared.js";
 import {
   CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF,
   VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
@@ -76,24 +79,7 @@ export function applyCloudflareAiGatewayProviderConfig(
 
 export function applyVercelAiGatewayConfig(cfg: OpenClawConfig): OpenClawConfig {
   const next = applyVercelAiGatewayProviderConfig(cfg);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, VERCEL_AI_GATEWAY_DEFAULT_MODEL_REF);
 }
 
 export function applyCloudflareAiGatewayConfig(
@@ -101,22 +87,5 @@ export function applyCloudflareAiGatewayConfig(
   params?: { accountId?: string; gatewayId?: string },
 ): OpenClawConfig {
   const next = applyCloudflareAiGatewayProviderConfig(cfg, params);
-  const existingModel = next.agents?.defaults?.model;
-  return {
-    ...next,
-    agents: {
-      ...next.agents,
-      defaults: {
-        ...next.agents?.defaults,
-        model: {
-          ...(existingModel && "fallbacks" in (existingModel as Record<string, unknown>)
-            ? {
-                fallbacks: (existingModel as { fallbacks?: string[] }).fallbacks,
-              }
-            : undefined),
-          primary: CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF,
-        },
-      },
-    },
-  };
+  return applyAgentDefaultModelPrimary(next, CLOUDFLARE_AI_GATEWAY_DEFAULT_MODEL_REF);
 }
diff --git a/src/commands/onboard-auth.e2e.test.ts b/src/commands/onboard-auth.e2e.test.ts
index eb6858f87d5..a26c544e133 100644
--- a/src/commands/onboard-auth.e2e.test.ts
+++ b/src/commands/onboard-auth.e2e.test.ts
@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import {
   applyAuthProfileConfig,
   applyLitellmProviderConfig,
@@ -40,9 +41,12 @@ const requireAgentDir = () => {
 };
 
 describe("writeOAuthCredentials", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const envSnapshot = captureEnv([
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+    "OPENCLAW_OAUTH_DIR",
+  ]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -50,22 +54,7 @@ describe("writeOAuthCredentials", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
-    delete process.env.OPENCLAW_OAUTH_DIR;
+    envSnapshot.restore();
   });
 
   it("writes auth-profiles.json under OPENCLAW_AGENT_DIR when set", async () => {
@@ -100,9 +89,11 @@ describe("writeOAuthCredentials", () => {
 });
 
 describe("setMinimaxApiKey", () => {
-  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
-  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
-  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const envSnapshot = captureEnv([
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+  ]);
   let tempStateDir: string | null = null;
 
   afterEach(async () => {
@@ -110,21 +101,7 @@ describe("setMinimaxApiKey", () => {
       await fs.rm(tempStateDir, { recursive: true, force: true });
       tempStateDir = null;
     }
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
-    if (previousAgentDir === undefined) {
-      delete process.env.OPENCLAW_AGENT_DIR;
-    } else {
-      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
-    }
-    if (previousPiAgentDir === undefined) {
-      delete process.env.PI_CODING_AGENT_DIR;
-    } else {
-      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
-    }
+    envSnapshot.restore();
   });
 
   it("writes to OPENCLAW_AGENT_DIR when set", async () => {
diff --git a/src/commands/onboard-channels.e2e.test.ts b/src/commands/onboard-channels.e2e.test.ts
index 25c1c6fc220..210ef5b7ad1 100644
--- a/src/commands/onboard-channels.e2e.test.ts
+++ b/src/commands/onboard-channels.e2e.test.ts
@@ -12,6 +12,32 @@ import { setActivePluginRegistry } from "../plugins/runtime.js";
 import { createTestRegistry } from "../test-utils/channel-plugins.js";
 import { setupChannels } from "./onboard-channels.js";
 
+const noopAsync = async () => {};
+
+function createRuntime(): RuntimeEnv {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: vi.fn((code: number) => {
+      throw new Error(`exit:${code}`);
+    }),
+  };
+}
+
+function createPrompter(overrides: Partial<WizardPrompter>): WizardPrompter {
+  return {
+    intro: vi.fn(noopAsync),
+    outro: vi.fn(noopAsync),
+    note: vi.fn(noopAsync),
+    select: vi.fn(async () => "__done__" as never),
+    multiselect: vi.fn(async () => []),
+    text: vi.fn(async () => "") as unknown as WizardPrompter["text"],
+    confirm: vi.fn(async () => false),
+    progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
+    ...overrides,
+  };
+}
+
 vi.mock("node:fs/promises", () => ({
   default: {
     access: vi.fn(async () => {
@@ -56,24 +82,13 @@ describe("setupChannels", () => {
       throw new Error(`unexpected text prompt: ${message}`);
     });
 
-    const prompter: WizardPrompter = {
-      intro: vi.fn(async () => {}),
-      outro: vi.fn(async () => {}),
-      note: vi.fn(async () => {}),
+    const prompter = createPrompter({
       select,
       multiselect,
       text: text as unknown as WizardPrompter["text"],
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
-    };
+    });
 
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const runtime = createRuntime();
 
     await setupChannels({} as OpenClawConfig, runtime, prompter, {
       skipConfirm: true,
@@ -97,24 +112,14 @@ describe("setupChannels", () => {
       throw new Error(`unexpected text prompt: ${message}`);
     });
 
-    const prompter: WizardPrompter = {
-      intro: vi.fn(async () => {}),
-      outro: vi.fn(async () => {}),
+    const prompter = createPrompter({
       note,
       select,
       multiselect,
       text: text as unknown as WizardPrompter["text"],
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
-    };
+    });
 
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const runtime = createRuntime();
 
     await setupChannels({} as OpenClawConfig, runtime, prompter, {
       skipConfirm: true,
@@ -146,24 +151,13 @@ describe("setupChannels", () => {
       throw new Error(`unexpected text prompt: ${message}`);
     });
 
-    const prompter: WizardPrompter = {
-      intro: vi.fn(async () => {}),
-      outro: vi.fn(async () => {}),
-      note: vi.fn(async () => {}),
+    const prompter = createPrompter({
       select,
       multiselect,
       text: text as unknown as WizardPrompter["text"],
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
-    };
+    });
 
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const runtime = createRuntime();
 
     await setupChannels(
       {
@@ -209,24 +203,13 @@ describe("setupChannels", () => {
     const multiselect = vi.fn(async () => {
       throw new Error("unexpected multiselect");
     });
-    const prompter: WizardPrompter = {
-      intro: vi.fn(async () => {}),
-      outro: vi.fn(async () => {}),
-      note: vi.fn(async () => {}),
+    const prompter = createPrompter({
       select,
       multiselect,
-      text: vi.fn(async () => ""),
-      confirm: vi.fn(async () => false),
-      progress: vi.fn(() => ({ update: vi.fn(), stop: vi.fn() })),
-    };
+      text: vi.fn(async () => "") as unknown as WizardPrompter["text"],
+    });
 
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: vi.fn((code: number) => {
-        throw new Error(`exit:${code}`);
-      }),
-    };
+    const runtime = createRuntime();
 
     await setupChannels(
       {
diff --git a/src/commands/onboard-non-interactive.provider-auth.e2e.test.ts b/src/commands/onboard-non-interactive.provider-auth.e2e.test.ts
index 188bfae6aa1..ea2a4199307 100644
--- a/src/commands/onboard-non-interactive.provider-auth.e2e.test.ts
+++ b/src/commands/onboard-non-interactive.provider-auth.e2e.test.ts
@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { MINIMAX_API_BASE_URL, MINIMAX_CN_API_BASE_URL } from "./onboard-auth.js";
 import { OPENAI_DEFAULT_MODEL } from "./openai-model-default.js";
 
@@ -12,20 +13,6 @@ type RuntimeMock = {
   exit: (code: number) => never;
 };
 
-type EnvSnapshot = {
-  home: string | undefined;
-  stateDir: string | undefined;
-  configPath: string | undefined;
-  skipChannels: string | undefined;
-  skipGmail: string | undefined;
-  skipCron: string | undefined;
-  skipCanvas: string | undefined;
-  token: string | undefined;
-  password: string | undefined;
-  customApiKey: string | undefined;
-  disableConfigCache: string | undefined;
-};
-
 type OnboardEnv = {
   configPath: string;
   runtime: RuntimeMock;
@@ -47,49 +34,23 @@ async function removeDirWithRetry(dir: string): Promise<void> {
   }
 }
 
-function captureEnv(): EnvSnapshot {
-  return {
-    home: process.env.HOME,
-    stateDir: process.env.OPENCLAW_STATE_DIR,
-    configPath: process.env.OPENCLAW_CONFIG_PATH,
-    skipChannels: process.env.OPENCLAW_SKIP_CHANNELS,
-    skipGmail: process.env.OPENCLAW_SKIP_GMAIL_WATCHER,
-    skipCron: process.env.OPENCLAW_SKIP_CRON,
-    skipCanvas: process.env.OPENCLAW_SKIP_CANVAS_HOST,
-    token: process.env.OPENCLAW_GATEWAY_TOKEN,
-    password: process.env.OPENCLAW_GATEWAY_PASSWORD,
-    customApiKey: process.env.CUSTOM_API_KEY,
-    disableConfigCache: process.env.OPENCLAW_DISABLE_CONFIG_CACHE,
-  };
-}
-
-function restoreEnvVar(key: keyof NodeJS.ProcessEnv, value: string | undefined): void {
-  if (value == null) {
-    delete process.env[key];
-    return;
-  }
-  process.env[key] = value;
-}
-
-function restoreEnv(prev: EnvSnapshot): void {
-  restoreEnvVar("HOME", prev.home);
-  restoreEnvVar("OPENCLAW_STATE_DIR", prev.stateDir);
-  restoreEnvVar("OPENCLAW_CONFIG_PATH", prev.configPath);
-  restoreEnvVar("OPENCLAW_SKIP_CHANNELS", prev.skipChannels);
-  restoreEnvVar("OPENCLAW_SKIP_GMAIL_WATCHER", prev.skipGmail);
-  restoreEnvVar("OPENCLAW_SKIP_CRON", prev.skipCron);
-  restoreEnvVar("OPENCLAW_SKIP_CANVAS_HOST", prev.skipCanvas);
-  restoreEnvVar("OPENCLAW_GATEWAY_TOKEN", prev.token);
-  restoreEnvVar("OPENCLAW_GATEWAY_PASSWORD", prev.password);
-  restoreEnvVar("CUSTOM_API_KEY", prev.customApiKey);
-  restoreEnvVar("OPENCLAW_DISABLE_CONFIG_CACHE", prev.disableConfigCache);
-}
-
 async function withOnboardEnv(
   prefix: string,
   run: (ctx: OnboardEnv) => Promise<void>,
 ): Promise<void> {
-  const prev = captureEnv();
+  const prev = captureEnv([
+    "HOME",
+    "OPENCLAW_STATE_DIR",
+    "OPENCLAW_CONFIG_PATH",
+    "OPENCLAW_SKIP_CHANNELS",
+    "OPENCLAW_SKIP_GMAIL_WATCHER",
+    "OPENCLAW_SKIP_CRON",
+    "OPENCLAW_SKIP_CANVAS_HOST",
+    "OPENCLAW_GATEWAY_TOKEN",
+    "OPENCLAW_GATEWAY_PASSWORD",
+    "CUSTOM_API_KEY",
+    "OPENCLAW_DISABLE_CONFIG_CACHE",
+  ]);
 
   process.env.OPENCLAW_SKIP_CHANNELS = "1";
   process.env.OPENCLAW_SKIP_GMAIL_WATCHER = "1";
@@ -120,7 +81,7 @@ async function withOnboardEnv(
     await run({ configPath, runtime });
   } finally {
     await removeDirWithRetry(tempHome);
-    restoreEnv(prev);
+    prev.restore();
   }
 }
 
diff --git a/src/commands/opencode-zen-model-default.ts b/src/commands/opencode-zen-model-default.ts
index 9f3d4b45654..9efb9c17ade 100644
--- a/src/commands/opencode-zen-model-default.ts
+++ b/src/commands/opencode-zen-model-default.ts
@@ -1,5 +1,5 @@
 import type { OpenClawConfig } from "../config/config.js";
-import type { AgentModelListConfig } from "../config/types.js";
+import { applyAgentDefaultPrimaryModel } from "./model-default.js";
 
 export const OPENCODE_ZEN_DEFAULT_MODEL = "opencode/claude-opus-4-6";
 const LEGACY_OPENCODE_ZEN_DEFAULT_MODELS = new Set([
@@ -7,46 +7,13 @@ const LEGACY_OPENCODE_ZEN_DEFAULT_MODELS = new Set([
   "opencode-zen/claude-opus-4-5",
 ]);
 
-function resolvePrimaryModel(model?: AgentModelListConfig | string): string | undefined {
-  if (typeof model === "string") {
-    return model;
-  }
-  if (model && typeof model === "object" && typeof model.primary === "string") {
-    return model.primary;
-  }
-  return undefined;
-}
-
 export function applyOpencodeZenModelDefault(cfg: OpenClawConfig): {
   next: OpenClawConfig;
   changed: boolean;
 } {
-  const current = resolvePrimaryModel(cfg.agents?.defaults?.model)?.trim();
-  const normalizedCurrent =
-    current && LEGACY_OPENCODE_ZEN_DEFAULT_MODELS.has(current)
-      ? OPENCODE_ZEN_DEFAULT_MODEL
-      : current;
-  if (normalizedCurrent === OPENCODE_ZEN_DEFAULT_MODEL) {
-    return { next: cfg, changed: false };
-  }
-
-  return {
-    next: {
-      ...cfg,
-      agents: {
-        ...cfg.agents,
-        defaults: {
-          ...cfg.agents?.defaults,
-          model:
-            cfg.agents?.defaults?.model && typeof cfg.agents.defaults.model === "object"
-              ? {
-                  ...cfg.agents.defaults.model,
-                  primary: OPENCODE_ZEN_DEFAULT_MODEL,
-                }
-              : { primary: OPENCODE_ZEN_DEFAULT_MODEL },
-        },
-      },
-    },
-    changed: true,
-  };
+  return applyAgentDefaultPrimaryModel({
+    cfg,
+    model: OPENCODE_ZEN_DEFAULT_MODEL,
+    legacyModels: LEGACY_OPENCODE_ZEN_DEFAULT_MODELS,
+  });
 }
diff --git a/src/commands/reset.ts b/src/commands/reset.ts
index 0717544a431..fd6203c0af8 100644
--- a/src/commands/reset.ts
+++ b/src/commands/reset.ts
@@ -1,21 +1,11 @@
 import { cancel, confirm, isCancel, select } from "@clack/prompts";
 import type { RuntimeEnv } from "../runtime.js";
 import { formatCliCommand } from "../cli/command-format.js";
-import {
-  isNixMode,
-  loadConfig,
-  resolveConfigPath,
-  resolveOAuthDir,
-  resolveStateDir,
-} from "../config/config.js";
+import { isNixMode } from "../config/config.js";
 import { resolveGatewayService } from "../daemon/service.js";
 import { stylePromptHint, stylePromptMessage, stylePromptTitle } from "../terminal/prompt-style.js";
-import {
-  collectWorkspaceDirs,
-  isPathWithin,
-  listAgentSessionDirs,
-  removePath,
-} from "./cleanup-utils.js";
+import { resolveCleanupPlanFromDisk } from "./cleanup-plan.js";
+import { listAgentSessionDirs, removePath } from "./cleanup-utils.js";
 
 export type ResetScope = "config" | "config+creds+sessions" | "full";
 
@@ -119,13 +109,8 @@ export async function resetCommand(runtime: RuntimeEnv, opts: ResetOptions) {
   }
 
   const dryRun = Boolean(opts.dryRun);
-  const cfg = loadConfig();
-  const stateDir = resolveStateDir();
-  const configPath = resolveConfigPath();
-  const oauthDir = resolveOAuthDir();
-  const configInsideState = isPathWithin(configPath, stateDir);
-  const oauthInsideState = isPathWithin(oauthDir, stateDir);
-  const workspaceDirs = collectWorkspaceDirs(cfg);
+  const { stateDir, configPath, oauthDir, configInsideState, oauthInsideState, workspaceDirs } =
+    resolveCleanupPlanFromDisk();
 
   if (scope !== "config") {
     if (dryRun) {
diff --git a/src/commands/sessions.ts b/src/commands/sessions.ts
index deb22a3814c..03a912e63e3 100644
--- a/src/commands/sessions.ts
+++ b/src/commands/sessions.ts
@@ -9,6 +9,7 @@ import {
   resolveStorePath,
   type SessionEntry,
 } from "../config/sessions.js";
+import { classifySessionKey } from "../gateway/session-utils.js";
 import { info } from "../globals.js";
 import { formatTimeAgo } from "../infra/format-time/format-relative.ts";
 import { isRich, theme } from "../terminal/theme.js";
@@ -129,29 +130,13 @@ const formatFlagsCell = (row: SessionRow, rich: boolean) => {
   return label.length === 0 ? "" : rich ? theme.muted(label) : label;
 };
 
-function classifyKey(key: string, entry?: SessionEntry): SessionRow["kind"] {
-  if (key === "global") {
-    return "global";
-  }
-  if (key === "unknown") {
-    return "unknown";
-  }
-  if (entry?.chatType === "group" || entry?.chatType === "channel") {
-    return "group";
-  }
-  if (key.includes(":group:") || key.includes(":channel:")) {
-    return "group";
-  }
-  return "direct";
-}
-
 function toRows(store: Record<string, SessionEntry>): SessionRow[] {
   return Object.entries(store)
     .map(([key, entry]) => {
       const updatedAt = entry?.updatedAt ?? null;
       return {
         key,
-        kind: classifyKey(key, entry),
+        kind: classifySessionKey(key, entry),
         updatedAt,
         ageMs: updatedAt ? Date.now() - updatedAt : null,
         sessionId: entry?.sessionId,
diff --git a/src/commands/status.e2e.test.ts b/src/commands/status.e2e.test.ts
index d5a8dcb0944..ae866bbd2ac 100644
--- a/src/commands/status.e2e.test.ts
+++ b/src/commands/status.e2e.test.ts
@@ -1,18 +1,15 @@
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 
-let previousProfile: string | undefined;
+let envSnapshot: ReturnType<typeof captureEnv>;
 
 beforeAll(() => {
-  previousProfile = process.env.OPENCLAW_PROFILE;
+  envSnapshot = captureEnv(["OPENCLAW_PROFILE"]);
   process.env.OPENCLAW_PROFILE = "isolated";
 });
 
 afterAll(() => {
-  if (previousProfile === undefined) {
-    delete process.env.OPENCLAW_PROFILE;
-  } else {
-    process.env.OPENCLAW_PROFILE = previousProfile;
-  }
+  envSnapshot.restore();
 });
 
 const mocks = vi.hoisted(() => ({
@@ -249,6 +246,7 @@ vi.mock("../infra/update-check.js", () => ({
     },
     registry: { latestVersion: "0.0.0" },
   }),
+  formatGitInstallLabel: vi.fn(() => "main · @ deadbeef"),
   compareSemverStrings: vi.fn(() => 0),
 }));
 vi.mock("../config/config.js", async (importOriginal) => {
diff --git a/src/commands/status.update.test.ts b/src/commands/status.update.test.ts
new file mode 100644
index 00000000000..8c29a37839f
--- /dev/null
+++ b/src/commands/status.update.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import type { UpdateCheckResult } from "../infra/update-check.js";
+import { VERSION } from "../version.js";
+import {
+  formatUpdateAvailableHint,
+  formatUpdateOneLiner,
+  resolveUpdateAvailability,
+} from "./status.update.js";
+
+function buildUpdate(partial: Partial<UpdateCheckResult>): UpdateCheckResult {
+  return {
+    root: null,
+    installKind: "unknown",
+    packageManager: "unknown",
+    ...partial,
+  };
+}
+
+function nextMajorVersion(version: string): string {
+  const [majorPart] = version.split(".");
+  const major = Number.parseInt(majorPart ?? "", 10);
+  if (Number.isFinite(major) && major >= 0) {
+    return `${major + 1}.0.0`;
+  }
+  return "999999.0.0";
+}
+
+describe("resolveUpdateAvailability", () => {
+  it("flags git update when behind upstream", () => {
+    const update = buildUpdate({
+      installKind: "git",
+      git: {
+        root: "/tmp/repo",
+        sha: null,
+        tag: null,
+        branch: "main",
+        upstream: "origin/main",
+        dirty: false,
+        ahead: 0,
+        behind: 3,
+        fetchOk: true,
+      },
+    });
+    expect(resolveUpdateAvailability(update)).toEqual({
+      available: true,
+      hasGitUpdate: true,
+      hasRegistryUpdate: false,
+      latestVersion: null,
+      gitBehind: 3,
+    });
+  });
+
+  it("flags registry update when latest version is newer", () => {
+    const latestVersion = nextMajorVersion(VERSION);
+    const update = buildUpdate({
+      installKind: "package",
+      packageManager: "pnpm",
+      registry: { latestVersion },
+    });
+    const availability = resolveUpdateAvailability(update);
+    expect(availability.available).toBe(true);
+    expect(availability.hasGitUpdate).toBe(false);
+    expect(availability.hasRegistryUpdate).toBe(true);
+    expect(availability.latestVersion).toBe(latestVersion);
+  });
+});
+
+describe("formatUpdateOneLiner", () => {
+  it("renders git status and registry latest summary", () => {
+    const update = buildUpdate({
+      installKind: "git",
+      git: {
+        root: "/tmp/repo",
+        sha: "abc123456789",
+        tag: null,
+        branch: "main",
+        upstream: "origin/main",
+        dirty: true,
+        ahead: 0,
+        behind: 2,
+        fetchOk: true,
+      },
+      registry: { latestVersion: VERSION },
+      deps: {
+        manager: "pnpm",
+        status: "ok",
+        lockfilePath: "pnpm-lock.yaml",
+        markerPath: "node_modules/.modules.yaml",
+      },
+    });
+
+    expect(formatUpdateOneLiner(update)).toBe(
+      `Update: git main · ↔ origin/main · dirty · behind 2 · npm latest ${VERSION} · deps ok`,
+    );
+  });
+
+  it("renders package-manager mode with registry error", () => {
+    const update = buildUpdate({
+      installKind: "package",
+      packageManager: "npm",
+      registry: { latestVersion: null, error: "offline" },
+      deps: {
+        manager: "npm",
+        status: "missing",
+        lockfilePath: "package-lock.json",
+        markerPath: "node_modules",
+      },
+    });
+
+    expect(formatUpdateOneLiner(update)).toBe("Update: npm · npm latest unknown · deps missing");
+  });
+});
+
+describe("formatUpdateAvailableHint", () => {
+  it("returns null when no update is available", () => {
+    const update = buildUpdate({
+      installKind: "package",
+      packageManager: "pnpm",
+      registry: { latestVersion: VERSION },
+    });
+
+    expect(formatUpdateAvailableHint(update)).toBeNull();
+  });
+
+  it("renders git and registry update details", () => {
+    const latestVersion = nextMajorVersion(VERSION);
+    const update = buildUpdate({
+      installKind: "git",
+      git: {
+        root: "/tmp/repo",
+        sha: null,
+        tag: null,
+        branch: "main",
+        upstream: "origin/main",
+        dirty: false,
+        ahead: 0,
+        behind: 2,
+        fetchOk: true,
+      },
+      registry: { latestVersion },
+    });
+
+    expect(formatUpdateAvailableHint(update)).toBe(
+      `Update available (git behind 2 · npm ${latestVersion}). Run: openclaw update`,
+    );
+  });
+});
diff --git a/src/commands/status.update.ts b/src/commands/status.update.ts
index 9d3215995de..9fd7809989b 100644
--- a/src/commands/status.update.ts
+++ b/src/commands/status.update.ts
@@ -71,6 +71,24 @@ export function formatUpdateAvailableHint(update: UpdateCheckResult): string | n
 
 export function formatUpdateOneLiner(update: UpdateCheckResult): string {
   const parts: string[] = [];
+
+  const appendRegistryUpdateSummary = () => {
+    if (update.registry?.latestVersion) {
+      const cmp = compareSemverStrings(VERSION, update.registry.latestVersion);
+      if (cmp === 0) {
+        parts.push(`npm latest ${update.registry.latestVersion}`);
+      } else if (cmp != null && cmp < 0) {
+        parts.push(`npm update ${update.registry.latestVersion}`);
+      } else {
+        parts.push(`npm latest ${update.registry.latestVersion} (local newer)`);
+      }
+      return;
+    }
+    if (update.registry?.error) {
+      parts.push("npm latest unknown");
+    }
+  };
+
   if (update.installKind === "git" && update.git) {
     const branch = update.git.branch ? `git ${update.git.branch}` : "git";
     parts.push(branch);
@@ -94,33 +112,10 @@ export function formatUpdateOneLiner(update: UpdateCheckResult): string {
     if (update.git.fetchOk === false) {
       parts.push("fetch failed");
     }
-
-    if (update.registry?.latestVersion) {
-      const cmp = compareSemverStrings(VERSION, update.registry.latestVersion);
-      if (cmp === 0) {
-        parts.push(`npm latest ${update.registry.latestVersion}`);
-      } else if (cmp != null && cmp < 0) {
-        parts.push(`npm update ${update.registry.latestVersion}`);
-      } else {
-        parts.push(`npm latest ${update.registry.latestVersion} (local newer)`);
-      }
-    } else if (update.registry?.error) {
-      parts.push("npm latest unknown");
-    }
+    appendRegistryUpdateSummary();
   } else {
     parts.push(update.packageManager !== "unknown" ? update.packageManager : "pkg");
-    if (update.registry?.latestVersion) {
-      const cmp = compareSemverStrings(VERSION, update.registry.latestVersion);
-      if (cmp === 0) {
-        parts.push(`npm latest ${update.registry.latestVersion}`);
-      } else if (cmp != null && cmp < 0) {
-        parts.push(`npm update ${update.registry.latestVersion}`);
-      } else {
-        parts.push(`npm latest ${update.registry.latestVersion} (local newer)`);
-      }
-    } else if (update.registry?.error) {
-      parts.push("npm latest unknown");
-    }
+    appendRegistryUpdateSummary();
   }
 
   if (update.deps) {
diff --git a/src/commands/uninstall.ts b/src/commands/uninstall.ts
index 6f9e9941e3c..333d664112c 100644
--- a/src/commands/uninstall.ts
+++ b/src/commands/uninstall.ts
@@ -1,17 +1,12 @@
 import { cancel, confirm, isCancel, multiselect } from "@clack/prompts";
 import path from "node:path";
 import type { RuntimeEnv } from "../runtime.js";
-import {
-  isNixMode,
-  loadConfig,
-  resolveConfigPath,
-  resolveOAuthDir,
-  resolveStateDir,
-} from "../config/config.js";
+import { isNixMode } from "../config/config.js";
 import { resolveGatewayService } from "../daemon/service.js";
 import { stylePromptHint, stylePromptMessage, stylePromptTitle } from "../terminal/prompt-style.js";
 import { resolveHomeDir } from "../utils.js";
-import { collectWorkspaceDirs, isPathWithin, removePath } from "./cleanup-utils.js";
+import { resolveCleanupPlanFromDisk } from "./cleanup-plan.js";
+import { removePath } from "./cleanup-utils.js";
 
 type UninstallScope = "service" | "state" | "workspace" | "app";
 
@@ -157,13 +152,8 @@ export async function uninstallCommand(runtime: RuntimeEnv, opts: UninstallOptio
   }
 
   const dryRun = Boolean(opts.dryRun);
-  const cfg = loadConfig();
-  const stateDir = resolveStateDir();
-  const configPath = resolveConfigPath();
-  const oauthDir = resolveOAuthDir();
-  const configInsideState = isPathWithin(configPath, stateDir);
-  const oauthInsideState = isPathWithin(oauthDir, stateDir);
-  const workspaceDirs = collectWorkspaceDirs(cfg);
+  const { stateDir, configPath, oauthDir, configInsideState, oauthInsideState, workspaceDirs } =
+    resolveCleanupPlanFromDisk();
 
   if (scopes.has("service")) {
     if (dryRun) {
diff --git a/src/config/config-misc.test.ts b/src/config/config-misc.test.ts
new file mode 100644
index 00000000000..4f6eaf41bdb
--- /dev/null
+++ b/src/config/config-misc.test.ts
@@ -0,0 +1,293 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  getConfigValueAtPath,
+  parseConfigPath,
+  setConfigValueAtPath,
+  unsetConfigValueAtPath,
+} from "./config-paths.js";
+import { readConfigFileSnapshot, validateConfigObject } from "./config.js";
+import { withTempHome } from "./test-helpers.js";
+import { OpenClawSchema } from "./zod-schema.js";
+
+describe("$schema key in config (#14998)", () => {
+  it("accepts config with $schema string", () => {
+    const result = OpenClawSchema.safeParse({
+      $schema: "https://openclaw.ai/config.json",
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.$schema).toBe("https://openclaw.ai/config.json");
+    }
+  });
+
+  it("accepts config without $schema", () => {
+    const result = OpenClawSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects non-string $schema", () => {
+    const result = OpenClawSchema.safeParse({ $schema: 123 });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ui.seamColor", () => {
+  it("accepts hex colors", () => {
+    const res = validateConfigObject({ ui: { seamColor: "#FF4500" } });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects non-hex colors", () => {
+    const res = validateConfigObject({ ui: { seamColor: "lobster" } });
+    expect(res.ok).toBe(false);
+  });
+
+  it("rejects invalid hex length", () => {
+    const res = validateConfigObject({ ui: { seamColor: "#FF4500FF" } });
+    expect(res.ok).toBe(false);
+  });
+});
+
+describe("web search provider config", () => {
+  it("accepts perplexity provider and config", () => {
+    const res = validateConfigObject({
+      tools: {
+        web: {
+          search: {
+            enabled: true,
+            provider: "perplexity",
+            perplexity: {
+              apiKey: "test-key",
+              baseUrl: "https://api.perplexity.ai",
+              model: "perplexity/sonar-pro",
+            },
+          },
+        },
+      },
+    });
+
+    expect(res.ok).toBe(true);
+  });
+});
+
+describe("talk.voiceAliases", () => {
+  it("accepts a string map of voice aliases", () => {
+    const res = validateConfigObject({
+      talk: {
+        voiceAliases: {
+          Clawd: "EXAVITQu4vr4xnSDxMaL",
+          Roger: "CwhRBWXzGAHq8TQ4Fs17",
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects non-string voice alias values", () => {
+    const res = validateConfigObject({
+      talk: {
+        voiceAliases: {
+          Clawd: 123,
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+  });
+});
+
+describe("gateway.remote.transport", () => {
+  it("accepts direct transport", () => {
+    const res = validateConfigObject({
+      gateway: {
+        remote: {
+          transport: "direct",
+          url: "wss://gateway.example.ts.net",
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects unknown transport", () => {
+    const res = validateConfigObject({
+      gateway: {
+        remote: {
+          transport: "udp",
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues[0]?.path).toBe("gateway.remote.transport");
+    }
+  });
+});
+
+describe("gateway.tools config", () => {
+  it("accepts gateway.tools allow and deny lists", () => {
+    const res = validateConfigObject({
+      gateway: {
+        tools: {
+          allow: ["gateway"],
+          deny: ["sessions_spawn", "sessions_send"],
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects invalid gateway.tools values", () => {
+    const res = validateConfigObject({
+      gateway: {
+        tools: {
+          allow: "gateway",
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues[0]?.path).toBe("gateway.tools.allow");
+    }
+  });
+});
+
+describe("cron webhook schema", () => {
+  it("accepts cron.webhookToken and legacy cron.webhook", () => {
+    const res = OpenClawSchema.safeParse({
+      cron: {
+        enabled: true,
+        webhook: "https://example.invalid/legacy-cron-webhook",
+        webhookToken: "secret-token",
+      },
+    });
+
+    expect(res.success).toBe(true);
+  });
+
+  it("rejects non-http cron.webhook URLs", () => {
+    const res = OpenClawSchema.safeParse({
+      cron: {
+        webhook: "ftp://example.invalid/legacy-cron-webhook",
+      },
+    });
+
+    expect(res.success).toBe(false);
+  });
+});
+
+describe("broadcast", () => {
+  it("accepts a broadcast peer map with strategy", () => {
+    const res = validateConfigObject({
+      agents: {
+        list: [{ id: "alfred" }, { id: "baerbel" }],
+      },
+      broadcast: {
+        strategy: "parallel",
+        "120363403215116621@g.us": ["alfred", "baerbel"],
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects invalid broadcast strategy", () => {
+    const res = validateConfigObject({
+      broadcast: { strategy: "nope" },
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it("rejects non-array broadcast entries", () => {
+    const res = validateConfigObject({
+      broadcast: { "120363403215116621@g.us": 123 },
+    });
+    expect(res.ok).toBe(false);
+  });
+});
+
+describe("model compat config schema", () => {
+  it("accepts full openai-completions compat fields", () => {
+    const res = validateConfigObject({
+      models: {
+        providers: {
+          local: {
+            baseUrl: "http://127.0.0.1:1234/v1",
+            api: "openai-completions",
+            models: [
+              {
+                id: "qwen3-32b",
+                name: "Qwen3 32B",
+                compat: {
+                  supportsUsageInStreaming: true,
+                  supportsStrictMode: false,
+                  thinkingFormat: "qwen",
+                  requiresToolResultName: true,
+                  requiresAssistantAfterToolResult: false,
+                  requiresThinkingAsText: false,
+                  requiresMistralToolIds: false,
+                },
+              },
+            ],
+          },
+        },
+      },
+    });
+
+    expect(res.ok).toBe(true);
+  });
+});
+
+describe("config paths", () => {
+  it("rejects empty and blocked paths", () => {
+    expect(parseConfigPath("")).toEqual({
+      ok: false,
+      error: "Invalid path. Use dot notation (e.g. foo.bar).",
+    });
+    expect(parseConfigPath("__proto__.polluted").ok).toBe(false);
+    expect(parseConfigPath("constructor.polluted").ok).toBe(false);
+    expect(parseConfigPath("prototype.polluted").ok).toBe(false);
+  });
+
+  it("sets, gets, and unsets nested values", () => {
+    const root: Record<string, unknown> = {};
+    const parsed = parseConfigPath("foo.bar");
+    if (!parsed.ok || !parsed.path) {
+      throw new Error("path parse failed");
+    }
+    setConfigValueAtPath(root, parsed.path, 123);
+    expect(getConfigValueAtPath(root, parsed.path)).toBe(123);
+    expect(unsetConfigValueAtPath(root, parsed.path)).toBe(true);
+    expect(getConfigValueAtPath(root, parsed.path)).toBeUndefined();
+  });
+});
+
+describe("config strict validation", () => {
+  it("rejects unknown fields", async () => {
+    const res = validateConfigObject({
+      agents: { list: [{ id: "pi" }] },
+      customUnknownField: { nested: "value" },
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it("flags legacy config entries without auto-migrating", async () => {
+    await withTempHome(async (home) => {
+      const configDir = path.join(home, ".openclaw");
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(
+        path.join(configDir, "openclaw.json"),
+        JSON.stringify({
+          agents: { list: [{ id: "pi" }] },
+          routing: { allowFrom: ["+15555550123"] },
+        }),
+        "utf-8",
+      );
+
+      const snap = await readConfigFileSnapshot();
+
+      expect(snap.valid).toBe(false);
+      expect(snap.legacyIssues).not.toHaveLength(0);
+    });
+  });
+});
diff --git a/src/config/config-paths.test.ts b/src/config/config-paths.test.ts
deleted file mode 100644
index a4dc7192ecd..00000000000
--- a/src/config/config-paths.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getConfigValueAtPath,
-  parseConfigPath,
-  setConfigValueAtPath,
-  unsetConfigValueAtPath,
-} from "./config-paths.js";
-
-describe("config paths", () => {
-  it("rejects empty and blocked paths", () => {
-    expect(parseConfigPath("")).toEqual({
-      ok: false,
-      error: "Invalid path. Use dot notation (e.g. foo.bar).",
-    });
-    expect(parseConfigPath("__proto__.polluted").ok).toBe(false);
-    expect(parseConfigPath("constructor.polluted").ok).toBe(false);
-    expect(parseConfigPath("prototype.polluted").ok).toBe(false);
-  });
-
-  it("sets, gets, and unsets nested values", () => {
-    const root: Record<string, unknown> = {};
-    const parsed = parseConfigPath("foo.bar");
-    if (!parsed.ok || !parsed.path) {
-      throw new Error("path parse failed");
-    }
-    setConfigValueAtPath(root, parsed.path, 123);
-    expect(getConfigValueAtPath(root, parsed.path)).toBe(123);
-    expect(unsetConfigValueAtPath(root, parsed.path)).toBe(true);
-    expect(getConfigValueAtPath(root, parsed.path)).toBeUndefined();
-  });
-});
diff --git a/src/config/config.agent-concurrency-defaults.test.ts b/src/config/config.agent-concurrency-defaults.test.ts
index accedc42a2b..d2fc3853914 100644
--- a/src/config/config.agent-concurrency-defaults.test.ts
+++ b/src/config/config.agent-concurrency-defaults.test.ts
@@ -17,19 +17,6 @@ describe("agent concurrency defaults", () => {
     expect(resolveSubagentMaxConcurrent({})).toBe(DEFAULT_SUBAGENT_MAX_CONCURRENT);
   });
 
-  it("resolves configured values", () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          maxConcurrent: 6,
-          subagents: { maxConcurrent: 9 },
-        },
-      },
-    };
-    expect(resolveAgentMaxConcurrent(cfg)).toBe(6);
-    expect(resolveSubagentMaxConcurrent(cfg)).toBe(9);
-  });
-
   it("clamps invalid values to at least 1", () => {
     const cfg = {
       agents: {
diff --git a/src/config/config.broadcast.test.ts b/src/config/config.broadcast.test.ts
deleted file mode 100644
index cab0cdf12b1..00000000000
--- a/src/config/config.broadcast.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("broadcast", () => {
-  it("accepts a broadcast peer map with strategy", () => {
-    const res = validateConfigObject({
-      agents: {
-        list: [{ id: "alfred" }, { id: "baerbel" }],
-      },
-      broadcast: {
-        strategy: "parallel",
-        "120363403215116621@g.us": ["alfred", "baerbel"],
-      },
-    });
-    expect(res.ok).toBe(true);
-  });
-
-  it("rejects invalid broadcast strategy", () => {
-    const res = validateConfigObject({
-      broadcast: { strategy: "nope" },
-    });
-    expect(res.ok).toBe(false);
-  });
-
-  it("rejects non-array broadcast entries", () => {
-    const res = validateConfigObject({
-      broadcast: { "120363403215116621@g.us": 123 },
-    });
-    expect(res.ok).toBe(false);
-  });
-});
diff --git a/src/config/config.gateway-remote-transport.test.ts b/src/config/config.gateway-remote-transport.test.ts
deleted file mode 100644
index a729a163772..00000000000
--- a/src/config/config.gateway-remote-transport.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("gateway.remote.transport", () => {
-  it("accepts direct transport", () => {
-    const res = validateConfigObject({
-      gateway: {
-        remote: {
-          transport: "direct",
-          url: "wss://gateway.example.ts.net",
-        },
-      },
-    });
-    expect(res.ok).toBe(true);
-  });
-
-  it("rejects unknown transport", () => {
-    const res = validateConfigObject({
-      gateway: {
-        remote: {
-          transport: "udp",
-        },
-      },
-    });
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.issues[0]?.path).toBe("gateway.remote.transport");
-    }
-  });
-});
diff --git a/src/config/config.gateway-tools-config.test.ts b/src/config/config.gateway-tools-config.test.ts
deleted file mode 100644
index 022dfc79abd..00000000000
--- a/src/config/config.gateway-tools-config.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("gateway.tools config", () => {
-  it("accepts gateway.tools allow and deny lists", () => {
-    const res = validateConfigObject({
-      gateway: {
-        tools: {
-          allow: ["gateway"],
-          deny: ["sessions_spawn", "sessions_send"],
-        },
-      },
-    });
-    expect(res.ok).toBe(true);
-  });
-
-  it("rejects invalid gateway.tools values", () => {
-    const res = validateConfigObject({
-      gateway: {
-        tools: {
-          allow: "gateway",
-        },
-      },
-    });
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.issues[0]?.path).toBe("gateway.tools.allow");
-    }
-  });
-});
diff --git a/src/config/config.identity-defaults.test.ts b/src/config/config.identity-defaults.test.ts
index a2d67e3f5e8..6c3d15f9bed 100644
--- a/src/config/config.identity-defaults.test.ts
+++ b/src/config/config.identity-defaults.test.ts
@@ -171,26 +171,4 @@ describe("config identity defaults", () => {
       expect(cfg.messages?.responsePrefix).toBe("");
     });
   });
-
-  it("does not derive responsePrefix from identity emoji", async () => {
-    await withTempHome("openclaw-config-identity-", async (home) => {
-      const cfg = await writeAndLoadConfig(home, {
-        agents: {
-          list: [
-            {
-              id: "main",
-              identity: {
-                name: "OpenClaw",
-                theme: "space lobster",
-                emoji: "🦞",
-              },
-            },
-          ],
-        },
-        messages: {},
-      });
-
-      expect(cfg.messages?.responsePrefix).toBeUndefined();
-    });
-  });
 });
diff --git a/src/config/config.model-compat-schema.test.ts b/src/config/config.model-compat-schema.test.ts
deleted file mode 100644
index 7039e44f34c..00000000000
--- a/src/config/config.model-compat-schema.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./validation.js";
-
-describe("model compat config schema", () => {
-  it("accepts full openai-completions compat fields", () => {
-    const res = validateConfigObject({
-      models: {
-        providers: {
-          local: {
-            baseUrl: "http://127.0.0.1:1234/v1",
-            api: "openai-completions",
-            models: [
-              {
-                id: "qwen3-32b",
-                name: "Qwen3 32B",
-                compat: {
-                  supportsUsageInStreaming: true,
-                  supportsStrictMode: false,
-                  thinkingFormat: "qwen",
-                  requiresToolResultName: true,
-                  requiresAssistantAfterToolResult: false,
-                  requiresThinkingAsText: false,
-                  requiresMistralToolIds: false,
-                },
-              },
-            ],
-          },
-        },
-      },
-    });
-
-    expect(res.ok).toBe(true);
-  });
-});
diff --git a/src/config/config.nix-integration-u3-u5-u9.e2e.test.ts b/src/config/config.nix-integration-u3-u5-u9.e2e.test.ts
index da574e9a4d8..371b1da121c 100644
--- a/src/config/config.nix-integration-u3-u5-u9.e2e.test.ts
+++ b/src/config/config.nix-integration-u3-u5-u9.e2e.test.ts
@@ -12,7 +12,8 @@ import {
 import { withTempHome } from "./test-helpers.js";
 
 function envWith(overrides: Record<string, string | undefined>): NodeJS.ProcessEnv {
-  return { ...process.env, ...overrides };
+  // Hermetic env: don't inherit process.env because other tests may mutate it.
+  return { ...overrides };
 }
 
 function loadConfigForHome(home: string) {
diff --git a/src/config/config.preservation-on-validation-failure.test.ts b/src/config/config.preservation-on-validation-failure.test.ts
deleted file mode 100644
index b82b861d289..00000000000
--- a/src/config/config.preservation-on-validation-failure.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { readConfigFileSnapshot, validateConfigObject } from "./config.js";
-import { withTempHome } from "./test-helpers.js";
-
-describe("config strict validation", () => {
-  it("rejects unknown fields", async () => {
-    const res = validateConfigObject({
-      agents: { list: [{ id: "pi" }] },
-      customUnknownField: { nested: "value" },
-    });
-    expect(res.ok).toBe(false);
-  });
-
-  it("flags legacy config entries without auto-migrating", async () => {
-    await withTempHome(async (home) => {
-      const configDir = path.join(home, ".openclaw");
-      await fs.mkdir(configDir, { recursive: true });
-      await fs.writeFile(
-        path.join(configDir, "openclaw.json"),
-        JSON.stringify({
-          agents: { list: [{ id: "pi" }] },
-          routing: { allowFrom: ["+15555550123"] },
-        }),
-        "utf-8",
-      );
-
-      const snap = await readConfigFileSnapshot();
-
-      expect(snap.valid).toBe(false);
-      expect(snap.legacyIssues).not.toHaveLength(0);
-    });
-  });
-});
diff --git a/src/config/config.sandbox-docker.test.ts b/src/config/config.sandbox-docker.test.ts
index 92903ff32f7..7add1d3c293 100644
--- a/src/config/config.sandbox-docker.test.ts
+++ b/src/config/config.sandbox-docker.test.ts
@@ -3,13 +3,13 @@ import { resolveSandboxBrowserConfig } from "../agents/sandbox/config.js";
 import { validateConfigObject } from "./config.js";
 
 describe("sandbox docker config", () => {
-  it("accepts binds array in sandbox.docker config", () => {
+  it("accepts safe binds array in sandbox.docker config", () => {
     const res = validateConfigObject({
       agents: {
         defaults: {
           sandbox: {
             docker: {
-              binds: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"],
+              binds: ["/home/user/source:/source:rw", "/var/data/myapp:/data:ro"],
             },
           },
         },
@@ -29,8 +29,8 @@ describe("sandbox docker config", () => {
     expect(res.ok).toBe(true);
     if (res.ok) {
       expect(res.config.agents?.defaults?.sandbox?.docker?.binds).toEqual([
-        "/var/run/docker.sock:/var/run/docker.sock",
         "/home/user/source:/source:rw",
+        "/var/data/myapp:/data:ro",
       ]);
       expect(res.config.agents?.list?.[0]?.sandbox?.docker?.binds).toEqual([
         "/home/user/projects:/projects:ro",
@@ -38,6 +38,51 @@ describe("sandbox docker config", () => {
     }
   });
 
+  it("rejects network host mode via Zod schema validation", () => {
+    const res = validateConfigObject({
+      agents: {
+        defaults: {
+          sandbox: {
+            docker: {
+              network: "host",
+            },
+          },
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it("rejects seccomp unconfined via Zod schema validation", () => {
+    const res = validateConfigObject({
+      agents: {
+        defaults: {
+          sandbox: {
+            docker: {
+              seccompProfile: "unconfined",
+            },
+          },
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+  });
+
+  it("rejects apparmor unconfined via Zod schema validation", () => {
+    const res = validateConfigObject({
+      agents: {
+        defaults: {
+          sandbox: {
+            docker: {
+              apparmorProfile: "unconfined",
+            },
+          },
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+  });
+
   it("rejects non-string values in binds array", () => {
     const res = validateConfigObject({
       agents: {
diff --git a/src/config/config.schema-key.test.ts b/src/config/config.schema-key.test.ts
deleted file mode 100644
index effa08347fa..00000000000
--- a/src/config/config.schema-key.test.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { OpenClawSchema } from "./zod-schema.js";
-
-describe("$schema key in config (#14998)", () => {
-  it("accepts config with $schema string", () => {
-    const result = OpenClawSchema.safeParse({
-      $schema: "https://openclaw.ai/config.json",
-    });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data.$schema).toBe("https://openclaw.ai/config.json");
-    }
-  });
-
-  it("accepts config without $schema", () => {
-    const result = OpenClawSchema.safeParse({});
-    expect(result.success).toBe(true);
-  });
-
-  it("rejects non-string $schema", () => {
-    const result = OpenClawSchema.safeParse({ $schema: 123 });
-    expect(result.success).toBe(false);
-  });
-});
diff --git a/src/config/config.talk-voicealiases.test.ts b/src/config/config.talk-voicealiases.test.ts
deleted file mode 100644
index e7e32c5b698..00000000000
--- a/src/config/config.talk-voicealiases.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("talk.voiceAliases", () => {
-  it("accepts a string map of voice aliases", () => {
-    const res = validateConfigObject({
-      talk: {
-        voiceAliases: {
-          Clawd: "EXAVITQu4vr4xnSDxMaL",
-          Roger: "CwhRBWXzGAHq8TQ4Fs17",
-        },
-      },
-    });
-    expect(res.ok).toBe(true);
-  });
-
-  it("rejects non-string voice alias values", () => {
-    const res = validateConfigObject({
-      talk: {
-        voiceAliases: {
-          Clawd: 123,
-        },
-      },
-    });
-    expect(res.ok).toBe(false);
-  });
-});
diff --git a/src/config/config.web-search-provider.test.ts b/src/config/config.web-search-provider.test.ts
deleted file mode 100644
index a0f1c6acded..00000000000
--- a/src/config/config.web-search-provider.test.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("web search provider config", () => {
-  it("accepts perplexity provider and config", () => {
-    const res = validateConfigObject({
-      tools: {
-        web: {
-          search: {
-            enabled: true,
-            provider: "perplexity",
-            perplexity: {
-              apiKey: "test-key",
-              baseUrl: "https://api.perplexity.ai",
-              model: "perplexity/sonar-pro",
-            },
-          },
-        },
-      },
-    });
-
-    expect(res.ok).toBe(true);
-  });
-});
diff --git a/src/config/home-env.test-harness.ts b/src/config/home-env.test-harness.ts
index 02808461b0f..78abde370dc 100644
--- a/src/config/home-env.test-harness.ts
+++ b/src/config/home-env.test-harness.ts
@@ -1,39 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-
-type HomeEnvSnapshot = {
-  home: string | undefined;
-  userProfile: string | undefined;
-  homeDrive: string | undefined;
-  homePath: string | undefined;
-  stateDir: string | undefined;
-};
-
-function snapshotHomeEnv(): HomeEnvSnapshot {
-  return {
-    home: process.env.HOME,
-    userProfile: process.env.USERPROFILE,
-    homeDrive: process.env.HOMEDRIVE,
-    homePath: process.env.HOMEPATH,
-    stateDir: process.env.OPENCLAW_STATE_DIR,
-  };
-}
-
-function restoreHomeEnv(snapshot: HomeEnvSnapshot) {
-  const restoreKey = (key: string, value: string | undefined) => {
-    if (value === undefined) {
-      delete process.env[key];
-    } else {
-      process.env[key] = value;
-    }
-  };
-  restoreKey("HOME", snapshot.home);
-  restoreKey("USERPROFILE", snapshot.userProfile);
-  restoreKey("HOMEDRIVE", snapshot.homeDrive);
-  restoreKey("HOMEPATH", snapshot.homePath);
-  restoreKey("OPENCLAW_STATE_DIR", snapshot.stateDir);
-}
+import { captureEnv } from "../test-utils/env.js";
 
 export async function withTempHome<T>(
   prefix: string,
@@ -42,7 +10,13 @@ export async function withTempHome<T>(
   const home = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
   await fs.mkdir(path.join(home, ".openclaw"), { recursive: true });
 
-  const snapshot = snapshotHomeEnv();
+  const snapshot = captureEnv([
+    "HOME",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "OPENCLAW_STATE_DIR",
+  ]);
   process.env.HOME = home;
   process.env.USERPROFILE = home;
   process.env.OPENCLAW_STATE_DIR = path.join(home, ".openclaw");
@@ -58,7 +32,7 @@ export async function withTempHome<T>(
   try {
     return await fn(home);
   } finally {
-    restoreHomeEnv(snapshot);
+    snapshot.restore();
     await fs.rm(home, { recursive: true, force: true });
   }
 }
diff --git a/src/config/io.ts b/src/config/io.ts
index 8ce2ae1d25c..e922e005a4b 100644
--- a/src/config/io.ts
+++ b/src/config/io.ts
@@ -933,6 +933,12 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) {
       if (suspiciousReasons.length === 0) {
         return;
       }
+      // Tests often write minimal configs (missing meta, etc); keep output quiet unless requested.
+      const isVitest = deps.env.VITEST === "true";
+      const shouldLogInVitest = deps.env.OPENCLAW_TEST_CONFIG_WRITE_ANOMALY_LOG === "1";
+      if (isVitest && !shouldLogInVitest) {
+        return;
+      }
       deps.logger.warn(`Config write anomaly: ${configPath} (${suspiciousReasons.join(", ")})`);
     };
     const auditRecordBase = {
diff --git a/src/config/io.write-config.test.ts b/src/config/io.write-config.test.ts
index 75eeaaac0c4..04f5e34a77f 100644
--- a/src/config/io.write-config.test.ts
+++ b/src/config/io.write-config.test.ts
@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
-import { withTempHome } from "./home-env.test-harness.js";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { createConfigIO } from "./io.js";
 
 describe("config io write", () => {
@@ -10,6 +11,51 @@ describe("config io write", () => {
     error: () => {},
   };
 
+  let fixtureRoot = "";
+  let caseId = 0;
+
+  async function withTempHome(prefix: string, fn: (home: string) => Promise<void>): Promise<void> {
+    const safePrefix = prefix.trim().replace(/[^a-zA-Z0-9._-]+/g, "-") || "tmp";
+    const home = path.join(fixtureRoot, `${safePrefix}${caseId++}`);
+    await fs.mkdir(path.join(home, ".openclaw"), { recursive: true });
+
+    const snapshot = captureEnv([
+      "HOME",
+      "USERPROFILE",
+      "HOMEDRIVE",
+      "HOMEPATH",
+      "OPENCLAW_STATE_DIR",
+    ]);
+    process.env.HOME = home;
+    process.env.USERPROFILE = home;
+    process.env.OPENCLAW_STATE_DIR = path.join(home, ".openclaw");
+
+    if (process.platform === "win32") {
+      const match = home.match(/^([A-Za-z]:)(.*)$/);
+      if (match) {
+        process.env.HOMEDRIVE = match[1];
+        process.env.HOMEPATH = match[2] || "\\";
+      }
+    }
+
+    try {
+      await fn(home);
+    } finally {
+      snapshot.restore();
+    }
+  }
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-config-io-"));
+  });
+
+  afterAll(async () => {
+    if (!fixtureRoot) {
+      return;
+    }
+    await fs.rm(fixtureRoot, { recursive: true, force: true });
+  });
+
   it("persists caller changes onto resolved config without leaking runtime defaults", async () => {
     await withTempHome("openclaw-config-io-", async (home) => {
       const configPath = path.join(home, ".openclaw", "openclaw.json");
diff --git a/src/config/legacy.migrations.part-1.ts b/src/config/legacy.migrations.part-1.ts
index 036a0c5a227..3c4d187610e 100644
--- a/src/config/legacy.migrations.part-1.ts
+++ b/src/config/legacy.migrations.part-1.ts
@@ -6,80 +6,85 @@ import {
   mergeMissing,
 } from "./legacy.shared.js";
 
+function migrateBindings(
+  raw: Record<string, unknown>,
+  changes: string[],
+  changeNote: string,
+  mutator: (match: Record<string, unknown>) => boolean,
+) {
+  const bindings = Array.isArray(raw.bindings) ? raw.bindings : null;
+  if (!bindings) {
+    return;
+  }
+
+  let touched = false;
+  for (const entry of bindings) {
+    if (!isRecord(entry)) {
+      continue;
+    }
+    const match = getRecord(entry.match);
+    if (!match) {
+      continue;
+    }
+    if (!mutator(match)) {
+      continue;
+    }
+    entry.match = match;
+    touched = true;
+  }
+
+  if (touched) {
+    raw.bindings = bindings;
+    changes.push(changeNote);
+  }
+}
+
 export const LEGACY_CONFIG_MIGRATIONS_PART_1: LegacyConfigMigration[] = [
   {
     id: "bindings.match.provider->bindings.match.channel",
     describe: "Move bindings[].match.provider to bindings[].match.channel",
     apply: (raw, changes) => {
-      const bindings = Array.isArray(raw.bindings) ? raw.bindings : null;
-      if (!bindings) {
-        return;
-      }
-
-      let touched = false;
-      for (const entry of bindings) {
-        if (!isRecord(entry)) {
-          continue;
-        }
-        const match = getRecord(entry.match);
-        if (!match) {
-          continue;
-        }
-        if (typeof match.channel === "string" && match.channel.trim()) {
-          continue;
-        }
-        const provider = typeof match.provider === "string" ? match.provider.trim() : "";
-        if (!provider) {
-          continue;
-        }
-        match.channel = provider;
-        delete match.provider;
-        entry.match = match;
-        touched = true;
-      }
-
-      if (touched) {
-        raw.bindings = bindings;
-        changes.push("Moved bindings[].match.provider → bindings[].match.channel.");
-      }
+      migrateBindings(
+        raw,
+        changes,
+        "Moved bindings[].match.provider → bindings[].match.channel.",
+        (match) => {
+          if (typeof match.channel === "string" && match.channel.trim()) {
+            return false;
+          }
+          const provider = typeof match.provider === "string" ? match.provider.trim() : "";
+          if (!provider) {
+            return false;
+          }
+          match.channel = provider;
+          delete match.provider;
+          return true;
+        },
+      );
     },
   },
   {
     id: "bindings.match.accountID->bindings.match.accountId",
     describe: "Move bindings[].match.accountID to bindings[].match.accountId",
     apply: (raw, changes) => {
-      const bindings = Array.isArray(raw.bindings) ? raw.bindings : null;
-      if (!bindings) {
-        return;
-      }
-
-      let touched = false;
-      for (const entry of bindings) {
-        if (!isRecord(entry)) {
-          continue;
-        }
-        const match = getRecord(entry.match);
-        if (!match) {
-          continue;
-        }
-        if (match.accountId !== undefined) {
-          continue;
-        }
-        const accountID =
-          typeof match.accountID === "string" ? match.accountID.trim() : match.accountID;
-        if (!accountID) {
-          continue;
-        }
-        match.accountId = accountID;
-        delete match.accountID;
-        entry.match = match;
-        touched = true;
-      }
-
-      if (touched) {
-        raw.bindings = bindings;
-        changes.push("Moved bindings[].match.accountID → bindings[].match.accountId.");
-      }
+      migrateBindings(
+        raw,
+        changes,
+        "Moved bindings[].match.accountID → bindings[].match.accountId.",
+        (match) => {
+          if (match.accountId !== undefined) {
+            return false;
+          }
+          const accountID =
+            typeof match.accountID === "string" ? match.accountID.trim() : match.accountID;
+          if (!accountID) {
+            return false;
+          }
+          match.accountId = accountID;
+          delete match.accountID;
+          return true;
+        },
+      );
     },
   },
   {
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
index 62a6d05e95b..b246c1ea6d4 100644
--- a/src/config/schema.help.ts
+++ b/src/config/schema.help.ts
@@ -71,6 +71,8 @@ export const FIELD_HELP: Record<string, string> = {
     "Allow stdin-only safe binaries to run without explicit allowlist entries.",
   "tools.fs.workspaceOnly":
     "Restrict filesystem tools (read/write/edit/apply_patch) to the workspace directory (default: false).",
+  "tools.sessions.visibility":
+    'Controls which sessions can be targeted by sessions_list/sessions_history/sessions_send. ("tree" default = current session + spawned subagent sessions; "self" = only current; "agent" = any session in the current agent id; "all" = any session; cross-agent still requires tools.agentToAgent).',
   "tools.message.allowCrossContextSend":
     "Legacy override: allow cross-context sends across all providers.",
   "tools.message.crossContext.allowWithinProvider":
@@ -373,6 +375,8 @@ export const FIELD_HELP: Record<string, string> = {
   "channels.discord.retry.maxDelayMs": "Maximum retry delay cap in ms for Discord outbound calls.",
   "channels.discord.retry.jitter": "Jitter factor (0-1) applied to Discord retry delays.",
   "channels.discord.maxLinesPerMessage": "Soft max line count per Discord message (default: 17).",
+  "channels.discord.ui.components.accentColor":
+    "Accent color for Discord component containers (hex). Set per account via channels.discord.accounts.<id>.ui.components.accentColor.",
   "channels.discord.intents.presence":
     "Enable the Guild Presences privileged intent. Must also be enabled in the Discord Developer Portal. Allows tracking user activities (e.g. Spotify). Default: false.",
   "channels.discord.intents.guildMembers":
diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts
index c27ca6d5311..e7fc90854ca 100644
--- a/src/config/schema.labels.ts
+++ b/src/config/schema.labels.ts
@@ -74,6 +74,7 @@ export const FIELD_LABELS: Record<string, string> = {
   "tools.exec.applyPatch.workspaceOnly": "apply_patch Workspace-Only",
   "tools.exec.applyPatch.allowModels": "apply_patch Model Allowlist",
   "tools.fs.workspaceOnly": "Workspace-only FS tools",
+  "tools.sessions.visibility": "Session Tools Visibility",
   "tools.exec.notifyOnExit": "Exec Notify On Exit",
   "tools.exec.notifyOnExitEmptySuccess": "Exec Notify On Empty Success",
   "tools.exec.approvalRunningNoticeMs": "Exec Approval Running Notice (ms)",
@@ -261,6 +262,7 @@ export const FIELD_LABELS: Record<string, string> = {
   "channels.discord.retry.maxDelayMs": "Discord Retry Max Delay (ms)",
   "channels.discord.retry.jitter": "Discord Retry Jitter",
   "channels.discord.maxLinesPerMessage": "Discord Max Lines Per Message",
+  "channels.discord.ui.components.accentColor": "Discord Component Accent Color",
   "channels.discord.intents.presence": "Discord Presence Intent",
   "channels.discord.intents.guildMembers": "Discord Guild Members Intent",
   "channels.discord.pluralkit.enabled": "Discord PluralKit Enabled",
diff --git a/src/config/sessions.cache.test.ts b/src/config/sessions.cache.test.ts
index 92922576bb5..cc3c6cb75a4 100644
--- a/src/config/sessions.cache.test.ts
+++ b/src/config/sessions.cache.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   clearSessionStoreCacheForTest,
   loadSessionStore,
@@ -10,12 +10,23 @@ import {
 } from "./sessions.js";
 
 describe("Session Store Cache", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
   let testDir: string;
   let storePath: string;
 
+  beforeAll(() => {
+    fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), "session-cache-test-"));
+  });
+
+  afterAll(() => {
+    if (fixtureRoot) {
+      fs.rmSync(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
   beforeEach(() => {
-    // Create a temporary directory for test
-    testDir = path.join(os.tmpdir(), `session-cache-test-${Date.now()}`);
+    testDir = path.join(fixtureRoot, `case-${caseId++}`);
     fs.mkdirSync(testDir, { recursive: true });
     storePath = path.join(testDir, "sessions.json");
 
@@ -27,10 +38,6 @@ describe("Session Store Cache", () => {
   });
 
   afterEach(() => {
-    // Clean up test directory
-    if (fs.existsSync(testDir)) {
-      fs.rmSync(testDir, { recursive: true, force: true });
-    }
     clearSessionStoreCacheForTest();
     delete process.env.OPENCLAW_SESSION_CACHE_TTL_MS;
   });
diff --git a/src/config/sessions.test.ts b/src/config/sessions.test.ts
index 686a46d3740..4bce24426a4 100644
--- a/src/config/sessions.test.ts
+++ b/src/config/sessions.test.ts
@@ -2,7 +2,6 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { sleep } from "../utils.js";
 import {
   buildGroupDisplayName,
   deriveSessionKey,
@@ -490,24 +489,39 @@ describe("sessions", () => {
       "utf-8",
     );
 
-    await Promise.all([
-      updateSessionStoreEntry({
-        storePath,
-        sessionKey: mainSessionKey,
-        update: async () => {
-          await sleep(10);
-          return { modelOverride: "anthropic/claude-opus-4-5" };
-        },
-      }),
-      updateSessionStoreEntry({
-        storePath,
-        sessionKey: mainSessionKey,
-        update: async () => {
-          await sleep(1);
-          return { thinkingLevel: "high" };
-        },
-      }),
-    ]);
+    const createDeferred = <T>() => {
+      let resolve!: (value: T) => void;
+      let reject!: (reason?: unknown) => void;
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      return { promise, resolve, reject };
+    };
+    const firstStarted = createDeferred<void>();
+    const releaseFirst = createDeferred<void>();
+
+    const p1 = updateSessionStoreEntry({
+      storePath,
+      sessionKey: mainSessionKey,
+      update: async () => {
+        firstStarted.resolve();
+        await releaseFirst.promise;
+        return { modelOverride: "anthropic/claude-opus-4-5" };
+      },
+    });
+    const p2 = updateSessionStoreEntry({
+      storePath,
+      sessionKey: mainSessionKey,
+      update: async () => {
+        await firstStarted.promise;
+        return { thinkingLevel: "high" };
+      },
+    });
+
+    await firstStarted.promise;
+    releaseFirst.resolve();
+    await Promise.all([p1, p2]);
 
     const store = loadSessionStore(storePath);
     expect(store[mainSessionKey]?.modelOverride).toBe("anthropic/claude-opus-4-5");
diff --git a/src/config/sessions/metadata.test.ts b/src/config/sessions/metadata.test.ts
deleted file mode 100644
index c85624f0cbb..00000000000
--- a/src/config/sessions/metadata.test.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { deriveSessionMetaPatch } from "./metadata.js";
-
-describe("deriveSessionMetaPatch", () => {
-  it("captures origin + group metadata", () => {
-    const patch = deriveSessionMetaPatch({
-      ctx: {
-        Provider: "whatsapp",
-        ChatType: "group",
-        GroupSubject: "Family",
-        From: "123@g.us",
-      },
-      sessionKey: "agent:main:whatsapp:group:123@g.us",
-    });
-
-    expect(patch?.origin?.label).toBe("Family id:123@g.us");
-    expect(patch?.origin?.provider).toBe("whatsapp");
-    expect(patch?.subject).toBe("Family");
-    expect(patch?.channel).toBe("whatsapp");
-    expect(patch?.groupId).toBe("123@g.us");
-  });
-});
diff --git a/src/config/sessions/paths.test.ts b/src/config/sessions/paths.test.ts
deleted file mode 100644
index 443b7791b8f..00000000000
--- a/src/config/sessions/paths.test.ts
+++ /dev/null
@@ -1,196 +0,0 @@
-import path from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import {
-  resolveSessionFilePath,
-  resolveSessionFilePathOptions,
-  resolveSessionTranscriptPath,
-  resolveSessionTranscriptPathInDir,
-  resolveStorePath,
-  validateSessionId,
-} from "./paths.js";
-
-describe("resolveStorePath", () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-
-  it("uses OPENCLAW_HOME for tilde expansion", () => {
-    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
-    vi.stubEnv("HOME", "/home/other");
-
-    const resolved = resolveStorePath("~/.openclaw/agents/{agentId}/sessions/sessions.json", {
-      agentId: "research",
-    });
-
-    expect(resolved).toBe(
-      path.resolve("/srv/openclaw-home/.openclaw/agents/research/sessions/sessions.json"),
-    );
-  });
-});
-
-describe("session path safety", () => {
-  it("validates safe session IDs", () => {
-    expect(validateSessionId("sess-1")).toBe("sess-1");
-    expect(validateSessionId("ABC_123.hello")).toBe("ABC_123.hello");
-  });
-
-  it("rejects unsafe session IDs", () => {
-    expect(() => validateSessionId("../etc/passwd")).toThrow(/Invalid session ID/);
-    expect(() => validateSessionId("a/b")).toThrow(/Invalid session ID/);
-    expect(() => validateSessionId("a\\b")).toThrow(/Invalid session ID/);
-    expect(() => validateSessionId("/abs")).toThrow(/Invalid session ID/);
-  });
-
-  it("resolves transcript path inside an explicit sessions dir", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-    const resolved = resolveSessionTranscriptPathInDir("sess-1", sessionsDir, "topic/a+b");
-
-    expect(resolved).toBe(path.resolve(sessionsDir, "sess-1-topic-topic%2Fa%2Bb.jsonl"));
-  });
-
-  it("rejects unsafe sessionFile candidates that escape the sessions dir", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-
-    expect(() =>
-      resolveSessionFilePath("sess-1", { sessionFile: "../../etc/passwd" }, { sessionsDir }),
-    ).toThrow(/within sessions directory/);
-
-    expect(() =>
-      resolveSessionFilePath("sess-1", { sessionFile: "/etc/passwd" }, { sessionsDir }),
-    ).toThrow(/within sessions directory/);
-  });
-
-  it("accepts sessionFile candidates within the sessions dir", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: "subdir/threaded-session.jsonl" },
-      { sessionsDir },
-    );
-
-    expect(resolved).toBe(path.resolve(sessionsDir, "subdir/threaded-session.jsonl"));
-  });
-
-  it("accepts absolute sessionFile paths that resolve within the sessions dir", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: "/tmp/openclaw/agents/main/sessions/abc-123.jsonl" },
-      { sessionsDir },
-    );
-
-    expect(resolved).toBe(path.resolve(sessionsDir, "abc-123.jsonl"));
-  });
-
-  it("accepts absolute sessionFile with topic suffix within the sessions dir", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: "/tmp/openclaw/agents/main/sessions/abc-123-topic-42.jsonl" },
-      { sessionsDir },
-    );
-
-    expect(resolved).toBe(path.resolve(sessionsDir, "abc-123-topic-42.jsonl"));
-  });
-
-  it("rejects absolute sessionFile paths outside known agent sessions dirs", () => {
-    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
-
-    expect(() =>
-      resolveSessionFilePath(
-        "sess-1",
-        { sessionFile: "/tmp/openclaw/agents/work/not-sessions/abc-123.jsonl" },
-        { sessionsDir },
-      ),
-    ).toThrow(/within sessions directory/);
-  });
-
-  it("uses explicit agentId fallback for absolute sessionFile outside sessionsDir", () => {
-    const mainSessionsDir = path.dirname(resolveStorePath(undefined, { agentId: "main" }));
-    const opsSessionsDir = path.dirname(resolveStorePath(undefined, { agentId: "ops" }));
-    const opsSessionFile = path.join(opsSessionsDir, "abc-123.jsonl");
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: opsSessionFile },
-      { sessionsDir: mainSessionsDir, agentId: "ops" },
-    );
-
-    expect(resolved).toBe(path.resolve(opsSessionFile));
-  });
-
-  it("uses absolute path fallback when sessionFile includes a different agent dir", () => {
-    const mainSessionsDir = path.dirname(resolveStorePath(undefined, { agentId: "main" }));
-    const opsSessionsDir = path.dirname(resolveStorePath(undefined, { agentId: "ops" }));
-    const opsSessionFile = path.join(opsSessionsDir, "abc-123.jsonl");
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: opsSessionFile },
-      { sessionsDir: mainSessionsDir },
-    );
-
-    expect(resolved).toBe(path.resolve(opsSessionFile));
-  });
-
-  it("uses sibling fallback for custom per-agent store roots", () => {
-    const mainSessionsDir = "/srv/custom/agents/main/sessions";
-    const opsSessionFile = "/srv/custom/agents/ops/sessions/abc-123.jsonl";
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: opsSessionFile },
-      { sessionsDir: mainSessionsDir, agentId: "ops" },
-    );
-
-    expect(resolved).toBe(path.resolve(opsSessionFile));
-  });
-
-  it("uses extracted agent fallback for custom per-agent store roots", () => {
-    const mainSessionsDir = "/srv/custom/agents/main/sessions";
-    const opsSessionFile = "/srv/custom/agents/ops/sessions/abc-123.jsonl";
-
-    const resolved = resolveSessionFilePath(
-      "sess-1",
-      { sessionFile: opsSessionFile },
-      { sessionsDir: mainSessionsDir },
-    );
-
-    expect(resolved).toBe(path.resolve(opsSessionFile));
-  });
-
-  it("uses agent sessions dir fallback for transcript path", () => {
-    const resolved = resolveSessionTranscriptPath("sess-1", "main");
-    expect(resolved.endsWith(path.join("agents", "main", "sessions", "sess-1.jsonl"))).toBe(true);
-  });
-
-  it("keeps storePath and agentId when resolving session file options", () => {
-    const opts = resolveSessionFilePathOptions({
-      storePath: "/tmp/custom/agent-store/sessions.json",
-      agentId: "ops",
-    });
-    expect(opts).toEqual({
-      sessionsDir: path.resolve("/tmp/custom/agent-store"),
-      agentId: "ops",
-    });
-  });
-
-  it("keeps custom per-agent store roots when agentId is provided", () => {
-    const opts = resolveSessionFilePathOptions({
-      storePath: "/srv/custom/agents/ops/sessions/sessions.json",
-      agentId: "ops",
-    });
-    expect(opts).toEqual({
-      sessionsDir: path.resolve("/srv/custom/agents/ops/sessions"),
-      agentId: "ops",
-    });
-  });
-
-  it("falls back to agentId when storePath is absent", () => {
-    const opts = resolveSessionFilePathOptions({ agentId: "ops" });
-    expect(opts).toEqual({ agentId: "ops" });
-  });
-});
diff --git a/src/config/sessions/reset.test.ts b/src/config/sessions/reset.test.ts
deleted file mode 100644
index 01962a887e5..00000000000
--- a/src/config/sessions/reset.test.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { SessionConfig } from "../types.base.js";
-import { resolveSessionResetPolicy } from "./reset.js";
-
-describe("resolveSessionResetPolicy", () => {
-  describe("backward compatibility: resetByType.dm → direct", () => {
-    it("uses resetByType.direct when available", () => {
-      const sessionCfg = {
-        resetByType: {
-          direct: { mode: "idle" as const, idleMinutes: 30 },
-        },
-      } satisfies SessionConfig;
-
-      const policy = resolveSessionResetPolicy({
-        sessionCfg,
-        resetType: "direct",
-      });
-
-      expect(policy.mode).toBe("idle");
-      expect(policy.idleMinutes).toBe(30);
-    });
-
-    it("falls back to resetByType.dm (legacy) when direct is missing", () => {
-      // Simulating legacy config with "dm" key instead of "direct"
-      const sessionCfg = {
-        resetByType: {
-          dm: { mode: "idle" as const, idleMinutes: 45 },
-        },
-      } as unknown as SessionConfig;
-
-      const policy = resolveSessionResetPolicy({
-        sessionCfg,
-        resetType: "direct",
-      });
-
-      expect(policy.mode).toBe("idle");
-      expect(policy.idleMinutes).toBe(45);
-    });
-
-    it("prefers resetByType.direct over resetByType.dm when both present", () => {
-      const sessionCfg = {
-        resetByType: {
-          direct: { mode: "daily" as const },
-          dm: { mode: "idle" as const, idleMinutes: 99 },
-        },
-      } as unknown as SessionConfig;
-
-      const policy = resolveSessionResetPolicy({
-        sessionCfg,
-        resetType: "direct",
-      });
-
-      expect(policy.mode).toBe("daily");
-    });
-
-    it("does not use dm fallback for group/thread types", () => {
-      const sessionCfg = {
-        resetByType: {
-          dm: { mode: "idle" as const, idleMinutes: 45 },
-        },
-      } as unknown as SessionConfig;
-
-      const groupPolicy = resolveSessionResetPolicy({
-        sessionCfg,
-        resetType: "group",
-      });
-
-      // Should use default mode since group has no config and dm doesn't apply
-      expect(groupPolicy.mode).toBe("daily");
-    });
-  });
-});
diff --git a/src/config/sessions/sessions.test.ts b/src/config/sessions/sessions.test.ts
new file mode 100644
index 00000000000..f29ff5a7f2b
--- /dev/null
+++ b/src/config/sessions/sessions.test.ts
@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { SessionConfig } from "../types.base.js";
+import type { SessionEntry } from "./types.js";
+import {
+  clearSessionStoreCacheForTest,
+  loadSessionStore,
+  updateSessionStore,
+} from "../sessions.js";
+import {
+  resolveSessionFilePath,
+  resolveSessionTranscriptPathInDir,
+  validateSessionId,
+} from "./paths.js";
+import { resolveSessionResetPolicy } from "./reset.js";
+import { appendAssistantMessageToSessionTranscript } from "./transcript.js";
+
+describe("session path safety", () => {
+  it("rejects unsafe session IDs", () => {
+    expect(() => validateSessionId("../etc/passwd")).toThrow(/Invalid session ID/);
+    expect(() => validateSessionId("a/b")).toThrow(/Invalid session ID/);
+    expect(() => validateSessionId("a\\b")).toThrow(/Invalid session ID/);
+    expect(() => validateSessionId("/abs")).toThrow(/Invalid session ID/);
+  });
+
+  it("resolves transcript path inside an explicit sessions dir", () => {
+    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
+    const resolved = resolveSessionTranscriptPathInDir("sess-1", sessionsDir, "topic/a+b");
+
+    expect(resolved).toBe(path.resolve(sessionsDir, "sess-1-topic-topic%2Fa%2Bb.jsonl"));
+  });
+
+  it("rejects absolute sessionFile paths outside known agent sessions dirs", () => {
+    const sessionsDir = "/tmp/openclaw/agents/main/sessions";
+
+    expect(() =>
+      resolveSessionFilePath(
+        "sess-1",
+        { sessionFile: "/tmp/openclaw/agents/work/not-sessions/abc-123.jsonl" },
+        { sessionsDir },
+      ),
+    ).toThrow(/within sessions directory/);
+  });
+});
+
+describe("resolveSessionResetPolicy", () => {
+  describe("backward compatibility: resetByType.dm -> direct", () => {
+    it("does not use dm fallback for group/thread types", () => {
+      const sessionCfg = {
+        resetByType: {
+          dm: { mode: "idle" as const, idleMinutes: 45 },
+        },
+      } as unknown as SessionConfig;
+
+      const groupPolicy = resolveSessionResetPolicy({
+        sessionCfg,
+        resetType: "group",
+      });
+
+      expect(groupPolicy.mode).toBe("daily");
+    });
+  });
+});
+
+describe("session store lock (Promise chain mutex)", () => {
+  let lockFixtureRoot = "";
+  let lockCaseId = 0;
+  let lockTmpDirs: string[] = [];
+
+  async function makeTmpStore(
+    initial: Record<string, unknown> = {},
+  ): Promise<{ dir: string; storePath: string }> {
+    const dir = path.join(lockFixtureRoot, `case-${lockCaseId++}`);
+    await fsPromises.mkdir(dir);
+    lockTmpDirs.push(dir);
+    const storePath = path.join(dir, "sessions.json");
+    if (Object.keys(initial).length > 0) {
+      await fsPromises.writeFile(storePath, JSON.stringify(initial, null, 2), "utf-8");
+    }
+    return { dir, storePath };
+  }
+
+  beforeAll(async () => {
+    lockFixtureRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), "openclaw-lock-test-"));
+  });
+
+  afterAll(async () => {
+    if (lockFixtureRoot) {
+      await fsPromises.rm(lockFixtureRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  afterEach(async () => {
+    clearSessionStoreCacheForTest();
+    lockTmpDirs = [];
+  });
+
+  it("serializes concurrent updateSessionStore calls without data loss", async () => {
+    const key = "agent:main:test";
+    const { storePath } = await makeTmpStore({
+      [key]: { sessionId: "s1", updatedAt: 100, counter: 0 },
+    });
+
+    const N = 4;
+    await Promise.all(
+      Array.from({ length: N }, (_, i) =>
+        updateSessionStore(storePath, async (store) => {
+          const entry = store[key] as Record<string, unknown>;
+          await Promise.resolve();
+          entry.counter = (entry.counter as number) + 1;
+          entry.tag = `writer-${i}`;
+        }),
+      ),
+    );
+
+    const store = loadSessionStore(storePath);
+    expect((store[key] as Record<string, unknown>).counter).toBe(N);
+  });
+
+  it("multiple consecutive errors do not permanently poison the queue", async () => {
+    const key = "agent:main:multi-err";
+    const { storePath } = await makeTmpStore({
+      [key]: { sessionId: "s1", updatedAt: 100 },
+    });
+
+    const errors = Array.from({ length: 3 }, (_, i) =>
+      updateSessionStore(storePath, async () => {
+        throw new Error(`fail-${i}`);
+      }),
+    );
+
+    const success = updateSessionStore(storePath, async (store) => {
+      store[key] = { ...store[key], modelOverride: "recovered" } as unknown as SessionEntry;
+    });
+
+    for (const p of errors) {
+      await expect(p).rejects.toThrow();
+    }
+    await success;
+
+    const store = loadSessionStore(storePath);
+    expect(store[key]?.modelOverride).toBe("recovered");
+  });
+});
+
+describe("appendAssistantMessageToSessionTranscript", () => {
+  let tempDir: string;
+  let storePath: string;
+  let sessionsDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "transcript-test-"));
+    sessionsDir = path.join(tempDir, "agents", "main", "sessions");
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    storePath = path.join(sessionsDir, "sessions.json");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("creates transcript file and appends message for valid session", async () => {
+    const sessionId = "test-session-id";
+    const sessionKey = "test-session";
+    const store = {
+      [sessionKey]: {
+        sessionId,
+        chatType: "direct",
+        channel: "discord",
+      },
+    };
+    fs.writeFileSync(storePath, JSON.stringify(store), "utf-8");
+
+    const result = await appendAssistantMessageToSessionTranscript({
+      sessionKey,
+      text: "Hello from delivery mirror!",
+      storePath,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(fs.existsSync(result.sessionFile)).toBe(true);
+
+      const lines = fs.readFileSync(result.sessionFile, "utf-8").trim().split("\n");
+      expect(lines.length).toBe(2);
+
+      const header = JSON.parse(lines[0]);
+      expect(header.type).toBe("session");
+      expect(header.id).toBe(sessionId);
+
+      const messageLine = JSON.parse(lines[1]);
+      expect(messageLine.type).toBe("message");
+      expect(messageLine.message.role).toBe("assistant");
+      expect(messageLine.message.content[0].type).toBe("text");
+      expect(messageLine.message.content[0].text).toBe("Hello from delivery mirror!");
+    }
+  });
+});
diff --git a/src/config/sessions/store.lock.test.ts b/src/config/sessions/store.lock.test.ts
deleted file mode 100644
index 826b3715e33..00000000000
--- a/src/config/sessions/store.lock.test.ts
+++ /dev/null
@@ -1,366 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
-import type { SessionEntry } from "./types.js";
-import {
-  clearSessionStoreCacheForTest,
-  getSessionStoreLockQueueSizeForTest,
-  loadSessionStore,
-  updateSessionStore,
-  updateSessionStoreEntry,
-  withSessionStoreLockForTest,
-} from "../sessions.js";
-
-describe("session store lock (Promise chain mutex)", () => {
-  let fixtureRoot = "";
-  let caseId = 0;
-  let tmpDirs: string[] = [];
-
-  function createDeferred<T>() {
-    let resolve!: (value: T) => void;
-    let reject!: (reason?: unknown) => void;
-    const promise = new Promise<T>((res, rej) => {
-      resolve = res;
-      reject = rej;
-    });
-    return { promise, resolve, reject };
-  }
-
-  async function waitForFile(filePath: string, maxTicks = 50): Promise<void> {
-    for (let tick = 0; tick < maxTicks; tick += 1) {
-      try {
-        await fs.access(filePath);
-        return;
-      } catch {
-        // Works under both real + fake timers (setImmediate is faked).
-        await new Promise<void>((resolve) => process.nextTick(resolve));
-      }
-    }
-    throw new Error(`timed out waiting for file: ${filePath}`);
-  }
-
-  async function makeTmpStore(
-    initial: Record<string, unknown> = {},
-  ): Promise<{ dir: string; storePath: string }> {
-    const dir = path.join(fixtureRoot, `case-${caseId++}`);
-    await fs.mkdir(dir);
-    tmpDirs.push(dir);
-    const storePath = path.join(dir, "sessions.json");
-    if (Object.keys(initial).length > 0) {
-      await fs.writeFile(storePath, JSON.stringify(initial, null, 2), "utf-8");
-    }
-    return { dir, storePath };
-  }
-
-  beforeAll(async () => {
-    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lock-test-"));
-  });
-
-  afterAll(async () => {
-    if (fixtureRoot) {
-      await fs.rm(fixtureRoot, { recursive: true, force: true }).catch(() => undefined);
-    }
-  });
-
-  afterEach(async () => {
-    clearSessionStoreCacheForTest();
-    tmpDirs = [];
-  });
-
-  // ── 1. Concurrent access does not corrupt data ──────────────────────
-
-  it("serializes concurrent updateSessionStore calls without data loss", async () => {
-    const key = "agent:main:test";
-    const { storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100, counter: 0 },
-    });
-
-    // Launch 10 concurrent read-modify-write cycles.
-    const N = 10;
-    await Promise.all(
-      Array.from({ length: N }, (_, i) =>
-        updateSessionStore(storePath, async (store) => {
-          const entry = store[key] as Record<string, unknown>;
-          // Keep an async boundary so stale-read races would surface without serialization.
-          await Promise.resolve();
-          entry.counter = (entry.counter as number) + 1;
-          entry.tag = `writer-${i}`;
-        }),
-      ),
-    );
-
-    const store = loadSessionStore(storePath);
-    expect((store[key] as Record<string, unknown>).counter).toBe(N);
-  });
-
-  it("concurrent updateSessionStoreEntry patches all merge correctly", async () => {
-    const key = "agent:main:merge";
-    const { storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100 },
-    });
-
-    await Promise.all([
-      updateSessionStoreEntry({
-        storePath,
-        sessionKey: key,
-        update: async () => {
-          await Promise.resolve();
-          return { modelOverride: "model-a" };
-        },
-      }),
-      updateSessionStoreEntry({
-        storePath,
-        sessionKey: key,
-        update: async () => {
-          await Promise.resolve();
-          return { thinkingLevel: "high" as const };
-        },
-      }),
-      updateSessionStoreEntry({
-        storePath,
-        sessionKey: key,
-        update: async () => {
-          await Promise.resolve();
-          return { systemPromptOverride: "custom" };
-        },
-      }),
-    ]);
-
-    const store = loadSessionStore(storePath);
-    const entry = store[key];
-    expect(entry.modelOverride).toBe("model-a");
-    expect(entry.thinkingLevel).toBe("high");
-    expect(entry.systemPromptOverride).toBe("custom");
-  });
-
-  // ── 2. Error in fn() does not break queue ───────────────────────────
-
-  it("continues processing queued tasks after a preceding task throws", async () => {
-    const key = "agent:main:err";
-    const { storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100 },
-    });
-
-    const errorPromise = updateSessionStore(storePath, async () => {
-      throw new Error("boom");
-    });
-
-    // Queue a second write immediately after the failing one.
-    const successPromise = updateSessionStore(storePath, async (store) => {
-      store[key] = { ...store[key], modelOverride: "after-error" } as unknown as SessionEntry;
-    });
-
-    await expect(errorPromise).rejects.toThrow("boom");
-    await successPromise; // must resolve, not hang or reject
-
-    const store = loadSessionStore(storePath);
-    expect(store[key]?.modelOverride).toBe("after-error");
-  });
-
-  it("multiple consecutive errors do not permanently poison the queue", async () => {
-    const key = "agent:main:multi-err";
-    const { storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100 },
-    });
-
-    const errors = Array.from({ length: 3 }, (_, i) =>
-      updateSessionStore(storePath, async () => {
-        throw new Error(`fail-${i}`);
-      }),
-    );
-
-    const success = updateSessionStore(storePath, async (store) => {
-      store[key] = { ...store[key], modelOverride: "recovered" } as unknown as SessionEntry;
-    });
-
-    // All error promises reject.
-    for (const p of errors) {
-      await expect(p).rejects.toThrow();
-    }
-    // The trailing write succeeds.
-    await success;
-
-    const store = loadSessionStore(storePath);
-    expect(store[key]?.modelOverride).toBe("recovered");
-  });
-
-  // ── 3. Different storePaths run independently / in parallel ─────────
-
-  it("operations on different storePaths execute concurrently", async () => {
-    const { storePath: pathA } = await makeTmpStore({
-      a: { sessionId: "a", updatedAt: 100 },
-    });
-    const { storePath: pathB } = await makeTmpStore({
-      b: { sessionId: "b", updatedAt: 100 },
-    });
-
-    const order: string[] = [];
-    let started = 0;
-    let releaseBoth: (() => void) | undefined;
-    const gate = new Promise<void>((resolve) => {
-      releaseBoth = resolve;
-    });
-    const markStarted = () => {
-      started += 1;
-      if (started === 2) {
-        releaseBoth?.();
-      }
-    };
-
-    const opA = updateSessionStore(pathA, async (store) => {
-      order.push("a-start");
-      markStarted();
-      await gate;
-      store.a = { ...store.a, modelOverride: "done-a" } as unknown as SessionEntry;
-      order.push("a-end");
-    });
-
-    const opB = updateSessionStore(pathB, async (store) => {
-      order.push("b-start");
-      markStarted();
-      await gate;
-      store.b = { ...store.b, modelOverride: "done-b" } as unknown as SessionEntry;
-      order.push("b-end");
-    });
-
-    await Promise.all([opA, opB]);
-
-    // Parallel behavior: both ops start before either one finishes.
-    const aStart = order.indexOf("a-start");
-    const bStart = order.indexOf("b-start");
-    const aEnd = order.indexOf("a-end");
-    const bEnd = order.indexOf("b-end");
-    const firstEnd = Math.min(aEnd, bEnd);
-    expect(aStart).toBeGreaterThanOrEqual(0);
-    expect(bStart).toBeGreaterThanOrEqual(0);
-    expect(aEnd).toBeGreaterThanOrEqual(0);
-    expect(bEnd).toBeGreaterThanOrEqual(0);
-    expect(aStart).toBeLessThan(firstEnd);
-    expect(bStart).toBeLessThan(firstEnd);
-
-    expect(loadSessionStore(pathA).a?.modelOverride).toBe("done-a");
-    expect(loadSessionStore(pathB).b?.modelOverride).toBe("done-b");
-  });
-
-  // ── 4. LOCK_QUEUES cleanup ─────────────────────────────────────────
-
-  it("cleans up LOCK_QUEUES entry after all tasks complete", async () => {
-    const { storePath } = await makeTmpStore({
-      x: { sessionId: "x", updatedAt: 100 },
-    });
-
-    await updateSessionStore(storePath, async (store) => {
-      store.x = { ...store.x, modelOverride: "done" } as unknown as SessionEntry;
-    });
-
-    // Allow microtask (finally) to run.
-    await Promise.resolve();
-
-    expect(getSessionStoreLockQueueSizeForTest()).toBe(0);
-  });
-
-  it("cleans up LOCK_QUEUES entry even after errors", async () => {
-    const { storePath } = await makeTmpStore({});
-
-    await updateSessionStore(storePath, async () => {
-      throw new Error("fail");
-    }).catch(() => undefined);
-
-    await Promise.resolve();
-
-    expect(getSessionStoreLockQueueSizeForTest()).toBe(0);
-  });
-
-  // ── 5. FIFO order guarantee ──────────────────────────────────────────
-
-  it("executes queued operations in FIFO order", async () => {
-    const key = "agent:main:fifo";
-    const { storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100, order: "" },
-    });
-
-    const executionOrder: number[] = [];
-
-    // Queue 5 operations sequentially (no awaiting in between).
-    const promises = Array.from({ length: 5 }, (_, i) =>
-      updateSessionStore(storePath, async (store) => {
-        executionOrder.push(i);
-        const entry = store[key] as Record<string, unknown>;
-        entry.order = ((entry.order as string) || "") + String(i);
-      }),
-    );
-
-    await Promise.all(promises);
-
-    // Execution order must be 0, 1, 2, 3, 4 (FIFO).
-    expect(executionOrder).toEqual([0, 1, 2, 3, 4]);
-
-    // The store should reflect sequential application.
-    const store = loadSessionStore(storePath);
-    expect((store[key] as Record<string, unknown>).order).toBe("01234");
-  });
-
-  it("times out queued operations strictly and does not run them later", async () => {
-    vi.useFakeTimers();
-    try {
-      const { storePath } = await makeTmpStore({
-        x: { sessionId: "x", updatedAt: 100 },
-      });
-      let timedOutRan = false;
-
-      const lockPath = `${storePath}.lock`;
-      const releaseLock = createDeferred<void>();
-      const lockHolder = withSessionStoreLockForTest(
-        storePath,
-        async () => {
-          await releaseLock.promise;
-        },
-        { timeoutMs: 1_000 },
-      );
-      await waitForFile(lockPath);
-      const timedOut = withSessionStoreLockForTest(
-        storePath,
-        async () => {
-          timedOutRan = true;
-        },
-        { timeoutMs: 5 },
-      );
-
-      // Attach rejection handler before advancing fake timers to avoid unhandled rejections.
-      const timedOutExpectation = expect(timedOut).rejects.toThrow(
-        "timeout waiting for session store lock",
-      );
-      await vi.advanceTimersByTimeAsync(5);
-      await timedOutExpectation;
-      releaseLock.resolve();
-      await lockHolder;
-      await vi.runOnlyPendingTimersAsync();
-      expect(timedOutRan).toBe(false);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it("creates and removes lock file while operation runs", async () => {
-    const key = "agent:main:no-lock-file";
-    const { dir, storePath } = await makeTmpStore({
-      [key]: { sessionId: "s1", updatedAt: 100 },
-    });
-
-    const lockPath = `${storePath}.lock`;
-    const allowWrite = createDeferred<void>();
-    const write = updateSessionStore(storePath, async (store) => {
-      await allowWrite.promise;
-      store[key] = { ...store[key], modelOverride: "v" } as unknown as SessionEntry;
-    });
-
-    await waitForFile(lockPath);
-    allowWrite.resolve();
-    await write;
-
-    const files = await fs.readdir(dir);
-    const lockFiles = files.filter((f) => f.endsWith(".lock"));
-    expect(lockFiles).toHaveLength(0);
-  });
-});
diff --git a/src/config/sessions/store.pruning.e2e.test.ts b/src/config/sessions/store.pruning.e2e.test.ts
new file mode 100644
index 00000000000..92cd0da77fd
--- /dev/null
+++ b/src/config/sessions/store.pruning.e2e.test.ts
@@ -0,0 +1,114 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionEntry } from "./types.js";
+import { clearSessionStoreCacheForTest, loadSessionStore, saveSessionStore } from "./store.js";
+
+// Keep integration tests deterministic: never read a real openclaw.json.
+vi.mock("../config.js", () => ({
+  loadConfig: vi.fn().mockReturnValue({}),
+}));
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+let fixtureRoot = "";
+let fixtureCount = 0;
+
+function makeEntry(updatedAt: number): SessionEntry {
+  return { sessionId: crypto.randomUUID(), updatedAt };
+}
+
+async function createCaseDir(prefix: string): Promise<string> {
+  const dir = path.join(fixtureRoot, `${prefix}-${fixtureCount++}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+describe("Integration: saveSessionStore with pruning", () => {
+  let testDir: string;
+  let storePath: string;
+  let savedCacheTtl: string | undefined;
+  let mockLoadConfig: ReturnType<typeof vi.fn>;
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-pruning-integ-"));
+  });
+
+  afterAll(async () => {
+    await fs.rm(fixtureRoot, { recursive: true, force: true });
+  });
+
+  beforeEach(async () => {
+    testDir = await createCaseDir("pruning-integ");
+    storePath = path.join(testDir, "sessions.json");
+    savedCacheTtl = process.env.OPENCLAW_SESSION_CACHE_TTL_MS;
+    process.env.OPENCLAW_SESSION_CACHE_TTL_MS = "0";
+    clearSessionStoreCacheForTest();
+
+    const configModule = await import("../config.js");
+    mockLoadConfig = configModule.loadConfig as ReturnType<typeof vi.fn>;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    clearSessionStoreCacheForTest();
+    if (savedCacheTtl === undefined) {
+      delete process.env.OPENCLAW_SESSION_CACHE_TTL_MS;
+    } else {
+      process.env.OPENCLAW_SESSION_CACHE_TTL_MS = savedCacheTtl;
+    }
+  });
+
+  it("saveSessionStore prunes stale entries on write", async () => {
+    mockLoadConfig.mockReturnValue({
+      session: {
+        maintenance: {
+          mode: "enforce",
+          pruneAfter: "7d",
+          maxEntries: 500,
+          rotateBytes: 10_485_760,
+        },
+      },
+    });
+
+    const now = Date.now();
+    const store: Record<string, SessionEntry> = {
+      stale: makeEntry(now - 30 * DAY_MS),
+      fresh: makeEntry(now),
+    };
+
+    await saveSessionStore(storePath, store);
+
+    const loaded = loadSessionStore(storePath);
+    expect(loaded.stale).toBeUndefined();
+    expect(loaded.fresh).toBeDefined();
+  });
+
+  it("saveSessionStore skips enforcement when maintenance mode is warn", async () => {
+    mockLoadConfig.mockReturnValue({
+      session: {
+        maintenance: {
+          mode: "warn",
+          pruneAfter: "7d",
+          maxEntries: 1,
+          rotateBytes: 10_485_760,
+        },
+      },
+    });
+
+    const now = Date.now();
+    const store: Record<string, SessionEntry> = {
+      stale: makeEntry(now - 30 * DAY_MS),
+      fresh: makeEntry(now),
+    };
+
+    await saveSessionStore(storePath, store);
+
+    const loaded = loadSessionStore(storePath);
+    expect(loaded.stale).toBeDefined();
+    expect(loaded.fresh).toBeDefined();
+    expect(Object.keys(loaded)).toHaveLength(2);
+  });
+});
diff --git a/src/config/sessions/store.pruning.test.ts b/src/config/sessions/store.pruning.test.ts
index 973763b55c5..a31a97b8f91 100644
--- a/src/config/sessions/store.pruning.test.ts
+++ b/src/config/sessions/store.pruning.test.ts
@@ -2,23 +2,9 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { SessionEntry } from "./types.js";
-import {
-  capEntryCount,
-  clearSessionStoreCacheForTest,
-  loadSessionStore,
-  pruneStaleEntries,
-  rotateSessionFile,
-  saveSessionStore,
-} from "./store.js";
-
-// Mock loadConfig so resolveMaintenanceConfig() never reads a real openclaw.json.
-// Unit tests always pass explicit overrides so this mock is inert for them.
-// Integration tests set return values to control the config.
-vi.mock("../config.js", () => ({
-  loadConfig: vi.fn().mockReturnValue({}),
-}));
+import { capEntryCount, pruneStaleEntries, rotateSessionFile } from "./store.js";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 
@@ -66,94 +52,6 @@ describe("pruneStaleEntries", () => {
     expect(store.old).toBeUndefined();
     expect(store.fresh).toBeDefined();
   });
-
-  it("keeps entries newer than maxAgeDays", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["a", makeEntry(now - 1 * DAY_MS)],
-      ["b", makeEntry(now - 6 * DAY_MS)],
-      ["c", makeEntry(now)],
-    ]);
-
-    const pruned = pruneStaleEntries(store, 7 * DAY_MS);
-
-    expect(pruned).toBe(0);
-    expect(Object.keys(store)).toHaveLength(3);
-  });
-
-  it("keeps entries with no updatedAt", () => {
-    const store: Record<string, SessionEntry> = {
-      noDate: { sessionId: crypto.randomUUID() } as SessionEntry,
-      fresh: makeEntry(Date.now()),
-    };
-
-    const pruned = pruneStaleEntries(store, 1 * DAY_MS);
-
-    expect(pruned).toBe(0);
-    expect(store.noDate).toBeDefined();
-  });
-
-  it("empty store is a no-op", () => {
-    const store: Record<string, SessionEntry> = {};
-    const pruned = pruneStaleEntries(store, 30 * DAY_MS);
-
-    expect(pruned).toBe(0);
-    expect(Object.keys(store)).toHaveLength(0);
-  });
-
-  it("all entries stale results in empty store", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["a", makeEntry(now - 10 * DAY_MS)],
-      ["b", makeEntry(now - 20 * DAY_MS)],
-      ["c", makeEntry(now - 100 * DAY_MS)],
-    ]);
-
-    const pruned = pruneStaleEntries(store, 5 * DAY_MS);
-
-    expect(pruned).toBe(3);
-    expect(Object.keys(store)).toHaveLength(0);
-  });
-
-  it("returns count of pruned entries", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["stale1", makeEntry(now - 15 * DAY_MS)],
-      ["stale2", makeEntry(now - 30 * DAY_MS)],
-      ["fresh1", makeEntry(now - 5 * DAY_MS)],
-      ["fresh2", makeEntry(now)],
-    ]);
-
-    const pruned = pruneStaleEntries(store, 10 * DAY_MS);
-
-    expect(pruned).toBe(2);
-    expect(Object.keys(store)).toHaveLength(2);
-  });
-
-  it("entry exactly at the boundary is kept", () => {
-    const now = Date.now();
-    const store = makeStore([["borderline", makeEntry(now - 30 * DAY_MS + 1000)]]);
-
-    const pruned = pruneStaleEntries(store, 30 * DAY_MS);
-
-    expect(pruned).toBe(0);
-    expect(store.borderline).toBeDefined();
-  });
-
-  it("falls back to built-in default (30 days) when no override given", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["old", makeEntry(now - 31 * DAY_MS)],
-      ["fresh", makeEntry(now - 29 * DAY_MS)],
-    ]);
-
-    // loadConfig mock returns {} → maintenance is undefined → default 30 days
-    const pruned = pruneStaleEntries(store);
-
-    expect(pruned).toBe(1);
-    expect(store.old).toBeUndefined();
-    expect(store.fresh).toBeDefined();
-  });
 });
 
 describe("capEntryCount", () => {
@@ -177,90 +75,6 @@ describe("capEntryCount", () => {
     expect(store.oldest).toBeUndefined();
     expect(store.old).toBeUndefined();
   });
-
-  it("under limit: no-op", () => {
-    const store = makeStore([
-      ["a", makeEntry(Date.now())],
-      ["b", makeEntry(Date.now() - DAY_MS)],
-    ]);
-
-    const evicted = capEntryCount(store, 10);
-
-    expect(evicted).toBe(0);
-    expect(Object.keys(store)).toHaveLength(2);
-  });
-
-  it("exactly at limit: no-op", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["a", makeEntry(now)],
-      ["b", makeEntry(now - DAY_MS)],
-      ["c", makeEntry(now - 2 * DAY_MS)],
-    ]);
-
-    const evicted = capEntryCount(store, 3);
-
-    expect(evicted).toBe(0);
-    expect(Object.keys(store)).toHaveLength(3);
-  });
-
-  it("entries without updatedAt are evicted first (lowest priority)", () => {
-    const now = Date.now();
-    const store: Record<string, SessionEntry> = {
-      noDate1: { sessionId: crypto.randomUUID() } as SessionEntry,
-      noDate2: { sessionId: crypto.randomUUID() } as SessionEntry,
-      recent: makeEntry(now),
-      older: makeEntry(now - DAY_MS),
-    };
-
-    const evicted = capEntryCount(store, 2);
-
-    expect(evicted).toBe(2);
-    expect(store.recent).toBeDefined();
-    expect(store.older).toBeDefined();
-    expect(store.noDate1).toBeUndefined();
-    expect(store.noDate2).toBeUndefined();
-  });
-
-  it("returns count of evicted entries", () => {
-    const now = Date.now();
-    const store = makeStore([
-      ["a", makeEntry(now)],
-      ["b", makeEntry(now - DAY_MS)],
-      ["c", makeEntry(now - 2 * DAY_MS)],
-    ]);
-
-    const evicted = capEntryCount(store, 1);
-
-    expect(evicted).toBe(2);
-    expect(Object.keys(store)).toHaveLength(1);
-    expect(store.a).toBeDefined();
-  });
-
-  it("falls back to built-in default (500) when no override given", () => {
-    const now = Date.now();
-    const entries: Array<[string, SessionEntry]> = [];
-    for (let i = 0; i < 501; i++) {
-      entries.push([`key-${i}`, makeEntry(now - i * 1000)]);
-    }
-    const store = makeStore(entries);
-
-    // loadConfig mock returns {} → maintenance is undefined → default 500
-    const evicted = capEntryCount(store);
-
-    expect(evicted).toBe(1);
-    expect(Object.keys(store)).toHaveLength(500);
-    expect(store["key-0"]).toBeDefined();
-    expect(store["key-500"]).toBeUndefined();
-  });
-
-  it("empty store is a no-op", () => {
-    const store: Record<string, SessionEntry> = {};
-
-    const evicted = capEntryCount(store, 5);
-
-    expect(evicted).toBe(0);
-  });
 });
 
 describe("rotateSessionFile", () => {
@@ -272,16 +86,6 @@ describe("rotateSessionFile", () => {
     storePath = path.join(testDir, "sessions.json");
   });
 
-  it("file under maxBytes: no rotation (returns false)", async () => {
-    await fs.writeFile(storePath, "x".repeat(500), "utf-8");
-
-    const rotated = await rotateSessionFile(storePath, 1000);
-
-    expect(rotated).toBe(false);
-    const content = await fs.readFile(storePath, "utf-8");
-    expect(content).toBe("x".repeat(500));
-  });
-
   it("file over maxBytes: renamed to .bak.{timestamp}, returns true", async () => {
     const bigContent = "x".repeat(200);
     await fs.writeFile(storePath, bigContent, "utf-8");
@@ -314,266 +118,4 @@ describe("rotateSessionFile", () => {
 
     expect(bakFiles.length).toBeLessThanOrEqual(3);
   });
-
-  it("non-existent file: no rotation (returns false)", async () => {
-    const missingPath = path.join(testDir, "missing.json");
-
-    const rotated = await rotateSessionFile(missingPath, 100);
-
-    expect(rotated).toBe(false);
-  });
-
-  it("file exactly at maxBytes: no rotation (returns false)", async () => {
-    await fs.writeFile(storePath, "x".repeat(100), "utf-8");
-
-    const rotated = await rotateSessionFile(storePath, 100);
-
-    expect(rotated).toBe(false);
-  });
-
-  it("backup file name includes a timestamp", async () => {
-    await fs.writeFile(storePath, "x".repeat(100), "utf-8");
-    const before = Date.now();
-
-    await rotateSessionFile(storePath, 50);
-
-    const after = Date.now();
-    const files = await fs.readdir(testDir);
-    const bakFiles = files.filter((f) => f.startsWith("sessions.json.bak."));
-    expect(bakFiles).toHaveLength(1);
-    const timestamp = Number(bakFiles[0].replace("sessions.json.bak.", ""));
-    expect(timestamp).toBeGreaterThanOrEqual(before);
-    expect(timestamp).toBeLessThanOrEqual(after);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Integration tests — exercise saveSessionStore end-to-end.
-// The file-level vi.mock("../config.js") stubs loadConfig; per-test
-// mockReturnValue controls what resolveMaintenanceConfig() returns.
-// ---------------------------------------------------------------------------
-
-describe("Integration: saveSessionStore with pruning", () => {
-  let testDir: string;
-  let storePath: string;
-  let savedCacheTtl: string | undefined;
-  let mockLoadConfig: ReturnType<typeof vi.fn>;
-
-  beforeEach(async () => {
-    testDir = await createCaseDir("pruning-integ");
-    storePath = path.join(testDir, "sessions.json");
-    savedCacheTtl = process.env.OPENCLAW_SESSION_CACHE_TTL_MS;
-    process.env.OPENCLAW_SESSION_CACHE_TTL_MS = "0";
-    clearSessionStoreCacheForTest();
-
-    const configModule = await import("../config.js");
-    mockLoadConfig = configModule.loadConfig as ReturnType<typeof vi.fn>;
-  });
-
-  afterEach(async () => {
-    vi.restoreAllMocks();
-    clearSessionStoreCacheForTest();
-    if (savedCacheTtl === undefined) {
-      delete process.env.OPENCLAW_SESSION_CACHE_TTL_MS;
-    } else {
-      process.env.OPENCLAW_SESSION_CACHE_TTL_MS = savedCacheTtl;
-    }
-  });
-
-  it("saveSessionStore prunes stale entries on write", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: {
-          mode: "enforce",
-          pruneAfter: "7d",
-          maxEntries: 500,
-          rotateBytes: 10_485_760,
-        },
-      },
-    });
-
-    const now = Date.now();
-    const store: Record<string, SessionEntry> = {
-      stale: makeEntry(now - 30 * DAY_MS),
-      fresh: makeEntry(now),
-    };
-
-    await saveSessionStore(storePath, store);
-
-    const loaded = loadSessionStore(storePath);
-    expect(loaded.stale).toBeUndefined();
-    expect(loaded.fresh).toBeDefined();
-  });
-
-  it("saveSessionStore caps entries over limit", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: {
-          mode: "enforce",
-          pruneAfter: "30d",
-          maxEntries: 5,
-          rotateBytes: 10_485_760,
-        },
-      },
-    });
-
-    const now = Date.now();
-    const store: Record<string, SessionEntry> = {};
-    for (let i = 0; i < 10; i++) {
-      store[`key-${i}`] = makeEntry(now - i * 1000);
-    }
-
-    await saveSessionStore(storePath, store);
-
-    const loaded = loadSessionStore(storePath);
-    expect(Object.keys(loaded)).toHaveLength(5);
-    for (let i = 0; i < 5; i++) {
-      expect(loaded[`key-${i}`]).toBeDefined();
-    }
-    for (let i = 5; i < 10; i++) {
-      expect(loaded[`key-${i}`]).toBeUndefined();
-    }
-  });
-
-  it("saveSessionStore rotates file when over size limit and creates .bak", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: {
-          mode: "enforce",
-          pruneAfter: "30d",
-          maxEntries: 500,
-          rotateBytes: "100b",
-        },
-      },
-    });
-
-    const now = Date.now();
-    const largeStore: Record<string, SessionEntry> = {};
-    for (let i = 0; i < 50; i++) {
-      largeStore[`agent:main:session-${crypto.randomUUID()}`] = makeEntry(now - i * 1000);
-    }
-    await fs.mkdir(path.dirname(storePath), { recursive: true });
-    await fs.writeFile(storePath, JSON.stringify(largeStore, null, 2), "utf-8");
-
-    const statBefore = await fs.stat(storePath);
-    expect(statBefore.size).toBeGreaterThan(100);
-
-    const smallStore: Record<string, SessionEntry> = {
-      only: makeEntry(now),
-    };
-    await saveSessionStore(storePath, smallStore);
-
-    const files = await fs.readdir(testDir);
-    const bakFiles = files.filter((f) => f.startsWith("sessions.json.bak."));
-    expect(bakFiles.length).toBeGreaterThanOrEqual(1);
-
-    const loaded = loadSessionStore(storePath);
-    expect(loaded.only).toBeDefined();
-  });
-
-  it("saveSessionStore applies both pruning and capping together", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: {
-          mode: "enforce",
-          pruneAfter: "10d",
-          maxEntries: 3,
-          rotateBytes: 10_485_760,
-        },
-      },
-    });
-
-    const now = Date.now();
-    const store: Record<string, SessionEntry> = {
-      stale1: makeEntry(now - 15 * DAY_MS),
-      stale2: makeEntry(now - 20 * DAY_MS),
-      fresh1: makeEntry(now),
-      fresh2: makeEntry(now - 1 * DAY_MS),
-      fresh3: makeEntry(now - 2 * DAY_MS),
-      fresh4: makeEntry(now - 5 * DAY_MS),
-    };
-
-    await saveSessionStore(storePath, store);
-
-    const loaded = loadSessionStore(storePath);
-    expect(loaded.stale1).toBeUndefined();
-    expect(loaded.stale2).toBeUndefined();
-    expect(Object.keys(loaded).length).toBeLessThanOrEqual(3);
-    expect(loaded.fresh1).toBeDefined();
-    expect(loaded.fresh2).toBeDefined();
-    expect(loaded.fresh3).toBeDefined();
-    expect(loaded.fresh4).toBeUndefined();
-  });
-
-  it("saveSessionStore skips enforcement when maintenance mode is warn", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: {
-          mode: "warn",
-          pruneAfter: "7d",
-          maxEntries: 1,
-          rotateBytes: 10_485_760,
-        },
-      },
-    });
-
-    const now = Date.now();
-    const store: Record<string, SessionEntry> = {
-      stale: makeEntry(now - 30 * DAY_MS),
-      fresh: makeEntry(now),
-    };
-
-    await saveSessionStore(storePath, store);
-
-    const loaded = loadSessionStore(storePath);
-    expect(loaded.stale).toBeDefined();
-    expect(loaded.fresh).toBeDefined();
-    expect(Object.keys(loaded)).toHaveLength(2);
-  });
-
-  it("resolveMaintenanceConfig reads from loadConfig().session.maintenance", async () => {
-    mockLoadConfig.mockReturnValue({
-      session: {
-        maintenance: { pruneAfter: "7d", maxEntries: 100, rotateBytes: "5mb" },
-      },
-    });
-
-    const { resolveMaintenanceConfig } = await import("./store.js");
-    const config = resolveMaintenanceConfig();
-
-    expect(config).toEqual({
-      mode: "warn",
-      pruneAfterMs: 7 * DAY_MS,
-      maxEntries: 100,
-      rotateBytes: 5 * 1024 * 1024,
-    });
-  });
-
-  it("resolveMaintenanceConfig uses defaults for missing fields", async () => {
-    mockLoadConfig.mockReturnValue({ session: { maintenance: { pruneAfter: "14d" } } });
-
-    const { resolveMaintenanceConfig } = await import("./store.js");
-    const config = resolveMaintenanceConfig();
-
-    expect(config).toEqual({
-      mode: "warn",
-      pruneAfterMs: 14 * DAY_MS,
-      maxEntries: 500,
-      rotateBytes: 10_485_760,
-    });
-  });
-
-  it("resolveMaintenanceConfig falls back to deprecated pruneDays", async () => {
-    mockLoadConfig.mockReturnValue({ session: { maintenance: { pruneDays: 2 } } });
-
-    const { resolveMaintenanceConfig } = await import("./store.js");
-    const config = resolveMaintenanceConfig();
-
-    expect(config).toEqual({
-      mode: "warn",
-      pruneAfterMs: 2 * DAY_MS,
-      maxEntries: 500,
-      rotateBytes: 10_485_760,
-    });
-  });
 });
diff --git a/src/config/sessions/store.undefined-path.test.ts b/src/config/sessions/store.undefined-path.test.ts
deleted file mode 100644
index 8d0bc1b05be..00000000000
--- a/src/config/sessions/store.undefined-path.test.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-/**
- * Regression test for #14717: path.dirname(undefined) crash in withSessionStoreLock
- *
- * When a channel plugin passes undefined as storePath to recordSessionMetaFromInbound,
- * the call chain reaches withSessionStoreLock → path.dirname(undefined) → TypeError crash.
- * After fix, a clear Error is thrown instead of an unhandled TypeError.
- */
-import { describe, expect, it } from "vitest";
-import { updateSessionStore } from "./store.js";
-
-describe("withSessionStoreLock storePath guard (#14717)", () => {
-  it("throws descriptive error when storePath is undefined", async () => {
-    await expect(
-      updateSessionStore(undefined as unknown as string, (store) => store),
-    ).rejects.toThrow("withSessionStoreLock: storePath must be a non-empty string");
-  });
-
-  it("throws descriptive error when storePath is empty string", async () => {
-    await expect(updateSessionStore("", (store) => store)).rejects.toThrow(
-      "withSessionStoreLock: storePath must be a non-empty string",
-    );
-  });
-});
diff --git a/src/config/sessions/transcript.test.ts b/src/config/sessions/transcript.test.ts
deleted file mode 100644
index 540ebd04752..00000000000
--- a/src/config/sessions/transcript.test.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  appendAssistantMessageToSessionTranscript,
-  resolveMirroredTranscriptText,
-} from "./transcript.js";
-
-describe("resolveMirroredTranscriptText", () => {
-  it("prefers media filenames over text", () => {
-    const result = resolveMirroredTranscriptText({
-      text: "caption here",
-      mediaUrls: ["https://example.com/files/report.pdf?sig=123"],
-    });
-    expect(result).toBe("report.pdf");
-  });
-
-  it("returns trimmed text when no media", () => {
-    const result = resolveMirroredTranscriptText({ text: "  hello  " });
-    expect(result).toBe("hello");
-  });
-});
-
-describe("appendAssistantMessageToSessionTranscript", () => {
-  let tempDir: string;
-  let storePath: string;
-  let sessionsDir: string;
-
-  beforeEach(() => {
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "transcript-test-"));
-    sessionsDir = path.join(tempDir, "agents", "main", "sessions");
-    fs.mkdirSync(sessionsDir, { recursive: true });
-    storePath = path.join(sessionsDir, "sessions.json");
-  });
-
-  afterEach(() => {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  it("returns error for missing sessionKey", async () => {
-    const result = await appendAssistantMessageToSessionTranscript({
-      sessionKey: "",
-      text: "test",
-      storePath,
-    });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.reason).toBe("missing sessionKey");
-    }
-  });
-
-  it("returns error for empty text", async () => {
-    const result = await appendAssistantMessageToSessionTranscript({
-      sessionKey: "test-session",
-      text: "   ",
-      storePath,
-    });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.reason).toBe("empty text");
-    }
-  });
-
-  it("returns error for unknown sessionKey", async () => {
-    fs.writeFileSync(storePath, JSON.stringify({}), "utf-8");
-    const result = await appendAssistantMessageToSessionTranscript({
-      sessionKey: "nonexistent",
-      text: "test message",
-      storePath,
-    });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.reason).toContain("unknown sessionKey");
-    }
-  });
-
-  it("creates transcript file and appends message for valid session", async () => {
-    const sessionId = "test-session-id";
-    const sessionKey = "test-session";
-    const store = {
-      [sessionKey]: {
-        sessionId,
-        chatType: "direct",
-        channel: "discord",
-      },
-    };
-    fs.writeFileSync(storePath, JSON.stringify(store), "utf-8");
-
-    const result = await appendAssistantMessageToSessionTranscript({
-      sessionKey,
-      text: "Hello from delivery mirror!",
-      storePath,
-    });
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(fs.existsSync(result.sessionFile)).toBe(true);
-
-      const lines = fs.readFileSync(result.sessionFile, "utf-8").trim().split("\n");
-      expect(lines.length).toBe(2); // header + message
-
-      const header = JSON.parse(lines[0]);
-      expect(header.type).toBe("session");
-      expect(header.id).toBe(sessionId);
-
-      const messageLine = JSON.parse(lines[1]);
-      expect(messageLine.type).toBe("message");
-      expect(messageLine.message.role).toBe("assistant");
-      expect(messageLine.message.content[0].type).toBe("text");
-      expect(messageLine.message.content[0].text).toBe("Hello from delivery mirror!");
-    }
-  });
-});
diff --git a/src/config/sessions/types.ts b/src/config/sessions/types.ts
index 1d0012a749f..012d59f728d 100644
--- a/src/config/sessions/types.ts
+++ b/src/config/sessions/types.ts
@@ -144,6 +144,8 @@ export type GroupKeyResolution = {
 export type SessionSkillSnapshot = {
   prompt: string;
   skills: Array<{ name: string; primaryEnv?: string }>;
+  /** Normalized agent-level filter used to build this snapshot; undefined means unrestricted. */
+  skillFilter?: string[];
   resolvedSkills?: Skill[];
   version?: number;
 };
diff --git a/src/config/slack-token-validation.test.ts b/src/config/slack-token-validation.test.ts
index 8a678afdc10..6ebfcabb858 100644
--- a/src/config/slack-token-validation.test.ts
+++ b/src/config/slack-token-validation.test.ts
@@ -33,4 +33,39 @@ describe("Slack token config fields", () => {
     });
     expect(res.ok).toBe(true);
   });
+
+  it("rejects invalid userTokenReadOnly types", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          botToken: "xoxb-any",
+          appToken: "xapp-any",
+          userToken: "xoxp-any",
+          // oxlint-disable-next-line typescript/no-explicit-any
+          userTokenReadOnly: "no" as any,
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues.some((iss) => iss.path.includes("userTokenReadOnly"))).toBe(true);
+    }
+  });
+
+  it("rejects invalid userToken types", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          botToken: "xoxb-any",
+          appToken: "xapp-any",
+          // oxlint-disable-next-line typescript/no-explicit-any
+          userToken: 123 as any,
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues.some((iss) => iss.path.includes("userToken"))).toBe(true);
+    }
+  });
 });
diff --git a/src/config/types.agent-defaults.ts b/src/config/types.agent-defaults.ts
index b58a8039064..2774105fb2b 100644
--- a/src/config/types.agent-defaults.ts
+++ b/src/config/types.agent-defaults.ts
@@ -91,6 +91,34 @@ export type CliBackendConfig = {
   imageMode?: "repeat" | "list";
   /** Serialize runs for this CLI. */
   serialize?: boolean;
+  /** Runtime reliability tuning for this backend's process lifecycle. */
+  reliability?: {
+    /** No-output watchdog tuning (fresh vs resumed runs). */
+    watchdog?: {
+      /** Fresh/new sessions (non-resume). */
+      fresh?: {
+        /** Fixed watchdog timeout in ms (overrides ratio when set). */
+        noOutputTimeoutMs?: number;
+        /** Fraction of overall timeout used when fixed timeout is not set. */
+        noOutputTimeoutRatio?: number;
+        /** Lower bound for computed watchdog timeout. */
+        minMs?: number;
+        /** Upper bound for computed watchdog timeout. */
+        maxMs?: number;
+      };
+      /** Resume sessions. */
+      resume?: {
+        /** Fixed watchdog timeout in ms (overrides ratio when set). */
+        noOutputTimeoutMs?: number;
+        /** Fraction of overall timeout used when fixed timeout is not set. */
+        noOutputTimeoutRatio?: number;
+        /** Lower bound for computed watchdog timeout. */
+        minMs?: number;
+        /** Upper bound for computed watchdog timeout. */
+        maxMs?: number;
+      };
+    };
+  };
 };
 
 export type AgentDefaultsConfig = {
@@ -230,7 +258,7 @@ export type AgentDefaultsConfig = {
     workspaceAccess?: "none" | "ro" | "rw";
     /**
      * Session tools visibility for sandboxed sessions.
-     * - "spawned": only allow session tools to target sessions spawned from this session (default)
+     * - "spawned": only allow session tools to target the current session and sessions spawned from it (default)
      * - "all": allow session tools to target any session
      */
     sessionToolsVisibility?: "spawned" | "all";
diff --git a/src/config/types.cron.ts b/src/config/types.cron.ts
index 62a9c1da139..45a8b715103 100644
--- a/src/config/types.cron.ts
+++ b/src/config/types.cron.ts
@@ -2,6 +2,13 @@ export type CronConfig = {
   enabled?: boolean;
   store?: string;
   maxConcurrentRuns?: number;
+  /**
+   * Deprecated legacy fallback webhook URL used only for stored jobs with notify=true.
+   * Prefer per-job delivery.mode="webhook" with delivery.to.
+   */
+  webhook?: string;
+  /** Bearer token for cron webhook POST delivery. */
+  webhookToken?: string;
   /**
    * How long to retain completed cron run sessions before automatic pruning.
    * Accepts a duration string (e.g. "24h", "7d", "1h30m") or `false` to disable pruning.
diff --git a/src/config/types.discord.ts b/src/config/types.discord.ts
index b2f248459f4..b2e1652907c 100644
--- a/src/config/types.discord.ts
+++ b/src/config/types.discord.ts
@@ -113,6 +113,15 @@ export type DiscordAgentComponentsConfig = {
   enabled?: boolean;
 };
 
+export type DiscordUiComponentsConfig = {
+  /** Accent color used by Discord component containers (hex). */
+  accentColor?: string;
+};
+
+export type DiscordUiConfig = {
+  components?: DiscordUiComponentsConfig;
+};
+
 export type DiscordAccountConfig = {
   /** Optional display name for this account (used in CLI/UI lists). */
   name?: string;
@@ -183,12 +192,19 @@ export type DiscordAccountConfig = {
   execApprovals?: DiscordExecApprovalConfig;
   /** Agent-controlled interactive components (buttons, select menus). */
   agentComponents?: DiscordAgentComponentsConfig;
+  /** Discord UI customization (components, modals, etc.). */
+  ui?: DiscordUiConfig;
   /** Privileged Gateway Intents (must also be enabled in Discord Developer Portal). */
   intents?: DiscordIntentsConfig;
   /** PluralKit identity resolution for proxied messages. */
   pluralkit?: DiscordPluralKitConfig;
   /** Outbound response prefix override for this channel/account. */
   responsePrefix?: string;
+  /**
+   * Per-channel ack reaction override.
+   * Discord supports both unicode emoji and custom emoji names.
+   */
+  ackReaction?: string;
   /** Bot activity status text (e.g. "Watching X"). */
   activity?: string;
   /** Bot status (online|dnd|idle|invisible). Defaults to online when presence is configured. */
diff --git a/src/config/types.slack.ts b/src/config/types.slack.ts
index a7f7bef2c80..ead656cce29 100644
--- a/src/config/types.slack.ts
+++ b/src/config/types.slack.ts
@@ -156,6 +156,11 @@ export type SlackAccountConfig = {
   heartbeat?: ChannelHeartbeatVisibilityConfig;
   /** Outbound response prefix override for this channel/account. */
   responsePrefix?: string;
+  /**
+   * Per-channel ack reaction override.
+   * Slack uses shortcodes (e.g., "eyes") rather than unicode emoji.
+   */
+  ackReaction?: string;
 };
 
 export type SlackConfig = {
diff --git a/src/config/types.telegram.ts b/src/config/types.telegram.ts
index 99b28cf793c..d8e189e756a 100644
--- a/src/config/types.telegram.ts
+++ b/src/config/types.telegram.ts
@@ -141,6 +141,11 @@ export type TelegramAccountConfig = {
    * Use `"auto"` to derive `[{identity.name}]` from the routed agent.
    */
   responsePrefix?: string;
+  /**
+   * Per-channel ack reaction override.
+   * Telegram expects unicode emoji (e.g., "👀") rather than shortcodes.
+   */
+  ackReaction?: string;
 };
 
 export type TelegramTopicConfig = {
diff --git a/src/config/types.tools.ts b/src/config/types.tools.ts
index e6fa1eec10b..4f02166d7aa 100644
--- a/src/config/types.tools.ts
+++ b/src/config/types.tools.ts
@@ -138,6 +138,8 @@ export type MediaToolsConfig = {
 
 export type ToolProfileId = "minimal" | "coding" | "messaging" | "full";
 
+export type SessionsToolsVisibility = "self" | "tree" | "agent" | "all";
+
 export type ToolPolicyConfig = {
   allow?: string[];
   /**
@@ -453,6 +455,21 @@ export type ToolsConfig = {
     /** Allowlist of agent ids or patterns (implementation-defined). */
     allow?: string[];
   };
+  /**
+   * Session tool visibility controls which sessions can be targeted by session tools
+   * (sessions_list, sessions_history, sessions_send).
+   *
+   * Default: "tree" (current session + spawned subagent sessions).
+   */
+  sessions?: {
+    /**
+     * - "self": only the current session
+     * - "tree": current session + sessions spawned by this session (default)
+     * - "agent": any session belonging to the current agent id (can include other users)
+     * - "all": any session (cross-agent still requires tools.agentToAgent)
+     */
+    visibility?: SessionsToolsVisibility;
+  };
   /** Elevated exec permissions for the host machine. */
   elevated?: {
     /** Enable or disable elevated mode (default: true). */
diff --git a/src/config/ui-seam-color.test.ts b/src/config/ui-seam-color.test.ts
deleted file mode 100644
index 6483a0c8129..00000000000
--- a/src/config/ui-seam-color.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateConfigObject } from "./config.js";
-
-describe("ui.seamColor", () => {
-  it("accepts hex colors", () => {
-    const res = validateConfigObject({ ui: { seamColor: "#FF4500" } });
-    expect(res.ok).toBe(true);
-  });
-
-  it("rejects non-hex colors", () => {
-    const res = validateConfigObject({ ui: { seamColor: "lobster" } });
-    expect(res.ok).toBe(false);
-  });
-
-  it("rejects invalid hex length", () => {
-    const res = validateConfigObject({ ui: { seamColor: "#FF4500FF" } });
-    expect(res.ok).toBe(false);
-  });
-});
diff --git a/src/config/zod-schema.agent-defaults.ts b/src/config/zod-schema.agent-defaults.ts
index d655a797ad2..2508179707c 100644
--- a/src/config/zod-schema.agent-defaults.ts
+++ b/src/config/zod-schema.agent-defaults.ts
@@ -1,10 +1,9 @@
 import { z } from "zod";
 import {
   HeartbeatSchema,
+  AgentSandboxSchema,
+  AgentModelSchema,
   MemorySearchSchema,
-  SandboxBrowserSchema,
-  SandboxDockerSchema,
-  SandboxPruneSchema,
 } from "./zod-schema.agent-runtime.js";
 import {
   BlockStreamingChunkSchema,
@@ -160,35 +159,12 @@ export const AgentDefaultsSchema = z
             "Maximum number of active children a single agent session can spawn (default: 5).",
           ),
         archiveAfterMinutes: z.number().int().positive().optional(),
-        model: z
-          .union([
-            z.string(),
-            z
-              .object({
-                primary: z.string().optional(),
-                fallbacks: z.array(z.string()).optional(),
-              })
-              .strict(),
-          ])
-          .optional(),
+        model: AgentModelSchema.optional(),
         thinking: z.string().optional(),
       })
       .strict()
       .optional(),
-    sandbox: z
-      .object({
-        mode: z.union([z.literal("off"), z.literal("non-main"), z.literal("all")]).optional(),
-        workspaceAccess: z.union([z.literal("none"), z.literal("ro"), z.literal("rw")]).optional(),
-        sessionToolsVisibility: z.union([z.literal("spawned"), z.literal("all")]).optional(),
-        scope: z.union([z.literal("session"), z.literal("agent"), z.literal("shared")]).optional(),
-        perSession: z.boolean().optional(),
-        workspaceRoot: z.string().optional(),
-        docker: SandboxDockerSchema,
-        browser: SandboxBrowserSchema,
-        prune: SandboxPruneSchema,
-      })
-      .strict()
-      .optional(),
+    sandbox: AgentSandboxSchema,
   })
   .strict()
   .optional();
diff --git a/src/config/zod-schema.agent-model.ts b/src/config/zod-schema.agent-model.ts
new file mode 100644
index 00000000000..3a6bac05c24
--- /dev/null
+++ b/src/config/zod-schema.agent-model.ts
@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const AgentModelSchema = z.union([
+  z.string(),
+  z
+    .object({
+      primary: z.string().optional(),
+      fallbacks: z.array(z.string()).optional(),
+    })
+    .strict(),
+]);
diff --git a/src/config/zod-schema.agent-runtime.ts b/src/config/zod-schema.agent-runtime.ts
index bab2b645115..52f768ff24f 100644
--- a/src/config/zod-schema.agent-runtime.ts
+++ b/src/config/zod-schema.agent-runtime.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { parseDurationMs } from "../cli/parse-duration.js";
+import { AgentModelSchema } from "./zod-schema.agent-model.js";
 import {
   GroupChatSchema,
   HumanDelaySchema,
@@ -124,6 +125,58 @@ export const SandboxDockerSchema = z
     binds: z.array(z.string()).optional(),
   })
   .strict()
+  .superRefine((data, ctx) => {
+    if (data.binds) {
+      for (let i = 0; i < data.binds.length; i += 1) {
+        const bind = data.binds[i]?.trim() ?? "";
+        if (!bind) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["binds", i],
+            message: "Sandbox security: bind mount entry must be a non-empty string.",
+          });
+          continue;
+        }
+        const firstColon = bind.indexOf(":");
+        const source = (firstColon <= 0 ? bind : bind.slice(0, firstColon)).trim();
+        if (!source.startsWith("/")) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["binds", i],
+            message:
+              `Sandbox security: bind mount "${bind}" uses a non-absolute source path "${source}". ` +
+              "Only absolute POSIX paths are supported for sandbox binds.",
+          });
+        }
+      }
+    }
+    if (data.network?.trim().toLowerCase() === "host") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["network"],
+        message:
+          'Sandbox security: network mode "host" is blocked. Use "bridge" or "none" instead.',
+      });
+    }
+    if (data.seccompProfile?.trim().toLowerCase() === "unconfined") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["seccompProfile"],
+        message:
+          'Sandbox security: seccomp profile "unconfined" is blocked. ' +
+          "Use a custom seccomp profile file or omit this setting.",
+      });
+    }
+    if (data.apparmorProfile?.trim().toLowerCase() === "unconfined") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["apparmorProfile"],
+        message:
+          'Sandbox security: apparmor profile "unconfined" is blocked. ' +
+          "Use a named AppArmor profile or omit this setting.",
+      });
+    }
+  })
   .optional();
 
 export const SandboxBrowserSchema = z
@@ -450,15 +503,7 @@ export const MemorySearchSchema = z
   })
   .strict()
   .optional();
-export const AgentModelSchema = z.union([
-  z.string(),
-  z
-    .object({
-      primary: z.string().optional(),
-      fallbacks: z.array(z.string()).optional(),
-    })
-    .strict(),
-]);
+export { AgentModelSchema };
 export const AgentEntrySchema = z
   .object({
     id: z.string(),
@@ -506,6 +551,12 @@ export const ToolsSchema = z
     web: ToolsWebSchema,
     media: ToolsMediaSchema,
     links: ToolsLinksSchema,
+    sessions: z
+      .object({
+        visibility: z.enum(["self", "tree", "agent", "all"]).optional(),
+      })
+      .strict()
+      .optional(),
     message: z
       .object({
         allowCrossContextSend: z.boolean().optional(),
diff --git a/src/config/zod-schema.core.ts b/src/config/zod-schema.core.ts
index 213ed9bedba..dbcbf80652f 100644
--- a/src/config/zod-schema.core.ts
+++ b/src/config/zod-schema.core.ts
@@ -275,6 +275,34 @@ export const CliBackendSchema = z
     imageArg: z.string().optional(),
     imageMode: z.union([z.literal("repeat"), z.literal("list")]).optional(),
     serialize: z.boolean().optional(),
+    reliability: z
+      .object({
+        watchdog: z
+          .object({
+            fresh: z
+              .object({
+                noOutputTimeoutMs: z.number().int().min(1000).optional(),
+                noOutputTimeoutRatio: z.number().min(0.05).max(0.95).optional(),
+                minMs: z.number().int().min(1000).optional(),
+                maxMs: z.number().int().min(1000).optional(),
+              })
+              .strict()
+              .optional(),
+            resume: z
+              .object({
+                noOutputTimeoutMs: z.number().int().min(1000).optional(),
+                noOutputTimeoutRatio: z.number().min(0.05).max(0.95).optional(),
+                minMs: z.number().int().min(1000).optional(),
+                maxMs: z.number().int().min(1000).optional(),
+              })
+              .strict()
+              .optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict();
 
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
index 1f5866eadf0..ed40d5e62bc 100644
--- a/src/config/zod-schema.providers-core.ts
+++ b/src/config/zod-schema.providers-core.ts
@@ -13,6 +13,7 @@ import {
   DmPolicySchema,
   ExecutableTokenSchema,
   GroupPolicySchema,
+  HexColorSchema,
   MarkdownConfigSchema,
   MSTeamsReplyStyleSchema,
   ProviderCommandsSchema,
@@ -142,6 +143,7 @@ export const TelegramAccountSchemaBase = z
     heartbeat: ChannelHeartbeatVisibilitySchema,
     linkPreview: z.boolean().optional(),
     responsePrefix: z.string().optional(),
+    ackReaction: z.string().optional(),
   })
   .strict();
 
@@ -247,6 +249,18 @@ export const DiscordGuildSchema = z
   })
   .strict();
 
+const DiscordUiSchema = z
+  .object({
+    components: z
+      .object({
+        accentColor: HexColorSchema.optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+  .optional();
+
 export const DiscordAccountSchema = z
   .object({
     name: z.string().optional(),
@@ -312,6 +326,7 @@ export const DiscordAccountSchema = z
       })
       .strict()
       .optional(),
+    ui: DiscordUiSchema,
     intents: z
       .object({
         presence: z.boolean().optional(),
@@ -327,6 +342,7 @@ export const DiscordAccountSchema = z
       .strict()
       .optional(),
     responsePrefix: z.string().optional(),
+    ackReaction: z.string().optional(),
     activity: z.string().optional(),
     status: z.enum(["online", "dnd", "idle", "invisible"]).optional(),
     activityType: z
@@ -558,6 +574,7 @@ export const SlackAccountSchema = z
     channels: z.record(z.string(), SlackChannelSchema.optional()).optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
     responsePrefix: z.string().optional(),
+    ackReaction: z.string().optional(),
   })
   .strict()
   .superRefine((value, ctx) => {
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index 7f43b4b1a08..3d718f2f1a5 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -93,6 +93,14 @@ const MemorySchema = z
   .strict()
   .optional();
 
+const HttpUrlSchema = z
+  .string()
+  .url()
+  .refine((value) => {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+  }, "Expected http:// or https:// URL");
+
 export const OpenClawSchema = z
   .object({
     $schema: z.string().optional(),
@@ -295,6 +303,8 @@ export const OpenClawSchema = z
         enabled: z.boolean().optional(),
         store: z.string().optional(),
         maxConcurrentRuns: z.number().int().positive().optional(),
+        webhook: HttpUrlSchema.optional(),
+        webhookToken: z.string().optional().register(sensitive),
         sessionRetention: z.union([z.string(), z.literal(false)]).optional(),
       })
       .strict()
diff --git a/src/cron/cron-protocol-conformance.test.ts b/src/cron/cron-protocol-conformance.test.ts
index 99a4b05de51..51fe8f4767c 100644
--- a/src/cron/cron-protocol-conformance.test.ts
+++ b/src/cron/cron-protocol-conformance.test.ts
@@ -5,16 +5,28 @@ import { MACOS_APP_SOURCES_DIR } from "../compat/legacy-names.js";
 import { CronDeliverySchema } from "../gateway/protocol/schema.js";
 
 type SchemaLike = {
-  anyOf?: Array<{ properties?: Record<string, unknown>; const?: unknown }>;
+  anyOf?: Array<SchemaLike>;
   properties?: Record<string, unknown>;
   const?: unknown;
 };
 
 function extractDeliveryModes(schema: SchemaLike): string[] {
   const modeSchema = schema.properties?.mode as SchemaLike | undefined;
-  return (modeSchema?.anyOf ?? [])
+  const directModes = (modeSchema?.anyOf ?? [])
     .map((entry) => entry?.const)
     .filter((value): value is string => typeof value === "string");
+  if (directModes.length > 0) {
+    return directModes;
+  }
+
+  const unionModes = (schema.anyOf ?? [])
+    .map((entry) => {
+      const mode = entry.properties?.mode as SchemaLike | undefined;
+      return mode?.const;
+    })
+    .filter((value): value is string => typeof value === "string");
+
+  return Array.from(new Set(unionModes));
 }
 
 const UI_FILES = ["ui/src/ui/types.ts", "ui/src/ui/ui-types.ts", "ui/src/ui/views/cron.ts"];
diff --git a/src/cron/delivery.test.ts b/src/cron/delivery.test.ts
index fcbe9e99a3b..783d0532b34 100644
--- a/src/cron/delivery.test.ts
+++ b/src/cron/delivery.test.ts
@@ -42,4 +42,16 @@ describe("resolveCronDeliveryPlan", () => {
     expect(plan.mode).toBe("none");
     expect(plan.requested).toBe(false);
   });
+
+  it("resolves webhook mode without channel routing", () => {
+    const plan = resolveCronDeliveryPlan(
+      makeJob({
+        delivery: { mode: "webhook", to: "https://example.invalid/cron" },
+      }),
+    );
+    expect(plan.mode).toBe("webhook");
+    expect(plan.requested).toBe(false);
+    expect(plan.channel).toBeUndefined();
+    expect(plan.to).toBe("https://example.invalid/cron");
+  });
 });
diff --git a/src/cron/delivery.ts b/src/cron/delivery.ts
index f0ba2c2b072..377cdb49b2f 100644
--- a/src/cron/delivery.ts
+++ b/src/cron/delivery.ts
@@ -2,7 +2,7 @@ import type { CronDeliveryMode, CronJob, CronMessageChannel } from "./types.js";
 
 export type CronDeliveryPlan = {
   mode: CronDeliveryMode;
-  channel: CronMessageChannel;
+  channel?: CronMessageChannel;
   to?: string;
   source: "delivery" | "payload";
   requested: boolean;
@@ -36,11 +36,13 @@ export function resolveCronDeliveryPlan(job: CronJob): CronDeliveryPlan {
   const mode =
     normalizedMode === "announce"
       ? "announce"
-      : normalizedMode === "none"
-        ? "none"
-        : normalizedMode === "deliver"
-          ? "announce"
-          : undefined;
+      : normalizedMode === "webhook"
+        ? "webhook"
+        : normalizedMode === "none"
+          ? "none"
+          : normalizedMode === "deliver"
+            ? "announce"
+            : undefined;
 
   const payloadChannel = normalizeChannel(payload?.channel);
   const payloadTo = normalizeTo(payload?.to);
@@ -55,7 +57,7 @@ export function resolveCronDeliveryPlan(job: CronJob): CronDeliveryPlan {
     const resolvedMode = mode ?? "announce";
     return {
       mode: resolvedMode,
-      channel,
+      channel: resolvedMode === "announce" ? channel : undefined,
       to,
       source: "delivery",
       requested: resolvedMode === "announce",
diff --git a/src/cron/isolated-agent/run.skill-filter.test.ts b/src/cron/isolated-agent/run.skill-filter.test.ts
new file mode 100644
index 00000000000..407918c74ac
--- /dev/null
+++ b/src/cron/isolated-agent/run.skill-filter.test.ts
@@ -0,0 +1,345 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ---------- mocks ----------
+
+const buildWorkspaceSkillSnapshotMock = vi.fn();
+const resolveAgentSkillsFilterMock = vi.fn();
+
+vi.mock("../../agents/agent-scope.js", () => ({
+  resolveAgentConfig: vi.fn().mockReturnValue(undefined),
+  resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent-dir"),
+  resolveAgentModelFallbacksOverride: vi.fn().mockReturnValue(undefined),
+  resolveAgentWorkspaceDir: vi.fn().mockReturnValue("/tmp/workspace"),
+  resolveDefaultAgentId: vi.fn().mockReturnValue("default"),
+  resolveAgentSkillsFilter: resolveAgentSkillsFilterMock,
+}));
+
+vi.mock("../../agents/skills.js", () => ({
+  buildWorkspaceSkillSnapshot: buildWorkspaceSkillSnapshotMock,
+}));
+
+vi.mock("../../agents/skills/refresh.js", () => ({
+  getSkillsSnapshotVersion: vi.fn().mockReturnValue(42),
+}));
+
+vi.mock("../../agents/workspace.js", () => ({
+  ensureAgentWorkspace: vi.fn().mockResolvedValue({ dir: "/tmp/workspace" }),
+}));
+
+vi.mock("../../agents/model-catalog.js", () => ({
+  loadModelCatalog: vi.fn().mockResolvedValue({ models: [] }),
+}));
+
+vi.mock("../../agents/model-selection.js", () => ({
+  getModelRefStatus: vi.fn().mockReturnValue({ allowed: false }),
+  isCliProvider: vi.fn().mockReturnValue(false),
+  resolveAllowedModelRef: vi.fn().mockReturnValue({ ref: { provider: "openai", model: "gpt-4" } }),
+  resolveConfiguredModelRef: vi.fn().mockReturnValue({ provider: "openai", model: "gpt-4" }),
+  resolveHooksGmailModel: vi.fn().mockReturnValue(null),
+  resolveThinkingDefault: vi.fn().mockReturnValue(undefined),
+}));
+
+vi.mock("../../agents/model-fallback.js", () => ({
+  runWithModelFallback: vi.fn().mockResolvedValue({
+    result: {
+      payloads: [{ text: "test output" }],
+      meta: { agentMeta: { usage: { input: 10, output: 20 } } },
+    },
+    provider: "openai",
+    model: "gpt-4",
+  }),
+}));
+
+vi.mock("../../agents/pi-embedded.js", () => ({
+  runEmbeddedPiAgent: vi.fn().mockResolvedValue({
+    payloads: [{ text: "test output" }],
+    meta: { agentMeta: { usage: { input: 10, output: 20 } } },
+  }),
+}));
+
+vi.mock("../../agents/context.js", () => ({
+  lookupContextTokens: vi.fn().mockReturnValue(128000),
+}));
+
+vi.mock("../../agents/date-time.js", () => ({
+  formatUserTime: vi.fn().mockReturnValue("2026-02-10 12:00"),
+  resolveUserTimeFormat: vi.fn().mockReturnValue("24h"),
+  resolveUserTimezone: vi.fn().mockReturnValue("UTC"),
+}));
+
+vi.mock("../../agents/timeout.js", () => ({
+  resolveAgentTimeoutMs: vi.fn().mockReturnValue(60_000),
+}));
+
+vi.mock("../../agents/usage.js", () => ({
+  deriveSessionTotalTokens: vi.fn().mockReturnValue(30),
+  hasNonzeroUsage: vi.fn().mockReturnValue(false),
+}));
+
+vi.mock("../../agents/subagent-announce.js", () => ({
+  runSubagentAnnounceFlow: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock("../../agents/cli-runner.js", () => ({
+  runCliAgent: vi.fn(),
+}));
+
+vi.mock("../../agents/cli-session.js", () => ({
+  getCliSessionId: vi.fn().mockReturnValue(undefined),
+  setCliSessionId: vi.fn(),
+}));
+
+vi.mock("../../auto-reply/thinking.js", () => ({
+  normalizeThinkLevel: vi.fn().mockReturnValue(undefined),
+  normalizeVerboseLevel: vi.fn().mockReturnValue("off"),
+  supportsXHighThinking: vi.fn().mockReturnValue(false),
+}));
+
+vi.mock("../../cli/outbound-send-deps.js", () => ({
+  createOutboundSendDeps: vi.fn().mockReturnValue({}),
+}));
+
+vi.mock("../../config/sessions.js", () => ({
+  resolveAgentMainSessionKey: vi.fn().mockReturnValue("main:default"),
+  resolveSessionTranscriptPath: vi.fn().mockReturnValue("/tmp/transcript.jsonl"),
+  updateSessionStore: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../../routing/session-key.js", () => ({
+  buildAgentMainSessionKey: vi.fn().mockReturnValue("agent:default:cron:test"),
+  normalizeAgentId: vi.fn((id: string) => id),
+}));
+
+vi.mock("../../infra/agent-events.js", () => ({
+  registerAgentRunContext: vi.fn(),
+}));
+
+vi.mock("../../infra/outbound/deliver.js", () => ({
+  deliverOutboundPayloads: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../../infra/skills-remote.js", () => ({
+  getRemoteSkillEligibility: vi.fn().mockReturnValue({}),
+}));
+
+vi.mock("../../logger.js", () => ({
+  logWarn: vi.fn(),
+}));
+
+vi.mock("../../security/external-content.js", () => ({
+  buildSafeExternalPrompt: vi.fn().mockReturnValue("safe prompt"),
+  detectSuspiciousPatterns: vi.fn().mockReturnValue([]),
+  getHookType: vi.fn().mockReturnValue("unknown"),
+  isExternalHookSession: vi.fn().mockReturnValue(false),
+}));
+
+vi.mock("../delivery.js", () => ({
+  resolveCronDeliveryPlan: vi.fn().mockReturnValue({ requested: false }),
+}));
+
+vi.mock("./delivery-target.js", () => ({
+  resolveDeliveryTarget: vi.fn().mockResolvedValue({
+    channel: "discord",
+    to: undefined,
+    accountId: undefined,
+    error: undefined,
+  }),
+}));
+
+vi.mock("./helpers.js", () => ({
+  isHeartbeatOnlyResponse: vi.fn().mockReturnValue(false),
+  pickLastDeliverablePayload: vi.fn().mockReturnValue(undefined),
+  pickLastNonEmptyTextFromPayloads: vi.fn().mockReturnValue("test output"),
+  pickSummaryFromOutput: vi.fn().mockReturnValue("summary"),
+  pickSummaryFromPayloads: vi.fn().mockReturnValue("summary"),
+  resolveHeartbeatAckMaxChars: vi.fn().mockReturnValue(100),
+}));
+
+const resolveCronSessionMock = vi.fn();
+vi.mock("./session.js", () => ({
+  resolveCronSession: resolveCronSessionMock,
+}));
+
+vi.mock("../../agents/defaults.js", () => ({
+  DEFAULT_CONTEXT_TOKENS: 128000,
+  DEFAULT_MODEL: "gpt-4",
+  DEFAULT_PROVIDER: "openai",
+}));
+
+const { runCronIsolatedAgentTurn } = await import("./run.js");
+
+// ---------- helpers ----------
+
+function makeJob(overrides?: Record<string, unknown>) {
+  return {
+    id: "test-job",
+    name: "Test Job",
+    schedule: { kind: "cron", expr: "0 9 * * *", tz: "UTC" },
+    sessionTarget: "isolated",
+    payload: { kind: "agentTurn", message: "test" },
+    ...overrides,
+  } as never;
+}
+
+function makeParams(overrides?: Record<string, unknown>) {
+  return {
+    cfg: {},
+    deps: {} as never,
+    job: makeJob(),
+    message: "test",
+    sessionKey: "cron:test",
+    ...overrides,
+  };
+}
+
+// ---------- tests ----------
+
+describe("runCronIsolatedAgentTurn — skill filter", () => {
+  let previousFastTestEnv: string | undefined;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    previousFastTestEnv = process.env.OPENCLAW_TEST_FAST;
+    delete process.env.OPENCLAW_TEST_FAST;
+    buildWorkspaceSkillSnapshotMock.mockReturnValue({
+      prompt: "<available_skills></available_skills>",
+      resolvedSkills: [],
+      version: 42,
+    });
+    resolveAgentSkillsFilterMock.mockReturnValue(undefined);
+    // Fresh session object per test — prevents mutation leaking between tests
+    resolveCronSessionMock.mockReturnValue({
+      storePath: "/tmp/store.json",
+      store: {},
+      sessionEntry: {
+        sessionId: "test-session-id",
+        updatedAt: 0,
+        systemSent: false,
+        skillsSnapshot: undefined,
+      },
+      systemSent: false,
+      isNewSession: true,
+    });
+  });
+
+  afterEach(() => {
+    if (previousFastTestEnv == null) {
+      delete process.env.OPENCLAW_TEST_FAST;
+      return;
+    }
+    process.env.OPENCLAW_TEST_FAST = previousFastTestEnv;
+  });
+
+  it("passes agent-level skillFilter to buildWorkspaceSkillSnapshot", async () => {
+    resolveAgentSkillsFilterMock.mockReturnValue(["meme-factory", "weather"]);
+
+    const result = await runCronIsolatedAgentTurn(
+      makeParams({
+        cfg: { agents: { list: [{ id: "scout", skills: ["meme-factory", "weather"] }] } },
+        agentId: "scout",
+      }),
+    );
+
+    expect(result.status).toBe("ok");
+    expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledOnce();
+    expect(buildWorkspaceSkillSnapshotMock.mock.calls[0][1]).toHaveProperty("skillFilter", [
+      "meme-factory",
+      "weather",
+    ]);
+  });
+
+  it("omits skillFilter when agent has no skills config", async () => {
+    resolveAgentSkillsFilterMock.mockReturnValue(undefined);
+
+    const result = await runCronIsolatedAgentTurn(
+      makeParams({
+        cfg: { agents: { list: [{ id: "general" }] } },
+        agentId: "general",
+      }),
+    );
+
+    expect(result.status).toBe("ok");
+    expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledOnce();
+    // When no skills config, skillFilter should be undefined (no filtering applied)
+    expect(buildWorkspaceSkillSnapshotMock.mock.calls[0][1].skillFilter).toBeUndefined();
+  });
+
+  it("passes empty skillFilter when agent explicitly disables all skills", async () => {
+    resolveAgentSkillsFilterMock.mockReturnValue([]);
+
+    const result = await runCronIsolatedAgentTurn(
+      makeParams({
+        cfg: { agents: { list: [{ id: "silent", skills: [] }] } },
+        agentId: "silent",
+      }),
+    );
+
+    expect(result.status).toBe("ok");
+    expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledOnce();
+    // Explicit empty skills list should forward [] to filter out all skills
+    expect(buildWorkspaceSkillSnapshotMock.mock.calls[0][1]).toHaveProperty("skillFilter", []);
+  });
+
+  it("refreshes cached snapshot when skillFilter changes without version bump", async () => {
+    resolveAgentSkillsFilterMock.mockReturnValue(["weather"]);
+    resolveCronSessionMock.mockReturnValue({
+      storePath: "/tmp/store.json",
+      store: {},
+      sessionEntry: {
+        sessionId: "test-session-id",
+        updatedAt: 0,
+        systemSent: false,
+        skillsSnapshot: {
+          prompt: "<available_skills><skill>meme-factory</skill></available_skills>",
+          skills: [{ name: "meme-factory" }],
+          version: 42,
+        },
+      },
+      systemSent: false,
+      isNewSession: true,
+    });
+
+    const result = await runCronIsolatedAgentTurn(
+      makeParams({
+        cfg: { agents: { list: [{ id: "weather-bot", skills: ["weather"] }] } },
+        agentId: "weather-bot",
+      }),
+    );
+
+    expect(result.status).toBe("ok");
+    expect(buildWorkspaceSkillSnapshotMock).toHaveBeenCalledOnce();
+    expect(buildWorkspaceSkillSnapshotMock.mock.calls[0][1]).toHaveProperty("skillFilter", [
+      "weather",
+    ]);
+  });
+
+  it("reuses cached snapshot when version and normalized skillFilter are unchanged", async () => {
+    resolveAgentSkillsFilterMock.mockReturnValue([" weather ", "meme-factory", "weather"]);
+    resolveCronSessionMock.mockReturnValue({
+      storePath: "/tmp/store.json",
+      store: {},
+      sessionEntry: {
+        sessionId: "test-session-id",
+        updatedAt: 0,
+        systemSent: false,
+        skillsSnapshot: {
+          prompt: "<available_skills><skill>weather</skill></available_skills>",
+          skills: [{ name: "weather" }],
+          skillFilter: ["meme-factory", "weather"],
+          version: 42,
+        },
+      },
+      systemSent: false,
+      isNewSession: true,
+    });
+
+    const result = await runCronIsolatedAgentTurn(
+      makeParams({
+        cfg: { agents: { list: [{ id: "weather-bot", skills: ["weather", "meme-factory"] }] } },
+        agentId: "weather-bot",
+      }),
+    );
+
+    expect(result.status).toBe("ok");
+    expect(buildWorkspaceSkillSnapshotMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/cron/isolated-agent/run.ts b/src/cron/isolated-agent/run.ts
index 116507f8e4e..8aba703dfbd 100644
--- a/src/cron/isolated-agent/run.ts
+++ b/src/cron/isolated-agent/run.ts
@@ -25,15 +25,9 @@ import {
   resolveThinkingDefault,
 } from "../../agents/model-selection.js";
 import { runEmbeddedPiAgent } from "../../agents/pi-embedded.js";
-import { buildWorkspaceSkillSnapshot } from "../../agents/skills.js";
-import { getSkillsSnapshotVersion } from "../../agents/skills/refresh.js";
 import { runSubagentAnnounceFlow } from "../../agents/subagent-announce.js";
-import {
-  countActiveDescendantRuns,
-  listDescendantRunsForRequester,
-} from "../../agents/subagent-registry.js";
+import { countActiveDescendantRuns } from "../../agents/subagent-registry.js";
 import { resolveAgentTimeoutMs } from "../../agents/timeout.js";
-import { readLatestAssistantReply } from "../../agents/tools/agent-step.js";
 import { deriveSessionTotalTokens, hasNonzeroUsage } from "../../agents/usage.js";
 import { ensureAgentWorkspace } from "../../agents/workspace.js";
 import {
@@ -51,7 +45,6 @@ import {
 import { registerAgentRunContext } from "../../infra/agent-events.js";
 import { deliverOutboundPayloads } from "../../infra/outbound/deliver.js";
 import { resolveAgentOutboundIdentity } from "../../infra/outbound/identity.js";
-import { getRemoteSkillEligibility } from "../../infra/skills-remote.js";
 import { logWarn } from "../../logger.js";
 import { buildAgentMainSessionKey, normalizeAgentId } from "../../routing/session-key.js";
 import {
@@ -71,6 +64,13 @@ import {
   resolveHeartbeatAckMaxChars,
 } from "./helpers.js";
 import { resolveCronSession } from "./session.js";
+import { resolveCronSkillsSnapshot } from "./skills-snapshot.js";
+import {
+  expectsSubagentFollowup,
+  isLikelyInterimCronMessage,
+  readDescendantSubagentFallbackReply,
+  waitForDescendantSubagentSummary,
+} from "./subagent-followup.js";
 
 function matchesMessagingToolDeliveryTarget(
   target: MessagingToolSend,
@@ -100,152 +100,6 @@ function resolveCronDeliveryBestEffort(job: CronJob): boolean {
   return false;
 }
 
-const CRON_SUBAGENT_WAIT_POLL_MS = 500;
-const CRON_SUBAGENT_WAIT_MIN_MS = 30_000;
-const CRON_SUBAGENT_FINAL_REPLY_GRACE_MS = 5_000;
-
-function isLikelyInterimCronMessage(value: string): boolean {
-  const text = value.trim();
-  if (!text) {
-    return true;
-  }
-  const normalized = text.toLowerCase().replace(/\s+/g, " ");
-  const words = normalized.split(" ").filter(Boolean).length;
-  const interimHints = [
-    "on it",
-    "pulling everything together",
-    "give me a few",
-    "give me a few min",
-    "few minutes",
-    "let me compile",
-    "i'll gather",
-    "i will gather",
-    "working on it",
-    "retrying now",
-    "should be about",
-    "should have your summary",
-    "subagent spawned",
-    "spawned a subagent",
-    "it'll auto-announce when done",
-    "it will auto-announce when done",
-    "auto-announce when done",
-    "both subagents are running",
-    "wait for them to report back",
-  ];
-  return words <= 45 && interimHints.some((hint) => normalized.includes(hint));
-}
-
-function expectsSubagentFollowup(value: string): boolean {
-  const normalized = value.trim().toLowerCase().replace(/\s+/g, " ");
-  if (!normalized) {
-    return false;
-  }
-  const hints = [
-    "subagent spawned",
-    "spawned a subagent",
-    "auto-announce when done",
-    "both subagents are running",
-    "wait for them to report back",
-  ];
-  return hints.some((hint) => normalized.includes(hint));
-}
-
-async function readDescendantSubagentFallbackReply(params: {
-  sessionKey: string;
-  runStartedAt: number;
-}): Promise<string | undefined> {
-  const descendants = listDescendantRunsForRequester(params.sessionKey)
-    .filter(
-      (entry) =>
-        typeof entry.endedAt === "number" &&
-        entry.endedAt >= params.runStartedAt &&
-        entry.childSessionKey.trim().length > 0,
-    )
-    .toSorted((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
-  if (descendants.length === 0) {
-    return undefined;
-  }
-
-  const latestByChild = new Map<string, (typeof descendants)[number]>();
-  for (const entry of descendants) {
-    const childKey = entry.childSessionKey.trim();
-    if (!childKey) {
-      continue;
-    }
-    const current = latestByChild.get(childKey);
-    if (!current || (entry.endedAt ?? 0) >= (current.endedAt ?? 0)) {
-      latestByChild.set(childKey, entry);
-    }
-  }
-
-  const replies: string[] = [];
-  const latestRuns = [...latestByChild.values()]
-    .toSorted((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0))
-    .slice(-4);
-  for (const entry of latestRuns) {
-    const reply = (await readLatestAssistantReply({ sessionKey: entry.childSessionKey }))?.trim();
-    if (!reply || reply.toUpperCase() === SILENT_REPLY_TOKEN.toUpperCase()) {
-      continue;
-    }
-    replies.push(reply);
-  }
-  if (replies.length === 0) {
-    return undefined;
-  }
-  if (replies.length === 1) {
-    return replies[0];
-  }
-  return replies.join("\n\n");
-}
-
-async function waitForDescendantSubagentSummary(params: {
-  sessionKey: string;
-  initialReply?: string;
-  timeoutMs: number;
-  observedActiveDescendants?: boolean;
-}): Promise<string | undefined> {
-  const initialReply = params.initialReply?.trim();
-  const deadline = Date.now() + Math.max(CRON_SUBAGENT_WAIT_MIN_MS, Math.floor(params.timeoutMs));
-  let sawActiveDescendants = params.observedActiveDescendants === true;
-  let drainedAtMs: number | undefined;
-  while (Date.now() < deadline) {
-    const activeDescendants = countActiveDescendantRuns(params.sessionKey);
-    if (activeDescendants > 0) {
-      sawActiveDescendants = true;
-      drainedAtMs = undefined;
-      await new Promise((resolve) => setTimeout(resolve, CRON_SUBAGENT_WAIT_POLL_MS));
-      continue;
-    }
-    if (!sawActiveDescendants) {
-      return initialReply;
-    }
-    if (!drainedAtMs) {
-      drainedAtMs = Date.now();
-    }
-    const latest = (await readLatestAssistantReply({ sessionKey: params.sessionKey }))?.trim();
-    if (
-      latest &&
-      latest.toUpperCase() !== SILENT_REPLY_TOKEN.toUpperCase() &&
-      (latest !== initialReply || !isLikelyInterimCronMessage(latest))
-    ) {
-      return latest;
-    }
-    if (Date.now() - drainedAtMs >= CRON_SUBAGENT_FINAL_REPLY_GRACE_MS) {
-      return undefined;
-    }
-    await new Promise((resolve) => setTimeout(resolve, CRON_SUBAGENT_WAIT_POLL_MS));
-  }
-  const latest = (await readLatestAssistantReply({ sessionKey: params.sessionKey }))?.trim();
-  if (
-    latest &&
-    latest.toUpperCase() !== SILENT_REPLY_TOKEN.toUpperCase() &&
-    (latest !== initialReply || !isLikelyInterimCronMessage(latest))
-  ) {
-    return latest;
-  }
-  return undefined;
-}
-
 export type RunCronAgentTurnResult = {
   status: "ok" | "error" | "skipped";
   summary?: string;
@@ -520,30 +374,21 @@ export async function runCronIsolatedAgentTurn(params: {
       `${commandBody}\n\nReturn your summary as plain text; it will be delivered automatically. If the task explicitly calls for messaging a specific external recipient, note who/where it should go instead of sending it yourself.`.trim();
   }
 
-  let skillsSnapshot = cronSession.sessionEntry.skillsSnapshot;
-  if (isFastTestEnv) {
-    // Fast unit-test mode: avoid scanning the workspace and writing session stores.
-    skillsSnapshot = skillsSnapshot ?? { prompt: "", skills: [] };
-  } else {
-    const existingSnapshot = cronSession.sessionEntry.skillsSnapshot;
-    const skillsSnapshotVersion = getSkillsSnapshotVersion(workspaceDir);
-    const needsSkillsSnapshot =
-      !existingSnapshot || existingSnapshot.version !== skillsSnapshotVersion;
-    if (needsSkillsSnapshot) {
-      skillsSnapshot = buildWorkspaceSkillSnapshot(workspaceDir, {
-        config: cfgWithAgentDefaults,
-        eligibility: { remote: getRemoteSkillEligibility() },
-        snapshotVersion: skillsSnapshotVersion,
-      });
-      if (skillsSnapshot) {
-        cronSession.sessionEntry = {
-          ...cronSession.sessionEntry,
-          updatedAt: Date.now(),
-          skillsSnapshot,
-        };
-        await persistSessionEntry();
-      }
-    }
+  const existingSkillsSnapshot = cronSession.sessionEntry.skillsSnapshot;
+  const skillsSnapshot = resolveCronSkillsSnapshot({
+    workspaceDir,
+    config: cfgWithAgentDefaults,
+    agentId,
+    existingSnapshot: existingSkillsSnapshot,
+    isFastTestEnv,
+  });
+  if (!isFastTestEnv && skillsSnapshot !== existingSkillsSnapshot) {
+    cronSession.sessionEntry = {
+      ...cronSession.sessionEntry,
+      updatedAt: Date.now(),
+      skillsSnapshot,
+    };
+    await persistSessionEntry();
   }
 
   // Persist systemSent before the run, mirroring the inbound auto-reply behavior.
diff --git a/src/cron/isolated-agent/skills-snapshot.ts b/src/cron/isolated-agent/skills-snapshot.ts
new file mode 100644
index 00000000000..2a491717a2c
--- /dev/null
+++ b/src/cron/isolated-agent/skills-snapshot.ts
@@ -0,0 +1,37 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import { resolveAgentSkillsFilter } from "../../agents/agent-scope.js";
+import { buildWorkspaceSkillSnapshot, type SkillSnapshot } from "../../agents/skills.js";
+import { matchesSkillFilter } from "../../agents/skills/filter.js";
+import { getSkillsSnapshotVersion } from "../../agents/skills/refresh.js";
+import { getRemoteSkillEligibility } from "../../infra/skills-remote.js";
+
+export function resolveCronSkillsSnapshot(params: {
+  workspaceDir: string;
+  config: OpenClawConfig;
+  agentId: string;
+  existingSnapshot?: SkillSnapshot;
+  isFastTestEnv: boolean;
+}): SkillSnapshot {
+  if (params.isFastTestEnv) {
+    // Fast unit-test mode skips filesystem scans and snapshot refresh writes.
+    return params.existingSnapshot ?? { prompt: "", skills: [] };
+  }
+
+  const snapshotVersion = getSkillsSnapshotVersion(params.workspaceDir);
+  const skillFilter = resolveAgentSkillsFilter(params.config, params.agentId);
+  const existingSnapshot = params.existingSnapshot;
+  const shouldRefresh =
+    !existingSnapshot ||
+    existingSnapshot.version !== snapshotVersion ||
+    !matchesSkillFilter(existingSnapshot.skillFilter, skillFilter);
+  if (!shouldRefresh) {
+    return existingSnapshot;
+  }
+
+  return buildWorkspaceSkillSnapshot(params.workspaceDir, {
+    config: params.config,
+    skillFilter,
+    eligibility: { remote: getRemoteSkillEligibility() },
+    snapshotVersion,
+  });
+}
diff --git a/src/cron/isolated-agent/subagent-followup.ts b/src/cron/isolated-agent/subagent-followup.ts
new file mode 100644
index 00000000000..9bf92925019
--- /dev/null
+++ b/src/cron/isolated-agent/subagent-followup.ts
@@ -0,0 +1,152 @@
+import {
+  countActiveDescendantRuns,
+  listDescendantRunsForRequester,
+} from "../../agents/subagent-registry.js";
+import { readLatestAssistantReply } from "../../agents/tools/agent-step.js";
+import { SILENT_REPLY_TOKEN } from "../../auto-reply/tokens.js";
+
+const CRON_SUBAGENT_WAIT_POLL_MS = 500;
+const CRON_SUBAGENT_WAIT_MIN_MS = 30_000;
+const CRON_SUBAGENT_FINAL_REPLY_GRACE_MS = 5_000;
+
+export function isLikelyInterimCronMessage(value: string): boolean {
+  const text = value.trim();
+  if (!text) {
+    return true;
+  }
+  const normalized = text.toLowerCase().replace(/\s+/g, " ");
+  const words = normalized.split(" ").filter(Boolean).length;
+  const interimHints = [
+    "on it",
+    "pulling everything together",
+    "give me a few",
+    "give me a few min",
+    "few minutes",
+    "let me compile",
+    "i'll gather",
+    "i will gather",
+    "working on it",
+    "retrying now",
+    "should be about",
+    "should have your summary",
+    "subagent spawned",
+    "spawned a subagent",
+    "it'll auto-announce when done",
+    "it will auto-announce when done",
+    "auto-announce when done",
+    "both subagents are running",
+    "wait for them to report back",
+  ];
+  return words <= 45 && interimHints.some((hint) => normalized.includes(hint));
+}
+
+export function expectsSubagentFollowup(value: string): boolean {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, " ");
+  if (!normalized) {
+    return false;
+  }
+  const hints = [
+    "subagent spawned",
+    "spawned a subagent",
+    "auto-announce when done",
+    "both subagents are running",
+    "wait for them to report back",
+  ];
+  return hints.some((hint) => normalized.includes(hint));
+}
+
+export async function readDescendantSubagentFallbackReply(params: {
+  sessionKey: string;
+  runStartedAt: number;
+}): Promise<string | undefined> {
+  const descendants = listDescendantRunsForRequester(params.sessionKey)
+    .filter(
+      (entry) =>
+        typeof entry.endedAt === "number" &&
+        entry.endedAt >= params.runStartedAt &&
+        entry.childSessionKey.trim().length > 0,
+    )
+    .toSorted((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
+  if (descendants.length === 0) {
+    return undefined;
+  }
+
+  const latestByChild = new Map<string, (typeof descendants)[number]>();
+  for (const entry of descendants) {
+    const childKey = entry.childSessionKey.trim();
+    if (!childKey) {
+      continue;
+    }
+    const current = latestByChild.get(childKey);
+    if (!current || (entry.endedAt ?? 0) >= (current.endedAt ?? 0)) {
+      latestByChild.set(childKey, entry);
+    }
+  }
+
+  const replies: string[] = [];
+  const latestRuns = [...latestByChild.values()]
+    .toSorted((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0))
+    .slice(-4);
+  for (const entry of latestRuns) {
+    const reply = (await readLatestAssistantReply({ sessionKey: entry.childSessionKey }))?.trim();
+    if (!reply || reply.toUpperCase() === SILENT_REPLY_TOKEN.toUpperCase()) {
+      continue;
+    }
+    replies.push(reply);
+  }
+  if (replies.length === 0) {
+    return undefined;
+  }
+  if (replies.length === 1) {
+    return replies[0];
+  }
+  return replies.join("\n\n");
+}
+
+export async function waitForDescendantSubagentSummary(params: {
+  sessionKey: string;
+  initialReply?: string;
+  timeoutMs: number;
+  observedActiveDescendants?: boolean;
+}): Promise<string | undefined> {
+  const initialReply = params.initialReply?.trim();
+  const deadline = Date.now() + Math.max(CRON_SUBAGENT_WAIT_MIN_MS, Math.floor(params.timeoutMs));
+  let sawActiveDescendants = params.observedActiveDescendants === true;
+  let drainedAtMs: number | undefined;
+  while (Date.now() < deadline) {
+    const activeDescendants = countActiveDescendantRuns(params.sessionKey);
+    if (activeDescendants > 0) {
+      sawActiveDescendants = true;
+      drainedAtMs = undefined;
+      await new Promise((resolve) => setTimeout(resolve, CRON_SUBAGENT_WAIT_POLL_MS));
+      continue;
+    }
+    if (!sawActiveDescendants) {
+      return initialReply;
+    }
+    if (!drainedAtMs) {
+      drainedAtMs = Date.now();
+    }
+    const latest = (await readLatestAssistantReply({ sessionKey: params.sessionKey }))?.trim();
+    if (
+      latest &&
+      latest.toUpperCase() !== SILENT_REPLY_TOKEN.toUpperCase() &&
+      (latest !== initialReply || !isLikelyInterimCronMessage(latest))
+    ) {
+      return latest;
+    }
+    if (Date.now() - drainedAtMs >= CRON_SUBAGENT_FINAL_REPLY_GRACE_MS) {
+      return undefined;
+    }
+    await new Promise((resolve) => setTimeout(resolve, CRON_SUBAGENT_WAIT_POLL_MS));
+  }
+  const latest = (await readLatestAssistantReply({ sessionKey: params.sessionKey }))?.trim();
+  if (
+    latest &&
+    latest.toUpperCase() !== SILENT_REPLY_TOKEN.toUpperCase() &&
+    (latest !== initialReply || !isLikelyInterimCronMessage(latest))
+  ) {
+    return latest;
+  }
+  return undefined;
+}
diff --git a/src/cron/legacy-delivery.ts b/src/cron/legacy-delivery.ts
new file mode 100644
index 00000000000..326f000b7a4
--- /dev/null
+++ b/src/cron/legacy-delivery.ts
@@ -0,0 +1,48 @@
+export function hasLegacyDeliveryHints(payload: Record<string, unknown>) {
+  if (typeof payload.deliver === "boolean") {
+    return true;
+  }
+  if (typeof payload.bestEffortDeliver === "boolean") {
+    return true;
+  }
+  if (typeof payload.to === "string" && payload.to.trim()) {
+    return true;
+  }
+  return false;
+}
+
+export function buildDeliveryFromLegacyPayload(
+  payload: Record<string, unknown>,
+): Record<string, unknown> {
+  const deliver = payload.deliver;
+  const mode = deliver === false ? "none" : "announce";
+  const channelRaw =
+    typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
+  const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
+  const next: Record<string, unknown> = { mode };
+  if (channelRaw) {
+    next.channel = channelRaw;
+  }
+  if (toRaw) {
+    next.to = toRaw;
+  }
+  if (typeof payload.bestEffortDeliver === "boolean") {
+    next.bestEffort = payload.bestEffortDeliver;
+  }
+  return next;
+}
+
+export function stripLegacyDeliveryFields(payload: Record<string, unknown>) {
+  if ("deliver" in payload) {
+    delete payload.deliver;
+  }
+  if ("channel" in payload) {
+    delete payload.channel;
+  }
+  if ("to" in payload) {
+    delete payload.to;
+  }
+  if ("bestEffortDeliver" in payload) {
+    delete payload.bestEffortDeliver;
+  }
+}
diff --git a/src/cron/normalize.test.ts b/src/cron/normalize.test.ts
index f5d7910044e..bcc2849ae57 100644
--- a/src/cron/normalize.test.ts
+++ b/src/cron/normalize.test.ts
@@ -163,6 +163,25 @@ describe("normalizeCronJobCreate", () => {
     expect(delivery.to).toBe("7200373102");
   });
 
+  it("normalizes webhook delivery mode and target URL", () => {
+    const normalized = normalizeCronJobCreate({
+      name: "webhook delivery",
+      enabled: true,
+      schedule: { kind: "every", everyMs: 60_000 },
+      sessionTarget: "main",
+      wakeMode: "now",
+      payload: { kind: "systemEvent", text: "hello" },
+      delivery: {
+        mode: " WeBhOoK ",
+        to: " https://example.invalid/cron ",
+      },
+    }) as unknown as Record<string, unknown>;
+
+    const delivery = normalized.delivery as Record<string, unknown>;
+    expect(delivery.mode).toBe("webhook");
+    expect(delivery.to).toBe("https://example.invalid/cron");
+  });
+
   it("defaults isolated agentTurn delivery to announce", () => {
     const normalized = normalizeCronJobCreate({
       name: "default-announce",
diff --git a/src/cron/normalize.ts b/src/cron/normalize.ts
index 00e56164631..2e09aefd576 100644
--- a/src/cron/normalize.ts
+++ b/src/cron/normalize.ts
@@ -1,6 +1,11 @@
 import type { CronJobCreate, CronJobPatch } from "./types.js";
 import { sanitizeAgentId } from "../routing/session-key.js";
 import { isRecord } from "../utils.js";
+import {
+  buildDeliveryFromLegacyPayload,
+  hasLegacyDeliveryHints,
+  stripLegacyDeliveryFields,
+} from "./legacy-delivery.js";
 import { parseAbsoluteTimeMs } from "./parse.js";
 import { migrateLegacyCronPayload } from "./payload-migration.js";
 import { inferLegacyName } from "./service/normalize.js";
@@ -146,7 +151,7 @@ function coerceDelivery(delivery: UnknownRecord) {
     const mode = delivery.mode.trim().toLowerCase();
     if (mode === "deliver") {
       next.mode = "announce";
-    } else if (mode === "announce" || mode === "none") {
+    } else if (mode === "announce" || mode === "none" || mode === "webhook") {
       next.mode = mode;
     } else {
       delete next.mode;
@@ -173,53 +178,6 @@ function coerceDelivery(delivery: UnknownRecord) {
   return next;
 }
 
-function hasLegacyDeliveryHints(payload: UnknownRecord) {
-  if (typeof payload.deliver === "boolean") {
-    return true;
-  }
-  if (typeof payload.bestEffortDeliver === "boolean") {
-    return true;
-  }
-  if (typeof payload.to === "string" && payload.to.trim()) {
-    return true;
-  }
-  return false;
-}
-
-function buildDeliveryFromLegacyPayload(payload: UnknownRecord): UnknownRecord {
-  const deliver = payload.deliver;
-  const mode = deliver === false ? "none" : "announce";
-  const channelRaw =
-    typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
-  const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
-  const next: UnknownRecord = { mode };
-  if (channelRaw) {
-    next.channel = channelRaw;
-  }
-  if (toRaw) {
-    next.to = toRaw;
-  }
-  if (typeof payload.bestEffortDeliver === "boolean") {
-    next.bestEffort = payload.bestEffortDeliver;
-  }
-  return next;
-}
-
-function stripLegacyDeliveryFields(payload: UnknownRecord) {
-  if ("deliver" in payload) {
-    delete payload.deliver;
-  }
-  if ("channel" in payload) {
-    delete payload.channel;
-  }
-  if ("to" in payload) {
-    delete payload.to;
-  }
-  if ("bestEffortDeliver" in payload) {
-    delete payload.bestEffortDeliver;
-  }
-}
-
 function unwrapJob(raw: UnknownRecord) {
   if (isRecord(raw.data)) {
     return raw.data;
diff --git a/src/cron/service.every-jobs-fire.test.ts b/src/cron/service.every-jobs-fire.test.ts
index 9a38121aecb..b70c3654f7b 100644
--- a/src/cron/service.every-jobs-fire.test.ts
+++ b/src/cron/service.every-jobs-fire.test.ts
@@ -190,12 +190,14 @@ describe("CronService interval/cron jobs fire on time", () => {
     });
 
     await cron.start();
-    for (let minute = 1; minute <= 6; minute++) {
+    // Perf: a few recomputation cycles are enough to catch legacy "every" drift.
+    for (let minute = 1; minute <= 3; minute++) {
       vi.setSystemTime(new Date(nowMs + minute * 60_000));
       const minuteRun = await cron.run("minute-cron", "force");
       expect(minuteRun).toEqual({ ok: true, ran: true });
     }
 
+    // "every" cadence is 2m; verify it stays due at the 6-minute boundary.
     vi.setSystemTime(new Date(nowMs + 6 * 60_000));
     const sfRun = await cron.run("legacy-every", "due");
     expect(sfRun).toEqual({ ok: true, ran: true });
diff --git a/src/cron/service.get-job.test.ts b/src/cron/service.get-job.test.ts
new file mode 100644
index 00000000000..a3e56004d46
--- /dev/null
+++ b/src/cron/service.get-job.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from "vitest";
+import { CronService } from "./service.js";
+import {
+  createCronStoreHarness,
+  createNoopLogger,
+  installCronTestHooks,
+} from "./service.test-harness.js";
+
+const logger = createNoopLogger();
+const { makeStorePath } = createCronStoreHarness({ prefix: "openclaw-cron-get-job-" });
+installCronTestHooks({ logger });
+
+function createCronService(storePath: string) {
+  return new CronService({
+    storePath,
+    cronEnabled: true,
+    log: logger,
+    enqueueSystemEvent: vi.fn(),
+    requestHeartbeatNow: vi.fn(),
+    runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" })),
+  });
+}
+
+describe("CronService.getJob", () => {
+  it("returns added jobs and undefined for missing ids", async () => {
+    const { storePath } = await makeStorePath();
+    const cron = createCronService(storePath);
+    await cron.start();
+
+    try {
+      const added = await cron.add({
+        name: "lookup-test",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "ping" },
+      });
+
+      expect(cron.getJob(added.id)?.id).toBe(added.id);
+      expect(cron.getJob("missing-job-id")).toBeUndefined();
+    } finally {
+      cron.stop();
+    }
+  });
+
+  it("preserves webhook delivery on create", async () => {
+    const { storePath } = await makeStorePath();
+    const cron = createCronService(storePath);
+    await cron.start();
+
+    try {
+      const webhookJob = await cron.add({
+        name: "webhook-job",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "ping" },
+        delivery: { mode: "webhook", to: "https://example.invalid/cron" },
+      });
+      expect(cron.getJob(webhookJob.id)?.delivery).toEqual({
+        mode: "webhook",
+        to: "https://example.invalid/cron",
+      });
+    } finally {
+      cron.stop();
+    }
+  });
+});
diff --git a/src/cron/service.issue-16156-list-skips-cron.test.ts b/src/cron/service.issue-16156-list-skips-cron.test.ts
index 85b960dd333..dd9363a5194 100644
--- a/src/cron/service.issue-16156-list-skips-cron.test.ts
+++ b/src/cron/service.issue-16156-list-skips-cron.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CronEvent } from "./service.js";
 import { CronService } from "./service.js";
 
@@ -12,14 +12,14 @@ const noopLogger = {
   error: vi.fn(),
 };
 
+let fixtureRoot = "";
+let caseId = 0;
+
 async function makeStorePath() {
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-cron-16156-"));
-  return {
-    storePath: path.join(dir, "cron", "jobs.json"),
-    cleanup: async () => {
-      await fs.rm(dir, { recursive: true, force: true });
-    },
-  };
+  const dir = path.join(fixtureRoot, `case-${caseId++}`);
+  const storePath = path.join(dir, "cron", "jobs.json");
+  await fs.mkdir(path.dirname(storePath), { recursive: true });
+  return { storePath };
 }
 
 function createFinishedBarrier() {
@@ -44,6 +44,16 @@ function createFinishedBarrier() {
 }
 
 describe("#16156: cron.list() must not silently advance past-due recurring jobs", () => {
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-cron-16156-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
   beforeEach(() => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2025-12-13T00:00:00.000Z"));
@@ -119,7 +129,6 @@ describe("#16156: cron.list() must not silently advance past-due recurring jobs"
     expect(updated?.state.nextRunAtMs).toBeGreaterThan(firstDueAt);
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("does not skip a cron job when status() is called while the job is past-due", async () => {
@@ -172,7 +181,6 @@ describe("#16156: cron.list() must not silently advance past-due recurring jobs"
     expect(updated?.state.lastStatus).toBe("ok");
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("still fills missing nextRunAtMs via list() for enabled jobs", async () => {
@@ -226,6 +234,5 @@ describe("#16156: cron.list() must not silently advance past-due recurring jobs"
     expect(job?.state.nextRunAtMs).toBeGreaterThan(nowMs);
 
     cron.stop();
-    await store.cleanup();
   });
 });
diff --git a/src/cron/service.issue-regressions.test.ts b/src/cron/service.issue-regressions.test.ts
index df1f867cf5f..e7dd5285519 100644
--- a/src/cron/service.issue-regressions.test.ts
+++ b/src/cron/service.issue-regressions.test.ts
@@ -24,9 +24,6 @@ async function makeStorePath() {
   const storePath = path.join(dir, "jobs.json");
   return {
     storePath,
-    cleanup: async () => {
-      await fs.rm(dir, { recursive: true, force: true });
-    },
   };
 }
 
@@ -152,7 +149,6 @@ describe("Cron issue regressions", () => {
     }
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("repairs missing nextRunAtMs on non-schedule updates without touching other jobs", async () => {
@@ -183,7 +179,6 @@ describe("Cron issue regressions", () => {
     expect(updated.state.nextRunAtMs).toBe(created.state.nextRunAtMs);
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("does not advance unrelated due jobs when updating another job", async () => {
@@ -230,7 +225,6 @@ describe("Cron issue regressions", () => {
     expect(persistedDueJob?.state?.nextRunAtMs).toBe(originalDueNextRunAtMs);
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("treats persisted jobs with missing enabled as enabled during update()", async () => {
@@ -282,7 +276,6 @@ describe("Cron issue regressions", () => {
     expect(updated.state.nextRunAtMs).toBeGreaterThan(now);
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("treats persisted due jobs with missing enabled as runnable", async () => {
@@ -333,7 +326,6 @@ describe("Cron issue regressions", () => {
     );
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("caps timer delay to 60s for far-future schedules", async () => {
@@ -366,7 +358,6 @@ describe("Cron issue regressions", () => {
 
     cron.stop();
     timeoutSpy.mockRestore();
-    await store.cleanup();
   });
 
   it("re-arms timer without hot-looping when a run is already in progress", async () => {
@@ -400,7 +391,6 @@ describe("Cron issue regressions", () => {
       .filter((d): d is number => typeof d === "number");
     expect(delays).toContain(60_000);
     timeoutSpy.mockRestore();
-    await store.cleanup();
   });
 
   it("skips forced manual runs while a timer-triggered run is in progress", async () => {
@@ -467,7 +457,6 @@ describe("Cron issue regressions", () => {
     await cron.list({ includeDisabled: true });
 
     cron.stop();
-    await store.cleanup();
   });
 
   it("#13845: one-shot jobs with terminal statuses do not re-fire on restart", async () => {
@@ -523,7 +512,6 @@ describe("Cron issue regressions", () => {
       expect(enqueueSystemEvent).not.toHaveBeenCalled();
       cron.stop();
     }
-    await store.cleanup();
   });
 
   it("records per-job start time and duration for batched due jobs", async () => {
@@ -569,7 +557,5 @@ describe("Cron issue regressions", () => {
     expect(secondDone?.state.lastRunAtMs).toBe(dueAt + 50);
     expect(secondDone?.state.lastDurationMs).toBe(20);
     expect(startedAtEvents).toEqual([dueAt, dueAt + 50]);
-
-    await store.cleanup();
   });
 });
diff --git a/src/cron/service.jobs.test.ts b/src/cron/service.jobs.test.ts
index b11ca9854b1..ed28d592757 100644
--- a/src/cron/service.jobs.test.ts
+++ b/src/cron/service.jobs.test.ts
@@ -30,6 +30,32 @@ describe("applyJobPatch", () => {
     expect(job.delivery).toBeUndefined();
   });
 
+  it("keeps webhook delivery when switching to main session", () => {
+    const now = Date.now();
+    const job: CronJob = {
+      id: "job-webhook",
+      name: "job-webhook",
+      enabled: true,
+      createdAtMs: now,
+      updatedAtMs: now,
+      schedule: { kind: "every", everyMs: 60_000 },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      payload: { kind: "agentTurn", message: "do it" },
+      delivery: { mode: "webhook", to: "https://example.invalid/cron" },
+      state: {},
+    };
+
+    const patch: CronJobPatch = {
+      sessionTarget: "main",
+      payload: { kind: "systemEvent", text: "ping" },
+    };
+
+    expect(() => applyJobPatch(job, patch)).not.toThrow();
+    expect(job.sessionTarget).toBe("main");
+    expect(job.delivery).toEqual({ mode: "webhook", to: "https://example.invalid/cron" });
+  });
+
   it("maps legacy payload delivery updates onto delivery", () => {
     const now = Date.now();
     const job: CronJob = {
@@ -100,4 +126,56 @@ describe("applyJobPatch", () => {
       bestEffort: undefined,
     });
   });
+
+  it("rejects webhook delivery without a valid http(s) target URL", () => {
+    const now = Date.now();
+    const job: CronJob = {
+      id: "job-webhook-invalid",
+      name: "job-webhook-invalid",
+      enabled: true,
+      createdAtMs: now,
+      updatedAtMs: now,
+      schedule: { kind: "every", everyMs: 60_000 },
+      sessionTarget: "main",
+      wakeMode: "now",
+      payload: { kind: "systemEvent", text: "ping" },
+      delivery: { mode: "webhook" },
+      state: {},
+    };
+
+    expect(() => applyJobPatch(job, { enabled: true })).toThrow(
+      "cron webhook delivery requires delivery.to to be a valid http(s) URL",
+    );
+    expect(() => applyJobPatch(job, { delivery: { mode: "webhook", to: "" } })).toThrow(
+      "cron webhook delivery requires delivery.to to be a valid http(s) URL",
+    );
+    expect(() =>
+      applyJobPatch(job, { delivery: { mode: "webhook", to: "ftp://example.invalid" } }),
+    ).toThrow("cron webhook delivery requires delivery.to to be a valid http(s) URL");
+    expect(() => applyJobPatch(job, { delivery: { mode: "webhook", to: "not-a-url" } })).toThrow(
+      "cron webhook delivery requires delivery.to to be a valid http(s) URL",
+    );
+  });
+
+  it("trims webhook delivery target URLs", () => {
+    const now = Date.now();
+    const job: CronJob = {
+      id: "job-webhook-trim",
+      name: "job-webhook-trim",
+      enabled: true,
+      createdAtMs: now,
+      updatedAtMs: now,
+      schedule: { kind: "every", everyMs: 60_000 },
+      sessionTarget: "main",
+      wakeMode: "now",
+      payload: { kind: "systemEvent", text: "ping" },
+      delivery: { mode: "webhook", to: "https://example.invalid/original" },
+      state: {},
+    };
+
+    expect(() =>
+      applyJobPatch(job, { delivery: { mode: "webhook", to: "  https://example.invalid/trim  " } }),
+    ).not.toThrow();
+    expect(job.delivery).toEqual({ mode: "webhook", to: "https://example.invalid/trim" });
+  });
 });
diff --git a/src/cron/service.read-ops-nonblocking.test.ts b/src/cron/service.read-ops-nonblocking.test.ts
index 048246cc5cb..3a649d7ce90 100644
--- a/src/cron/service.read-ops-nonblocking.test.ts
+++ b/src/cron/service.read-ops-nonblocking.test.ts
@@ -16,6 +16,21 @@ async function makeStorePath() {
   return {
     storePath: path.join(dir, "cron", "jobs.json"),
     cleanup: async () => {
+      // On macOS, teardown can race with trailing async fs writes and leave
+      // transient ENOTEMPTY errors. Retry briefly for stability.
+      for (let i = 0; i < 10; i += 1) {
+        try {
+          await fs.rm(dir, { recursive: true, force: true });
+          return;
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException).code;
+          if (code !== "ENOTEMPTY") {
+            throw err;
+          }
+          // eslint-disable-next-line no-await-in-loop
+          await new Promise<void>((resolve) => setTimeout(resolve, 10));
+        }
+      }
       await fs.rm(dir, { recursive: true, force: true });
     },
   };
@@ -23,24 +38,35 @@ async function makeStorePath() {
 
 describe("CronService read ops while job is running", () => {
   it("keeps list and status responsive during a long isolated run", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2025-12-13T00:00:00.000Z"));
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
+    let resolveFinished: (() => void) | undefined;
+    const finished = new Promise<void>((resolve) => {
+      resolveFinished = resolve;
+    });
 
     let resolveRun:
       | ((value: { status: "ok" | "error" | "skipped"; summary?: string; error?: string }) => void)
       | undefined;
 
-    const runIsolatedAgentJob = vi.fn(
-      async () =>
-        await new Promise<{
-          status: "ok" | "error" | "skipped";
-          summary?: string;
-          error?: string;
-        }>((resolve) => {
-          resolveRun = resolve;
-        }),
-    );
+    let resolveRunStarted: (() => void) | undefined;
+    const runStarted = new Promise<void>((resolve) => {
+      resolveRunStarted = resolve;
+    });
+
+    const runIsolatedAgentJob = vi.fn(async () => {
+      resolveRunStarted?.();
+      return await new Promise<{
+        status: "ok" | "error" | "skipped";
+        summary?: string;
+        error?: string;
+      }>((resolve) => {
+        resolveRun = resolve;
+      });
+    });
 
     const cron = new CronService({
       storePath: store.storePath,
@@ -49,70 +75,67 @@ describe("CronService read ops while job is running", () => {
       enqueueSystemEvent,
       requestHeartbeatNow,
       runIsolatedAgentJob,
+      onEvent: (evt) => {
+        if (evt.action === "finished" && evt.status === "ok") {
+          resolveFinished?.();
+        }
+      },
     });
 
-    const timeout = async <T>(promise: Promise<T>, ms: number): Promise<T> => {
-      let t: NodeJS.Timeout;
-      const timeoutPromise = new Promise<never>((_, reject) => {
-        t = setTimeout(() => reject(new Error("timeout")), ms);
-      });
-      return await Promise.race([promise.finally(() => clearTimeout(t!)), timeoutPromise]);
-    };
-
     try {
       await cron.start();
 
-      // Schedule the job in the past so the cron timer fires immediately.
+      // Schedule the job a second in the future; then jump time to trigger the tick.
       await cron.add({
         name: "slow isolated",
         enabled: true,
         deleteAfterRun: false,
-        schedule: { kind: "at", at: new Date(Date.now() - 1).toISOString() },
+        schedule: {
+          kind: "at",
+          at: new Date("2025-12-13T00:00:01.000Z").toISOString(),
+        },
         sessionTarget: "isolated",
         wakeMode: "next-heartbeat",
         payload: { kind: "agentTurn", message: "long task" },
         delivery: { mode: "none" },
       });
 
-      // Let the scheduler tick and start the job.
-      await timeout(
-        (async () => {
-          for (;;) {
-            if (runIsolatedAgentJob.mock.calls.length > 0) {
-              return;
-            }
-            await new Promise<void>((resolve) => setTimeout(resolve, 0));
-          }
-        })(),
-        2000,
-      );
+      vi.setSystemTime(new Date("2025-12-13T00:00:01.000Z"));
+      await vi.runOnlyPendingTimersAsync();
 
+      await runStarted;
       expect(runIsolatedAgentJob).toHaveBeenCalledTimes(1);
 
-      await expect(timeout(cron.list({ includeDisabled: true }), 1000)).resolves.toBeTypeOf(
-        "object",
-      );
-      await expect(timeout(cron.status(), 1000)).resolves.toBeTypeOf("object");
+      await expect(cron.list({ includeDisabled: true })).resolves.toBeTypeOf("object");
+      await expect(cron.status()).resolves.toBeTypeOf("object");
 
       const running = await cron.list({ includeDisabled: true });
       expect(running[0]?.state.runningAtMs).toBeTypeOf("number");
 
       resolveRun?.({ status: "ok", summary: "done" });
 
-      await timeout(
-        (async () => {
-          for (;;) {
-            const finished = await cron.list({ includeDisabled: true });
-            if (finished[0]?.state.lastStatus === "ok") {
-              return;
-            }
-            await new Promise<void>((resolve) => setTimeout(resolve, 0));
-          }
-        })(),
-        2000,
-      );
+      // Wait until the scheduler writes the result back to the store.
+      await finished;
+      // Ensure any trailing store writes have finished before cleanup.
+      await cron.status();
+
+      const completed = await cron.list({ includeDisabled: true });
+      expect(completed[0]?.state.lastStatus).toBe("ok");
+
+      // Ensure the scheduler loop has fully settled before deleting the store directory.
+      const internal = cron as unknown as { state?: { running?: boolean } };
+      for (let i = 0; i < 100; i += 1) {
+        if (!internal.state?.running) {
+          break;
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.resolve();
+      }
+      expect(internal.state?.running).toBe(false);
     } finally {
       cron.stop();
+      vi.clearAllTimers();
+      vi.useRealTimers();
       await store.cleanup();
     }
   });
diff --git a/src/cron/service.runs-one-shot-main-job-disables-it.test.ts b/src/cron/service.runs-one-shot-main-job-disables-it.test.ts
index f9aa49c8975..912ea9d1a00 100644
--- a/src/cron/service.runs-one-shot-main-job-disables-it.test.ts
+++ b/src/cron/service.runs-one-shot-main-job-disables-it.test.ts
@@ -1,19 +1,201 @@
-import fs from "node:fs/promises";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { HeartbeatRunResult } from "../infra/heartbeat-wake.js";
 import type { CronEvent } from "./service.js";
 import { CronService } from "./service.js";
-import {
-  createCronStoreHarness,
-  createNoopLogger,
-  installCronTestHooks,
-} from "./service.test-harness.js";
+import { createNoopLogger, installCronTestHooks } from "./service.test-harness.js";
 
 const noopLogger = createNoopLogger();
-const { makeStorePath } = createCronStoreHarness();
 installCronTestHooks({ logger: noopLogger });
 
+type FakeFsEntry =
+  | { kind: "file"; content: string; mtimeMs: number }
+  | { kind: "dir"; mtimeMs: number };
+
+const fsState = vi.hoisted(() => ({
+  entries: new Map<string, FakeFsEntry>(),
+  nowMs: 0,
+  fixtureCount: 0,
+}));
+
+const abs = (p: string) => path.resolve(p);
+const fixturesRoot = abs(path.join("__openclaw_vitest__", "cron", "runs-one-shot"));
+const isFixturePath = (p: string) => {
+  const resolved = abs(p);
+  const rootPrefix = `${fixturesRoot}${path.sep}`;
+  return resolved === fixturesRoot || resolved.startsWith(rootPrefix);
+};
+
+function bumpMtimeMs() {
+  fsState.nowMs += 1;
+  return fsState.nowMs;
+}
+
+function ensureDir(dirPath: string) {
+  let current = abs(dirPath);
+  while (true) {
+    if (!fsState.entries.has(current)) {
+      fsState.entries.set(current, { kind: "dir", mtimeMs: bumpMtimeMs() });
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+}
+
+function setFile(filePath: string, content: string) {
+  const resolved = abs(filePath);
+  ensureDir(path.dirname(resolved));
+  fsState.entries.set(resolved, { kind: "file", content, mtimeMs: bumpMtimeMs() });
+}
+
+async function makeStorePath() {
+  const dir = path.join(fixturesRoot, `case-${fsState.fixtureCount++}`);
+  ensureDir(dir);
+  const storePath = path.join(dir, "cron", "jobs.json");
+  ensureDir(path.dirname(storePath));
+  return { storePath, cleanup: async () => {} };
+}
+
+function writeStoreFile(storePath: string, payload: unknown) {
+  setFile(storePath, JSON.stringify(payload, null, 2));
+}
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+  const isFixtureInMock = (p: string) => {
+    const resolved = absInMock(p);
+    const rootPrefix = `${absInMock(fixturesRoot)}${pathMod.sep}`;
+    return resolved === absInMock(fixturesRoot) || resolved.startsWith(rootPrefix);
+  };
+
+  const mkErr = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+  const promises = {
+    ...actual.promises,
+    mkdir: async (p: string) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.mkdir as any)(p, { recursive: true });
+      }
+      ensureDir(p);
+    },
+    readFile: async (p: string) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.readFile as any)(p, "utf-8");
+      }
+      const entry = fsState.entries.get(absInMock(p));
+      if (!entry || entry.kind !== "file") {
+        throw mkErr("ENOENT", `ENOENT: no such file or directory, open '${p}'`);
+      }
+      return entry.content;
+    },
+    writeFile: async (p: string, data: string | Uint8Array) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.writeFile as any)(p, data, "utf-8");
+      }
+      const content = typeof data === "string" ? data : Buffer.from(data).toString("utf-8");
+      setFile(p, content);
+    },
+    rename: async (from: string, to: string) => {
+      if (!isFixtureInMock(from) || !isFixtureInMock(to)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.rename as any)(from, to);
+      }
+      const fromAbs = absInMock(from);
+      const toAbs = absInMock(to);
+      const entry = fsState.entries.get(fromAbs);
+      if (!entry || entry.kind !== "file") {
+        throw mkErr("ENOENT", `ENOENT: no such file or directory, rename '${from}' -> '${to}'`);
+      }
+      ensureDir(pathMod.dirname(toAbs));
+      fsState.entries.delete(fromAbs);
+      fsState.entries.set(toAbs, { ...entry, mtimeMs: bumpMtimeMs() });
+    },
+    copyFile: async (from: string, to: string) => {
+      if (!isFixtureInMock(from) || !isFixtureInMock(to)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.copyFile as any)(from, to);
+      }
+      const entry = fsState.entries.get(absInMock(from));
+      if (!entry || entry.kind !== "file") {
+        throw mkErr("ENOENT", `ENOENT: no such file or directory, copyfile '${from}' -> '${to}'`);
+      }
+      setFile(to, entry.content);
+    },
+    stat: async (p: string) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.stat as any)(p);
+      }
+      const entry = fsState.entries.get(absInMock(p));
+      if (!entry) {
+        throw mkErr("ENOENT", `ENOENT: no such file or directory, stat '${p}'`);
+      }
+      return {
+        mtimeMs: entry.mtimeMs,
+        isDirectory: () => entry.kind === "dir",
+        isFile: () => entry.kind === "file",
+      };
+    },
+    access: async (p: string) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.access as any)(p);
+      }
+      const entry = fsState.entries.get(absInMock(p));
+      if (!entry) {
+        throw mkErr("ENOENT", `ENOENT: no such file or directory, access '${p}'`);
+      }
+    },
+    unlink: async (p: string) => {
+      if (!isFixtureInMock(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.promises.unlink as any)(p);
+      }
+      fsState.entries.delete(absInMock(p));
+    },
+  } satisfies typeof actual.promises;
+
+  const wrapped = { ...actual, promises };
+  return { ...wrapped, default: wrapped };
+});
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  const wrapped = {
+    ...actual,
+    mkdir: async (p: string, _opts?: unknown) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.mkdir as any)(p, { recursive: true });
+      }
+      ensureDir(p);
+    },
+    writeFile: async (p: string, data: string, _enc?: unknown) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await (actual.writeFile as any)(p, data, "utf-8");
+      }
+      setFile(p, data);
+    },
+  };
+  return { ...wrapped, default: wrapped };
+});
+
+beforeEach(() => {
+  fsState.entries.clear();
+  fsState.nowMs = 0;
+  fsState.fixtureCount = 0;
+  ensureDir(fixturesRoot);
+});
+
 function createDeferred<T>() {
   let resolve!: (value: T) => void;
   let reject!: (reason?: unknown) => void;
@@ -57,35 +239,8 @@ function createCronEventHarness() {
 }
 
 describe("CronService", () => {
-  async function loadLegacyJobFromStore(rawJob: Record<string, unknown>) {
-    const store = await makeStorePath();
-    const enqueueSystemEvent = vi.fn();
-    const requestHeartbeatNow = vi.fn();
-
-    await fs.mkdir(path.dirname(store.storePath), { recursive: true });
-    await fs.writeFile(
-      store.storePath,
-      JSON.stringify({ version: 1, jobs: [rawJob] }, null, 2),
-      "utf-8",
-    );
-
-    const cron = new CronService({
-      storePath: store.storePath,
-      cronEnabled: true,
-      log: noopLogger,
-      enqueueSystemEvent,
-      requestHeartbeatNow,
-      runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" })),
-    });
-
-    await cron.start();
-    const jobs = await cron.list({ includeDisabled: true });
-    const job = jobs.find((j) => j.id === rawJob.id);
-
-    return { cron, store, enqueueSystemEvent, requestHeartbeatNow, job };
-  }
-
   it("runs a one-shot main job and disables it after success when requested", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -134,6 +289,7 @@ describe("CronService", () => {
   });
 
   it("runs a one-shot job and deletes it after success by default", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -177,6 +333,7 @@ describe("CronService", () => {
   });
 
   it("wakeMode now waits for heartbeat completion when available", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -244,6 +401,7 @@ describe("CronService", () => {
   });
 
   it("passes agentId to runHeartbeatOnce for main-session wakeMode now jobs", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -293,6 +451,7 @@ describe("CronService", () => {
   });
 
   it("wakeMode now falls back to queued heartbeat when main lane stays busy", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -343,6 +502,7 @@ describe("CronService", () => {
   });
 
   it("runs an isolated job and posts summary to main", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -391,6 +551,7 @@ describe("CronService", () => {
   });
 
   it("does not post isolated summary to main when run already delivered output", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -437,6 +598,11 @@ describe("CronService", () => {
   });
 
   it("migrates legacy payload.provider to payload.channel on load", async () => {
+    ensureDir(fixturesRoot);
+    const store = await makeStorePath();
+    const enqueueSystemEvent = vi.fn();
+    const requestHeartbeatNow = vi.fn();
+
     const rawJob = {
       id: "legacy-1",
       name: "legacy",
@@ -456,7 +622,20 @@ describe("CronService", () => {
       state: {},
     };
 
-    const { cron, store, job } = await loadLegacyJobFromStore(rawJob);
+    writeStoreFile(store.storePath, { version: 1, jobs: [rawJob] });
+
+    const cron = new CronService({
+      storePath: store.storePath,
+      cronEnabled: true,
+      log: noopLogger,
+      enqueueSystemEvent,
+      requestHeartbeatNow,
+      runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" })),
+    });
+
+    await cron.start();
+    const jobs = await cron.list({ includeDisabled: true });
+    const job = jobs.find((j) => j.id === rawJob.id);
     // Legacy delivery fields are migrated to the top-level delivery object
     const delivery = job?.delivery as unknown as Record<string, unknown>;
     expect(delivery?.channel).toBe("telegram");
@@ -469,6 +648,11 @@ describe("CronService", () => {
   });
 
   it("canonicalizes payload.channel casing on load", async () => {
+    ensureDir(fixturesRoot);
+    const store = await makeStorePath();
+    const enqueueSystemEvent = vi.fn();
+    const requestHeartbeatNow = vi.fn();
+
     const rawJob = {
       id: "legacy-2",
       name: "legacy",
@@ -488,7 +672,20 @@ describe("CronService", () => {
       state: {},
     };
 
-    const { cron, store, job } = await loadLegacyJobFromStore(rawJob);
+    writeStoreFile(store.storePath, { version: 1, jobs: [rawJob] });
+
+    const cron = new CronService({
+      storePath: store.storePath,
+      cronEnabled: true,
+      log: noopLogger,
+      enqueueSystemEvent,
+      requestHeartbeatNow,
+      runIsolatedAgentJob: vi.fn(async () => ({ status: "ok" })),
+    });
+
+    await cron.start();
+    const jobs = await cron.list({ includeDisabled: true });
+    const job = jobs.find((j) => j.id === rawJob.id);
     // Legacy delivery fields are migrated to the top-level delivery object
     const delivery = job?.delivery as unknown as Record<string, unknown>;
     expect(delivery?.channel).toBe("telegram");
@@ -498,6 +695,7 @@ describe("CronService", () => {
   });
 
   it("posts last output to main even when isolated job errors", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
@@ -546,6 +744,7 @@ describe("CronService", () => {
   });
 
   it("rejects unsupported session/payload combinations", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
 
     const cron = new CronService({
@@ -586,32 +785,29 @@ describe("CronService", () => {
   });
 
   it("skips invalid main jobs with agentTurn payloads from disk", async () => {
+    ensureDir(fixturesRoot);
     const store = await makeStorePath();
     const enqueueSystemEvent = vi.fn();
     const requestHeartbeatNow = vi.fn();
     const events = createCronEventHarness();
 
     const atMs = Date.parse("2025-12-13T00:00:01.000Z");
-    await fs.mkdir(path.dirname(store.storePath), { recursive: true });
-    await fs.writeFile(
-      store.storePath,
-      JSON.stringify({
-        version: 1,
-        jobs: [
-          {
-            id: "job-1",
-            enabled: true,
-            createdAtMs: Date.parse("2025-12-13T00:00:00.000Z"),
-            updatedAtMs: Date.parse("2025-12-13T00:00:00.000Z"),
-            schedule: { kind: "at", at: new Date(atMs).toISOString() },
-            sessionTarget: "main",
-            wakeMode: "now",
-            payload: { kind: "agentTurn", message: "bad" },
-            state: {},
-          },
-        ],
-      }),
-    );
+    writeStoreFile(store.storePath, {
+      version: 1,
+      jobs: [
+        {
+          id: "job-1",
+          enabled: true,
+          createdAtMs: Date.parse("2025-12-13T00:00:00.000Z"),
+          updatedAtMs: Date.parse("2025-12-13T00:00:00.000Z"),
+          schedule: { kind: "at", at: new Date(atMs).toISOString() },
+          sessionTarget: "main",
+          wakeMode: "now",
+          payload: { kind: "agentTurn", message: "bad" },
+          state: {},
+        },
+      ],
+    });
 
     const cron = new CronService({
       storePath: store.storePath,
diff --git a/src/cron/service.ts b/src/cron/service.ts
index 8f82a2e6947..8891ee9915b 100644
--- a/src/cron/service.ts
+++ b/src/cron/service.ts
@@ -1,4 +1,4 @@
-import type { CronJobCreate, CronJobPatch } from "./types.js";
+import type { CronJob, CronJobCreate, CronJobPatch } from "./types.js";
 import * as ops from "./service/ops.js";
 import { type CronServiceDeps, createCronServiceState } from "./service/state.js";
 
@@ -42,6 +42,10 @@ export class CronService {
     return await ops.run(this.state, id, mode);
   }
 
+  getJob(id: string): CronJob | undefined {
+    return this.state.store?.jobs.find((job) => job.id === id);
+  }
+
   wake(opts: { mode: "now" | "next-heartbeat"; text: string }) {
     return ops.wakeNow(this.state, opts);
   }
diff --git a/src/cron/service/jobs.ts b/src/cron/service/jobs.ts
index 71a11af7bca..4185987f5a7 100644
--- a/src/cron/service/jobs.ts
+++ b/src/cron/service/jobs.ts
@@ -11,6 +11,7 @@ import type {
 import type { CronServiceState } from "./state.js";
 import { parseAbsoluteTimeMs } from "../parse.js";
 import { computeNextRunAtMs } from "../schedule.js";
+import { normalizeHttpWebhookUrl } from "../webhook-url.js";
 import {
   normalizeOptionalAgentId,
   normalizeOptionalText,
@@ -41,8 +42,19 @@ export function assertSupportedJobSpec(job: Pick<CronJob, "sessionTarget" | "pay
 }
 
 function assertDeliverySupport(job: Pick<CronJob, "sessionTarget" | "delivery">) {
-  if (job.delivery && job.sessionTarget !== "isolated") {
-    throw new Error('cron delivery config is only supported for sessionTarget="isolated"');
+  if (!job.delivery) {
+    return;
+  }
+  if (job.delivery.mode === "webhook") {
+    const target = normalizeHttpWebhookUrl(job.delivery.to);
+    if (!target) {
+      throw new Error("cron webhook delivery requires delivery.to to be a valid http(s) URL");
+    }
+    job.delivery.to = target;
+    return;
+  }
+  if (job.sessionTarget !== "isolated") {
+    throw new Error('cron channel delivery config is only supported for sessionTarget="isolated"');
   }
 }
 
@@ -127,7 +139,10 @@ function normalizeJobTickState(params: { state: CronServiceState; job: CronJob;
   return { changed, skip: false };
 }
 
-export function recomputeNextRuns(state: CronServiceState): boolean {
+function walkSchedulableJobs(
+  state: CronServiceState,
+  fn: (params: { job: CronJob; nowMs: number }) => boolean,
+): boolean {
   if (!state.store) {
     return false;
   }
@@ -141,6 +156,16 @@ export function recomputeNextRuns(state: CronServiceState): boolean {
     if (tick.skip) {
       continue;
     }
+    if (fn({ job, nowMs: now })) {
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export function recomputeNextRuns(state: CronServiceState): boolean {
+  return walkSchedulableJobs(state, ({ job, nowMs: now }) => {
+    let changed = false;
     // Only recompute if nextRunAtMs is missing or already past-due.
     // Preserving a still-future nextRunAtMs avoids accidentally advancing
     // a job that hasn't fired yet (e.g. during restart recovery).
@@ -179,8 +204,8 @@ export function recomputeNextRuns(state: CronServiceState): boolean {
         }
       }
     }
-  }
-  return changed;
+    return changed;
+  });
 }
 
 /**
@@ -191,19 +216,8 @@ export function recomputeNextRuns(state: CronServiceState): boolean {
  * (see #13992).
  */
 export function recomputeNextRunsForMaintenance(state: CronServiceState): boolean {
-  if (!state.store) {
-    return false;
-  }
-  let changed = false;
-  const now = state.deps.nowMs();
-  for (const job of state.store.jobs) {
-    const tick = normalizeJobTickState({ state, job, nowMs: now });
-    if (tick.changed) {
-      changed = true;
-    }
-    if (tick.skip) {
-      continue;
-    }
+  return walkSchedulableJobs(state, ({ job, nowMs: now }) => {
+    let changed = false;
     // Only compute missing nextRunAtMs, do NOT recompute existing ones.
     // If a job was past-due but not found by findDueJobs, recomputing would
     // cause it to be silently skipped.
@@ -214,8 +228,8 @@ export function recomputeNextRunsForMaintenance(state: CronServiceState): boolea
         changed = true;
       }
     }
-  }
-  return changed;
+    return changed;
+  });
 }
 
 export function nextWakeAtMs(state: CronServiceState) {
@@ -313,7 +327,7 @@ export function applyJobPatch(job: CronJob, patch: CronJobPatch) {
   if (patch.delivery) {
     job.delivery = mergeCronDelivery(job.delivery, patch.delivery);
   }
-  if (job.sessionTarget === "main" && job.delivery) {
+  if (job.sessionTarget === "main" && job.delivery?.mode !== "webhook") {
     job.delivery = undefined;
   }
   if (patch.state) {
diff --git a/src/cron/service/ops.ts b/src/cron/service/ops.ts
index 1df1dfc95e3..2545a84d210 100644
--- a/src/cron/service/ops.ts
+++ b/src/cron/service/ops.ts
@@ -14,6 +14,19 @@ import { locked } from "./locked.js";
 import { ensureLoaded, persist, warnIfDisabled } from "./store.js";
 import { armTimer, emit, executeJob, runMissedJobs, stopTimer, wake } from "./timer.js";
 
+async function ensureLoadedForRead(state: CronServiceState) {
+  await ensureLoaded(state, { skipRecompute: true });
+  if (!state.store) {
+    return;
+  }
+  // Use the maintenance-only version so that read-only operations never
+  // advance a past-due nextRunAtMs without executing the job (#16156).
+  const changed = recomputeNextRunsForMaintenance(state);
+  if (changed) {
+    await persist(state);
+  }
+}
+
 export async function start(state: CronServiceState) {
   await locked(state, async () => {
     if (!state.deps.cronEnabled) {
@@ -54,15 +67,7 @@ export function stop(state: CronServiceState) {
 
 export async function status(state: CronServiceState) {
   return await locked(state, async () => {
-    await ensureLoaded(state, { skipRecompute: true });
-    if (state.store) {
-      // Use the maintenance-only version so that read-only operations never
-      // advance a past-due nextRunAtMs without executing the job (#16156).
-      const changed = recomputeNextRunsForMaintenance(state);
-      if (changed) {
-        await persist(state);
-      }
-    }
+    await ensureLoadedForRead(state);
     return {
       enabled: state.deps.cronEnabled,
       storePath: state.deps.storePath,
@@ -74,15 +79,7 @@ export async function status(state: CronServiceState) {
 
 export async function list(state: CronServiceState, opts?: { includeDisabled?: boolean }) {
   return await locked(state, async () => {
-    await ensureLoaded(state, { skipRecompute: true });
-    if (state.store) {
-      // Use the maintenance-only version so that read-only operations never
-      // advance a past-due nextRunAtMs without executing the job (#16156).
-      const changed = recomputeNextRunsForMaintenance(state);
-      if (changed) {
-        await persist(state);
-      }
-    }
+    await ensureLoadedForRead(state);
     const includeDisabled = opts?.includeDisabled === true;
     const jobs = (state.store?.jobs ?? []).filter((j) => includeDisabled || j.enabled);
     return jobs.toSorted((a, b) => (a.state.nextRunAtMs ?? 0) - (b.state.nextRunAtMs ?? 0));
diff --git a/src/cron/service/store.ts b/src/cron/service/store.ts
index 3da848f3e38..9a171f9e078 100644
--- a/src/cron/service/store.ts
+++ b/src/cron/service/store.ts
@@ -1,44 +1,17 @@
 import fs from "node:fs";
 import type { CronJob } from "../types.js";
 import type { CronServiceState } from "./state.js";
+import {
+  buildDeliveryFromLegacyPayload,
+  hasLegacyDeliveryHints,
+  stripLegacyDeliveryFields,
+} from "../legacy-delivery.js";
 import { parseAbsoluteTimeMs } from "../parse.js";
 import { migrateLegacyCronPayload } from "../payload-migration.js";
 import { loadCronStore, saveCronStore } from "../store.js";
 import { recomputeNextRuns } from "./jobs.js";
 import { inferLegacyName, normalizeOptionalText } from "./normalize.js";
 
-function hasLegacyDeliveryHints(payload: Record<string, unknown>) {
-  if (typeof payload.deliver === "boolean") {
-    return true;
-  }
-  if (typeof payload.bestEffortDeliver === "boolean") {
-    return true;
-  }
-  if (typeof payload.to === "string" && payload.to.trim()) {
-    return true;
-  }
-  return false;
-}
-
-function buildDeliveryFromLegacyPayload(payload: Record<string, unknown>) {
-  const deliver = payload.deliver;
-  const mode = deliver === false ? "none" : "announce";
-  const channelRaw =
-    typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
-  const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
-  const next: Record<string, unknown> = { mode };
-  if (channelRaw) {
-    next.channel = channelRaw;
-  }
-  if (toRaw) {
-    next.to = toRaw;
-  }
-  if (typeof payload.bestEffortDeliver === "boolean") {
-    next.bestEffort = payload.bestEffortDeliver;
-  }
-  return next;
-}
-
 function buildDeliveryPatchFromLegacyPayload(payload: Record<string, unknown>) {
   const deliver = payload.deliver;
   const channelRaw =
@@ -102,21 +75,6 @@ function mergeLegacyDeliveryInto(
   return { delivery: next, mutated };
 }
 
-function stripLegacyDeliveryFields(payload: Record<string, unknown>) {
-  if ("deliver" in payload) {
-    delete payload.deliver;
-  }
-  if ("channel" in payload) {
-    delete payload.channel;
-  }
-  if ("to" in payload) {
-    delete payload.to;
-  }
-  if ("bestEffortDeliver" in payload) {
-    delete payload.bestEffortDeliver;
-  }
-}
-
 function normalizePayloadKind(payload: Record<string, unknown>) {
   const raw = typeof payload.kind === "string" ? payload.kind.trim().toLowerCase() : "";
   if (raw === "agentturn") {
diff --git a/src/cron/service/timer.ts b/src/cron/service/timer.ts
index 3c18a5e03fd..674f191a875 100644
--- a/src/cron/service/timer.ts
+++ b/src/cron/service/timer.ts
@@ -144,12 +144,13 @@ export function armTimer(state: CronServiceState) {
   // Wake at least once a minute to avoid schedule drift and recover quickly
   // when the process was paused or wall-clock time jumps.
   const clampedDelay = Math.min(delay, MAX_TIMER_DELAY_MS);
-  state.timer = setTimeout(async () => {
-    try {
-      await onTimer(state);
-    } catch (err) {
+  // Intentionally avoid an `async` timer callback:
+  // Vitest's fake-timer helpers can await async callbacks, which would block
+  // tests that simulate long-running jobs. Runtime behavior is unchanged.
+  state.timer = setTimeout(() => {
+    void onTimer(state).catch((err) => {
       state.deps.log.error({ err: String(err) }, "cron: timer tick failed");
-    }
+    });
   }, clampedDelay);
   state.deps.log.debug(
     { nextAt, delayMs: clampedDelay, clamped: delay > MAX_TIMER_DELAY_MS },
@@ -172,12 +173,10 @@ export async function onTimer(state: CronServiceState) {
     if (state.timer) {
       clearTimeout(state.timer);
     }
-    state.timer = setTimeout(async () => {
-      try {
-        await onTimer(state);
-      } catch (err) {
+    state.timer = setTimeout(() => {
+      void onTimer(state).catch((err) => {
         state.deps.log.error({ err: String(err) }, "cron: timer tick failed");
-      }
+      });
     }, MAX_TIMER_DELAY_MS);
     return;
   }
@@ -276,18 +275,7 @@ export async function onTimer(state: CronServiceState) {
             endedAt: result.endedAt,
           });
 
-          emit(state, {
-            jobId: job.id,
-            action: "finished",
-            status: result.status,
-            error: result.error,
-            summary: result.summary,
-            sessionId: result.sessionId,
-            sessionKey: result.sessionKey,
-            runAtMs: result.startedAt,
-            durationMs: job.state.lastDurationMs,
-            nextRunAtMs: job.state.nextRunAtMs,
-          });
+          emitJobFinished(state, job, result, result.startedAt);
 
           if (shouldDelete && state.store) {
             state.store.jobs = state.store.jobs.filter((j) => j.id !== job.id);
@@ -342,19 +330,54 @@ function findDueJobs(state: CronServiceState): CronJob[] {
     return [];
   }
   const now = state.deps.nowMs();
-  return state.store.jobs.filter((j) => {
-    if (!j.state) {
-      j.state = {};
-    }
-    if (!j.enabled) {
-      return false;
-    }
-    if (typeof j.state.runningAtMs === "number") {
-      return false;
-    }
-    const next = j.state.nextRunAtMs;
-    return typeof next === "number" && now >= next;
-  });
+  return collectRunnableJobs(state, now);
+}
+
+function isRunnableJob(params: {
+  job: CronJob;
+  nowMs: number;
+  skipJobIds?: ReadonlySet<string>;
+  skipAtIfAlreadyRan?: boolean;
+}): boolean {
+  const { job, nowMs } = params;
+  if (!job.state) {
+    job.state = {};
+  }
+  if (!job.enabled) {
+    return false;
+  }
+  if (params.skipJobIds?.has(job.id)) {
+    return false;
+  }
+  if (typeof job.state.runningAtMs === "number") {
+    return false;
+  }
+  if (params.skipAtIfAlreadyRan && job.schedule.kind === "at" && job.state.lastStatus) {
+    // Any terminal status (ok, error, skipped) means the job already ran at least once.
+    // Don't re-fire it on restart — applyJobResult disables one-shot jobs, but guard
+    // here defensively (#13845).
+    return false;
+  }
+  const next = job.state.nextRunAtMs;
+  return typeof next === "number" && nowMs >= next;
+}
+
+function collectRunnableJobs(
+  state: CronServiceState,
+  nowMs: number,
+  opts?: { skipJobIds?: ReadonlySet<string>; skipAtIfAlreadyRan?: boolean },
+): CronJob[] {
+  if (!state.store) {
+    return [];
+  }
+  return state.store.jobs.filter((job) =>
+    isRunnableJob({
+      job,
+      nowMs,
+      skipJobIds: opts?.skipJobIds,
+      skipAtIfAlreadyRan: opts?.skipAtIfAlreadyRan,
+    }),
+  );
 }
 
 export async function runMissedJobs(
@@ -366,28 +389,7 @@ export async function runMissedJobs(
   }
   const now = state.deps.nowMs();
   const skipJobIds = opts?.skipJobIds;
-  const missed = state.store.jobs.filter((j) => {
-    if (!j.state) {
-      j.state = {};
-    }
-    if (!j.enabled) {
-      return false;
-    }
-    if (skipJobIds?.has(j.id)) {
-      return false;
-    }
-    if (typeof j.state.runningAtMs === "number") {
-      return false;
-    }
-    const next = j.state.nextRunAtMs;
-    if (j.schedule.kind === "at" && j.state.lastStatus) {
-      // Any terminal status (ok, error, skipped) means the job already
-      // ran at least once.  Don't re-fire it on restart — applyJobResult
-      // disables one-shot jobs, but guard here defensively (#13845).
-      return false;
-    }
-    return typeof next === "number" && now >= next;
-  });
+  const missed = collectRunnableJobs(state, now, { skipJobIds, skipAtIfAlreadyRan: true });
 
   if (missed.length > 0) {
     state.deps.log.info(
@@ -405,19 +407,7 @@ export async function runDueJobs(state: CronServiceState) {
     return;
   }
   const now = state.deps.nowMs();
-  const due = state.store.jobs.filter((j) => {
-    if (!j.state) {
-      j.state = {};
-    }
-    if (!j.enabled) {
-      return false;
-    }
-    if (typeof j.state.runningAtMs === "number") {
-      return false;
-    }
-    const next = j.state.nextRunAtMs;
-    return typeof next === "number" && now >= next;
-  });
+  const due = collectRunnableJobs(state, now);
   for (const job of due) {
     await executeJob(state, job, now, { forced: false });
   }
@@ -563,18 +553,7 @@ export async function executeJob(
     endedAt,
   });
 
-  emit(state, {
-    jobId: job.id,
-    action: "finished",
-    status: coreResult.status,
-    error: coreResult.error,
-    summary: coreResult.summary,
-    sessionId: coreResult.sessionId,
-    sessionKey: coreResult.sessionKey,
-    runAtMs: startedAt,
-    durationMs: job.state.lastDurationMs,
-    nextRunAtMs: job.state.nextRunAtMs,
-  });
+  emitJobFinished(state, job, coreResult, startedAt);
 
   if (shouldDelete && state.store) {
     state.store.jobs = state.store.jobs.filter((j) => j.id !== job.id);
@@ -582,6 +561,32 @@ export async function executeJob(
   }
 }
 
+function emitJobFinished(
+  state: CronServiceState,
+  job: CronJob,
+  result: {
+    status: "ok" | "error" | "skipped";
+    error?: string;
+    summary?: string;
+    sessionId?: string;
+    sessionKey?: string;
+  },
+  runAtMs: number,
+) {
+  emit(state, {
+    jobId: job.id,
+    action: "finished",
+    status: result.status,
+    error: result.error,
+    summary: result.summary,
+    sessionId: result.sessionId,
+    sessionKey: result.sessionKey,
+    runAtMs,
+    durationMs: job.state.lastDurationMs,
+    nextRunAtMs: job.state.nextRunAtMs,
+  });
+}
+
 export function wake(
   state: CronServiceState,
   opts: { mode: "now" | "next-heartbeat"; text: string },
diff --git a/src/cron/types.ts b/src/cron/types.ts
index c3168346fb4..6c7e7bec02f 100644
--- a/src/cron/types.ts
+++ b/src/cron/types.ts
@@ -10,7 +10,7 @@ export type CronWakeMode = "next-heartbeat" | "now";
 
 export type CronMessageChannel = ChannelId | "last";
 
-export type CronDeliveryMode = "none" | "announce";
+export type CronDeliveryMode = "none" | "announce" | "webhook";
 
 export type CronDelivery = {
   mode: CronDeliveryMode;
diff --git a/src/cron/webhook-url.ts b/src/cron/webhook-url.ts
new file mode 100644
index 00000000000..7cd6c154173
--- /dev/null
+++ b/src/cron/webhook-url.ts
@@ -0,0 +1,22 @@
+function isAllowedWebhookProtocol(protocol: string) {
+  return protocol === "http:" || protocol === "https:";
+}
+
+export function normalizeHttpWebhookUrl(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    if (!isAllowedWebhookProtocol(parsed.protocol)) {
+      return null;
+    }
+    return trimmed;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/daemon/arg-split.test.ts b/src/daemon/arg-split.test.ts
deleted file mode 100644
index f9b8c89448e..00000000000
--- a/src/daemon/arg-split.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { splitArgsPreservingQuotes } from "./arg-split.js";
-
-describe("splitArgsPreservingQuotes", () => {
-  it("splits on whitespace outside quotes", () => {
-    expect(splitArgsPreservingQuotes('/usr/bin/openclaw gateway start --name "My Bot"')).toEqual([
-      "/usr/bin/openclaw",
-      "gateway",
-      "start",
-      "--name",
-      "My Bot",
-    ]);
-  });
-
-  it("supports systemd-style backslash escaping", () => {
-    expect(
-      splitArgsPreservingQuotes('openclaw --name "My \\"Bot\\"" --foo bar', {
-        escapeMode: "backslash",
-      }),
-    ).toEqual(["openclaw", "--name", 'My "Bot"', "--foo", "bar"]);
-  });
-
-  it("supports schtasks-style escaped quotes while preserving other backslashes", () => {
-    expect(
-      splitArgsPreservingQuotes('openclaw --path "C:\\\\Program Files\\\\OpenClaw"', {
-        escapeMode: "backslash-quote-only",
-      }),
-    ).toEqual(["openclaw", "--path", "C:\\\\Program Files\\\\OpenClaw"]);
-
-    expect(
-      splitArgsPreservingQuotes('openclaw --label "My \\"Quoted\\" Name"', {
-        escapeMode: "backslash-quote-only",
-      }),
-    ).toEqual(["openclaw", "--label", 'My "Quoted" Name']);
-  });
-});
diff --git a/src/daemon/constants.test.ts b/src/daemon/constants.test.ts
index c215ae1a88d..469832e41b0 100644
--- a/src/daemon/constants.test.ts
+++ b/src/daemon/constants.test.ts
@@ -4,12 +4,29 @@ import {
   GATEWAY_LAUNCH_AGENT_LABEL,
   GATEWAY_SYSTEMD_SERVICE_NAME,
   GATEWAY_WINDOWS_TASK_NAME,
+  normalizeGatewayProfile,
   resolveGatewayLaunchAgentLabel,
   resolveGatewayProfileSuffix,
+  resolveGatewayServiceDescription,
   resolveGatewaySystemdServiceName,
   resolveGatewayWindowsTaskName,
 } from "./constants.js";
 
+describe("normalizeGatewayProfile", () => {
+  it("returns null for empty/default profiles", () => {
+    expect(normalizeGatewayProfile()).toBeNull();
+    expect(normalizeGatewayProfile("")).toBeNull();
+    expect(normalizeGatewayProfile("   ")).toBeNull();
+    expect(normalizeGatewayProfile("default")).toBeNull();
+    expect(normalizeGatewayProfile(" Default ")).toBeNull();
+  });
+
+  it("returns trimmed custom profiles", () => {
+    expect(normalizeGatewayProfile("dev")).toBe("dev");
+    expect(normalizeGatewayProfile("  staging  ")).toBe("staging");
+  });
+});
+
 describe("resolveGatewayLaunchAgentLabel", () => {
   it("returns default label when no profile is set", () => {
     const result = resolveGatewayLaunchAgentLabel();
@@ -17,45 +34,10 @@ describe("resolveGatewayLaunchAgentLabel", () => {
     expect(result).toBe("ai.openclaw.gateway");
   });
 
-  it("returns default label when profile is undefined", () => {
-    const result = resolveGatewayLaunchAgentLabel(undefined);
-    expect(result).toBe(GATEWAY_LAUNCH_AGENT_LABEL);
-  });
-
-  it("returns default label when profile is 'default'", () => {
-    const result = resolveGatewayLaunchAgentLabel("default");
-    expect(result).toBe(GATEWAY_LAUNCH_AGENT_LABEL);
-  });
-
-  it("returns default label when profile is 'Default' (case-insensitive)", () => {
-    const result = resolveGatewayLaunchAgentLabel("Default");
-    expect(result).toBe(GATEWAY_LAUNCH_AGENT_LABEL);
-  });
-
   it("returns profile-specific label when profile is set", () => {
     const result = resolveGatewayLaunchAgentLabel("dev");
     expect(result).toBe("ai.openclaw.dev");
   });
-
-  it("returns profile-specific label for custom profile", () => {
-    const result = resolveGatewayLaunchAgentLabel("work");
-    expect(result).toBe("ai.openclaw.work");
-  });
-
-  it("trims whitespace from profile", () => {
-    const result = resolveGatewayLaunchAgentLabel("  staging  ");
-    expect(result).toBe("ai.openclaw.staging");
-  });
-
-  it("returns default label for empty string profile", () => {
-    const result = resolveGatewayLaunchAgentLabel("");
-    expect(result).toBe(GATEWAY_LAUNCH_AGENT_LABEL);
-  });
-
-  it("returns default label for whitespace-only profile", () => {
-    const result = resolveGatewayLaunchAgentLabel("   ");
-    expect(result).toBe(GATEWAY_LAUNCH_AGENT_LABEL);
-  });
 });
 
 describe("resolveGatewaySystemdServiceName", () => {
@@ -65,45 +47,10 @@ describe("resolveGatewaySystemdServiceName", () => {
     expect(result).toBe("openclaw-gateway");
   });
 
-  it("returns default service name when profile is undefined", () => {
-    const result = resolveGatewaySystemdServiceName(undefined);
-    expect(result).toBe(GATEWAY_SYSTEMD_SERVICE_NAME);
-  });
-
-  it("returns default service name when profile is 'default'", () => {
-    const result = resolveGatewaySystemdServiceName("default");
-    expect(result).toBe(GATEWAY_SYSTEMD_SERVICE_NAME);
-  });
-
-  it("returns default service name when profile is 'DEFAULT' (case-insensitive)", () => {
-    const result = resolveGatewaySystemdServiceName("DEFAULT");
-    expect(result).toBe(GATEWAY_SYSTEMD_SERVICE_NAME);
-  });
-
   it("returns profile-specific service name when profile is set", () => {
     const result = resolveGatewaySystemdServiceName("dev");
     expect(result).toBe("openclaw-gateway-dev");
   });
-
-  it("returns profile-specific service name for custom profile", () => {
-    const result = resolveGatewaySystemdServiceName("production");
-    expect(result).toBe("openclaw-gateway-production");
-  });
-
-  it("trims whitespace from profile", () => {
-    const result = resolveGatewaySystemdServiceName("  test  ");
-    expect(result).toBe("openclaw-gateway-test");
-  });
-
-  it("returns default service name for empty string profile", () => {
-    const result = resolveGatewaySystemdServiceName("");
-    expect(result).toBe(GATEWAY_SYSTEMD_SERVICE_NAME);
-  });
-
-  it("returns default service name for whitespace-only profile", () => {
-    const result = resolveGatewaySystemdServiceName("   ");
-    expect(result).toBe(GATEWAY_SYSTEMD_SERVICE_NAME);
-  });
 });
 
 describe("resolveGatewayWindowsTaskName", () => {
@@ -113,45 +60,10 @@ describe("resolveGatewayWindowsTaskName", () => {
     expect(result).toBe("OpenClaw Gateway");
   });
 
-  it("returns default task name when profile is undefined", () => {
-    const result = resolveGatewayWindowsTaskName(undefined);
-    expect(result).toBe(GATEWAY_WINDOWS_TASK_NAME);
-  });
-
-  it("returns default task name when profile is 'default'", () => {
-    const result = resolveGatewayWindowsTaskName("default");
-    expect(result).toBe(GATEWAY_WINDOWS_TASK_NAME);
-  });
-
-  it("returns default task name when profile is 'DeFaUlT' (case-insensitive)", () => {
-    const result = resolveGatewayWindowsTaskName("DeFaUlT");
-    expect(result).toBe(GATEWAY_WINDOWS_TASK_NAME);
-  });
-
   it("returns profile-specific task name when profile is set", () => {
     const result = resolveGatewayWindowsTaskName("dev");
     expect(result).toBe("OpenClaw Gateway (dev)");
   });
-
-  it("returns profile-specific task name for custom profile", () => {
-    const result = resolveGatewayWindowsTaskName("work");
-    expect(result).toBe("OpenClaw Gateway (work)");
-  });
-
-  it("trims whitespace from profile", () => {
-    const result = resolveGatewayWindowsTaskName("  ci  ");
-    expect(result).toBe("OpenClaw Gateway (ci)");
-  });
-
-  it("returns default task name for empty string profile", () => {
-    const result = resolveGatewayWindowsTaskName("");
-    expect(result).toBe(GATEWAY_WINDOWS_TASK_NAME);
-  });
-
-  it("returns default task name for whitespace-only profile", () => {
-    const result = resolveGatewayWindowsTaskName("   ");
-    expect(result).toBe(GATEWAY_WINDOWS_TASK_NAME);
-  });
 });
 
 describe("resolveGatewayProfileSuffix", () => {
@@ -196,3 +108,23 @@ describe("formatGatewayServiceDescription", () => {
     );
   });
 });
+
+describe("resolveGatewayServiceDescription", () => {
+  it("prefers explicit description override", () => {
+    expect(
+      resolveGatewayServiceDescription({
+        env: { OPENCLAW_PROFILE: "work", OPENCLAW_SERVICE_VERSION: "1.0.0" },
+        description: "Custom",
+      }),
+    ).toBe("Custom");
+  });
+
+  it("resolves version from explicit environment map", () => {
+    expect(
+      resolveGatewayServiceDescription({
+        env: { OPENCLAW_PROFILE: "work", OPENCLAW_SERVICE_VERSION: "local" },
+        environment: { OPENCLAW_SERVICE_VERSION: "remote" },
+      }),
+    ).toBe("OpenClaw Gateway (profile: work, vremote)");
+  });
+});
diff --git a/src/daemon/constants.ts b/src/daemon/constants.ts
index 212eb93a2a9..3ee523b1535 100644
--- a/src/daemon/constants.ts
+++ b/src/daemon/constants.ts
@@ -75,6 +75,20 @@ export function formatGatewayServiceDescription(params?: {
   return `OpenClaw Gateway (${parts.join(", ")})`;
 }
 
+export function resolveGatewayServiceDescription(params: {
+  env: Record<string, string | undefined>;
+  environment?: Record<string, string | undefined>;
+  description?: string;
+}): string {
+  return (
+    params.description ??
+    formatGatewayServiceDescription({
+      profile: params.env.OPENCLAW_PROFILE,
+      version: params.environment?.OPENCLAW_SERVICE_VERSION ?? params.env.OPENCLAW_SERVICE_VERSION,
+    })
+  );
+}
+
 export function resolveNodeLaunchAgentLabel(): string {
   return NODE_LAUNCH_AGENT_LABEL;
 }
diff --git a/src/daemon/launchd.test.ts b/src/daemon/launchd.test.ts
index beb67e7cefe..43222a0e298 100644
--- a/src/daemon/launchd.test.ts
+++ b/src/daemon/launchd.test.ts
@@ -1,8 +1,5 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
 import { PassThrough } from "node:stream";
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   installLaunchAgent,
   isLaunchAgentListed,
@@ -11,116 +8,69 @@ import {
   resolveLaunchAgentPlistPath,
 } from "./launchd.js";
 
-function parseLaunchctlCalls(raw: string): string[][] {
-  return raw
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => line.split(/\s+/));
-}
+const state = vi.hoisted(() => ({
+  launchctlCalls: [] as string[][],
+  listOutput: "",
+  dirs: new Set<string>(),
+  files: new Map<string, string>(),
+}));
 
-async function writeLaunchctlStub(binDir: string) {
-  if (process.platform === "win32") {
-    const stubJsPath = path.join(binDir, "launchctl.js");
-    await fs.writeFile(
-      stubJsPath,
-      [
-        'import fs from "node:fs";',
-        "const args = process.argv.slice(2);",
-        "const logPath = process.env.OPENCLAW_TEST_LAUNCHCTL_LOG;",
-        "if (logPath) {",
-        '  fs.appendFileSync(logPath, args.join("\\t") + "\\n", "utf8");',
-        "}",
-        'if (args[0] === "list") {',
-        '  const output = process.env.OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT || "";',
-        "  process.stdout.write(output);",
-        "}",
-        "process.exit(0);",
-        "",
-      ].join("\n"),
-      "utf8",
-    );
-    await fs.writeFile(
-      path.join(binDir, "launchctl.cmd"),
-      `@echo off\r\nnode "%~dp0\\launchctl.js" %*\r\n`,
-      "utf8",
-    );
-    return;
+function normalizeLaunchctlArgs(file: string, args: string[]): string[] {
+  if (file === "launchctl") {
+    return args;
   }
-
-  const shPath = path.join(binDir, "launchctl");
-  await fs.writeFile(
-    shPath,
-    [
-      "#!/bin/sh",
-      'log_path="${OPENCLAW_TEST_LAUNCHCTL_LOG:-}"',
-      'if [ -n "$log_path" ]; then',
-      '  line=""',
-      '  for arg in "$@"; do',
-      '    if [ -n "$line" ]; then',
-      '      line="$line $arg"',
-      "    else",
-      '      line="$arg"',
-      "    fi",
-      "  done",
-      '  printf \'%s\\n\' "$line" >> "$log_path"',
-      "fi",
-      'if [ "$1" = "list" ]; then',
-      "  printf '%s' \"${OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT:-}\"",
-      "fi",
-      "exit 0",
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-  await fs.chmod(shPath, 0o755);
-}
-
-async function withLaunchctlStub(
-  options: { listOutput?: string },
-  run: (context: { env: Record<string, string | undefined>; logPath: string }) => Promise<void>,
-) {
-  const originalPath = process.env.PATH;
-  const originalLogPath = process.env.OPENCLAW_TEST_LAUNCHCTL_LOG;
-  const originalListOutput = process.env.OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT;
-
-  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-launchctl-test-"));
-  try {
-    const binDir = path.join(tmpDir, "bin");
-    const homeDir = path.join(tmpDir, "home");
-    const logPath = path.join(tmpDir, "launchctl.log");
-    await fs.mkdir(binDir, { recursive: true });
-    await fs.mkdir(homeDir, { recursive: true });
-
-    await writeLaunchctlStub(binDir);
-
-    process.env.OPENCLAW_TEST_LAUNCHCTL_LOG = logPath;
-    process.env.OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT = options.listOutput ?? "";
-    process.env.PATH = `${binDir}${path.delimiter}${originalPath ?? ""}`;
-
-    await run({
-      env: {
-        HOME: homeDir,
-        OPENCLAW_PROFILE: "default",
-      },
-      logPath,
-    });
-  } finally {
-    process.env.PATH = originalPath;
-    if (originalLogPath === undefined) {
-      delete process.env.OPENCLAW_TEST_LAUNCHCTL_LOG;
-    } else {
-      process.env.OPENCLAW_TEST_LAUNCHCTL_LOG = originalLogPath;
-    }
-    if (originalListOutput === undefined) {
-      delete process.env.OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT;
-    } else {
-      process.env.OPENCLAW_TEST_LAUNCHCTL_LIST_OUTPUT = originalListOutput;
-    }
-    await fs.rm(tmpDir, { recursive: true, force: true });
+  const idx = args.indexOf("launchctl");
+  if (idx >= 0) {
+    return args.slice(idx + 1);
   }
+  return args;
 }
 
+vi.mock("./exec-file.js", () => ({
+  execFileUtf8: vi.fn(async (file: string, args: string[]) => {
+    const call = normalizeLaunchctlArgs(file, args);
+    state.launchctlCalls.push(call);
+    if (call[0] === "list") {
+      return { stdout: state.listOutput, stderr: "", code: 0 };
+    }
+    return { stdout: "", stderr: "", code: 0 };
+  }),
+}));
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  const wrapped = {
+    ...actual,
+    access: vi.fn(async (p: string) => {
+      const key = String(p);
+      if (state.files.has(key) || state.dirs.has(key)) {
+        return;
+      }
+      throw new Error(`ENOENT: no such file or directory, access '${key}'`);
+    }),
+    mkdir: vi.fn(async (p: string) => {
+      state.dirs.add(String(p));
+    }),
+    unlink: vi.fn(async (p: string) => {
+      state.files.delete(String(p));
+    }),
+    writeFile: vi.fn(async (p: string, data: string) => {
+      const key = String(p);
+      state.files.set(key, data);
+      state.dirs.add(String(key.split("/").slice(0, -1).join("/")));
+    }),
+  };
+  return { ...wrapped, default: wrapped };
+});
+
+beforeEach(() => {
+  state.launchctlCalls.length = 0;
+  state.listOutput = "";
+  state.dirs.clear();
+  state.files.clear();
+  vi.clearAllMocks();
+});
+
 describe("launchd runtime parsing", () => {
   it("parses state, pid, and exit status", () => {
     const output = [
@@ -140,103 +90,70 @@ describe("launchd runtime parsing", () => {
 
 describe("launchctl list detection", () => {
   it("detects the resolved label in launchctl list", async () => {
-    await withLaunchctlStub({ listOutput: "123 0 ai.openclaw.gateway\n" }, async ({ env }) => {
-      const listed = await isLaunchAgentListed({ env });
-      expect(listed).toBe(true);
+    state.listOutput = "123 0 ai.openclaw.gateway\n";
+    const listed = await isLaunchAgentListed({
+      env: { HOME: "/Users/test", OPENCLAW_PROFILE: "default" },
     });
+    expect(listed).toBe(true);
   });
 
   it("returns false when the label is missing", async () => {
-    await withLaunchctlStub({ listOutput: "123 0 com.other.service\n" }, async ({ env }) => {
-      const listed = await isLaunchAgentListed({ env });
-      expect(listed).toBe(false);
+    state.listOutput = "123 0 com.other.service\n";
+    const listed = await isLaunchAgentListed({
+      env: { HOME: "/Users/test", OPENCLAW_PROFILE: "default" },
     });
+    expect(listed).toBe(false);
   });
 });
 
 describe("launchd bootstrap repair", () => {
   it("bootstraps and kickstarts the resolved label", async () => {
-    await withLaunchctlStub({}, async ({ env, logPath }) => {
-      const repair = await repairLaunchAgentBootstrap({ env });
-      expect(repair.ok).toBe(true);
+    const env: Record<string, string | undefined> = {
+      HOME: "/Users/test",
+      OPENCLAW_PROFILE: "default",
+    };
+    const repair = await repairLaunchAgentBootstrap({ env });
+    expect(repair.ok).toBe(true);
 
-      const calls = parseLaunchctlCalls(await fs.readFile(logPath, "utf8"));
+    const domain = typeof process.getuid === "function" ? `gui/${process.getuid()}` : "gui/501";
+    const label = "ai.openclaw.gateway";
+    const plistPath = resolveLaunchAgentPlistPath(env);
 
-      const domain = typeof process.getuid === "function" ? `gui/${process.getuid()}` : "gui/501";
-      const label = "ai.openclaw.gateway";
-      const plistPath = resolveLaunchAgentPlistPath(env);
-
-      expect(calls).toContainEqual(["bootstrap", domain, plistPath]);
-      expect(calls).toContainEqual(["kickstart", "-k", `${domain}/${label}`]);
-    });
+    expect(state.launchctlCalls).toContainEqual(["bootstrap", domain, plistPath]);
+    expect(state.launchctlCalls).toContainEqual(["kickstart", "-k", `${domain}/${label}`]);
   });
 });
 
 describe("launchd install", () => {
   it("enables service before bootstrap (clears persisted disabled state)", async () => {
-    const originalPath = process.env.PATH;
-    const originalLogPath = process.env.OPENCLAW_TEST_LAUNCHCTL_LOG;
+    const env: Record<string, string | undefined> = {
+      HOME: "/Users/test",
+      OPENCLAW_PROFILE: "default",
+    };
+    await installLaunchAgent({
+      env,
+      stdout: new PassThrough(),
+      programArguments: ["node", "-e", "process.exit(0)"],
+    });
 
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-launchctl-test-"));
-    try {
-      const binDir = path.join(tmpDir, "bin");
-      const homeDir = path.join(tmpDir, "home");
-      const logPath = path.join(tmpDir, "launchctl.log");
-      await fs.mkdir(binDir, { recursive: true });
-      await fs.mkdir(homeDir, { recursive: true });
+    const domain = typeof process.getuid === "function" ? `gui/${process.getuid()}` : "gui/501";
+    const label = "ai.openclaw.gateway";
+    const plistPath = resolveLaunchAgentPlistPath(env);
+    const serviceId = `${domain}/${label}`;
 
-      await writeLaunchctlStub(binDir);
-
-      process.env.OPENCLAW_TEST_LAUNCHCTL_LOG = logPath;
-      process.env.PATH = `${binDir}${path.delimiter}${originalPath ?? ""}`;
-
-      const env: Record<string, string | undefined> = {
-        HOME: homeDir,
-        OPENCLAW_PROFILE: "default",
-      };
-      await installLaunchAgent({
-        env,
-        stdout: new PassThrough(),
-        programArguments: ["node", "-e", "process.exit(0)"],
-      });
-
-      const calls = parseLaunchctlCalls(await fs.readFile(logPath, "utf8"));
-
-      const domain = typeof process.getuid === "function" ? `gui/${process.getuid()}` : "gui/501";
-      const label = "ai.openclaw.gateway";
-      const plistPath = resolveLaunchAgentPlistPath(env);
-      const serviceId = `${domain}/${label}`;
-
-      const enableCalls = calls.filter((c) => c[0] === "enable" && c[1] === serviceId);
-      expect(enableCalls).toHaveLength(1);
-
-      const enableIndex = calls.findIndex((c) => c[0] === "enable" && c[1] === serviceId);
-      const bootstrapIndex = calls.findIndex(
-        (c) => c[0] === "bootstrap" && c[1] === domain && c[2] === plistPath,
-      );
-      expect(enableIndex).toBeGreaterThanOrEqual(0);
-      expect(bootstrapIndex).toBeGreaterThanOrEqual(0);
-      expect(enableIndex).toBeLessThan(bootstrapIndex);
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalLogPath === undefined) {
-        delete process.env.OPENCLAW_TEST_LAUNCHCTL_LOG;
-      } else {
-        process.env.OPENCLAW_TEST_LAUNCHCTL_LOG = originalLogPath;
-      }
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    }
+    const enableIndex = state.launchctlCalls.findIndex(
+      (c) => c[0] === "enable" && c[1] === serviceId,
+    );
+    const bootstrapIndex = state.launchctlCalls.findIndex(
+      (c) => c[0] === "bootstrap" && c[1] === domain && c[2] === plistPath,
+    );
+    expect(enableIndex).toBeGreaterThanOrEqual(0);
+    expect(bootstrapIndex).toBeGreaterThanOrEqual(0);
+    expect(enableIndex).toBeLessThan(bootstrapIndex);
   });
 });
 
 describe("resolveLaunchAgentPlistPath", () => {
-  it("uses default label when OPENCLAW_PROFILE is default", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "default" };
-    expect(resolveLaunchAgentPlistPath(env)).toBe(
-      "/Users/test/Library/LaunchAgents/ai.openclaw.gateway.plist",
-    );
-  });
-
   it("uses default label when OPENCLAW_PROFILE is unset", () => {
     const env = { HOME: "/Users/test" };
     expect(resolveLaunchAgentPlistPath(env)).toBe(
@@ -282,25 +199,4 @@ describe("resolveLaunchAgentPlistPath", () => {
       "/Users/test/Library/LaunchAgents/ai.openclaw.myprofile.plist",
     );
   });
-
-  it("handles case-insensitive 'Default' profile", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "Default" };
-    expect(resolveLaunchAgentPlistPath(env)).toBe(
-      "/Users/test/Library/LaunchAgents/ai.openclaw.gateway.plist",
-    );
-  });
-
-  it("handles case-insensitive 'DEFAULT' profile", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "DEFAULT" };
-    expect(resolveLaunchAgentPlistPath(env)).toBe(
-      "/Users/test/Library/LaunchAgents/ai.openclaw.gateway.plist",
-    );
-  });
-
-  it("trims whitespace from OPENCLAW_PROFILE", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "  myprofile  " };
-    expect(resolveLaunchAgentPlistPath(env)).toBe(
-      "/Users/test/Library/LaunchAgents/ai.openclaw.myprofile.plist",
-    );
-  });
 });
diff --git a/src/daemon/launchd.ts b/src/daemon/launchd.ts
index 3d33af682dc..795fe828096 100644
--- a/src/daemon/launchd.ts
+++ b/src/daemon/launchd.ts
@@ -2,8 +2,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import {
-  formatGatewayServiceDescription,
   GATEWAY_LAUNCH_AGENT_LABEL,
+  resolveGatewayServiceDescription,
   resolveGatewayLaunchAgentLabel,
   resolveLegacyGatewayLaunchAgentLabels,
 } from "./constants.js";
@@ -384,12 +384,7 @@ export async function installLaunchAgent({
   const plistPath = resolveLaunchAgentPlistPathForLabel(env, label);
   await fs.mkdir(path.dirname(plistPath), { recursive: true });
 
-  const serviceDescription =
-    description ??
-    formatGatewayServiceDescription({
-      profile: env.OPENCLAW_PROFILE,
-      version: environment?.OPENCLAW_SERVICE_VERSION ?? env.OPENCLAW_SERVICE_VERSION,
-    });
+  const serviceDescription = resolveGatewayServiceDescription({ env, environment, description });
   const plist = buildLaunchAgentPlist({
     label,
     comment: serviceDescription,
diff --git a/src/daemon/paths.test.ts b/src/daemon/paths.test.ts
deleted file mode 100644
index 5bcdb22cf69..00000000000
--- a/src/daemon/paths.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { resolveGatewayStateDir } from "./paths.js";
-
-describe("resolveGatewayStateDir", () => {
-  it("uses the default state dir when no overrides are set", () => {
-    const env = { HOME: "/Users/test" };
-    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw"));
-  });
-
-  it("appends the profile suffix when set", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "rescue" };
-    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw-rescue"));
-  });
-
-  it("treats default profiles as the base state dir", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "Default" };
-    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw"));
-  });
-
-  it("uses OPENCLAW_STATE_DIR when provided", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_STATE_DIR: "/var/lib/openclaw" };
-    expect(resolveGatewayStateDir(env)).toBe(path.resolve("/var/lib/openclaw"));
-  });
-
-  it("expands ~ in OPENCLAW_STATE_DIR", () => {
-    const env = { HOME: "/Users/test", OPENCLAW_STATE_DIR: "~/openclaw-state" };
-    expect(resolveGatewayStateDir(env)).toBe(path.resolve("/Users/test/openclaw-state"));
-  });
-
-  it("preserves Windows absolute paths without HOME", () => {
-    const env = { OPENCLAW_STATE_DIR: "C:\\State\\openclaw" };
-    expect(resolveGatewayStateDir(env)).toBe("C:\\State\\openclaw");
-  });
-});
diff --git a/src/daemon/schtasks.test.ts b/src/daemon/schtasks.test.ts
index c2a2fab42f0..a0d24d89da0 100644
--- a/src/daemon/schtasks.test.ts
+++ b/src/daemon/schtasks.test.ts
@@ -35,13 +35,6 @@ describe("schtasks runtime parsing", () => {
 });
 
 describe("resolveTaskScriptPath", () => {
-  it("uses default path when OPENCLAW_PROFILE is default", () => {
-    const env = { USERPROFILE: "C:\\Users\\test", OPENCLAW_PROFILE: "default" };
-    expect(resolveTaskScriptPath(env)).toBe(
-      path.join("C:\\Users\\test", ".openclaw", "gateway.cmd"),
-    );
-  });
-
   it("uses default path when OPENCLAW_PROFILE is unset", () => {
     const env = { USERPROFILE: "C:\\Users\\test" };
     expect(resolveTaskScriptPath(env)).toBe(
@@ -65,27 +58,6 @@ describe("resolveTaskScriptPath", () => {
     expect(resolveTaskScriptPath(env)).toBe(path.join("C:\\State\\openclaw", "gateway.cmd"));
   });
 
-  it("handles case-insensitive 'Default' profile", () => {
-    const env = { USERPROFILE: "C:\\Users\\test", OPENCLAW_PROFILE: "Default" };
-    expect(resolveTaskScriptPath(env)).toBe(
-      path.join("C:\\Users\\test", ".openclaw", "gateway.cmd"),
-    );
-  });
-
-  it("handles case-insensitive 'DEFAULT' profile", () => {
-    const env = { USERPROFILE: "C:\\Users\\test", OPENCLAW_PROFILE: "DEFAULT" };
-    expect(resolveTaskScriptPath(env)).toBe(
-      path.join("C:\\Users\\test", ".openclaw", "gateway.cmd"),
-    );
-  });
-
-  it("trims whitespace from OPENCLAW_PROFILE", () => {
-    const env = { USERPROFILE: "C:\\Users\\test", OPENCLAW_PROFILE: "  myprofile  " };
-    expect(resolveTaskScriptPath(env)).toBe(
-      path.join("C:\\Users\\test", ".openclaw-myprofile", "gateway.cmd"),
-    );
-  });
-
   it("falls back to HOME when USERPROFILE is not set", () => {
     const env = { HOME: "/home/test", OPENCLAW_PROFILE: "default" };
     expect(resolveTaskScriptPath(env)).toBe(path.join("/home/test", ".openclaw", "gateway.cmd"));
@@ -93,74 +65,6 @@ describe("resolveTaskScriptPath", () => {
 });
 
 describe("readScheduledTaskCommand", () => {
-  it("parses basic command script", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-schtasks-test-"));
-    try {
-      const scriptPath = path.join(tmpDir, ".openclaw", "gateway.cmd");
-      await fs.mkdir(path.dirname(scriptPath), { recursive: true });
-      await fs.writeFile(
-        scriptPath,
-        ["@echo off", "node gateway.js --port 18789"].join("\r\n"),
-        "utf8",
-      );
-
-      const env = { USERPROFILE: tmpDir, OPENCLAW_PROFILE: "default" };
-      const result = await readScheduledTaskCommand(env);
-      expect(result).toEqual({
-        programArguments: ["node", "gateway.js", "--port", "18789"],
-      });
-    } finally {
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  it("parses script with working directory", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-schtasks-test-"));
-    try {
-      const scriptPath = path.join(tmpDir, ".openclaw", "gateway.cmd");
-      await fs.mkdir(path.dirname(scriptPath), { recursive: true });
-      await fs.writeFile(
-        scriptPath,
-        ["@echo off", "cd /d C:\\Projects\\openclaw", "node gateway.js"].join("\r\n"),
-        "utf8",
-      );
-
-      const env = { USERPROFILE: tmpDir, OPENCLAW_PROFILE: "default" };
-      const result = await readScheduledTaskCommand(env);
-      expect(result).toEqual({
-        programArguments: ["node", "gateway.js"],
-        workingDirectory: "C:\\Projects\\openclaw",
-      });
-    } finally {
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  it("parses script with environment variables", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-schtasks-test-"));
-    try {
-      const scriptPath = path.join(tmpDir, ".openclaw", "gateway.cmd");
-      await fs.mkdir(path.dirname(scriptPath), { recursive: true });
-      await fs.writeFile(
-        scriptPath,
-        ["@echo off", "set NODE_ENV=production", "set PORT=18789", "node gateway.js"].join("\r\n"),
-        "utf8",
-      );
-
-      const env = { USERPROFILE: tmpDir, OPENCLAW_PROFILE: "default" };
-      const result = await readScheduledTaskCommand(env);
-      expect(result).toEqual({
-        programArguments: ["node", "gateway.js"],
-        environment: {
-          NODE_ENV: "production",
-          PORT: "18789",
-        },
-      });
-    } finally {
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    }
-  });
-
   it("parses script with quoted arguments containing spaces", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-schtasks-test-"));
     try {
diff --git a/src/daemon/schtasks.ts b/src/daemon/schtasks.ts
index d29d470ffe8..a70f100793a 100644
--- a/src/daemon/schtasks.ts
+++ b/src/daemon/schtasks.ts
@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import { splitArgsPreservingQuotes } from "./arg-split.js";
-import { formatGatewayServiceDescription, resolveGatewayWindowsTaskName } from "./constants.js";
+import { resolveGatewayServiceDescription, resolveGatewayWindowsTaskName } from "./constants.js";
 import { formatLine } from "./output.js";
 import { resolveGatewayStateDir } from "./paths.js";
 import { parseKeyValueOutput } from "./runtime-parse.js";
@@ -190,12 +190,7 @@ export async function installScheduledTask({
   await assertSchtasksAvailable();
   const scriptPath = resolveTaskScriptPath(env);
   await fs.mkdir(path.dirname(scriptPath), { recursive: true });
-  const taskDescription =
-    description ??
-    formatGatewayServiceDescription({
-      profile: env.OPENCLAW_PROFILE,
-      version: environment?.OPENCLAW_SERVICE_VERSION ?? env.OPENCLAW_SERVICE_VERSION,
-    });
+  const taskDescription = resolveGatewayServiceDescription({ env, environment, description });
   const script = buildTaskScript({
     description: taskDescription,
     programArguments,
diff --git a/src/daemon/service-env.test.ts b/src/daemon/service-env.test.ts
index 7ead6b2ec66..6a3b6a9399f 100644
--- a/src/daemon/service-env.test.ts
+++ b/src/daemon/service-env.test.ts
@@ -1,5 +1,6 @@
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { resolveGatewayStateDir } from "./paths.js";
 import {
   buildMinimalServicePath,
   buildNodeServiceEnvironment,
@@ -254,3 +255,35 @@ describe("buildNodeServiceEnvironment", () => {
     expect(env.HOME).toBe("/home/user");
   });
 });
+
+describe("resolveGatewayStateDir", () => {
+  it("uses the default state dir when no overrides are set", () => {
+    const env = { HOME: "/Users/test" };
+    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw"));
+  });
+
+  it("appends the profile suffix when set", () => {
+    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "rescue" };
+    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw-rescue"));
+  });
+
+  it("treats default profiles as the base state dir", () => {
+    const env = { HOME: "/Users/test", OPENCLAW_PROFILE: "Default" };
+    expect(resolveGatewayStateDir(env)).toBe(path.join("/Users/test", ".openclaw"));
+  });
+
+  it("uses OPENCLAW_STATE_DIR when provided", () => {
+    const env = { HOME: "/Users/test", OPENCLAW_STATE_DIR: "/var/lib/openclaw" };
+    expect(resolveGatewayStateDir(env)).toBe(path.resolve("/var/lib/openclaw"));
+  });
+
+  it("expands ~ in OPENCLAW_STATE_DIR", () => {
+    const env = { HOME: "/Users/test", OPENCLAW_STATE_DIR: "~/openclaw-state" };
+    expect(resolveGatewayStateDir(env)).toBe(path.resolve("/Users/test/openclaw-state"));
+  });
+
+  it("preserves Windows absolute paths without HOME", () => {
+    const env = { OPENCLAW_STATE_DIR: "C:\\State\\openclaw" };
+    expect(resolveGatewayStateDir(env)).toBe("C:\\State\\openclaw");
+  });
+});
diff --git a/src/daemon/systemd-availability.test.ts b/src/daemon/systemd-availability.test.ts
deleted file mode 100644
index 4897084ce52..00000000000
--- a/src/daemon/systemd-availability.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const execFileMock = vi.hoisted(() => vi.fn());
-
-vi.mock("node:child_process", () => ({
-  execFile: execFileMock,
-}));
-
-import { isSystemdUserServiceAvailable } from "./systemd.js";
-
-describe("systemd availability", () => {
-  beforeEach(() => {
-    execFileMock.mockReset();
-  });
-
-  it("returns true when systemctl --user succeeds", async () => {
-    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => {
-      cb(null, "", "");
-    });
-    await expect(isSystemdUserServiceAvailable()).resolves.toBe(true);
-  });
-
-  it("returns false when systemd user bus is unavailable", async () => {
-    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => {
-      const err = new Error("Failed to connect to bus") as Error & {
-        stderr?: string;
-        code?: number;
-      };
-      err.stderr = "Failed to connect to bus";
-      err.code = 1;
-      cb(err, "", "");
-    });
-    await expect(isSystemdUserServiceAvailable()).resolves.toBe(false);
-  });
-});
diff --git a/src/daemon/systemd-unit.test.ts b/src/daemon/systemd-unit.test.ts
deleted file mode 100644
index c671763409f..00000000000
--- a/src/daemon/systemd-unit.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseSystemdExecStart } from "./systemd-unit.js";
-
-describe("parseSystemdExecStart", () => {
-  it("splits on whitespace outside quotes", () => {
-    const execStart = "/usr/bin/openclaw gateway start --foo bar";
-    expect(parseSystemdExecStart(execStart)).toEqual([
-      "/usr/bin/openclaw",
-      "gateway",
-      "start",
-      "--foo",
-      "bar",
-    ]);
-  });
-
-  it("preserves quoted arguments", () => {
-    const execStart = '/usr/bin/openclaw gateway start --name "My Bot"';
-    expect(parseSystemdExecStart(execStart)).toEqual([
-      "/usr/bin/openclaw",
-      "gateway",
-      "start",
-      "--name",
-      "My Bot",
-    ]);
-  });
-
-  it("parses path arguments", () => {
-    const execStart = "/usr/bin/openclaw gateway start --path /tmp/openclaw";
-    expect(parseSystemdExecStart(execStart)).toEqual([
-      "/usr/bin/openclaw",
-      "gateway",
-      "start",
-      "--path",
-      "/tmp/openclaw",
-    ]);
-  });
-});
diff --git a/src/daemon/systemd.test.ts b/src/daemon/systemd.test.ts
index 692a445e5a9..5e9e09deed3 100644
--- a/src/daemon/systemd.test.ts
+++ b/src/daemon/systemd.test.ts
@@ -1,5 +1,44 @@
-import { describe, expect, it } from "vitest";
-import { parseSystemdShow, resolveSystemdUserUnitPath } from "./systemd.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const execFileMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:child_process", () => ({
+  execFile: execFileMock,
+}));
+
+import { splitArgsPreservingQuotes } from "./arg-split.js";
+import { parseSystemdExecStart } from "./systemd-unit.js";
+import {
+  isSystemdUserServiceAvailable,
+  parseSystemdShow,
+  resolveSystemdUserUnitPath,
+} from "./systemd.js";
+
+describe("systemd availability", () => {
+  beforeEach(() => {
+    execFileMock.mockReset();
+  });
+
+  it("returns true when systemctl --user succeeds", async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => {
+      cb(null, "", "");
+    });
+    await expect(isSystemdUserServiceAvailable()).resolves.toBe(true);
+  });
+
+  it("returns false when systemd user bus is unavailable", async () => {
+    execFileMock.mockImplementation((_cmd, _args, _opts, cb) => {
+      const err = new Error("Failed to connect to bus") as Error & {
+        stderr?: string;
+        code?: number;
+      };
+      err.stderr = "Failed to connect to bus";
+      err.code = 1;
+      cb(err, "", "");
+    });
+    await expect(isSystemdUserServiceAvailable()).resolves.toBe(false);
+  });
+});
 
 describe("systemd runtime parsing", () => {
   it("parses active state details", () => {
@@ -20,13 +59,6 @@ describe("systemd runtime parsing", () => {
 });
 
 describe("resolveSystemdUserUnitPath", () => {
-  it("uses default service name when OPENCLAW_PROFILE is default", () => {
-    const env = { HOME: "/home/test", OPENCLAW_PROFILE: "default" };
-    expect(resolveSystemdUserUnitPath(env)).toBe(
-      "/home/test/.config/systemd/user/openclaw-gateway.service",
-    );
-  });
-
   it("uses default service name when OPENCLAW_PROFILE is unset", () => {
     const env = { HOME: "/home/test" };
     expect(resolveSystemdUserUnitPath(env)).toBe(
@@ -71,25 +103,51 @@ describe("resolveSystemdUserUnitPath", () => {
       "/home/test/.config/systemd/user/custom-unit.service",
     );
   });
+});
 
-  it("handles case-insensitive 'Default' profile", () => {
-    const env = { HOME: "/home/test", OPENCLAW_PROFILE: "Default" };
-    expect(resolveSystemdUserUnitPath(env)).toBe(
-      "/home/test/.config/systemd/user/openclaw-gateway.service",
-    );
+describe("splitArgsPreservingQuotes", () => {
+  it("splits on whitespace outside quotes", () => {
+    expect(splitArgsPreservingQuotes('/usr/bin/openclaw gateway start --name "My Bot"')).toEqual([
+      "/usr/bin/openclaw",
+      "gateway",
+      "start",
+      "--name",
+      "My Bot",
+    ]);
   });
 
-  it("handles case-insensitive 'DEFAULT' profile", () => {
-    const env = { HOME: "/home/test", OPENCLAW_PROFILE: "DEFAULT" };
-    expect(resolveSystemdUserUnitPath(env)).toBe(
-      "/home/test/.config/systemd/user/openclaw-gateway.service",
-    );
+  it("supports systemd-style backslash escaping", () => {
+    expect(
+      splitArgsPreservingQuotes('openclaw --name "My \\"Bot\\"" --foo bar', {
+        escapeMode: "backslash",
+      }),
+    ).toEqual(["openclaw", "--name", 'My "Bot"', "--foo", "bar"]);
   });
 
-  it("trims whitespace from OPENCLAW_PROFILE", () => {
-    const env = { HOME: "/home/test", OPENCLAW_PROFILE: "  myprofile  " };
-    expect(resolveSystemdUserUnitPath(env)).toBe(
-      "/home/test/.config/systemd/user/openclaw-gateway-myprofile.service",
-    );
+  it("supports schtasks-style escaped quotes while preserving other backslashes", () => {
+    expect(
+      splitArgsPreservingQuotes('openclaw --path "C:\\\\Program Files\\\\OpenClaw"', {
+        escapeMode: "backslash-quote-only",
+      }),
+    ).toEqual(["openclaw", "--path", "C:\\\\Program Files\\\\OpenClaw"]);
+
+    expect(
+      splitArgsPreservingQuotes('openclaw --label "My \\"Quoted\\" Name"', {
+        escapeMode: "backslash-quote-only",
+      }),
+    ).toEqual(["openclaw", "--label", 'My "Quoted" Name']);
+  });
+});
+
+describe("parseSystemdExecStart", () => {
+  it("preserves quoted arguments", () => {
+    const execStart = '/usr/bin/openclaw gateway start --name "My Bot"';
+    expect(parseSystemdExecStart(execStart)).toEqual([
+      "/usr/bin/openclaw",
+      "gateway",
+      "start",
+      "--name",
+      "My Bot",
+    ]);
   });
 });
diff --git a/src/daemon/systemd.ts b/src/daemon/systemd.ts
index 6ef8af5765f..41107d4a2ee 100644
--- a/src/daemon/systemd.ts
+++ b/src/daemon/systemd.ts
@@ -2,8 +2,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import {
-  formatGatewayServiceDescription,
   LEGACY_GATEWAY_SYSTEMD_SERVICE_NAMES,
+  resolveGatewayServiceDescription,
   resolveGatewaySystemdServiceName,
 } from "./constants.js";
 import { execFileUtf8 } from "./exec-file.js";
@@ -200,12 +200,7 @@ export async function installSystemdService({
 
   const unitPath = resolveSystemdUnitPath(env);
   await fs.mkdir(path.dirname(unitPath), { recursive: true });
-  const serviceDescription =
-    description ??
-    formatGatewayServiceDescription({
-      profile: env.OPENCLAW_PROFILE,
-      version: environment?.OPENCLAW_SERVICE_VERSION ?? env.OPENCLAW_SERVICE_VERSION,
-    });
+  const serviceDescription = resolveGatewayServiceDescription({ env, environment, description });
   const unit = buildSystemdUnit({
     description: serviceDescription,
     programArguments,
diff --git a/src/discord/components-registry.ts b/src/discord/components-registry.ts
new file mode 100644
index 00000000000..ce7014aba75
--- /dev/null
+++ b/src/discord/components-registry.ts
@@ -0,0 +1,89 @@
+import type { DiscordComponentEntry, DiscordModalEntry } from "./components.js";
+
+const DEFAULT_COMPONENT_TTL_MS = 30 * 60 * 1000;
+
+const componentEntries = new Map<string, DiscordComponentEntry>();
+const modalEntries = new Map<string, DiscordModalEntry>();
+
+function isExpired(entry: { expiresAt?: number }, now: number) {
+  return typeof entry.expiresAt === "number" && entry.expiresAt <= now;
+}
+
+function normalizeEntryTimestamps<T extends { createdAt?: number; expiresAt?: number }>(
+  entry: T,
+  now: number,
+  ttlMs: number,
+): T {
+  const createdAt = entry.createdAt ?? now;
+  const expiresAt = entry.expiresAt ?? createdAt + ttlMs;
+  return { ...entry, createdAt, expiresAt };
+}
+
+export function registerDiscordComponentEntries(params: {
+  entries: DiscordComponentEntry[];
+  modals: DiscordModalEntry[];
+  ttlMs?: number;
+  messageId?: string;
+}): void {
+  const now = Date.now();
+  const ttlMs = params.ttlMs ?? DEFAULT_COMPONENT_TTL_MS;
+  for (const entry of params.entries) {
+    const normalized = normalizeEntryTimestamps(
+      { ...entry, messageId: params.messageId ?? entry.messageId },
+      now,
+      ttlMs,
+    );
+    componentEntries.set(entry.id, normalized);
+  }
+  for (const modal of params.modals) {
+    const normalized = normalizeEntryTimestamps(
+      { ...modal, messageId: params.messageId ?? modal.messageId },
+      now,
+      ttlMs,
+    );
+    modalEntries.set(modal.id, normalized);
+  }
+}
+
+export function resolveDiscordComponentEntry(params: {
+  id: string;
+  consume?: boolean;
+}): DiscordComponentEntry | null {
+  const entry = componentEntries.get(params.id);
+  if (!entry) {
+    return null;
+  }
+  const now = Date.now();
+  if (isExpired(entry, now)) {
+    componentEntries.delete(params.id);
+    return null;
+  }
+  if (params.consume !== false) {
+    componentEntries.delete(params.id);
+  }
+  return entry;
+}
+
+export function resolveDiscordModalEntry(params: {
+  id: string;
+  consume?: boolean;
+}): DiscordModalEntry | null {
+  const entry = modalEntries.get(params.id);
+  if (!entry) {
+    return null;
+  }
+  const now = Date.now();
+  if (isExpired(entry, now)) {
+    modalEntries.delete(params.id);
+    return null;
+  }
+  if (params.consume !== false) {
+    modalEntries.delete(params.id);
+  }
+  return entry;
+}
+
+export function clearDiscordComponentEntries(): void {
+  componentEntries.clear();
+  modalEntries.clear();
+}
diff --git a/src/discord/components.test.ts b/src/discord/components.test.ts
new file mode 100644
index 00000000000..9a49af7b469
--- /dev/null
+++ b/src/discord/components.test.ts
@@ -0,0 +1,98 @@
+import { MessageFlags } from "discord-api-types/v10";
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  clearDiscordComponentEntries,
+  registerDiscordComponentEntries,
+  resolveDiscordComponentEntry,
+  resolveDiscordModalEntry,
+} from "./components-registry.js";
+import {
+  buildDiscordComponentMessage,
+  buildDiscordComponentMessageFlags,
+  readDiscordComponentSpec,
+} from "./components.js";
+
+describe("discord components", () => {
+  it("builds v2 containers with modal trigger", () => {
+    const spec = readDiscordComponentSpec({
+      text: "Choose a path",
+      blocks: [
+        {
+          type: "actions",
+          buttons: [{ label: "Approve", style: "success" }],
+        },
+      ],
+      modal: {
+        title: "Details",
+        fields: [{ type: "text", label: "Requester" }],
+      },
+    });
+    if (!spec) {
+      throw new Error("Expected component spec to be parsed");
+    }
+
+    const result = buildDiscordComponentMessage({ spec });
+    expect(result.components).toHaveLength(1);
+    expect(result.components[0]?.isV2).toBe(true);
+    expect(buildDiscordComponentMessageFlags(result.components)).toBe(MessageFlags.IsComponentsV2);
+    expect(result.modals).toHaveLength(1);
+
+    const trigger = result.entries.find((entry) => entry.kind === "modal-trigger");
+    expect(trigger?.modalId).toBe(result.modals[0]?.id);
+  });
+
+  it("requires options for modal select fields", () => {
+    expect(() =>
+      readDiscordComponentSpec({
+        modal: {
+          title: "Details",
+          fields: [{ type: "select", label: "Priority" }],
+        },
+      }),
+    ).toThrow("options");
+  });
+
+  it("requires attachment references for file blocks", () => {
+    expect(() =>
+      readDiscordComponentSpec({
+        blocks: [{ type: "file", file: "https://example.com/report.pdf" }],
+      }),
+    ).toThrow("attachment://");
+    expect(() =>
+      readDiscordComponentSpec({
+        blocks: [{ type: "file", file: "attachment://" }],
+      }),
+    ).toThrow("filename");
+  });
+});
+
+describe("discord component registry", () => {
+  beforeEach(() => {
+    clearDiscordComponentEntries();
+  });
+
+  it("registers and consumes component entries", () => {
+    registerDiscordComponentEntries({
+      entries: [{ id: "btn_1", kind: "button", label: "Confirm" }],
+      modals: [
+        {
+          id: "mdl_1",
+          title: "Details",
+          fields: [{ id: "fld_1", name: "name", label: "Name", type: "text" }],
+        },
+      ],
+      messageId: "msg_1",
+      ttlMs: 1000,
+    });
+
+    const entry = resolveDiscordComponentEntry({ id: "btn_1", consume: false });
+    expect(entry?.messageId).toBe("msg_1");
+
+    const modal = resolveDiscordModalEntry({ id: "mdl_1", consume: false });
+    expect(modal?.messageId).toBe("msg_1");
+
+    const consumed = resolveDiscordComponentEntry({ id: "btn_1" });
+    expect(consumed?.id).toBe("btn_1");
+    expect(resolveDiscordComponentEntry({ id: "btn_1" })).toBeNull();
+  });
+});
diff --git a/src/discord/components.ts b/src/discord/components.ts
new file mode 100644
index 00000000000..b45c28b2109
--- /dev/null
+++ b/src/discord/components.ts
@@ -0,0 +1,1120 @@
+import {
+  Button,
+  ChannelSelectMenu,
+  CheckboxGroup,
+  Container,
+  File,
+  Label,
+  LinkButton,
+  MediaGallery,
+  MentionableSelectMenu,
+  Modal,
+  RadioGroup,
+  RoleSelectMenu,
+  Row,
+  Section,
+  Separator,
+  StringSelectMenu,
+  TextDisplay,
+  TextInput,
+  Thumbnail,
+  UserSelectMenu,
+  parseCustomId,
+  type ComponentParserResult,
+  type TopLevelComponents,
+} from "@buape/carbon";
+import { ButtonStyle, MessageFlags, TextInputStyle } from "discord-api-types/v10";
+import crypto from "node:crypto";
+
+export const DISCORD_COMPONENT_CUSTOM_ID_KEY = "occomp";
+export const DISCORD_MODAL_CUSTOM_ID_KEY = "ocmodal";
+export const DISCORD_COMPONENT_ATTACHMENT_PREFIX = "attachment://";
+
+export type DiscordComponentButtonStyle = "primary" | "secondary" | "success" | "danger" | "link";
+
+export type DiscordComponentSelectType = "string" | "user" | "role" | "mentionable" | "channel";
+
+export type DiscordComponentModalFieldType =
+  | "text"
+  | "checkbox"
+  | "radio"
+  | "select"
+  | "role-select"
+  | "user-select";
+
+export type DiscordComponentButtonSpec = {
+  label: string;
+  style?: DiscordComponentButtonStyle;
+  url?: string;
+  emoji?: {
+    name: string;
+    id?: string;
+    animated?: boolean;
+  };
+  disabled?: boolean;
+};
+
+export type DiscordComponentSelectOption = {
+  label: string;
+  value: string;
+  description?: string;
+  emoji?: {
+    name: string;
+    id?: string;
+    animated?: boolean;
+  };
+  default?: boolean;
+};
+
+export type DiscordComponentSelectSpec = {
+  type?: DiscordComponentSelectType;
+  placeholder?: string;
+  minValues?: number;
+  maxValues?: number;
+  options?: DiscordComponentSelectOption[];
+};
+
+export type DiscordComponentSectionAccessory =
+  | {
+      type: "thumbnail";
+      url: string;
+    }
+  | {
+      type: "button";
+      button: DiscordComponentButtonSpec;
+    };
+
+type DiscordComponentSeparatorSpacing = "small" | "large" | 1 | 2;
+
+export type DiscordComponentBlock =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "section";
+      text?: string;
+      texts?: string[];
+      accessory?: DiscordComponentSectionAccessory;
+    }
+  | {
+      type: "separator";
+      spacing?: DiscordComponentSeparatorSpacing;
+      divider?: boolean;
+    }
+  | {
+      type: "actions";
+      buttons?: DiscordComponentButtonSpec[];
+      select?: DiscordComponentSelectSpec;
+    }
+  | {
+      type: "media-gallery";
+      items: Array<{ url: string; description?: string; spoiler?: boolean }>;
+    }
+  | {
+      type: "file";
+      file: `attachment://${string}`;
+      spoiler?: boolean;
+    };
+
+export type DiscordModalFieldSpec = {
+  type: DiscordComponentModalFieldType;
+  name?: string;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  required?: boolean;
+  options?: DiscordComponentSelectOption[];
+  minValues?: number;
+  maxValues?: number;
+  minLength?: number;
+  maxLength?: number;
+  style?: "short" | "paragraph";
+};
+
+export type DiscordModalSpec = {
+  title: string;
+  triggerLabel?: string;
+  triggerStyle?: DiscordComponentButtonStyle;
+  fields: DiscordModalFieldSpec[];
+};
+
+export type DiscordComponentMessageSpec = {
+  text?: string;
+  container?: {
+    accentColor?: string | number;
+    spoiler?: boolean;
+  };
+  blocks?: DiscordComponentBlock[];
+  modal?: DiscordModalSpec;
+};
+
+export type DiscordComponentEntry = {
+  id: string;
+  kind: "button" | "select" | "modal-trigger";
+  label: string;
+  selectType?: DiscordComponentSelectType;
+  options?: Array<{ value: string; label: string }>;
+  modalId?: string;
+  sessionKey?: string;
+  agentId?: string;
+  accountId?: string;
+  messageId?: string;
+  createdAt?: number;
+  expiresAt?: number;
+};
+
+export type DiscordModalFieldDefinition = {
+  id: string;
+  name: string;
+  label: string;
+  type: DiscordComponentModalFieldType;
+  description?: string;
+  placeholder?: string;
+  required?: boolean;
+  options?: DiscordComponentSelectOption[];
+  minValues?: number;
+  maxValues?: number;
+  minLength?: number;
+  maxLength?: number;
+  style?: "short" | "paragraph";
+};
+
+export type DiscordModalEntry = {
+  id: string;
+  title: string;
+  fields: DiscordModalFieldDefinition[];
+  sessionKey?: string;
+  agentId?: string;
+  accountId?: string;
+  messageId?: string;
+  createdAt?: number;
+  expiresAt?: number;
+};
+
+export type DiscordComponentBuildResult = {
+  components: TopLevelComponents[];
+  entries: DiscordComponentEntry[];
+  modals: DiscordModalEntry[];
+};
+
+const BLOCK_ALIASES = new Map<string, DiscordComponentBlock["type"]>([
+  ["row", "actions"],
+  ["action-row", "actions"],
+]);
+
+function createShortId(prefix: string) {
+  return `${prefix}${crypto.randomBytes(6).toString("base64url")}`;
+}
+
+function requireObject(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown, label: string, opts?: { allowEmpty?: boolean }): string {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  const trimmed = value.trim();
+  if (!opts?.allowEmpty && !trimmed) {
+    throw new Error(`${label} cannot be empty`);
+  }
+  return opts?.allowEmpty ? value : trimmed;
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readOptionalNumber(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+function normalizeModalFieldName(value: string | undefined, index: number) {
+  const trimmed = value?.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  return `field_${index + 1}`;
+}
+
+function normalizeAttachmentRef(value: string, label: string): `attachment://${string}` {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith(DISCORD_COMPONENT_ATTACHMENT_PREFIX)) {
+    throw new Error(`${label} must start with "${DISCORD_COMPONENT_ATTACHMENT_PREFIX}"`);
+  }
+  const attachmentName = trimmed.slice(DISCORD_COMPONENT_ATTACHMENT_PREFIX.length).trim();
+  if (!attachmentName) {
+    throw new Error(`${label} must include an attachment filename`);
+  }
+  return `${DISCORD_COMPONENT_ATTACHMENT_PREFIX}${attachmentName}`;
+}
+
+export function resolveDiscordComponentAttachmentName(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith(DISCORD_COMPONENT_ATTACHMENT_PREFIX)) {
+    throw new Error(
+      `Attachment reference must start with "${DISCORD_COMPONENT_ATTACHMENT_PREFIX}"`,
+    );
+  }
+  const attachmentName = trimmed.slice(DISCORD_COMPONENT_ATTACHMENT_PREFIX.length).trim();
+  if (!attachmentName) {
+    throw new Error("Attachment reference must include a filename");
+  }
+  return attachmentName;
+}
+
+function mapButtonStyle(style?: DiscordComponentButtonStyle): ButtonStyle {
+  switch ((style ?? "primary").toLowerCase()) {
+    case "secondary":
+      return ButtonStyle.Secondary;
+    case "success":
+      return ButtonStyle.Success;
+    case "danger":
+      return ButtonStyle.Danger;
+    case "link":
+      return ButtonStyle.Link;
+    case "primary":
+    default:
+      return ButtonStyle.Primary;
+  }
+}
+
+function mapTextInputStyle(style?: DiscordModalFieldSpec["style"]) {
+  return style === "paragraph" ? TextInputStyle.Paragraph : TextInputStyle.Short;
+}
+
+function normalizeBlockType(raw: string) {
+  const lowered = raw.trim().toLowerCase();
+  return BLOCK_ALIASES.get(lowered) ?? (lowered as DiscordComponentBlock["type"]);
+}
+
+function parseSelectOptions(
+  raw: unknown,
+  label: string,
+): DiscordComponentSelectOption[] | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error(`${label} must be an array`);
+  }
+  return raw.map((entry, index) => {
+    const obj = requireObject(entry, `${label}[${index}]`);
+    return {
+      label: readString(obj.label, `${label}[${index}].label`),
+      value: readString(obj.value, `${label}[${index}].value`),
+      description: readOptionalString(obj.description),
+      emoji:
+        typeof obj.emoji === "object" && obj.emoji && !Array.isArray(obj.emoji)
+          ? {
+              name: readString(
+                (obj.emoji as { name?: unknown }).name,
+                `${label}[${index}].emoji.name`,
+              ),
+              id: readOptionalString((obj.emoji as { id?: unknown }).id),
+              animated:
+                typeof (obj.emoji as { animated?: unknown }).animated === "boolean"
+                  ? (obj.emoji as { animated?: boolean }).animated
+                  : undefined,
+            }
+          : undefined,
+      default: typeof obj.default === "boolean" ? obj.default : undefined,
+    };
+  });
+}
+
+function parseButtonSpec(raw: unknown, label: string): DiscordComponentButtonSpec {
+  const obj = requireObject(raw, label);
+  const style = readOptionalString(obj.style) as DiscordComponentButtonStyle | undefined;
+  const url = readOptionalString(obj.url);
+  if ((style === "link" || url) && !url) {
+    throw new Error(`${label}.url is required for link buttons`);
+  }
+  return {
+    label: readString(obj.label, `${label}.label`),
+    style,
+    url,
+    emoji:
+      typeof obj.emoji === "object" && obj.emoji && !Array.isArray(obj.emoji)
+        ? {
+            name: readString((obj.emoji as { name?: unknown }).name, `${label}.emoji.name`),
+            id: readOptionalString((obj.emoji as { id?: unknown }).id),
+            animated:
+              typeof (obj.emoji as { animated?: unknown }).animated === "boolean"
+                ? (obj.emoji as { animated?: boolean }).animated
+                : undefined,
+          }
+        : undefined,
+    disabled: typeof obj.disabled === "boolean" ? obj.disabled : undefined,
+  };
+}
+
+function parseSelectSpec(raw: unknown, label: string): DiscordComponentSelectSpec {
+  const obj = requireObject(raw, label);
+  const type = readOptionalString(obj.type) as DiscordComponentSelectType | undefined;
+  const allowedTypes: DiscordComponentSelectType[] = [
+    "string",
+    "user",
+    "role",
+    "mentionable",
+    "channel",
+  ];
+  if (type && !allowedTypes.includes(type)) {
+    throw new Error(`${label}.type must be one of ${allowedTypes.join(", ")}`);
+  }
+  return {
+    type,
+    placeholder: readOptionalString(obj.placeholder),
+    minValues: readOptionalNumber(obj.minValues),
+    maxValues: readOptionalNumber(obj.maxValues),
+    options: parseSelectOptions(obj.options, `${label}.options`),
+  };
+}
+
+function parseModalField(raw: unknown, label: string, index: number): DiscordModalFieldSpec {
+  const obj = requireObject(raw, label);
+  const type = readString(
+    obj.type,
+    `${label}.type`,
+  ).toLowerCase() as DiscordComponentModalFieldType;
+  const supported: DiscordComponentModalFieldType[] = [
+    "text",
+    "checkbox",
+    "radio",
+    "select",
+    "role-select",
+    "user-select",
+  ];
+  if (!supported.includes(type)) {
+    throw new Error(`${label}.type must be one of ${supported.join(", ")}`);
+  }
+  const options = parseSelectOptions(obj.options, `${label}.options`);
+  if (["checkbox", "radio", "select"].includes(type) && (!options || options.length === 0)) {
+    throw new Error(`${label}.options is required for ${type} fields`);
+  }
+  return {
+    type,
+    name: normalizeModalFieldName(readOptionalString(obj.name), index),
+    label: readString(obj.label, `${label}.label`),
+    description: readOptionalString(obj.description),
+    placeholder: readOptionalString(obj.placeholder),
+    required: typeof obj.required === "boolean" ? obj.required : undefined,
+    options,
+    minValues: readOptionalNumber(obj.minValues),
+    maxValues: readOptionalNumber(obj.maxValues),
+    minLength: readOptionalNumber(obj.minLength),
+    maxLength: readOptionalNumber(obj.maxLength),
+    style: readOptionalString(obj.style) as DiscordModalFieldSpec["style"],
+  };
+}
+
+function parseComponentBlock(raw: unknown, label: string): DiscordComponentBlock {
+  const obj = requireObject(raw, label);
+  const typeRaw = readString(obj.type, `${label}.type`).toLowerCase();
+  const type = normalizeBlockType(typeRaw);
+  switch (type) {
+    case "text":
+      return {
+        type: "text",
+        text: readString(obj.text, `${label}.text`),
+      };
+    case "section": {
+      const text = readOptionalString(obj.text);
+      const textsRaw = obj.texts;
+      const texts = Array.isArray(textsRaw)
+        ? textsRaw.map((entry, idx) => readString(entry, `${label}.texts[${idx}]`))
+        : undefined;
+      if (!text && (!texts || texts.length === 0)) {
+        throw new Error(`${label}.text or ${label}.texts is required for section blocks`);
+      }
+      let accessory: DiscordComponentSectionAccessory | undefined;
+      if (obj.accessory !== undefined) {
+        const accessoryObj = requireObject(obj.accessory, `${label}.accessory`);
+        const accessoryType = readString(
+          accessoryObj.type,
+          `${label}.accessory.type`,
+        ).toLowerCase();
+        if (accessoryType === "thumbnail") {
+          accessory = {
+            type: "thumbnail",
+            url: readString(accessoryObj.url, `${label}.accessory.url`),
+          };
+        } else if (accessoryType === "button") {
+          accessory = {
+            type: "button",
+            button: parseButtonSpec(accessoryObj.button, `${label}.accessory.button`),
+          };
+        } else {
+          throw new Error(`${label}.accessory.type must be "thumbnail" or "button"`);
+        }
+      }
+      return {
+        type: "section",
+        text,
+        texts,
+        accessory,
+      };
+    }
+    case "separator": {
+      const spacingRaw = obj.spacing;
+      let spacing: DiscordComponentSeparatorSpacing | undefined;
+      if (spacingRaw === "small" || spacingRaw === "large") {
+        spacing = spacingRaw;
+      } else if (spacingRaw === 1 || spacingRaw === 2) {
+        spacing = spacingRaw;
+      } else if (spacingRaw !== undefined) {
+        throw new Error(`${label}.spacing must be "small", "large", 1, or 2`);
+      }
+      const divider = typeof obj.divider === "boolean" ? obj.divider : undefined;
+      return {
+        type: "separator",
+        spacing,
+        divider,
+      };
+    }
+    case "actions": {
+      const buttonsRaw = obj.buttons;
+      const buttons = Array.isArray(buttonsRaw)
+        ? buttonsRaw.map((entry, idx) => parseButtonSpec(entry, `${label}.buttons[${idx}]`))
+        : undefined;
+      const select = obj.select ? parseSelectSpec(obj.select, `${label}.select`) : undefined;
+      if ((!buttons || buttons.length === 0) && !select) {
+        throw new Error(`${label} requires buttons or select`);
+      }
+      if (buttons && select) {
+        throw new Error(`${label} cannot include both buttons and select`);
+      }
+      return {
+        type: "actions",
+        buttons,
+        select,
+      };
+    }
+    case "media-gallery": {
+      const itemsRaw = obj.items;
+      if (!Array.isArray(itemsRaw) || itemsRaw.length === 0) {
+        throw new Error(`${label}.items must be a non-empty array`);
+      }
+      const items = itemsRaw.map((entry, idx) => {
+        const itemObj = requireObject(entry, `${label}.items[${idx}]`);
+        return {
+          url: readString(itemObj.url, `${label}.items[${idx}].url`),
+          description: readOptionalString(itemObj.description),
+          spoiler: typeof itemObj.spoiler === "boolean" ? itemObj.spoiler : undefined,
+        };
+      });
+      return {
+        type: "media-gallery",
+        items,
+      };
+    }
+    case "file": {
+      const file = readString(obj.file, `${label}.file`);
+      return {
+        type: "file",
+        file: normalizeAttachmentRef(file, `${label}.file`),
+        spoiler: typeof obj.spoiler === "boolean" ? obj.spoiler : undefined,
+      };
+    }
+    default:
+      throw new Error(`${label}.type must be a supported component block`);
+  }
+}
+
+export function readDiscordComponentSpec(raw: unknown): DiscordComponentMessageSpec | null {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  const obj = requireObject(raw, "components");
+  const blocksRaw = obj.blocks;
+  const blocks = Array.isArray(blocksRaw)
+    ? blocksRaw.map((entry, idx) => parseComponentBlock(entry, `components.blocks[${idx}]`))
+    : undefined;
+  const modalRaw = obj.modal;
+  let modal: DiscordModalSpec | undefined;
+  if (modalRaw !== undefined) {
+    const modalObj = requireObject(modalRaw, "components.modal");
+    const fieldsRaw = modalObj.fields;
+    if (!Array.isArray(fieldsRaw) || fieldsRaw.length === 0) {
+      throw new Error("components.modal.fields must be a non-empty array");
+    }
+    if (fieldsRaw.length > 5) {
+      throw new Error("components.modal.fields supports up to 5 inputs");
+    }
+    const fields = fieldsRaw.map((entry, idx) =>
+      parseModalField(entry, `components.modal.fields[${idx}]`, idx),
+    );
+    modal = {
+      title: readString(modalObj.title, "components.modal.title"),
+      triggerLabel: readOptionalString(modalObj.triggerLabel),
+      triggerStyle: readOptionalString(modalObj.triggerStyle) as DiscordComponentButtonStyle,
+      fields,
+    };
+  }
+  return {
+    text: readOptionalString(obj.text),
+    container:
+      typeof obj.container === "object" && obj.container && !Array.isArray(obj.container)
+        ? {
+            accentColor: (obj.container as { accentColor?: unknown }).accentColor as
+              | string
+              | number
+              | undefined,
+            spoiler:
+              typeof (obj.container as { spoiler?: unknown }).spoiler === "boolean"
+                ? ((obj.container as { spoiler?: boolean }).spoiler as boolean)
+                : undefined,
+          }
+        : undefined,
+    blocks,
+    modal,
+  };
+}
+
+export function buildDiscordComponentCustomId(params: {
+  componentId: string;
+  modalId?: string;
+}): string {
+  const base = `${DISCORD_COMPONENT_CUSTOM_ID_KEY}:cid=${params.componentId}`;
+  return params.modalId ? `${base};mid=${params.modalId}` : base;
+}
+
+export function buildDiscordModalCustomId(modalId: string): string {
+  return `${DISCORD_MODAL_CUSTOM_ID_KEY}:mid=${modalId}`;
+}
+
+export function parseDiscordComponentCustomId(
+  id: string,
+): { componentId: string; modalId?: string } | null {
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_COMPONENT_CUSTOM_ID_KEY) {
+    return null;
+  }
+  const componentId = parsed.data.cid;
+  if (typeof componentId !== "string" || !componentId.trim()) {
+    return null;
+  }
+  const modalId = parsed.data.mid;
+  return {
+    componentId,
+    modalId: typeof modalId === "string" && modalId.trim() ? modalId : undefined,
+  };
+}
+
+export function parseDiscordModalCustomId(id: string): string | null {
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_MODAL_CUSTOM_ID_KEY) {
+    return null;
+  }
+  const modalId = parsed.data.mid;
+  if (typeof modalId !== "string" || !modalId.trim()) {
+    return null;
+  }
+  return modalId;
+}
+
+export function parseDiscordComponentCustomIdForCarbon(id: string): ComponentParserResult {
+  if (id === "*") {
+    return { key: "*", data: {} };
+  }
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_COMPONENT_CUSTOM_ID_KEY) {
+    return parsed;
+  }
+  return { key: "*", data: parsed.data };
+}
+
+export function parseDiscordModalCustomIdForCarbon(id: string): ComponentParserResult {
+  if (id === "*") {
+    return { key: "*", data: {} };
+  }
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_MODAL_CUSTOM_ID_KEY) {
+    return parsed;
+  }
+  return { key: "*", data: parsed.data };
+}
+
+function buildTextDisplays(text?: string, texts?: string[]): TextDisplay[] {
+  if (texts && texts.length > 0) {
+    return texts.map((entry) => new TextDisplay(entry));
+  }
+  if (text) {
+    return [new TextDisplay(text)];
+  }
+  return [];
+}
+
+function createButtonComponent(params: {
+  spec: DiscordComponentButtonSpec;
+  componentId?: string;
+  modalId?: string;
+}): { component: Button | LinkButton; entry?: DiscordComponentEntry } {
+  const style = mapButtonStyle(params.spec.style);
+  const isLink = style === ButtonStyle.Link || Boolean(params.spec.url);
+  if (isLink) {
+    if (!params.spec.url) {
+      throw new Error("Link buttons require a url");
+    }
+    const linkUrl = params.spec.url;
+    class DynamicLinkButton extends LinkButton {
+      label = params.spec.label;
+      url = linkUrl;
+    }
+    return { component: new DynamicLinkButton() };
+  }
+  const componentId = params.componentId ?? createShortId("btn_");
+  const customId = buildDiscordComponentCustomId({
+    componentId,
+    modalId: params.modalId,
+  });
+  class DynamicButton extends Button {
+    label = params.spec.label;
+    customId = customId;
+    style = style;
+    emoji = params.spec.emoji;
+    disabled = params.spec.disabled ?? false;
+  }
+  return {
+    component: new DynamicButton(),
+    entry: {
+      id: componentId,
+      kind: params.modalId ? "modal-trigger" : "button",
+      label: params.spec.label,
+      modalId: params.modalId,
+    },
+  };
+}
+
+function createSelectComponent(params: {
+  spec: DiscordComponentSelectSpec;
+  componentId?: string;
+}): {
+  component:
+    | StringSelectMenu
+    | UserSelectMenu
+    | RoleSelectMenu
+    | MentionableSelectMenu
+    | ChannelSelectMenu;
+  entry: DiscordComponentEntry;
+} {
+  const type = (params.spec.type ?? "string").toLowerCase() as DiscordComponentSelectType;
+  const componentId = params.componentId ?? createShortId("sel_");
+  const customId = buildDiscordComponentCustomId({ componentId });
+  if (type === "string") {
+    const options = params.spec.options ?? [];
+    if (options.length === 0) {
+      throw new Error("String select menus require options");
+    }
+    class DynamicStringSelect extends StringSelectMenu {
+      customId = customId;
+      options = options;
+      minValues = params.spec.minValues;
+      maxValues = params.spec.maxValues;
+      placeholder = params.spec.placeholder;
+      disabled = false;
+    }
+    return {
+      component: new DynamicStringSelect(),
+      entry: {
+        id: componentId,
+        kind: "select",
+        label: params.spec.placeholder ?? "select",
+        selectType: "string",
+        options: options.map((option) => ({ value: option.value, label: option.label })),
+      },
+    };
+  }
+  if (type === "user") {
+    class DynamicUserSelect extends UserSelectMenu {
+      customId = customId;
+      minValues = params.spec.minValues;
+      maxValues = params.spec.maxValues;
+      placeholder = params.spec.placeholder;
+      disabled = false;
+    }
+    return {
+      component: new DynamicUserSelect(),
+      entry: {
+        id: componentId,
+        kind: "select",
+        label: params.spec.placeholder ?? "user select",
+        selectType: "user",
+      },
+    };
+  }
+  if (type === "role") {
+    class DynamicRoleSelect extends RoleSelectMenu {
+      customId = customId;
+      minValues = params.spec.minValues;
+      maxValues = params.spec.maxValues;
+      placeholder = params.spec.placeholder;
+      disabled = false;
+    }
+    return {
+      component: new DynamicRoleSelect(),
+      entry: {
+        id: componentId,
+        kind: "select",
+        label: params.spec.placeholder ?? "role select",
+        selectType: "role",
+      },
+    };
+  }
+  if (type === "mentionable") {
+    class DynamicMentionableSelect extends MentionableSelectMenu {
+      customId = customId;
+      minValues = params.spec.minValues;
+      maxValues = params.spec.maxValues;
+      placeholder = params.spec.placeholder;
+      disabled = false;
+    }
+    return {
+      component: new DynamicMentionableSelect(),
+      entry: {
+        id: componentId,
+        kind: "select",
+        label: params.spec.placeholder ?? "mentionable select",
+        selectType: "mentionable",
+      },
+    };
+  }
+  class DynamicChannelSelect extends ChannelSelectMenu {
+    customId = customId;
+    minValues = params.spec.minValues;
+    maxValues = params.spec.maxValues;
+    placeholder = params.spec.placeholder;
+    disabled = false;
+  }
+  return {
+    component: new DynamicChannelSelect(),
+    entry: {
+      id: componentId,
+      kind: "select",
+      label: params.spec.placeholder ?? "channel select",
+      selectType: "channel",
+    },
+  };
+}
+
+function isSelectComponent(
+  component: unknown,
+): component is
+  | StringSelectMenu
+  | UserSelectMenu
+  | RoleSelectMenu
+  | MentionableSelectMenu
+  | ChannelSelectMenu {
+  return (
+    component instanceof StringSelectMenu ||
+    component instanceof UserSelectMenu ||
+    component instanceof RoleSelectMenu ||
+    component instanceof MentionableSelectMenu ||
+    component instanceof ChannelSelectMenu
+  );
+}
+
+function createModalFieldComponent(
+  field: DiscordModalFieldDefinition,
+): TextInput | StringSelectMenu | UserSelectMenu | RoleSelectMenu | CheckboxGroup | RadioGroup {
+  if (field.type === "text") {
+    class DynamicTextInput extends TextInput {
+      customId = field.id;
+      style = mapTextInputStyle(field.style);
+      placeholder = field.placeholder;
+      required = field.required;
+      minLength = field.minLength;
+      maxLength = field.maxLength;
+    }
+    return new DynamicTextInput();
+  }
+  if (field.type === "select") {
+    const options = field.options ?? [];
+    class DynamicModalSelect extends StringSelectMenu {
+      customId = field.id;
+      options = options;
+      required = field.required;
+      minValues = field.minValues;
+      maxValues = field.maxValues;
+      placeholder = field.placeholder;
+    }
+    return new DynamicModalSelect();
+  }
+  if (field.type === "role-select") {
+    class DynamicModalRoleSelect extends RoleSelectMenu {
+      customId = field.id;
+      required = field.required;
+      minValues = field.minValues;
+      maxValues = field.maxValues;
+      placeholder = field.placeholder;
+    }
+    return new DynamicModalRoleSelect();
+  }
+  if (field.type === "user-select") {
+    class DynamicModalUserSelect extends UserSelectMenu {
+      customId = field.id;
+      required = field.required;
+      minValues = field.minValues;
+      maxValues = field.maxValues;
+      placeholder = field.placeholder;
+    }
+    return new DynamicModalUserSelect();
+  }
+  if (field.type === "checkbox") {
+    const options = field.options ?? [];
+    class DynamicCheckboxGroup extends CheckboxGroup {
+      customId = field.id;
+      options = options;
+      required = field.required;
+      minValues = field.minValues;
+      maxValues = field.maxValues;
+    }
+    return new DynamicCheckboxGroup();
+  }
+  const options = field.options ?? [];
+  class DynamicRadioGroup extends RadioGroup {
+    customId = field.id;
+    options = options;
+    required = field.required;
+    minValues = field.minValues;
+    maxValues = field.maxValues;
+  }
+  return new DynamicRadioGroup();
+}
+
+export function buildDiscordComponentMessage(params: {
+  spec: DiscordComponentMessageSpec;
+  fallbackText?: string;
+  sessionKey?: string;
+  agentId?: string;
+  accountId?: string;
+}): DiscordComponentBuildResult {
+  const entries: DiscordComponentEntry[] = [];
+  const modals: DiscordModalEntry[] = [];
+  const components: TopLevelComponents[] = [];
+  const containerChildren: Array<
+    | Row<
+        | Button
+        | LinkButton
+        | StringSelectMenu
+        | UserSelectMenu
+        | RoleSelectMenu
+        | MentionableSelectMenu
+        | ChannelSelectMenu
+      >
+    | TextDisplay
+    | Section
+    | MediaGallery
+    | Separator
+    | File
+  > = [];
+
+  const addEntry = (entry: DiscordComponentEntry) => {
+    entries.push({
+      ...entry,
+      sessionKey: params.sessionKey,
+      agentId: params.agentId,
+      accountId: params.accountId,
+    });
+  };
+
+  const text = params.spec.text ?? params.fallbackText;
+  if (text) {
+    containerChildren.push(new TextDisplay(text));
+  }
+
+  for (const block of params.spec.blocks ?? []) {
+    if (block.type === "text") {
+      containerChildren.push(new TextDisplay(block.text));
+      continue;
+    }
+    if (block.type === "section") {
+      const displays = buildTextDisplays(block.text, block.texts);
+      if (displays.length > 3) {
+        throw new Error("Section blocks support up to 3 text displays");
+      }
+      let accessory: Thumbnail | Button | LinkButton | undefined;
+      if (block.accessory?.type === "thumbnail") {
+        accessory = new Thumbnail(block.accessory.url);
+      } else if (block.accessory?.type === "button") {
+        const { component, entry } = createButtonComponent({ spec: block.accessory.button });
+        accessory = component;
+        if (entry) {
+          addEntry(entry);
+        }
+      }
+      containerChildren.push(new Section(displays, accessory));
+      continue;
+    }
+    if (block.type === "separator") {
+      containerChildren.push(new Separator({ spacing: block.spacing, divider: block.divider }));
+      continue;
+    }
+    if (block.type === "media-gallery") {
+      containerChildren.push(new MediaGallery(block.items));
+      continue;
+    }
+    if (block.type === "file") {
+      containerChildren.push(new File(block.file, block.spoiler));
+      continue;
+    }
+    if (block.type === "actions") {
+      const rowComponents: Array<
+        | Button
+        | LinkButton
+        | StringSelectMenu
+        | UserSelectMenu
+        | RoleSelectMenu
+        | MentionableSelectMenu
+        | ChannelSelectMenu
+      > = [];
+      if (block.buttons) {
+        if (block.buttons.length > 5) {
+          throw new Error("Action rows support up to 5 buttons");
+        }
+        for (const button of block.buttons) {
+          const { component, entry } = createButtonComponent({ spec: button });
+          rowComponents.push(component);
+          if (entry) {
+            addEntry(entry);
+          }
+        }
+      } else if (block.select) {
+        const { component, entry } = createSelectComponent({ spec: block.select });
+        rowComponents.push(component);
+        addEntry(entry);
+      }
+      containerChildren.push(new Row(rowComponents));
+    }
+  }
+
+  if (params.spec.modal) {
+    const modalId = createShortId("mdl_");
+    const fields = params.spec.modal.fields.map((field, index) => ({
+      id: createShortId("fld_"),
+      name: normalizeModalFieldName(field.name, index),
+      label: field.label,
+      type: field.type,
+      description: field.description,
+      placeholder: field.placeholder,
+      required: field.required,
+      options: field.options,
+      minValues: field.minValues,
+      maxValues: field.maxValues,
+      minLength: field.minLength,
+      maxLength: field.maxLength,
+      style: field.style,
+    }));
+    modals.push({
+      id: modalId,
+      title: params.spec.modal.title,
+      fields,
+      sessionKey: params.sessionKey,
+      agentId: params.agentId,
+      accountId: params.accountId,
+    });
+
+    const triggerSpec: DiscordComponentButtonSpec = {
+      label: params.spec.modal.triggerLabel ?? "Open form",
+      style: params.spec.modal.triggerStyle ?? "primary",
+    };
+
+    const { component, entry } = createButtonComponent({
+      spec: triggerSpec,
+      modalId,
+    });
+
+    if (entry) {
+      addEntry(entry);
+    }
+
+    const lastChild = containerChildren.at(-1);
+    if (lastChild instanceof Row) {
+      const row = lastChild;
+      const hasSelect = row.components.some((entry) => isSelectComponent(entry));
+      if (row.components.length < 5 && !hasSelect) {
+        row.addComponent(component as Button);
+      } else {
+        containerChildren.push(new Row([component as Button]));
+      }
+    } else {
+      containerChildren.push(new Row([component as Button]));
+    }
+  }
+
+  if (containerChildren.length === 0) {
+    throw new Error("components must include at least one block, text, or modal trigger");
+  }
+
+  const container = new Container(containerChildren, params.spec.container);
+  components.push(container);
+  return { components, entries, modals };
+}
+
+export function buildDiscordComponentMessageFlags(
+  components: TopLevelComponents[],
+): number | undefined {
+  const hasV2 = components.some((component) => component.isV2);
+  return hasV2 ? MessageFlags.IsComponentsV2 : undefined;
+}
+
+export class DiscordFormModal extends Modal {
+  title: string;
+  customId: string;
+  components: Array<Label | TextDisplay>;
+  customIdParser = parseDiscordModalCustomIdForCarbon;
+
+  constructor(params: { modalId: string; title: string; fields: DiscordModalFieldDefinition[] }) {
+    super();
+    this.title = params.title;
+    this.customId = buildDiscordModalCustomId(params.modalId);
+    this.components = params.fields.map((field) => {
+      const component = createModalFieldComponent(field);
+      class DynamicLabel extends Label {
+        label = field.label;
+        description = field.description;
+        component = component;
+        customId = field.id;
+      }
+      return new DynamicLabel(component);
+    });
+  }
+
+  async run(): Promise<void> {
+    throw new Error("Modal handler is not registered for dynamic forms");
+  }
+}
+
+export function createDiscordFormModal(entry: DiscordModalEntry): Modal {
+  return new DiscordFormModal({
+    modalId: entry.id,
+    title: entry.title,
+    fields: entry.fields,
+  });
+}
+
+export function formatDiscordComponentEventText(params: {
+  kind: "button" | "select";
+  label: string;
+  values?: string[];
+}): string {
+  if (params.kind === "button") {
+    return `Clicked "${params.label}".`;
+  }
+  const values = params.values ?? [];
+  if (values.length === 0) {
+    return `Updated "${params.label}".`;
+  }
+  return `Selected ${values.join(", ")} from "${params.label}".`;
+}
diff --git a/src/discord/monitor/agent-components.test.ts b/src/discord/monitor/agent-components.test.ts
deleted file mode 100644
index ea19695dc63..00000000000
--- a/src/discord/monitor/agent-components.test.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import type { ButtonInteraction, ComponentData, StringSelectMenuInteraction } from "@buape/carbon";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { createAgentComponentButton, createAgentSelectMenu } from "./agent-components.js";
-
-const readAllowFromStoreMock = vi.hoisted(() => vi.fn());
-const upsertPairingRequestMock = vi.hoisted(() => vi.fn());
-const enqueueSystemEventMock = vi.hoisted(() => vi.fn());
-
-vi.mock("../../pairing/pairing-store.js", () => ({
-  readChannelAllowFromStore: (...args: unknown[]) => readAllowFromStoreMock(...args),
-  upsertChannelPairingRequest: (...args: unknown[]) => upsertPairingRequestMock(...args),
-}));
-
-vi.mock("../../infra/system-events.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../infra/system-events.js")>();
-  return {
-    ...actual,
-    enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
-  };
-});
-
-const createCfg = (): OpenClawConfig => ({}) as OpenClawConfig;
-
-const createDmButtonInteraction = (overrides: Partial<ButtonInteraction> = {}) => {
-  const reply = vi.fn().mockResolvedValue(undefined);
-  const defer = vi.fn().mockResolvedValue(undefined);
-  const interaction = {
-    rawData: { channel_id: "dm-channel" },
-    user: { id: "123456789", username: "Alice", discriminator: "1234" },
-    defer,
-    reply,
-    ...overrides,
-  } as unknown as ButtonInteraction;
-  return { interaction, defer, reply };
-};
-
-const createDmSelectInteraction = (overrides: Partial<StringSelectMenuInteraction> = {}) => {
-  const reply = vi.fn().mockResolvedValue(undefined);
-  const defer = vi.fn().mockResolvedValue(undefined);
-  const interaction = {
-    rawData: { channel_id: "dm-channel" },
-    user: { id: "123456789", username: "Alice", discriminator: "1234" },
-    values: ["alpha"],
-    defer,
-    reply,
-    ...overrides,
-  } as unknown as StringSelectMenuInteraction;
-  return { interaction, defer, reply };
-};
-
-beforeEach(() => {
-  readAllowFromStoreMock.mockReset().mockResolvedValue([]);
-  upsertPairingRequestMock.mockReset().mockResolvedValue({ code: "PAIRCODE", created: true });
-  enqueueSystemEventMock.mockReset();
-});
-
-describe("agent components", () => {
-  it("sends pairing reply when DM sender is not allowlisted", async () => {
-    const button = createAgentComponentButton({
-      cfg: createCfg(),
-      accountId: "default",
-      dmPolicy: "pairing",
-    });
-    const { interaction, defer, reply } = createDmButtonInteraction();
-
-    await button.run(interaction, { componentId: "hello" } as ComponentData);
-
-    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
-    expect(reply).toHaveBeenCalledTimes(1);
-    expect(reply.mock.calls[0]?.[0]?.content).toContain("Pairing code: PAIRCODE");
-    expect(enqueueSystemEventMock).not.toHaveBeenCalled();
-  });
-
-  it("allows DM interactions when pairing store allowlist matches", async () => {
-    readAllowFromStoreMock.mockResolvedValue(["123456789"]);
-    const button = createAgentComponentButton({
-      cfg: createCfg(),
-      accountId: "default",
-      dmPolicy: "allowlist",
-    });
-    const { interaction, defer, reply } = createDmButtonInteraction();
-
-    await button.run(interaction, { componentId: "hello" } as ComponentData);
-
-    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
-    expect(reply).toHaveBeenCalledWith({ content: "✓" });
-    expect(enqueueSystemEventMock).toHaveBeenCalled();
-  });
-
-  it("matches tag-based allowlist entries for DM select menus", async () => {
-    const select = createAgentSelectMenu({
-      cfg: createCfg(),
-      accountId: "default",
-      dmPolicy: "allowlist",
-      allowFrom: ["Alice#1234"],
-    });
-    const { interaction, defer, reply } = createDmSelectInteraction();
-
-    await select.run(interaction, { componentId: "hello" } as ComponentData);
-
-    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
-    expect(reply).toHaveBeenCalledWith({ content: "✓" });
-    expect(enqueueSystemEventMock).toHaveBeenCalled();
-  });
-});
diff --git a/src/discord/monitor/agent-components.ts b/src/discord/monitor/agent-components.ts
index 898b0d419dc..87f6a3f5eaf 100644
--- a/src/discord/monitor/agent-components.ts
+++ b/src/discord/monitor/agent-components.ts
@@ -1,13 +1,34 @@
 import type { APIStringSelectComponent } from "discord-api-types/v10";
 import {
   Button,
-  type ButtonInteraction,
-  type ComponentData,
+  ChannelSelectMenu,
+  MentionableSelectMenu,
+  Modal,
+  RoleSelectMenu,
   StringSelectMenu,
+  UserSelectMenu,
+  type ButtonInteraction,
+  type ChannelSelectMenuInteraction,
+  type ComponentData,
+  type MentionableSelectMenuInteraction,
+  type ModalInteraction,
+  type RoleSelectMenuInteraction,
   type StringSelectMenuInteraction,
+  type UserSelectMenuInteraction,
 } from "@buape/carbon";
 import { ButtonStyle, ChannelType } from "discord-api-types/v10";
 import type { OpenClawConfig } from "../../config/config.js";
+import type { DiscordAccountConfig } from "../../config/types.discord.js";
+import { resolveHumanDelayConfig } from "../../agents/identity.js";
+import { resolveChunkMode, resolveTextChunkLimit } from "../../auto-reply/chunk.js";
+import { formatInboundEnvelope, resolveEnvelopeFormatOptions } from "../../auto-reply/envelope.js";
+import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
+import { dispatchReplyWithBufferedBlockDispatcher } from "../../auto-reply/reply/provider-dispatcher.js";
+import { createReplyReferencePlanner } from "../../auto-reply/reply/reply-reference.js";
+import { createReplyPrefixOptions } from "../../channels/reply-prefix.js";
+import { recordInboundSession } from "../../channels/session.js";
+import { resolveMarkdownTableMode } from "../../config/markdown-tables.js";
+import { readSessionUpdatedAt, resolveStorePath } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
 import { enqueueSystemEvent } from "../../infra/system-events.js";
 import { logDebug, logError } from "../../logger.js";
@@ -17,6 +38,18 @@ import {
   upsertChannelPairingRequest,
 } from "../../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { createNonExitingRuntime, type RuntimeEnv } from "../../runtime.js";
+import { resolveDiscordComponentEntry, resolveDiscordModalEntry } from "../components-registry.js";
+import {
+  createDiscordFormModal,
+  formatDiscordComponentEventText,
+  parseDiscordComponentCustomId,
+  parseDiscordComponentCustomIdForCarbon,
+  parseDiscordModalCustomId,
+  parseDiscordModalCustomIdForCarbon,
+  type DiscordComponentEntry,
+  type DiscordModalEntry,
+} from "../components.js";
 import {
   type DiscordGuildEntryResolved,
   normalizeDiscordAllowList,
@@ -24,16 +57,28 @@ import {
   resolveDiscordAllowListMatch,
   resolveDiscordChannelConfigWithFallback,
   resolveDiscordGuildEntry,
-  resolveDiscordMemberAllowed,
+  resolveDiscordMemberAccessState,
+  resolveDiscordOwnerAllowFrom,
 } from "./allow-list.js";
 import { formatDiscordUserTag } from "./format.js";
+import { buildDirectLabel, buildGuildLabel } from "./reply-context.js";
+import { deliverDiscordReply } from "./reply-delivery.js";
+import { sendTyping } from "./typing.js";
 
 const AGENT_BUTTON_KEY = "agent";
 const AGENT_SELECT_KEY = "agentsel";
 
 type DiscordUser = Parameters<typeof formatDiscordUserTag>[0];
 
-type AgentComponentInteraction = ButtonInteraction | StringSelectMenuInteraction;
+type AgentComponentMessageInteraction =
+  | ButtonInteraction
+  | StringSelectMenuInteraction
+  | RoleSelectMenuInteraction
+  | UserSelectMenuInteraction
+  | MentionableSelectMenuInteraction
+  | ChannelSelectMenuInteraction;
+
+type AgentComponentInteraction = AgentComponentMessageInteraction | ModalInteraction;
 
 type ComponentInteractionContext = NonNullable<
   Awaited<ReturnType<typeof resolveComponentInteractionContext>>
@@ -49,6 +94,44 @@ type DiscordChannelContext = {
   parentSlug: string;
 };
 
+function resolveAgentComponentRoute(params: {
+  ctx: AgentComponentContext;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  isDirectMessage: boolean;
+  userId: string;
+  channelId: string;
+  parentId: string | undefined;
+}) {
+  return resolveAgentRoute({
+    cfg: params.ctx.cfg,
+    channel: "discord",
+    accountId: params.ctx.accountId,
+    guildId: params.rawGuildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : "channel",
+      id: params.isDirectMessage ? params.userId : params.channelId,
+    },
+    parentPeer: params.parentId ? { kind: "channel", id: params.parentId } : undefined,
+  });
+}
+
+async function ackComponentInteraction(params: {
+  interaction: AgentComponentInteraction;
+  replyOpts: { ephemeral?: boolean };
+  label: string;
+}) {
+  try {
+    await params.interaction.reply({
+      content: "✓",
+      ...params.replyOpts,
+    });
+  } catch (err) {
+    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
+  }
+}
+
 function resolveDiscordChannelContext(
   interaction: AgentComponentInteraction,
 ): DiscordChannelContext {
@@ -78,6 +161,7 @@ function resolveDiscordChannelContext(
 async function resolveComponentInteractionContext(params: {
   interaction: AgentComponentInteraction;
   label: string;
+  defer?: boolean;
 }): Promise<{
   channelId: string;
   user: DiscordUser;
@@ -104,15 +188,18 @@ async function resolveComponentInteractionContext(params: {
     return null;
   }
 
+  const shouldDefer = params.defer !== false && "defer" in interaction;
   let didDefer = false;
   // Defer immediately to satisfy Discord's 3-second interaction ACK requirement.
   // We use an ephemeral deferred reply so subsequent interaction.reply() calls
   // can safely edit the original deferred response.
-  try {
-    await interaction.defer({ ephemeral: true });
-    didDefer = true;
-  } catch (err) {
-    logError(`${label}: failed to defer interaction: ${String(err)}`);
+  if (shouldDefer) {
+    try {
+      await (interaction as AgentComponentMessageInteraction).defer({ ephemeral: true });
+      didDefer = true;
+    } catch (err) {
+      logError(`${label}: failed to defer interaction: ${String(err)}`);
+    }
   }
   const replyOpts = didDefer ? {} : { ephemeral: true };
 
@@ -179,15 +266,15 @@ async function ensureGuildComponentMemberAllowed(params: {
     scope: channelCtx.isThread ? "thread" : "channel",
   });
 
-  const channelUsers = channelConfig?.users ?? guildInfo?.users;
-  const channelRoles = channelConfig?.roles ?? guildInfo?.roles;
-  const memberAllowed = resolveDiscordMemberAllowed({
-    userAllowList: channelUsers,
-    roleAllowList: channelRoles,
+  const { memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
     memberRoleIds,
-    userId: user.id,
-    userName: user.username,
-    userTag: user.discriminator ? `${user.username}#${user.discriminator}` : undefined,
+    sender: {
+      id: user.id,
+      name: user.username,
+      tag: user.discriminator ? `${user.username}#${user.discriminator}` : undefined,
+    },
   });
   if (memberAllowed) {
     return true;
@@ -205,9 +292,46 @@ async function ensureGuildComponentMemberAllowed(params: {
   return false;
 }
 
+async function ensureAgentComponentInteractionAllowed(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  channelId: string;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  user: DiscordUser;
+  replyOpts: { ephemeral?: boolean };
+  componentLabel: string;
+  unauthorizedReply: string;
+}): Promise<{ parentId: string | undefined } | null> {
+  const guildInfo = resolveDiscordGuildEntry({
+    guild: params.interaction.guild ?? undefined,
+    guildEntries: params.ctx.guildEntries,
+  });
+  const channelCtx = resolveDiscordChannelContext(params.interaction);
+  const memberAllowed = await ensureGuildComponentMemberAllowed({
+    interaction: params.interaction,
+    guildInfo,
+    channelId: params.channelId,
+    rawGuildId: params.rawGuildId,
+    channelCtx,
+    memberRoleIds: params.memberRoleIds,
+    user: params.user,
+    replyOpts: params.replyOpts,
+    componentLabel: params.componentLabel,
+    unauthorizedReply: params.unauthorizedReply,
+  });
+  if (!memberAllowed) {
+    return null;
+  }
+  return { parentId: channelCtx.parentId };
+}
+
 export type AgentComponentContext = {
   cfg: OpenClawConfig;
   accountId: string;
+  discordConfig?: DiscordAccountConfig;
+  runtime?: RuntimeEnv;
+  token?: string;
   guildEntries?: Record<string, DiscordGuildEntryResolved>;
   /** DM allowlist (from allowFrom config; legacy: dm.allowFrom) */
   allowFrom?: Array<string | number>;
@@ -358,10 +482,12 @@ async function resolveInteractionContextWithDmAuth(params: {
   interaction: AgentComponentInteraction;
   label: string;
   componentLabel: string;
+  defer?: boolean;
 }): Promise<ComponentInteractionContext | null> {
   const interactionCtx = await resolveComponentInteractionContext({
     interaction: params.interaction,
     label: params.label,
+    defer: params.defer,
   });
   if (!interactionCtx) {
     return null;
@@ -381,6 +507,602 @@ async function resolveInteractionContextWithDmAuth(params: {
   return interactionCtx;
 }
 
+function normalizeComponentId(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+}
+
+function parseDiscordComponentData(
+  data: ComponentData,
+  customId?: string,
+): { componentId: string; modalId?: string } | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const rawComponentId =
+    "cid" in data
+      ? (data as { cid?: unknown }).cid
+      : (data as { componentId?: unknown }).componentId;
+  const rawModalId =
+    "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
+  let componentId = normalizeComponentId(rawComponentId);
+  let modalId = normalizeComponentId(rawModalId);
+  if (!componentId && customId) {
+    const parsed = parseDiscordComponentCustomId(customId);
+    if (parsed) {
+      componentId = parsed.componentId;
+      modalId = parsed.modalId;
+    }
+  }
+  if (!componentId) {
+    return null;
+  }
+  return { componentId, modalId };
+}
+
+function parseDiscordModalId(data: ComponentData, customId?: string): string | null {
+  if (data && typeof data === "object") {
+    const rawModalId =
+      "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
+    const modalId = normalizeComponentId(rawModalId);
+    if (modalId) {
+      return modalId;
+    }
+  }
+  if (customId) {
+    return parseDiscordModalCustomId(customId);
+  }
+  return null;
+}
+
+function resolveInteractionCustomId(interaction: AgentComponentInteraction): string | undefined {
+  if (!interaction?.rawData || typeof interaction.rawData !== "object") {
+    return undefined;
+  }
+  if (!("data" in interaction.rawData)) {
+    return undefined;
+  }
+  const data = (interaction.rawData as { data?: { custom_id?: unknown } }).data;
+  const customId = data?.custom_id;
+  if (typeof customId !== "string") {
+    return undefined;
+  }
+  const trimmed = customId.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function mapOptionLabels(
+  options: Array<{ value: string; label: string }> | undefined,
+  values: string[],
+) {
+  if (!options || options.length === 0) {
+    return values;
+  }
+  const map = new Map(options.map((option) => [option.value, option.label]));
+  return values.map((value) => map.get(value) ?? value);
+}
+
+function mapSelectValues(entry: DiscordComponentEntry, values: string[]): string[] {
+  if (entry.selectType === "string") {
+    return mapOptionLabels(entry.options, values);
+  }
+  if (entry.selectType === "user") {
+    return values.map((value) => `user:${value}`);
+  }
+  if (entry.selectType === "role") {
+    return values.map((value) => `role:${value}`);
+  }
+  if (entry.selectType === "mentionable") {
+    return values.map((value) => `mentionable:${value}`);
+  }
+  if (entry.selectType === "channel") {
+    return values.map((value) => `channel:${value}`);
+  }
+  return values;
+}
+
+function resolveModalFieldValues(
+  field: DiscordModalEntry["fields"][number],
+  interaction: ModalInteraction,
+): string[] {
+  const fields = interaction.fields;
+  const optionLabels = field.options?.map((option) => ({
+    value: option.value,
+    label: option.label,
+  }));
+  const required = field.required === true;
+  try {
+    switch (field.type) {
+      case "text": {
+        const value = required ? fields.getText(field.id, true) : fields.getText(field.id);
+        return value ? [value] : [];
+      }
+      case "select":
+      case "checkbox":
+      case "radio": {
+        const values = required
+          ? fields.getStringSelect(field.id, true)
+          : (fields.getStringSelect(field.id) ?? []);
+        return mapOptionLabels(optionLabels, values);
+      }
+      case "role-select": {
+        try {
+          const roles = required
+            ? fields.getRoleSelect(field.id, true)
+            : (fields.getRoleSelect(field.id) ?? []);
+          return roles.map((role) => role.name ?? role.id);
+        } catch {
+          const values = required
+            ? fields.getStringSelect(field.id, true)
+            : (fields.getStringSelect(field.id) ?? []);
+          return values;
+        }
+      }
+      case "user-select": {
+        const users = required
+          ? fields.getUserSelect(field.id, true)
+          : (fields.getUserSelect(field.id) ?? []);
+        return users.map((user) => formatDiscordUserTag(user));
+      }
+      default:
+        return [];
+    }
+  } catch (err) {
+    logError(`agent modal: failed to read field ${field.id}: ${String(err)}`);
+    return [];
+  }
+}
+
+function formatModalSubmissionText(
+  entry: DiscordModalEntry,
+  interaction: ModalInteraction,
+): string {
+  const lines: string[] = [`Form "${entry.title}" submitted.`];
+  for (const field of entry.fields) {
+    const values = resolveModalFieldValues(field, interaction);
+    if (values.length === 0) {
+      continue;
+    }
+    lines.push(`- ${field.label}: ${values.join(", ")}`);
+  }
+  if (lines.length === 1) {
+    lines.push("- (no values)");
+  }
+  return lines.join("\n");
+}
+
+async function dispatchDiscordComponentEvent(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  interactionCtx: ComponentInteractionContext;
+  channelCtx: DiscordChannelContext;
+  guildInfo: ReturnType<typeof resolveDiscordGuildEntry>;
+  eventText: string;
+  replyToId?: string;
+  routeOverrides?: { sessionKey?: string; agentId?: string; accountId?: string };
+}): Promise<void> {
+  const { ctx, interaction, interactionCtx, channelCtx, guildInfo, eventText } = params;
+  const runtime = ctx.runtime ?? createNonExitingRuntime();
+  const route = resolveAgentRoute({
+    cfg: ctx.cfg,
+    channel: "discord",
+    accountId: ctx.accountId,
+    guildId: interactionCtx.rawGuildId,
+    memberRoleIds: interactionCtx.memberRoleIds,
+    peer: {
+      kind: interactionCtx.isDirectMessage ? "direct" : "channel",
+      id: interactionCtx.isDirectMessage ? interactionCtx.userId : interactionCtx.channelId,
+    },
+    parentPeer: channelCtx.parentId ? { kind: "channel", id: channelCtx.parentId } : undefined,
+  });
+  const sessionKey = params.routeOverrides?.sessionKey ?? route.sessionKey;
+  const agentId = params.routeOverrides?.agentId ?? route.agentId;
+  const accountId = params.routeOverrides?.accountId ?? route.accountId;
+
+  const fromLabel = interactionCtx.isDirectMessage
+    ? buildDirectLabel(interactionCtx.user)
+    : buildGuildLabel({
+        guild: interaction.guild ?? undefined,
+        channelName: channelCtx.channelName ?? interactionCtx.channelId,
+        channelId: interactionCtx.channelId,
+      });
+  const senderName = interactionCtx.user.globalName ?? interactionCtx.user.username;
+  const senderUsername = interactionCtx.user.username;
+  const senderTag = formatDiscordUserTag(interactionCtx.user);
+  const groupChannel =
+    !interactionCtx.isDirectMessage && channelCtx.channelSlug
+      ? `#${channelCtx.channelSlug}`
+      : undefined;
+  const groupSubject = interactionCtx.isDirectMessage ? undefined : groupChannel;
+  const channelConfig = resolveDiscordChannelConfigWithFallback({
+    guildInfo,
+    channelId: interactionCtx.channelId,
+    channelName: channelCtx.channelName,
+    channelSlug: channelCtx.channelSlug,
+    parentId: channelCtx.parentId,
+    parentName: channelCtx.parentName,
+    parentSlug: channelCtx.parentSlug,
+    scope: channelCtx.isThread ? "thread" : "channel",
+  });
+  const groupSystemPrompt = channelConfig?.systemPrompt?.trim() || undefined;
+  const ownerAllowFrom = resolveDiscordOwnerAllowFrom({
+    channelConfig,
+    guildInfo,
+    sender: { id: interactionCtx.user.id, name: interactionCtx.user.username, tag: senderTag },
+  });
+  const storePath = resolveStorePath(ctx.cfg.session?.store, { agentId });
+  const envelopeOptions = resolveEnvelopeFormatOptions(ctx.cfg);
+  const previousTimestamp = readSessionUpdatedAt({
+    storePath,
+    sessionKey,
+  });
+  const timestamp = Date.now();
+  const combinedBody = formatInboundEnvelope({
+    channel: "Discord",
+    from: fromLabel,
+    timestamp,
+    body: eventText,
+    chatType: interactionCtx.isDirectMessage ? "direct" : "channel",
+    senderLabel: senderName,
+    previousTimestamp,
+    envelope: envelopeOptions,
+  });
+
+  const ctxPayload = finalizeInboundContext({
+    Body: combinedBody,
+    BodyForAgent: eventText,
+    RawBody: eventText,
+    CommandBody: eventText,
+    From: interactionCtx.isDirectMessage
+      ? `discord:${interactionCtx.userId}`
+      : `discord:channel:${interactionCtx.channelId}`,
+    To: `channel:${interactionCtx.channelId}`,
+    SessionKey: sessionKey,
+    AccountId: accountId,
+    ChatType: interactionCtx.isDirectMessage ? "direct" : "channel",
+    ConversationLabel: fromLabel,
+    SenderName: senderName,
+    SenderId: interactionCtx.userId,
+    SenderUsername: senderUsername,
+    SenderTag: senderTag,
+    GroupSubject: groupSubject,
+    GroupChannel: groupChannel,
+    GroupSystemPrompt: interactionCtx.isDirectMessage ? undefined : groupSystemPrompt,
+    GroupSpace: guildInfo?.id ?? guildInfo?.slug ?? interactionCtx.rawGuildId ?? undefined,
+    OwnerAllowFrom: ownerAllowFrom,
+    Provider: "discord" as const,
+    Surface: "discord" as const,
+    WasMentioned: true,
+    CommandAuthorized: true,
+    CommandSource: "text" as const,
+    MessageSid: interaction.rawData.id,
+    Timestamp: timestamp,
+    OriginatingChannel: "discord" as const,
+    OriginatingTo: `channel:${interactionCtx.channelId}`,
+  });
+
+  await recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? sessionKey,
+    ctx: ctxPayload,
+    updateLastRoute: interactionCtx.isDirectMessage
+      ? {
+          sessionKey: route.mainSessionKey,
+          channel: "discord",
+          to: `user:${interactionCtx.userId}`,
+          accountId,
+        }
+      : undefined,
+    onRecordError: (err) => {
+      logVerbose(`discord: failed updating component session meta: ${String(err)}`);
+    },
+  });
+
+  const deliverTarget = `channel:${interactionCtx.channelId}`;
+  const typingChannelId = interactionCtx.channelId;
+  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+    cfg: ctx.cfg,
+    agentId,
+    channel: "discord",
+    accountId,
+  });
+  const tableMode = resolveMarkdownTableMode({
+    cfg: ctx.cfg,
+    channel: "discord",
+    accountId,
+  });
+  const textLimit = resolveTextChunkLimit(ctx.cfg, "discord", accountId, {
+    fallbackLimit: 2000,
+  });
+  const token = ctx.token ?? "";
+  const replyToMode =
+    ctx.discordConfig?.replyToMode ?? ctx.cfg.channels?.discord?.replyToMode ?? "off";
+  const replyReference = createReplyReferencePlanner({
+    replyToMode,
+    startId: params.replyToId,
+  });
+
+  await dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: ctx.cfg,
+    replyOptions: { onModelSelected },
+    dispatcherOptions: {
+      ...prefixOptions,
+      humanDelay: resolveHumanDelayConfig(ctx.cfg, agentId),
+      deliver: async (payload) => {
+        const replyToId = replyReference.use();
+        await deliverDiscordReply({
+          replies: [payload],
+          target: deliverTarget,
+          token,
+          accountId,
+          rest: interaction.client.rest,
+          runtime,
+          replyToId,
+          textLimit,
+          maxLinesPerMessage: ctx.discordConfig?.maxLinesPerMessage,
+          tableMode,
+          chunkMode: resolveChunkMode(ctx.cfg, "discord", accountId),
+        });
+        replyReference.markSent();
+      },
+      onReplyStart: async () => {
+        try {
+          await sendTyping({ client: interaction.client, channelId: typingChannelId });
+        } catch (err) {
+          logVerbose(`discord: typing failed for component reply: ${String(err)}`);
+        }
+      },
+      onError: (err) => {
+        logError(`discord component dispatch failed: ${String(err)}`);
+      },
+    },
+  });
+}
+
+async function handleDiscordComponentEvent(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentMessageInteraction;
+  data: ComponentData;
+  componentLabel: string;
+  values?: string[];
+  label: string;
+}): Promise<void> {
+  const parsed = parseDiscordComponentData(
+    params.data,
+    resolveInteractionCustomId(params.interaction),
+  );
+  if (!parsed) {
+    logError(`${params.label}: failed to parse component data`);
+    try {
+      await params.interaction.reply({
+        content: "This component is no longer valid.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const entry = resolveDiscordComponentEntry({ id: parsed.componentId, consume: false });
+  if (!entry) {
+    try {
+      await params.interaction.reply({
+        content: "This component has expired.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const interactionCtx = await resolveInteractionContextWithDmAuth({
+    ctx: params.ctx,
+    interaction: params.interaction,
+    label: params.label,
+    componentLabel: params.componentLabel,
+  });
+  if (!interactionCtx) {
+    return;
+  }
+  const { channelId, user, replyOpts, rawGuildId, memberRoleIds } = interactionCtx;
+  const guildInfo = resolveDiscordGuildEntry({
+    guild: params.interaction.guild ?? undefined,
+    guildEntries: params.ctx.guildEntries,
+  });
+  const channelCtx = resolveDiscordChannelContext(params.interaction);
+  const memberAllowed = await ensureGuildComponentMemberAllowed({
+    interaction: params.interaction,
+    guildInfo,
+    channelId,
+    rawGuildId,
+    channelCtx,
+    memberRoleIds,
+    user,
+    replyOpts,
+    componentLabel: params.componentLabel,
+    unauthorizedReply: `You are not authorized to use this ${params.componentLabel}.`,
+  });
+  if (!memberAllowed) {
+    return;
+  }
+
+  const consumed = resolveDiscordComponentEntry({ id: parsed.componentId });
+  if (!consumed) {
+    try {
+      await params.interaction.reply({
+        content: "This component has expired.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  if (consumed.kind === "modal-trigger") {
+    try {
+      await params.interaction.reply({
+        content: "This form is no longer available.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const values = params.values ? mapSelectValues(consumed, params.values) : undefined;
+  const eventText = formatDiscordComponentEventText({
+    kind: consumed.kind === "select" ? "select" : "button",
+    label: consumed.label,
+    values,
+  });
+
+  try {
+    await params.interaction.reply({ content: "✓", ...replyOpts });
+  } catch (err) {
+    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
+  }
+
+  await dispatchDiscordComponentEvent({
+    ctx: params.ctx,
+    interaction: params.interaction,
+    interactionCtx,
+    channelCtx,
+    guildInfo,
+    eventText,
+    replyToId: consumed.messageId ?? params.interaction.message?.id,
+    routeOverrides: {
+      sessionKey: consumed.sessionKey,
+      agentId: consumed.agentId,
+      accountId: consumed.accountId,
+    },
+  });
+}
+
+async function handleDiscordModalTrigger(params: {
+  ctx: AgentComponentContext;
+  interaction: ButtonInteraction;
+  data: ComponentData;
+  label: string;
+}): Promise<void> {
+  const parsed = parseDiscordComponentData(
+    params.data,
+    resolveInteractionCustomId(params.interaction),
+  );
+  if (!parsed) {
+    logError(`${params.label}: failed to parse modal trigger data`);
+    try {
+      await params.interaction.reply({
+        content: "This button is no longer valid.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+  const entry = resolveDiscordComponentEntry({ id: parsed.componentId, consume: false });
+  if (!entry || entry.kind !== "modal-trigger") {
+    try {
+      await params.interaction.reply({
+        content: "This button has expired.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const modalId = entry.modalId ?? parsed.modalId;
+  if (!modalId) {
+    try {
+      await params.interaction.reply({
+        content: "This form is no longer available.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const interactionCtx = await resolveInteractionContextWithDmAuth({
+    ctx: params.ctx,
+    interaction: params.interaction,
+    label: params.label,
+    componentLabel: "form",
+    defer: false,
+  });
+  if (!interactionCtx) {
+    return;
+  }
+  const { channelId, user, replyOpts, rawGuildId, memberRoleIds } = interactionCtx;
+  const guildInfo = resolveDiscordGuildEntry({
+    guild: params.interaction.guild ?? undefined,
+    guildEntries: params.ctx.guildEntries,
+  });
+  const channelCtx = resolveDiscordChannelContext(params.interaction);
+  const memberAllowed = await ensureGuildComponentMemberAllowed({
+    interaction: params.interaction,
+    guildInfo,
+    channelId,
+    rawGuildId,
+    channelCtx,
+    memberRoleIds,
+    user,
+    replyOpts,
+    componentLabel: "form",
+    unauthorizedReply: "You are not authorized to use this form.",
+  });
+  if (!memberAllowed) {
+    return;
+  }
+
+  const consumed = resolveDiscordComponentEntry({ id: parsed.componentId });
+  if (!consumed) {
+    try {
+      await params.interaction.reply({
+        content: "This form has expired.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  const resolvedModalId = consumed.modalId ?? modalId;
+  const modalEntry = resolveDiscordModalEntry({ id: resolvedModalId, consume: false });
+  if (!modalEntry) {
+    try {
+      await params.interaction.reply({
+        content: "This form has expired.",
+        ephemeral: true,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return;
+  }
+
+  try {
+    await params.interaction.showModal(createDiscordFormModal(modalEntry));
+  } catch (err) {
+    logError(`${params.label}: failed to show modal: ${String(err)}`);
+  }
+}
+
 export class AgentComponentButton extends Button {
   label = AGENT_BUTTON_KEY;
   customId = `${AGENT_BUTTON_KEY}:seed=1`;
@@ -430,42 +1152,32 @@ export class AgentComponentButton extends Button {
       memberRoleIds,
     } = interactionCtx;
 
-    // P2 FIX: Check user allowlist before processing component interaction
-    // This prevents unauthorized users from injecting system events
-    const guildInfo = resolveDiscordGuildEntry({
-      guild: interaction.guild ?? undefined,
-      guildEntries: this.ctx.guildEntries,
-    });
-    const channelCtx = resolveDiscordChannelContext(interaction);
-    const { parentId } = channelCtx;
-    const memberAllowed = await ensureGuildComponentMemberAllowed({
+    // Check user allowlist before processing component interaction
+    // This prevents unauthorized users from injecting system events.
+    const allowed = await ensureAgentComponentInteractionAllowed({
+      ctx: this.ctx,
       interaction,
-      guildInfo,
       channelId,
       rawGuildId,
-      channelCtx,
       memberRoleIds,
       user,
       replyOpts,
       componentLabel: "button",
       unauthorizedReply: "You are not authorized to use this button.",
     });
-    if (!memberAllowed) {
+    if (!allowed) {
       return;
     }
+    const { parentId } = allowed;
 
-    // Resolve route with full context (guildId, proper peer kind, parentPeer)
-    const route = resolveAgentRoute({
-      cfg: this.ctx.cfg,
-      channel: "discord",
-      accountId: this.ctx.accountId,
-      guildId: rawGuildId,
+    const route = resolveAgentComponentRoute({
+      ctx: this.ctx,
+      rawGuildId,
       memberRoleIds,
-      peer: {
-        kind: isDirectMessage ? "direct" : "channel",
-        id: isDirectMessage ? userId : channelId,
-      },
-      parentPeer: parentId ? { kind: "channel", id: parentId } : undefined,
+      isDirectMessage,
+      userId,
+      channelId,
+      parentId,
     });
 
     const eventText = `[Discord component: ${componentId} clicked by ${username} (${userId})]`;
@@ -477,15 +1189,7 @@ export class AgentComponentButton extends Button {
       contextKey: `discord:agent-button:${channelId}:${componentId}:${userId}`,
     });
 
-    // Acknowledge the interaction
-    try {
-      await interaction.reply({
-        content: "✓",
-        ...replyOpts,
-      });
-    } catch (err) {
-      logError(`agent button: failed to acknowledge interaction: ${String(err)}`);
-    }
+    await ackComponentInteraction({ interaction, replyOpts, label: "agent button" });
   }
 }
 
@@ -537,45 +1241,35 @@ export class AgentSelectMenu extends StringSelectMenu {
       memberRoleIds,
     } = interactionCtx;
 
-    // Check user allowlist before processing component interaction
-    const guildInfo = resolveDiscordGuildEntry({
-      guild: interaction.guild ?? undefined,
-      guildEntries: this.ctx.guildEntries,
-    });
-    const channelCtx = resolveDiscordChannelContext(interaction);
-    const { parentId } = channelCtx;
-    const memberAllowed = await ensureGuildComponentMemberAllowed({
+    // Check user allowlist before processing component interaction.
+    const allowed = await ensureAgentComponentInteractionAllowed({
+      ctx: this.ctx,
       interaction,
-      guildInfo,
       channelId,
       rawGuildId,
-      channelCtx,
       memberRoleIds,
       user,
       replyOpts,
       componentLabel: "select",
       unauthorizedReply: "You are not authorized to use this select menu.",
     });
-    if (!memberAllowed) {
+    if (!allowed) {
       return;
     }
+    const { parentId } = allowed;
 
     // Extract selected values
     const values = interaction.values ?? [];
     const valuesText = values.length > 0 ? ` (selected: ${values.join(", ")})` : "";
 
-    // Resolve route with full context (guildId, proper peer kind, parentPeer)
-    const route = resolveAgentRoute({
-      cfg: this.ctx.cfg,
-      channel: "discord",
-      accountId: this.ctx.accountId,
-      guildId: rawGuildId,
+    const route = resolveAgentComponentRoute({
+      ctx: this.ctx,
+      rawGuildId,
       memberRoleIds,
-      peer: {
-        kind: isDirectMessage ? "direct" : "channel",
-        id: isDirectMessage ? userId : channelId,
-      },
-      parentPeer: parentId ? { kind: "channel", id: parentId } : undefined,
+      isDirectMessage,
+      userId,
+      channelId,
+      parentId,
     });
 
     const eventText = `[Discord select menu: ${componentId} interacted by ${username} (${userId})${valuesText}]`;
@@ -587,15 +1281,260 @@ export class AgentSelectMenu extends StringSelectMenu {
       contextKey: `discord:agent-select:${channelId}:${componentId}:${userId}`,
     });
 
-    // Acknowledge the interaction
-    try {
-      await interaction.reply({
-        content: "✓",
-        ...replyOpts,
+    await ackComponentInteraction({ interaction, replyOpts, label: "agent select" });
+  }
+}
+
+class DiscordComponentButton extends Button {
+  label = "component";
+  customId = "*";
+  style = ButtonStyle.Primary;
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: ButtonInteraction, data: ComponentData): Promise<void> {
+    const parsed = parseDiscordComponentData(data, resolveInteractionCustomId(interaction));
+    if (parsed?.modalId) {
+      await handleDiscordModalTrigger({
+        ctx: this.ctx,
+        interaction,
+        data,
+        label: "discord component modal",
       });
-    } catch (err) {
-      logError(`agent select: failed to acknowledge interaction: ${String(err)}`);
+      return;
     }
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "button",
+      label: "discord component button",
+    });
+  }
+}
+
+class DiscordComponentStringSelect extends StringSelectMenu {
+  customId = "*";
+  options: APIStringSelectComponent["options"] = [];
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: StringSelectMenuInteraction, data: ComponentData): Promise<void> {
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "select menu",
+      label: "discord component select",
+      values: interaction.values ?? [],
+    });
+  }
+}
+
+class DiscordComponentUserSelect extends UserSelectMenu {
+  customId = "*";
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: UserSelectMenuInteraction, data: ComponentData): Promise<void> {
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "user select",
+      label: "discord component user select",
+      values: interaction.values ?? [],
+    });
+  }
+}
+
+class DiscordComponentRoleSelect extends RoleSelectMenu {
+  customId = "*";
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: RoleSelectMenuInteraction, data: ComponentData): Promise<void> {
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "role select",
+      label: "discord component role select",
+      values: interaction.values ?? [],
+    });
+  }
+}
+
+class DiscordComponentMentionableSelect extends MentionableSelectMenu {
+  customId = "*";
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: MentionableSelectMenuInteraction, data: ComponentData): Promise<void> {
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "mentionable select",
+      label: "discord component mentionable select",
+      values: interaction.values ?? [],
+    });
+  }
+}
+
+class DiscordComponentChannelSelect extends ChannelSelectMenu {
+  customId = "*";
+  customIdParser = parseDiscordComponentCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: ChannelSelectMenuInteraction, data: ComponentData): Promise<void> {
+    await handleDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      data,
+      componentLabel: "channel select",
+      label: "discord component channel select",
+      values: interaction.values ?? [],
+    });
+  }
+}
+
+class DiscordComponentModal extends Modal {
+  title = "OpenClaw form";
+  customId = "*";
+  components = [];
+  customIdParser = parseDiscordModalCustomIdForCarbon;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: ModalInteraction, data: ComponentData): Promise<void> {
+    const modalId = parseDiscordModalId(data, resolveInteractionCustomId(interaction));
+    if (!modalId) {
+      logError("discord component modal: missing modal id");
+      try {
+        await interaction.reply({
+          content: "This form is no longer valid.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const modalEntry = resolveDiscordModalEntry({ id: modalId, consume: false });
+    if (!modalEntry) {
+      try {
+        await interaction.reply({
+          content: "This form has expired.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const interactionCtx = await resolveInteractionContextWithDmAuth({
+      ctx: this.ctx,
+      interaction,
+      label: "discord component modal",
+      componentLabel: "form",
+      defer: false,
+    });
+    if (!interactionCtx) {
+      return;
+    }
+    const { channelId, user, replyOpts, rawGuildId, memberRoleIds } = interactionCtx;
+    const guildInfo = resolveDiscordGuildEntry({
+      guild: interaction.guild ?? undefined,
+      guildEntries: this.ctx.guildEntries,
+    });
+    const channelCtx = resolveDiscordChannelContext(interaction);
+    const memberAllowed = await ensureGuildComponentMemberAllowed({
+      interaction,
+      guildInfo,
+      channelId,
+      rawGuildId,
+      channelCtx,
+      memberRoleIds,
+      user,
+      replyOpts,
+      componentLabel: "form",
+      unauthorizedReply: "You are not authorized to use this form.",
+    });
+    if (!memberAllowed) {
+      return;
+    }
+
+    const consumed = resolveDiscordModalEntry({ id: modalId });
+    if (!consumed) {
+      try {
+        await interaction.reply({
+          content: "This form has expired.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    try {
+      await interaction.acknowledge();
+    } catch (err) {
+      logError(`discord component modal: failed to acknowledge: ${String(err)}`);
+    }
+
+    const eventText = formatModalSubmissionText(consumed, interaction);
+    await dispatchDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      interactionCtx,
+      channelCtx,
+      guildInfo,
+      eventText,
+      replyToId: consumed.messageId,
+      routeOverrides: {
+        sessionKey: consumed.sessionKey,
+        agentId: consumed.agentId,
+        accountId: consumed.accountId,
+      },
+    });
   }
 }
 
@@ -606,3 +1545,33 @@ export function createAgentComponentButton(ctx: AgentComponentContext): Button {
 export function createAgentSelectMenu(ctx: AgentComponentContext): StringSelectMenu {
   return new AgentSelectMenu(ctx);
 }
+
+export function createDiscordComponentButton(ctx: AgentComponentContext): Button {
+  return new DiscordComponentButton(ctx);
+}
+
+export function createDiscordComponentStringSelect(ctx: AgentComponentContext): StringSelectMenu {
+  return new DiscordComponentStringSelect(ctx);
+}
+
+export function createDiscordComponentUserSelect(ctx: AgentComponentContext): UserSelectMenu {
+  return new DiscordComponentUserSelect(ctx);
+}
+
+export function createDiscordComponentRoleSelect(ctx: AgentComponentContext): RoleSelectMenu {
+  return new DiscordComponentRoleSelect(ctx);
+}
+
+export function createDiscordComponentMentionableSelect(
+  ctx: AgentComponentContext,
+): MentionableSelectMenu {
+  return new DiscordComponentMentionableSelect(ctx);
+}
+
+export function createDiscordComponentChannelSelect(ctx: AgentComponentContext): ChannelSelectMenu {
+  return new DiscordComponentChannelSelect(ctx);
+}
+
+export function createDiscordComponentModal(ctx: AgentComponentContext): Modal {
+  return new DiscordComponentModal(ctx);
+}
diff --git a/src/discord/monitor/allow-list.test.ts b/src/discord/monitor/allow-list.test.ts
deleted file mode 100644
index c620bd71af1..00000000000
--- a/src/discord/monitor/allow-list.test.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { DiscordChannelConfigResolved } from "./allow-list.js";
-import {
-  resolveDiscordMemberAllowed,
-  resolveDiscordOwnerAllowFrom,
-  resolveDiscordRoleAllowed,
-} from "./allow-list.js";
-
-describe("resolveDiscordOwnerAllowFrom", () => {
-  it("returns undefined when no allowlist is configured", () => {
-    const result = resolveDiscordOwnerAllowFrom({
-      channelConfig: { allowed: true } as DiscordChannelConfigResolved,
-      sender: { id: "123" },
-    });
-
-    expect(result).toBeUndefined();
-  });
-
-  it("skips wildcard matches for owner allowFrom", () => {
-    const result = resolveDiscordOwnerAllowFrom({
-      channelConfig: { allowed: true, users: ["*"] } as DiscordChannelConfigResolved,
-      sender: { id: "123" },
-    });
-
-    expect(result).toBeUndefined();
-  });
-
-  it("returns a matching user id entry", () => {
-    const result = resolveDiscordOwnerAllowFrom({
-      channelConfig: { allowed: true, users: ["123"] } as DiscordChannelConfigResolved,
-      sender: { id: "123" },
-    });
-
-    expect(result).toEqual(["123"]);
-  });
-
-  it("returns the normalized name slug for name matches", () => {
-    const result = resolveDiscordOwnerAllowFrom({
-      channelConfig: { allowed: true, users: ["Some User"] } as DiscordChannelConfigResolved,
-      sender: { id: "999", name: "Some User" },
-    });
-
-    expect(result).toEqual(["some-user"]);
-  });
-});
-
-describe("resolveDiscordRoleAllowed", () => {
-  it("allows when no role allowlist is configured", () => {
-    const allowed = resolveDiscordRoleAllowed({
-      allowList: undefined,
-      memberRoleIds: ["role-1"],
-    });
-
-    expect(allowed).toBe(true);
-  });
-
-  it("matches role IDs only", () => {
-    const allowed = resolveDiscordRoleAllowed({
-      allowList: ["123"],
-      memberRoleIds: ["123", "456"],
-    });
-
-    expect(allowed).toBe(true);
-  });
-
-  it("does not match non-ID role entries", () => {
-    const allowed = resolveDiscordRoleAllowed({
-      allowList: ["Admin"],
-      memberRoleIds: ["Admin"],
-    });
-
-    expect(allowed).toBe(false);
-  });
-
-  it("returns false when no matching role IDs", () => {
-    const allowed = resolveDiscordRoleAllowed({
-      allowList: ["456"],
-      memberRoleIds: ["123"],
-    });
-
-    expect(allowed).toBe(false);
-  });
-});
-
-describe("resolveDiscordMemberAllowed", () => {
-  it("allows when no user or role allowlists are configured", () => {
-    const allowed = resolveDiscordMemberAllowed({
-      userAllowList: undefined,
-      roleAllowList: undefined,
-      memberRoleIds: [],
-      userId: "u1",
-    });
-
-    expect(allowed).toBe(true);
-  });
-
-  it("allows when user allowlist matches", () => {
-    const allowed = resolveDiscordMemberAllowed({
-      userAllowList: ["123"],
-      roleAllowList: ["456"],
-      memberRoleIds: ["999"],
-      userId: "123",
-    });
-
-    expect(allowed).toBe(true);
-  });
-
-  it("allows when role allowlist matches", () => {
-    const allowed = resolveDiscordMemberAllowed({
-      userAllowList: ["999"],
-      roleAllowList: ["456"],
-      memberRoleIds: ["456"],
-      userId: "123",
-    });
-
-    expect(allowed).toBe(true);
-  });
-
-  it("denies when user and role allowlists do not match", () => {
-    const allowed = resolveDiscordMemberAllowed({
-      userAllowList: ["u2"],
-      roleAllowList: ["role-2"],
-      memberRoleIds: ["role-1"],
-      userId: "u1",
-    });
-
-    expect(allowed).toBe(false);
-  });
-});
diff --git a/src/discord/monitor/allow-list.ts b/src/discord/monitor/allow-list.ts
index 452be0e4d5d..b81b0af9994 100644
--- a/src/discord/monitor/allow-list.ts
+++ b/src/discord/monitor/allow-list.ts
@@ -202,6 +202,28 @@ export function resolveDiscordMemberAllowed(params: {
   return userOk || roleOk;
 }
 
+export function resolveDiscordMemberAccessState(params: {
+  channelConfig?: DiscordChannelConfigResolved | null;
+  guildInfo?: DiscordGuildEntryResolved | null;
+  memberRoleIds: string[];
+  sender: { id: string; name?: string; tag?: string };
+}) {
+  const channelUsers = params.channelConfig?.users ?? params.guildInfo?.users;
+  const channelRoles = params.channelConfig?.roles ?? params.guildInfo?.roles;
+  const hasAccessRestrictions =
+    (Array.isArray(channelUsers) && channelUsers.length > 0) ||
+    (Array.isArray(channelRoles) && channelRoles.length > 0);
+  const memberAllowed = resolveDiscordMemberAllowed({
+    userAllowList: channelUsers,
+    roleAllowList: channelRoles,
+    memberRoleIds: params.memberRoleIds,
+    userId: params.sender.id,
+    userName: params.sender.name,
+    userTag: params.sender.tag,
+  });
+  return { channelUsers, channelRoles, hasAccessRestrictions, memberAllowed } as const;
+}
+
 export function resolveDiscordOwnerAllowFrom(params: {
   channelConfig?: DiscordChannelConfigResolved | null;
   guildInfo?: DiscordGuildEntryResolved | null;
diff --git a/src/discord/monitor/exec-approvals.test.ts b/src/discord/monitor/exec-approvals.test.ts
index 4ac2dc06e17..fdeb2b694ae 100644
--- a/src/discord/monitor/exec-approvals.test.ts
+++ b/src/discord/monitor/exec-approvals.test.ts
@@ -1,7 +1,11 @@
 import type { ButtonInteraction, ComponentData } from "@buape/carbon";
 import { Routes } from "discord-api-types/v10";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { DiscordExecApprovalConfig } from "../../config/types.discord.js";
+import { clearSessionStoreCacheForTest } from "../../config/sessions.js";
 import {
   buildExecApprovalCustomId,
   extractDiscordChannelId,
@@ -12,22 +16,38 @@ import {
   type ExecApprovalButtonContext,
 } from "./exec-approvals.js";
 
+const STORE_PATH = path.join(os.tmpdir(), "openclaw-exec-approvals-test.json");
+
+const writeStore = (store: Record<string, unknown>) => {
+  fs.writeFileSync(STORE_PATH, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  // CI runners can have coarse mtime resolution; avoid returning stale cached stores.
+  clearSessionStoreCacheForTest();
+};
+
+beforeEach(() => {
+  writeStore({});
+});
+
 // ─── Mocks ────────────────────────────────────────────────────────────────────
 
 const mockRestPost = vi.hoisted(() => vi.fn());
 const mockRestPatch = vi.hoisted(() => vi.fn());
 const mockRestDelete = vi.hoisted(() => vi.fn());
 
-vi.mock("../send.shared.js", () => ({
-  createDiscordClient: () => ({
-    rest: {
-      post: mockRestPost,
-      patch: mockRestPatch,
-      delete: mockRestDelete,
-    },
-    request: (_fn: () => Promise<unknown>, _label: string) => _fn(),
-  }),
-}));
+vi.mock("../send.shared.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../send.shared.js")>();
+  return {
+    ...actual,
+    createDiscordClient: () => ({
+      rest: {
+        post: mockRestPost,
+        patch: mockRestPatch,
+        delete: mockRestDelete,
+      },
+      request: (_fn: () => Promise<unknown>, _label: string) => _fn(),
+    }),
+  };
+});
 
 vi.mock("../../gateway/client.js", () => ({
   GatewayClient: class {
@@ -50,12 +70,12 @@ vi.mock("../../logger.js", () => ({
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function createHandler(config: DiscordExecApprovalConfig) {
+function createHandler(config: DiscordExecApprovalConfig, accountId = "default") {
   return new DiscordExecApprovalHandler({
     token: "test-token",
-    accountId: "default",
+    accountId,
     config,
-    cfg: {},
+    cfg: { session: { store: STORE_PATH } },
   });
 }
 
@@ -281,6 +301,21 @@ describe("DiscordExecApprovalHandler.shouldHandle", () => {
     );
   });
 
+  it("filters by discord account when session store includes account", () => {
+    writeStore({
+      "agent:test-agent:discord:channel:999888777": {
+        sessionId: "sess",
+        updatedAt: Date.now(),
+        origin: { provider: "discord", accountId: "secondary" },
+        lastAccountId: "secondary",
+      },
+    });
+    const handler = createHandler({ enabled: true, approvers: ["123"] }, "default");
+    expect(handler.shouldHandle(createRequest())).toBe(false);
+    const matching = createHandler({ enabled: true, approvers: ["123"] }, "secondary");
+    expect(matching.shouldHandle(createRequest())).toBe(true);
+  });
+
   it("combines agent and session filters", () => {
     const handler = createHandler({
       enabled: true,
@@ -618,7 +653,6 @@ describe("DiscordExecApprovalHandler delivery routing", () => {
       Routes.channelMessages("dm-1"),
       expect.objectContaining({
         body: expect.objectContaining({
-          embeds: expect.any(Array),
           components: expect.any(Array),
         }),
       }),
diff --git a/src/discord/monitor/exec-approvals.ts b/src/discord/monitor/exec-approvals.ts
index f6fc1c24d9d..2cefb30e6be 100644
--- a/src/discord/monitor/exec-approvals.ts
+++ b/src/discord/monitor/exec-approvals.ts
@@ -1,4 +1,14 @@
-import { Button, type ButtonInteraction, type ComponentData } from "@buape/carbon";
+import {
+  Button,
+  Row,
+  Separator,
+  TextDisplay,
+  serializePayload,
+  type ButtonInteraction,
+  type ComponentData,
+  type MessagePayloadObject,
+  type TopLevelComponents,
+} from "@buape/carbon";
 import { ButtonStyle, Routes } from "discord-api-types/v10";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { DiscordExecApprovalConfig } from "../../config/types.discord.js";
@@ -9,11 +19,18 @@ import type {
   ExecApprovalResolved,
 } from "../../infra/exec-approvals.js";
 import type { RuntimeEnv } from "../../runtime.js";
+import { loadSessionStore, resolveStorePath } from "../../config/sessions.js";
 import { buildGatewayConnectionDetails } from "../../gateway/call.js";
 import { GatewayClient } from "../../gateway/client.js";
 import { logDebug, logError } from "../../logger.js";
-import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
-import { createDiscordClient } from "../send.shared.js";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+import {
+  GATEWAY_CLIENT_MODES,
+  GATEWAY_CLIENT_NAMES,
+  normalizeMessageChannel,
+} from "../../utils/message-channel.js";
+import { createDiscordClient, stripUndefinedFields } from "../send.shared.js";
+import { DiscordUiContainer } from "../ui.js";
 
 const EXEC_APPROVAL_KEY = "execapproval";
 
@@ -79,105 +96,209 @@ export function parseExecApprovalData(
   };
 }
 
-function formatExecApprovalEmbed(request: ExecApprovalRequest) {
-  const commandText = request.request.command;
-  const commandPreview =
-    commandText.length > 1000 ? `${commandText.slice(0, 1000)}...` : commandText;
-  const expiresIn = Math.max(0, Math.round((request.expiresAtMs - Date.now()) / 1000));
+type ExecApprovalContainerParams = {
+  cfg: OpenClawConfig;
+  accountId: string;
+  title: string;
+  description?: string;
+  commandPreview: string;
+  metadataLines?: string[];
+  actionRow?: Row<Button>;
+  footer?: string;
+  accentColor?: string;
+};
 
-  const fields: Array<{ name: string; value: string; inline: boolean }> = [
-    {
-      name: "Command",
-      value: `\`\`\`\n${commandPreview}\n\`\`\``,
-      inline: false,
-    },
-  ];
-
-  if (request.request.cwd) {
-    fields.push({
-      name: "Working Directory",
-      value: request.request.cwd,
-      inline: true,
+class ExecApprovalContainer extends DiscordUiContainer {
+  constructor(params: ExecApprovalContainerParams) {
+    const components: Array<TextDisplay | Separator | Row<Button>> = [
+      new TextDisplay(`## ${params.title}`),
+    ];
+    if (params.description) {
+      components.push(new TextDisplay(params.description));
+    }
+    components.push(new Separator({ divider: true, spacing: "small" }));
+    components.push(new TextDisplay(`### Command\n\`\`\`\n${params.commandPreview}\n\`\`\``));
+    if (params.metadataLines?.length) {
+      components.push(new TextDisplay(params.metadataLines.join("\n")));
+    }
+    if (params.actionRow) {
+      components.push(params.actionRow);
+    }
+    if (params.footer) {
+      components.push(new Separator({ divider: false, spacing: "small" }));
+      components.push(new TextDisplay(`-# ${params.footer}`));
+    }
+    super({
+      cfg: params.cfg,
+      accountId: params.accountId,
+      components,
+      accentColor: params.accentColor,
     });
   }
-
-  if (request.request.host) {
-    fields.push({
-      name: "Host",
-      value: request.request.host,
-      inline: true,
-    });
-  }
-
-  if (request.request.agentId) {
-    fields.push({
-      name: "Agent",
-      value: request.request.agentId,
-      inline: true,
-    });
-  }
-
-  return {
-    title: "Exec Approval Required",
-    description: "A command needs your approval.",
-    color: 0xffa500, // Orange
-    fields,
-    footer: { text: `Expires in ${expiresIn}s | ID: ${request.id}` },
-    timestamp: new Date().toISOString(),
-  };
 }
 
-function formatResolvedEmbed(
-  request: ExecApprovalRequest,
-  decision: ExecApprovalDecision,
-  resolvedBy?: string | null,
-) {
-  const commandText = request.request.command;
+class ExecApprovalActionButton extends Button {
+  customId: string;
+  label: string;
+  style: ButtonStyle;
+
+  constructor(params: {
+    approvalId: string;
+    action: ExecApprovalDecision;
+    label: string;
+    style: ButtonStyle;
+  }) {
+    super();
+    this.customId = buildExecApprovalCustomId(params.approvalId, params.action);
+    this.label = params.label;
+    this.style = params.style;
+  }
+}
+
+class ExecApprovalActionRow extends Row<Button> {
+  constructor(approvalId: string) {
+    super([
+      new ExecApprovalActionButton({
+        approvalId,
+        action: "allow-once",
+        label: "Allow once",
+        style: ButtonStyle.Success,
+      }),
+      new ExecApprovalActionButton({
+        approvalId,
+        action: "allow-always",
+        label: "Always allow",
+        style: ButtonStyle.Primary,
+      }),
+      new ExecApprovalActionButton({
+        approvalId,
+        action: "deny",
+        label: "Deny",
+        style: ButtonStyle.Danger,
+      }),
+    ]);
+  }
+}
+
+function resolveExecApprovalAccountId(params: {
+  cfg: OpenClawConfig;
+  request: ExecApprovalRequest;
+}): string | null {
+  const sessionKey = params.request.request.sessionKey?.trim();
+  if (!sessionKey) {
+    return null;
+  }
+  try {
+    const agentId = resolveAgentIdFromSessionKey(sessionKey);
+    const storePath = resolveStorePath(params.cfg.session?.store, { agentId });
+    const store = loadSessionStore(storePath);
+    const entry = store[sessionKey];
+    const channel = normalizeMessageChannel(entry?.origin?.provider ?? entry?.lastChannel);
+    if (channel && channel !== "discord") {
+      return null;
+    }
+    const accountId = entry?.origin?.accountId ?? entry?.lastAccountId;
+    return accountId?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildExecApprovalMetadataLines(request: ExecApprovalRequest): string[] {
+  const lines: string[] = [];
+  if (request.request.cwd) {
+    lines.push(`- Working Directory: ${request.request.cwd}`);
+  }
+  if (request.request.host) {
+    lines.push(`- Host: ${request.request.host}`);
+  }
+  if (request.request.agentId) {
+    lines.push(`- Agent: ${request.request.agentId}`);
+  }
+  return lines;
+}
+
+function buildExecApprovalPayload(container: DiscordUiContainer): MessagePayloadObject {
+  const components: TopLevelComponents[] = [container];
+  return { components };
+}
+
+function createExecApprovalRequestContainer(params: {
+  request: ExecApprovalRequest;
+  cfg: OpenClawConfig;
+  accountId: string;
+  actionRow?: Row<Button>;
+}): ExecApprovalContainer {
+  const commandText = params.request.request.command;
+  const commandPreview =
+    commandText.length > 1000 ? `${commandText.slice(0, 1000)}...` : commandText;
+  const expiresAtSeconds = Math.max(0, Math.floor(params.request.expiresAtMs / 1000));
+
+  return new ExecApprovalContainer({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    title: "Exec Approval Required",
+    description: "A command needs your approval.",
+    commandPreview,
+    metadataLines: buildExecApprovalMetadataLines(params.request),
+    actionRow: params.actionRow,
+    footer: `Expires <t:${expiresAtSeconds}:R> · ID: ${params.request.id}`,
+    accentColor: "#FFA500",
+  });
+}
+
+function createResolvedContainer(params: {
+  request: ExecApprovalRequest;
+  decision: ExecApprovalDecision;
+  resolvedBy?: string | null;
+  cfg: OpenClawConfig;
+  accountId: string;
+}): ExecApprovalContainer {
+  const commandText = params.request.request.command;
   const commandPreview = commandText.length > 500 ? `${commandText.slice(0, 500)}...` : commandText;
 
   const decisionLabel =
-    decision === "allow-once"
+    params.decision === "allow-once"
       ? "Allowed (once)"
-      : decision === "allow-always"
+      : params.decision === "allow-always"
         ? "Allowed (always)"
         : "Denied";
 
-  const color = decision === "deny" ? 0xed4245 : decision === "allow-always" ? 0x5865f2 : 0x57f287;
+  const accentColor =
+    params.decision === "deny"
+      ? "#ED4245"
+      : params.decision === "allow-always"
+        ? "#5865F2"
+        : "#57F287";
 
-  return {
+  return new ExecApprovalContainer({
+    cfg: params.cfg,
+    accountId: params.accountId,
     title: `Exec Approval: ${decisionLabel}`,
-    description: resolvedBy ? `Resolved by ${resolvedBy}` : "Resolved",
-    color,
-    fields: [
-      {
-        name: "Command",
-        value: `\`\`\`\n${commandPreview}\n\`\`\``,
-        inline: false,
-      },
-    ],
-    footer: { text: `ID: ${request.id}` },
-    timestamp: new Date().toISOString(),
-  };
+    description: params.resolvedBy ? `Resolved by ${params.resolvedBy}` : "Resolved",
+    commandPreview,
+    footer: `ID: ${params.request.id}`,
+    accentColor,
+  });
 }
 
-function formatExpiredEmbed(request: ExecApprovalRequest) {
-  const commandText = request.request.command;
+function createExpiredContainer(params: {
+  request: ExecApprovalRequest;
+  cfg: OpenClawConfig;
+  accountId: string;
+}): ExecApprovalContainer {
+  const commandText = params.request.request.command;
   const commandPreview = commandText.length > 500 ? `${commandText.slice(0, 500)}...` : commandText;
 
-  return {
+  return new ExecApprovalContainer({
+    cfg: params.cfg,
+    accountId: params.accountId,
     title: "Exec Approval: Expired",
     description: "This approval request has expired.",
-    color: 0x99aab5, // Gray
-    fields: [
-      {
-        name: "Command",
-        value: `\`\`\`\n${commandPreview}\n\`\`\``,
-        inline: false,
-      },
-    ],
-    footer: { text: `ID: ${request.id}` },
-    timestamp: new Date().toISOString(),
-  };
+    commandPreview,
+    footer: `ID: ${params.request.id}`,
+    accentColor: "#99AAB5",
+  });
 }
 
 export type DiscordExecApprovalHandlerOpts = {
@@ -210,6 +331,17 @@ export class DiscordExecApprovalHandler {
       return false;
     }
 
+    const requestAccountId = resolveExecApprovalAccountId({
+      cfg: this.opts.cfg,
+      request,
+    });
+    if (requestAccountId) {
+      const handlerAccountId = normalizeAccountId(this.opts.accountId);
+      if (normalizeAccountId(requestAccountId) !== handlerAccountId) {
+        return false;
+      }
+    }
+
     // Check agent filter
     if (config.agentFilter?.length) {
       if (!request.request.agentId) {
@@ -329,34 +461,15 @@ export class DiscordExecApprovalHandler {
       this.opts.cfg,
     );
 
-    const embed = formatExecApprovalEmbed(request);
-
-    // Build action rows with buttons
-    const components = [
-      {
-        type: 1, // ACTION_ROW
-        components: [
-          {
-            type: 2, // BUTTON
-            style: ButtonStyle.Success,
-            label: "Allow once",
-            custom_id: buildExecApprovalCustomId(request.id, "allow-once"),
-          },
-          {
-            type: 2, // BUTTON
-            style: ButtonStyle.Primary,
-            label: "Always allow",
-            custom_id: buildExecApprovalCustomId(request.id, "allow-always"),
-          },
-          {
-            type: 2, // BUTTON
-            style: ButtonStyle.Danger,
-            label: "Deny",
-            custom_id: buildExecApprovalCustomId(request.id, "deny"),
-          },
-        ],
-      },
-    ];
+    const actionRow = new ExecApprovalActionRow(request.id);
+    const container = createExecApprovalRequestContainer({
+      request,
+      cfg: this.opts.cfg,
+      accountId: this.opts.accountId,
+      actionRow,
+    });
+    const payload = buildExecApprovalPayload(container);
+    const body = stripUndefinedFields(serializePayload(payload));
 
     const target = this.opts.config.target ?? "dm";
     const sendToDm = target === "dm" || target === "both";
@@ -371,10 +484,7 @@ export class DiscordExecApprovalHandler {
           const message = (await discordRequest(
             () =>
               rest.post(Routes.channelMessages(channelId), {
-                body: {
-                  embeds: [embed],
-                  components,
-                },
+                body,
               }) as Promise<{ id: string; channel_id: string }>,
             "send-approval-channel",
           )) as { id: string; channel_id: string };
@@ -403,7 +513,7 @@ export class DiscordExecApprovalHandler {
           );
           fallbackToDm = true;
         } else {
-          logDebug(`discord exec approvals: could not extract channel id from session key`);
+          logDebug("discord exec approvals: could not extract channel id from session key");
         }
       }
     }
@@ -429,14 +539,11 @@ export class DiscordExecApprovalHandler {
             continue;
           }
 
-          // Send message with embed and buttons
+          // Send message with components v2 + buttons
           const message = (await discordRequest(
             () =>
               rest.post(Routes.channelMessages(dmChannel.id), {
-                body: {
-                  embeds: [embed],
-                  components,
-                },
+                body,
               }) as Promise<{ id: string; channel_id: string }>,
             "send-approval",
           )) as { id: string; channel_id: string };
@@ -483,7 +590,13 @@ export class DiscordExecApprovalHandler {
 
     logDebug(`discord exec approvals: resolved ${resolved.id} with ${resolved.decision}`);
 
-    const resolvedEmbed = formatResolvedEmbed(request, resolved.decision, resolved.resolvedBy);
+    const container = createResolvedContainer({
+      request,
+      decision: resolved.decision,
+      resolvedBy: resolved.resolvedBy,
+      cfg: this.opts.cfg,
+      accountId: this.opts.accountId,
+    });
 
     for (const suffix of [":channel", ":dm", ""]) {
       const key = `${resolved.id}${suffix}`;
@@ -495,7 +608,7 @@ export class DiscordExecApprovalHandler {
       clearTimeout(pending.timeoutId);
       this.pending.delete(key);
 
-      await this.finalizeMessage(pending.discordChannelId, pending.discordMessageId, resolvedEmbed);
+      await this.finalizeMessage(pending.discordChannelId, pending.discordMessageId, container);
     }
   }
 
@@ -528,20 +641,21 @@ export class DiscordExecApprovalHandler {
 
     logDebug(`discord exec approvals: timeout for ${approvalId} (${source ?? "default"})`);
 
-    await this.finalizeMessage(
-      pending.discordChannelId,
-      pending.discordMessageId,
-      formatExpiredEmbed(request),
-    );
+    const container = createExpiredContainer({
+      request,
+      cfg: this.opts.cfg,
+      accountId: this.opts.accountId,
+    });
+    await this.finalizeMessage(pending.discordChannelId, pending.discordMessageId, container);
   }
 
   private async finalizeMessage(
     channelId: string,
     messageId: string,
-    embed: ReturnType<typeof formatExpiredEmbed>,
+    container: DiscordUiContainer,
   ): Promise<void> {
     if (!this.opts.config.cleanupAfterResolve) {
-      await this.updateMessage(channelId, messageId, embed);
+      await this.updateMessage(channelId, messageId, container);
       return;
     }
 
@@ -557,28 +671,26 @@ export class DiscordExecApprovalHandler {
       );
     } catch (err) {
       logError(`discord exec approvals: failed to delete message: ${String(err)}`);
-      await this.updateMessage(channelId, messageId, embed);
+      await this.updateMessage(channelId, messageId, container);
     }
   }
 
   private async updateMessage(
     channelId: string,
     messageId: string,
-    embed: ReturnType<typeof formatExpiredEmbed>,
+    container: DiscordUiContainer,
   ): Promise<void> {
     try {
       const { rest, request: discordRequest } = createDiscordClient(
         { token: this.opts.token, accountId: this.opts.accountId },
         this.opts.cfg,
       );
+      const payload = buildExecApprovalPayload(container);
 
       await discordRequest(
         () =>
           rest.patch(Routes.channelMessage(channelId, messageId), {
-            body: {
-              embeds: [embed],
-              components: [], // Remove buttons
-            },
+            body: stripUndefinedFields(serializePayload(payload)),
           }),
         "update-approval",
       );
diff --git a/src/discord/monitor/gateway-registry.test.ts b/src/discord/monitor/gateway-registry.test.ts
deleted file mode 100644
index 8e0c66a87e3..00000000000
--- a/src/discord/monitor/gateway-registry.test.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import type { GatewayPlugin } from "@buape/carbon/gateway";
-import { beforeEach, describe, expect, it } from "vitest";
-import {
-  clearGateways,
-  getGateway,
-  registerGateway,
-  unregisterGateway,
-} from "./gateway-registry.js";
-
-function fakeGateway(props: Partial<GatewayPlugin> = {}): GatewayPlugin {
-  return { isConnected: true, ...props } as unknown as GatewayPlugin;
-}
-
-describe("gateway-registry", () => {
-  beforeEach(() => {
-    clearGateways();
-  });
-
-  it("stores and retrieves a gateway by account", () => {
-    const gateway = fakeGateway();
-    registerGateway("account-a", gateway);
-    expect(getGateway("account-a")).toBe(gateway);
-    expect(getGateway("account-b")).toBeUndefined();
-  });
-
-  it("uses collision-safe key when accountId is undefined", () => {
-    const gateway = fakeGateway();
-    registerGateway(undefined, gateway);
-    expect(getGateway(undefined)).toBe(gateway);
-    // "default" as a literal account ID must not collide with the sentinel key
-    expect(getGateway("default")).toBeUndefined();
-  });
-
-  it("unregisters a gateway", () => {
-    const gateway = fakeGateway();
-    registerGateway("account-a", gateway);
-    unregisterGateway("account-a");
-    expect(getGateway("account-a")).toBeUndefined();
-  });
-
-  it("clears all gateways", () => {
-    registerGateway("a", fakeGateway());
-    registerGateway("b", fakeGateway());
-    clearGateways();
-    expect(getGateway("a")).toBeUndefined();
-    expect(getGateway("b")).toBeUndefined();
-  });
-
-  it("overwrites existing entry for same account", () => {
-    const gateway1 = fakeGateway({ isConnected: true });
-    const gateway2 = fakeGateway({ isConnected: false });
-    registerGateway("account-a", gateway1);
-    registerGateway("account-a", gateway2);
-    expect(getGateway("account-a")).toBe(gateway2);
-  });
-});
diff --git a/src/discord/monitor/listeners.ts b/src/discord/monitor/listeners.ts
index 5b21543fb1b..fadca3c82ea 100644
--- a/src/discord/monitor/listeners.ts
+++ b/src/discord/monitor/listeners.ts
@@ -272,8 +272,8 @@ async function handleDiscordReactionEvent(params: {
     const authorLabel = message?.author ? formatDiscordUserTag(message.author) : undefined;
     const baseText = `Discord reaction ${action}: ${emojiLabel} by ${actorLabel} on ${guildSlug} ${channelLabel} msg ${data.message_id}`;
     const text = authorLabel ? `${baseText} from ${authorLabel}` : baseText;
-    const memberRoleIds = Array.isArray(data.member?.roles)
-      ? data.member.roles.map((roleId: string) => String(roleId))
+    const memberRoleIds = Array.isArray(data.rawMember?.roles)
+      ? data.rawMember.roles.map((roleId: string) => String(roleId))
       : [];
     const route = resolveAgentRoute({
       cfg: params.cfg,
diff --git a/src/discord/monitor/message-handler.inbound-contract.test.ts b/src/discord/monitor/message-handler.inbound-contract.test.ts
index 06638531e35..da80e1c2ba8 100644
--- a/src/discord/monitor/message-handler.inbound-contract.test.ts
+++ b/src/discord/monitor/message-handler.inbound-contract.test.ts
@@ -59,6 +59,7 @@ describe("discord processDiscordMessage inbound contract", () => {
         attachments: [],
         // oxlint-disable-next-line typescript/no-explicit-any
       } as any,
+      messageChannelId: "c1",
       author: {
         id: "U1",
         username: "alice",
@@ -131,6 +132,7 @@ describe("discord processDiscordMessage inbound contract", () => {
         timestamp: new Date().toISOString(),
         attachments: [],
       },
+      messageChannelId: "c1",
       author: {
         id: "U1",
         username: "alice",
diff --git a/src/discord/monitor/message-handler.preflight.ts b/src/discord/monitor/message-handler.preflight.ts
index 6dba2ccecf2..d858f07502f 100644
--- a/src/discord/monitor/message-handler.preflight.ts
+++ b/src/discord/monitor/message-handler.preflight.ts
@@ -39,7 +39,7 @@ import {
   resolveDiscordAllowListMatch,
   resolveDiscordChannelConfigWithFallback,
   resolveDiscordGuildEntry,
-  resolveDiscordMemberAllowed,
+  resolveDiscordMemberAccessState,
   resolveDiscordShouldRequireMention,
   resolveGroupDmAllow,
 } from "./allow-list.js";
@@ -48,7 +48,11 @@ import {
   resolveDiscordSystemLocation,
   resolveTimestampMs,
 } from "./format.js";
-import { resolveDiscordChannelInfo, resolveDiscordMessageText } from "./message-utils.js";
+import {
+  resolveDiscordChannelInfo,
+  resolveDiscordMessageChannelId,
+  resolveDiscordMessageText,
+} from "./message-utils.js";
 import { resolveDiscordSenderIdentity, resolveDiscordWebhookId } from "./sender-identity.js";
 import { resolveDiscordSystemEvent } from "./system-events.js";
 import { resolveDiscordThreadChannel, resolveDiscordThreadParentInfo } from "./threading.js";
@@ -67,6 +71,14 @@ export async function preflightDiscordMessage(
   if (!author) {
     return null;
   }
+  const messageChannelId = resolveDiscordMessageChannelId({
+    message,
+    eventChannelId: params.data.channel_id,
+  });
+  if (!messageChannelId) {
+    logVerbose(`discord: drop message ${message.id} (missing channel id)`);
+    return null;
+  }
 
   const allowBots = params.discordConfig?.allowBots ?? false;
   if (params.botUserId && author.id === params.botUserId) {
@@ -102,11 +114,11 @@ export async function preflightDiscordMessage(
   }
 
   const isGuildMessage = Boolean(params.data.guild_id);
-  const channelInfo = await resolveDiscordChannelInfo(params.client, message.channelId);
+  const channelInfo = await resolveDiscordChannelInfo(params.client, messageChannelId);
   const isDirectMessage = channelInfo?.type === ChannelType.DM;
   const isGroupDm = channelInfo?.type === ChannelType.GroupDM;
   logDebug(
-    `[discord-preflight] channelId=${message.channelId} guild_id=${params.data.guild_id} channelType=${channelInfo?.type} isGuild=${isGuildMessage} isDM=${isDirectMessage} isGroupDm=${isGroupDm}`,
+    `[discord-preflight] channelId=${messageChannelId} guild_id=${params.data.guild_id} channelType=${channelInfo?.type} isGuild=${isGuildMessage} isDM=${isDirectMessage} isGroupDm=${isGroupDm}`,
   );
 
   if (isGroupDm && !params.groupDmEnabled) {
@@ -208,6 +220,7 @@ export async function preflightDiscordMessage(
     isGuildMessage,
     message,
     channelInfo,
+    messageChannelId,
   });
   let earlyThreadParentId: string | undefined;
   let earlyThreadParentName: string | undefined;
@@ -224,8 +237,8 @@ export async function preflightDiscordMessage(
   }
 
   // Fresh config for bindings lookup; other routing inputs are payload-derived.
-  const memberRoleIds = Array.isArray(params.data.member?.roles)
-    ? params.data.member.roles.map((roleId: string) => String(roleId))
+  const memberRoleIds = Array.isArray(params.data.rawMember?.roles)
+    ? params.data.rawMember.roles.map((roleId: string) => String(roleId))
     : [];
   const route = resolveAgentRoute({
     cfg: loadConfig(),
@@ -235,7 +248,7 @@ export async function preflightDiscordMessage(
     memberRoleIds,
     peer: {
       kind: isDirectMessage ? "direct" : isGroupDm ? "group" : "channel",
-      id: isDirectMessage ? author.id : message.channelId,
+      id: isDirectMessage ? author.id : messageChannelId,
     },
     // Pass parent peer for thread binding inheritance
     parentPeer: earlyThreadParentId ? { kind: "channel", id: earlyThreadParentId } : undefined,
@@ -305,7 +318,7 @@ export async function preflightDiscordMessage(
   const channelConfig = isGuildMessage
     ? resolveDiscordChannelConfigWithFallback({
         guildInfo,
-        channelId: message.channelId,
+        channelId: messageChannelId,
         channelName,
         channelSlug: threadChannelSlug,
         parentId: threadParentId ?? undefined,
@@ -320,13 +333,13 @@ export async function preflightDiscordMessage(
       ? `allowed=${channelConfig.allowed} enabled=${channelConfig.enabled ?? "unset"} requireMention=${channelConfig.requireMention ?? "unset"} matchKey=${channelConfig.matchKey ?? "none"} matchSource=${channelConfig.matchSource ?? "none"} users=${channelConfig.users?.length ?? 0} roles=${channelConfig.roles?.length ?? 0} skills=${channelConfig.skills?.length ?? 0}`
       : "none";
     logDebug(
-      `[discord-preflight] channelConfig=${channelConfigSummary} channelMatchMeta=${channelMatchMeta} channelId=${message.channelId}`,
+      `[discord-preflight] channelConfig=${channelConfigSummary} channelMatchMeta=${channelMatchMeta} channelId=${messageChannelId}`,
     );
   }
   if (isGuildMessage && channelConfig?.enabled === false) {
     logDebug(`[discord-preflight] drop: channel disabled`);
     logVerbose(
-      `Blocked discord channel ${message.channelId} (channel disabled, ${channelMatchMeta})`,
+      `Blocked discord channel ${messageChannelId} (channel disabled, ${channelMatchMeta})`,
     );
     return null;
   }
@@ -335,7 +348,7 @@ export async function preflightDiscordMessage(
     isGroupDm &&
     resolveGroupDmAllow({
       channels: params.groupDmChannels,
-      channelId: message.channelId,
+      channelId: messageChannelId,
       channelName: displayChannelName,
       channelSlug: displayChannelSlug,
     });
@@ -363,7 +376,7 @@ export async function preflightDiscordMessage(
       );
     } else {
       logVerbose(
-        `Blocked discord channel ${message.channelId} not in guild channel allowlist (groupPolicy: allowlist, ${channelMatchMeta})`,
+        `Blocked discord channel ${messageChannelId} not in guild channel allowlist (groupPolicy: allowlist, ${channelMatchMeta})`,
       );
     }
     return null;
@@ -372,13 +385,13 @@ export async function preflightDiscordMessage(
   if (isGuildMessage && channelConfig?.allowed === false) {
     logDebug(`[discord-preflight] drop: channelConfig.allowed===false`);
     logVerbose(
-      `Blocked discord channel ${message.channelId} not in guild channel allowlist (${channelMatchMeta})`,
+      `Blocked discord channel ${messageChannelId} not in guild channel allowlist (${channelMatchMeta})`,
     );
     return null;
   }
   if (isGuildMessage) {
     logDebug(`[discord-preflight] pass: channel allowed`);
-    logVerbose(`discord: allow channel ${message.channelId} (${channelMatchMeta})`);
+    logVerbose(`discord: allow channel ${messageChannelId} (${channelMatchMeta})`);
   }
 
   const textForHistory = resolveDiscordMessageText(message, {
@@ -467,7 +480,7 @@ export async function preflightDiscordMessage(
   );
   if (shouldLogVerbose()) {
     logVerbose(
-      `discord: inbound id=${message.id} guild=${params.data.guild_id ?? "dm"} channel=${message.channelId} mention=${wasMentioned ? "yes" : "no"} type=${isDirectMessage ? "dm" : isGroupDm ? "group-dm" : "guild"} content=${messageText ? "yes" : "no"}`,
+      `discord: inbound id=${message.id} guild=${params.data.guild_id ?? "dm"} channel=${messageChannelId} mention=${wasMentioned ? "yes" : "no"} type=${isDirectMessage ? "dm" : isGroupDm ? "group-dm" : "guild"} content=${messageText ? "yes" : "no"}`,
     );
   }
 
@@ -476,18 +489,11 @@ export async function preflightDiscordMessage(
     surface: "discord",
   });
   const hasControlCommandInMessage = hasControlCommand(baseText, params.cfg);
-  const channelUsers = channelConfig?.users ?? guildInfo?.users;
-  const channelRoles = channelConfig?.roles ?? guildInfo?.roles;
-  const hasAccessRestrictions =
-    (Array.isArray(channelUsers) && channelUsers.length > 0) ||
-    (Array.isArray(channelRoles) && channelRoles.length > 0);
-  const memberAllowed = resolveDiscordMemberAllowed({
-    userAllowList: channelUsers,
-    roleAllowList: channelRoles,
+  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
     memberRoleIds,
-    userId: sender.id,
-    userName: sender.name,
-    userTag: sender.tag,
+    sender,
   });
 
   if (!isDirectMessage) {
@@ -549,14 +555,14 @@ export async function preflightDiscordMessage(
       logVerbose(`discord: drop guild message (mention required, botId=${botId})`);
       logger.info(
         {
-          channelId: message.channelId,
+          channelId: messageChannelId,
           reason: "no-mention",
         },
         "discord: skipping guild message",
       );
       recordPendingHistoryEntryIfEnabled({
         historyMap: params.guildHistories,
-        historyKey: message.channelId,
+        historyKey: messageChannelId,
         limit: params.historyLimit,
         entry: historyEntry ?? null,
       });
@@ -574,14 +580,14 @@ export async function preflightDiscordMessage(
     isDirectMessage,
     isGroupDm,
     guild: params.data.guild ?? undefined,
-    channelName: channelName ?? message.channelId,
+    channelName: channelName ?? messageChannelId,
   });
   const systemText = resolveDiscordSystemEvent(message, systemLocation);
   if (systemText) {
     logDebug(`[discord-preflight] drop: system event`);
     enqueueSystemEvent(systemText, {
       sessionKey: route.sessionKey,
-      contextKey: `discord:system:${message.channelId}:${message.id}`,
+      contextKey: `discord:system:${messageChannelId}:${message.id}`,
     });
     return null;
   }
@@ -610,6 +616,7 @@ export async function preflightDiscordMessage(
     data: params.data,
     client: params.client,
     message,
+    messageChannelId,
     author,
     sender,
     channelInfo,
diff --git a/src/discord/monitor/message-handler.preflight.types.ts b/src/discord/monitor/message-handler.preflight.types.ts
index c447eab580d..931bdd75bb5 100644
--- a/src/discord/monitor/message-handler.preflight.types.ts
+++ b/src/discord/monitor/message-handler.preflight.types.ts
@@ -34,6 +34,7 @@ export type DiscordMessagePreflightContext = {
   data: DiscordMessageEvent;
   client: Client;
   message: DiscordMessageEvent["message"];
+  messageChannelId: string;
   author: User;
   sender: DiscordSenderIdentity;
 
diff --git a/src/discord/monitor/message-handler.process.test.ts b/src/discord/monitor/message-handler.process.test.ts
index 5e26257f317..c8bd869f252 100644
--- a/src/discord/monitor/message-handler.process.test.ts
+++ b/src/discord/monitor/message-handler.process.test.ts
@@ -59,6 +59,7 @@ async function createBaseContext(overrides: Record<string, unknown> = {}) {
       timestamp: new Date().toISOString(),
       attachments: [],
     },
+    messageChannelId: "c1",
     author: {
       id: "U1",
       username: "alice",
@@ -130,4 +131,25 @@ describe("processDiscordMessage ack reactions", () => {
 
     expect(reactMessageDiscord).toHaveBeenCalledWith("c1", "m1", "👀", { rest: {} });
   });
+
+  it("uses preflight-resolved messageChannelId when message.channelId is missing", async () => {
+    const ctx = await createBaseContext({
+      message: {
+        id: "m1",
+        timestamp: new Date().toISOString(),
+        attachments: [],
+      },
+      messageChannelId: "fallback-channel",
+      shouldRequireMention: true,
+      effectiveWasMentioned: true,
+      sender: { label: "user" },
+    });
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    await processDiscordMessage(ctx as any);
+
+    expect(reactMessageDiscord).toHaveBeenCalledWith("fallback-channel", "m1", "👀", {
+      rest: {},
+    });
+  });
 });
diff --git a/src/discord/monitor/message-handler.process.ts b/src/discord/monitor/message-handler.process.ts
index e0d849d40e3..8e936068c28 100644
--- a/src/discord/monitor/message-handler.process.ts
+++ b/src/discord/monitor/message-handler.process.ts
@@ -59,6 +59,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     client,
     channelInfo,
     channelName,
+    messageChannelId,
     isGuildMessage,
     isDirectMessage,
     isGroupDm,
@@ -88,7 +89,10 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     logVerbose(`discord: drop message ${message.id} (empty content)`);
     return;
   }
-  const ackReaction = resolveAckReaction(cfg, route.agentId);
+  const ackReaction = resolveAckReaction(cfg, route.agentId, {
+    channel: "discord",
+    accountId,
+  });
   const removeAckAfterReply = cfg.messages?.removeAckAfterReply ?? false;
   const shouldAckReaction = () =>
     Boolean(
@@ -105,12 +109,12 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
       }),
     );
   const ackReactionPromise = shouldAckReaction()
-    ? reactMessageDiscord(message.channelId, message.id, ackReaction, {
+    ? reactMessageDiscord(messageChannelId, message.id, ackReaction, {
         rest: client.rest,
       }).then(
         () => true,
         (err) => {
-          logVerbose(`discord react failed for channel ${message.channelId}: ${String(err)}`);
+          logVerbose(`discord react failed for channel ${messageChannelId}: ${String(err)}`);
           return false;
         },
       )
@@ -120,8 +124,8 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     ? buildDirectLabel(author)
     : buildGuildLabel({
         guild: data.guild ?? undefined,
-        channelName: channelName ?? message.channelId,
-        channelId: message.channelId,
+        channelName: channelName ?? messageChannelId,
+        channelId: messageChannelId,
       });
   const senderLabel = sender.label;
   const isForumParent =
@@ -181,7 +185,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
   if (shouldIncludeChannelHistory) {
     combinedBody = buildPendingHistoryContextFromMap({
       historyMap: guildHistories,
-      historyKey: message.channelId,
+      historyKey: messageChannelId,
       limit: historyLimit,
       currentMessage: combinedBody,
       formatEntry: (entry) =>
@@ -189,7 +193,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
           channel: "Discord",
           from: fromLabel,
           timestamp: entry.timestamp,
-          body: `${entry.body} [id:${entry.messageId ?? "unknown"} channel:${message.channelId}]`,
+          body: `${entry.body} [id:${entry.messageId ?? "unknown"} channel:${messageChannelId}]`,
           chatType: "channel",
           senderLabel: entry.sender,
           envelope: envelopeOptions,
@@ -234,13 +238,14 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
   const mediaPayload = buildDiscordMediaPayload(mediaList);
   const threadKeys = resolveThreadSessionKeys({
     baseSessionKey,
-    threadId: threadChannel ? message.channelId : undefined,
+    threadId: threadChannel ? messageChannelId : undefined,
     parentSessionKey,
     useSuffix: false,
   });
   const replyPlan = await resolveDiscordAutoThreadReplyPlan({
     client,
     message,
+    messageChannelId,
     isGuildMessage,
     channelConfig,
     threadChannel,
@@ -257,7 +262,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
 
   const effectiveFrom = isDirectMessage
     ? `discord:${author.id}`
-    : (autoThreadContext?.From ?? `discord:channel:${message.channelId}`);
+    : (autoThreadContext?.From ?? `discord:channel:${messageChannelId}`);
   const effectiveTo = autoThreadContext?.To ?? replyTarget;
   if (!effectiveTo) {
     runtime.error?.(danger("discord: missing reply target"));
@@ -266,7 +271,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
 
   const inboundHistory =
     shouldIncludeChannelHistory && historyLimit > 0
-      ? (guildHistories.get(message.channelId) ?? []).map((entry) => ({
+      ? (guildHistories.get(messageChannelId) ?? []).map((entry) => ({
           sender: entry.sender,
           body: entry.body,
           timestamp: entry.timestamp,
@@ -334,13 +339,13 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
   if (shouldLogVerbose()) {
     const preview = truncateUtf16Safe(combinedBody, 200).replace(/\n/g, "\\n");
     logVerbose(
-      `discord inbound: channel=${message.channelId} deliver=${deliverTarget} from=${ctxPayload.From} preview="${preview}"`,
+      `discord inbound: channel=${messageChannelId} deliver=${deliverTarget} from=${ctxPayload.From} preview="${preview}"`,
     );
   }
 
   const typingChannelId = deliverTarget.startsWith("channel:")
     ? deliverTarget.slice("channel:".length)
-    : message.channelId;
+    : messageChannelId;
 
   const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
     cfg,
@@ -409,7 +414,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     if (isGuildMessage) {
       clearHistoryEntriesIfEnabled({
         historyMap: guildHistories,
-        historyKey: message.channelId,
+        historyKey: messageChannelId,
         limit: historyLimit,
       });
     }
@@ -426,7 +431,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     ackReactionPromise,
     ackReactionValue: ackReaction,
     remove: async () => {
-      await removeReactionDiscord(message.channelId, message.id, ackReaction, {
+      await removeReactionDiscord(messageChannelId, message.id, ackReaction, {
         rest: client.rest,
       });
     },
@@ -434,7 +439,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
       logAckFailure({
         log: logVerbose,
         channel: "discord",
-        target: `${message.channelId}/${message.id}`,
+        target: `${messageChannelId}/${message.id}`,
         error: err,
       });
     },
@@ -442,7 +447,7 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
   if (isGuildMessage) {
     clearHistoryEntriesIfEnabled({
       historyMap: guildHistories,
-      historyKey: message.channelId,
+      historyKey: messageChannelId,
       limit: historyLimit,
     });
   }
diff --git a/src/discord/monitor/message-handler.ts b/src/discord/monitor/message-handler.ts
index 5945e719a2e..bfed7c16afd 100644
--- a/src/discord/monitor/message-handler.ts
+++ b/src/discord/monitor/message-handler.ts
@@ -1,9 +1,6 @@
 import type { Client } from "@buape/carbon";
-import type { HistoryEntry } from "../../auto-reply/reply/history.js";
-import type { ReplyToMode } from "../../config/config.js";
-import type { RuntimeEnv } from "../../runtime.js";
-import type { DiscordGuildEntryResolved } from "./allow-list.js";
 import type { DiscordMessageEvent, DiscordMessageHandler } from "./listeners.js";
+import type { DiscordMessagePreflightParams } from "./message-handler.preflight.types.js";
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
 import {
   createInboundDebouncer,
@@ -12,31 +9,16 @@ import {
 import { danger } from "../../globals.js";
 import { preflightDiscordMessage } from "./message-handler.preflight.js";
 import { processDiscordMessage } from "./message-handler.process.js";
-import { resolveDiscordMessageText } from "./message-utils.js";
+import { resolveDiscordMessageChannelId, resolveDiscordMessageText } from "./message-utils.js";
 
-type LoadedConfig = ReturnType<typeof import("../../config/config.js").loadConfig>;
-type DiscordConfig = NonNullable<
-  import("../../config/config.js").OpenClawConfig["channels"]
->["discord"];
+type DiscordMessageHandlerParams = Omit<
+  DiscordMessagePreflightParams,
+  "ackReactionScope" | "groupPolicy" | "data" | "client"
+>;
 
-export function createDiscordMessageHandler(params: {
-  cfg: LoadedConfig;
-  discordConfig: DiscordConfig;
-  accountId: string;
-  token: string;
-  runtime: RuntimeEnv;
-  botUserId?: string;
-  guildHistories: Map<string, HistoryEntry[]>;
-  historyLimit: number;
-  mediaMaxBytes: number;
-  textLimit: number;
-  replyToMode: ReplyToMode;
-  dmEnabled: boolean;
-  groupDmEnabled: boolean;
-  groupDmChannels?: Array<string | number>;
-  allowFrom?: Array<string | number>;
-  guildEntries?: Record<string, DiscordGuildEntryResolved>;
-}): DiscordMessageHandler {
+export function createDiscordMessageHandler(
+  params: DiscordMessageHandlerParams,
+): DiscordMessageHandler {
   const groupPolicy = params.discordConfig?.groupPolicy ?? "open";
   const ackReactionScope = params.cfg.messages?.ackReactionScope ?? "group-mentions";
   const debounceMs = resolveInboundDebounceMs({ cfg: params.cfg, channel: "discord" });
@@ -49,7 +31,10 @@ export function createDiscordMessageHandler(params: {
       if (!message || !authorId) {
         return null;
       }
-      const channelId = message.channelId;
+      const channelId = resolveDiscordMessageChannelId({
+        message,
+        eventChannelId: entry.data.channel_id,
+      });
       if (!channelId) {
         return null;
       }
diff --git a/src/discord/monitor/message-utils.test.ts b/src/discord/monitor/message-utils.test.ts
new file mode 100644
index 00000000000..a6221eb04c3
--- /dev/null
+++ b/src/discord/monitor/message-utils.test.ts
@@ -0,0 +1,38 @@
+import type { Message } from "@buape/carbon";
+import { describe, expect, it } from "vitest";
+import { resolveDiscordMessageChannelId } from "./message-utils.js";
+
+function asMessage(payload: Record<string, unknown>): Message {
+  return payload as unknown as Message;
+}
+
+describe("resolveDiscordMessageChannelId", () => {
+  it("uses message.channelId when present", () => {
+    const channelId = resolveDiscordMessageChannelId({
+      message: asMessage({ channelId: " 123 " }),
+    });
+    expect(channelId).toBe("123");
+  });
+
+  it("falls back to message.channel_id", () => {
+    const channelId = resolveDiscordMessageChannelId({
+      message: asMessage({ channel_id: " 234 " }),
+    });
+    expect(channelId).toBe("234");
+  });
+
+  it("falls back to message.rawData.channel_id", () => {
+    const channelId = resolveDiscordMessageChannelId({
+      message: asMessage({ rawData: { channel_id: "456" } }),
+    });
+    expect(channelId).toBe("456");
+  });
+
+  it("falls back to eventChannelId and coerces numeric values", () => {
+    const channelId = resolveDiscordMessageChannelId({
+      message: asMessage({}),
+      eventChannelId: 789,
+    });
+    expect(channelId).toBe("789");
+  });
+});
diff --git a/src/discord/monitor/message-utils.ts b/src/discord/monitor/message-utils.ts
index f3968312415..f7f5f0d86e8 100644
--- a/src/discord/monitor/message-utils.ts
+++ b/src/discord/monitor/message-utils.ts
@@ -18,6 +18,11 @@ export type DiscordChannelInfo = {
   ownerId?: string;
 };
 
+type DiscordMessageWithChannelId = Message & {
+  channel_id?: unknown;
+  rawData?: { channel_id?: unknown };
+};
+
 type DiscordSnapshotAuthor = {
   id?: string | null;
   username?: string | null;
@@ -48,6 +53,29 @@ export function __resetDiscordChannelInfoCacheForTest() {
   DISCORD_CHANNEL_INFO_CACHE.clear();
 }
 
+function normalizeDiscordChannelId(value: unknown): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value).trim();
+  }
+  return "";
+}
+
+export function resolveDiscordMessageChannelId(params: {
+  message: Message;
+  eventChannelId?: string | number | null;
+}): string {
+  const message = params.message as DiscordMessageWithChannelId;
+  return (
+    normalizeDiscordChannelId(message.channelId) ||
+    normalizeDiscordChannelId(message.channel_id) ||
+    normalizeDiscordChannelId(message.rawData?.channel_id) ||
+    normalizeDiscordChannelId(params.eventChannelId)
+  );
+}
+
 export async function resolveDiscordChannelInfo(
   client: Client,
   channelId: string,
diff --git a/src/discord/monitor/monitor.test.ts b/src/discord/monitor/monitor.test.ts
new file mode 100644
index 00000000000..4f5033dbccf
--- /dev/null
+++ b/src/discord/monitor/monitor.test.ts
@@ -0,0 +1,819 @@
+import type {
+  ButtonInteraction,
+  ComponentData,
+  ModalInteraction,
+  StringSelectMenuInteraction,
+} from "@buape/carbon";
+import type { Client } from "@buape/carbon";
+import type { GatewayPresenceUpdate } from "discord-api-types/v10";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { DiscordAccountConfig } from "../../config/types.discord.js";
+import type { DiscordChannelConfigResolved } from "./allow-list.js";
+import { buildAgentSessionKey } from "../../routing/resolve-route.js";
+import {
+  clearDiscordComponentEntries,
+  registerDiscordComponentEntries,
+  resolveDiscordComponentEntry,
+  resolveDiscordModalEntry,
+} from "../components-registry.js";
+import {
+  createAgentComponentButton,
+  createAgentSelectMenu,
+  createDiscordComponentButton,
+  createDiscordComponentModal,
+} from "./agent-components.js";
+import {
+  resolveDiscordMemberAllowed,
+  resolveDiscordOwnerAllowFrom,
+  resolveDiscordRoleAllowed,
+} from "./allow-list.js";
+import {
+  clearGateways,
+  getGateway,
+  registerGateway,
+  unregisterGateway,
+} from "./gateway-registry.js";
+import { clearPresences, getPresence, presenceCacheSize, setPresence } from "./presence-cache.js";
+import { resolveDiscordPresenceUpdate } from "./presence.js";
+import {
+  maybeCreateDiscordAutoThread,
+  resolveDiscordAutoThreadContext,
+  resolveDiscordAutoThreadReplyPlan,
+  resolveDiscordReplyDeliveryPlan,
+} from "./threading.js";
+
+const readAllowFromStoreMock = vi.hoisted(() => vi.fn());
+const upsertPairingRequestMock = vi.hoisted(() => vi.fn());
+const enqueueSystemEventMock = vi.hoisted(() => vi.fn());
+const dispatchReplyMock = vi.hoisted(() => vi.fn());
+const deliverDiscordReplyMock = vi.hoisted(() => vi.fn());
+const recordInboundSessionMock = vi.hoisted(() => vi.fn());
+const readSessionUpdatedAtMock = vi.hoisted(() => vi.fn());
+const resolveStorePathMock = vi.hoisted(() => vi.fn());
+let lastDispatchCtx: Record<string, unknown> | undefined;
+
+vi.mock("../../pairing/pairing-store.js", () => ({
+  readChannelAllowFromStore: (...args: unknown[]) => readAllowFromStoreMock(...args),
+  upsertChannelPairingRequest: (...args: unknown[]) => upsertPairingRequestMock(...args),
+}));
+
+vi.mock("../../infra/system-events.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../infra/system-events.js")>();
+  return {
+    ...actual,
+    enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
+  };
+});
+
+vi.mock("../../auto-reply/reply/provider-dispatcher.js", () => ({
+  dispatchReplyWithBufferedBlockDispatcher: (...args: unknown[]) => dispatchReplyMock(...args),
+}));
+
+vi.mock("./reply-delivery.js", () => ({
+  deliverDiscordReply: (...args: unknown[]) => deliverDiscordReplyMock(...args),
+}));
+
+vi.mock("../../channels/session.js", () => ({
+  recordInboundSession: (...args: unknown[]) => recordInboundSessionMock(...args),
+}));
+
+vi.mock("../../config/sessions.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../config/sessions.js")>();
+  return {
+    ...actual,
+    readSessionUpdatedAt: (...args: unknown[]) => readSessionUpdatedAtMock(...args),
+    resolveStorePath: (...args: unknown[]) => resolveStorePathMock(...args),
+  };
+});
+
+describe("agent components", () => {
+  const createCfg = (): OpenClawConfig => ({}) as OpenClawConfig;
+
+  const createDmButtonInteraction = (overrides: Partial<ButtonInteraction> = {}) => {
+    const reply = vi.fn().mockResolvedValue(undefined);
+    const defer = vi.fn().mockResolvedValue(undefined);
+    const interaction = {
+      rawData: { channel_id: "dm-channel" },
+      user: { id: "123456789", username: "Alice", discriminator: "1234" },
+      defer,
+      reply,
+      ...overrides,
+    } as unknown as ButtonInteraction;
+    return { interaction, defer, reply };
+  };
+
+  const createDmSelectInteraction = (overrides: Partial<StringSelectMenuInteraction> = {}) => {
+    const reply = vi.fn().mockResolvedValue(undefined);
+    const defer = vi.fn().mockResolvedValue(undefined);
+    const interaction = {
+      rawData: { channel_id: "dm-channel" },
+      user: { id: "123456789", username: "Alice", discriminator: "1234" },
+      values: ["alpha"],
+      defer,
+      reply,
+      ...overrides,
+    } as unknown as StringSelectMenuInteraction;
+    return { interaction, defer, reply };
+  };
+
+  beforeEach(() => {
+    readAllowFromStoreMock.mockReset().mockResolvedValue([]);
+    upsertPairingRequestMock.mockReset().mockResolvedValue({ code: "PAIRCODE", created: true });
+    enqueueSystemEventMock.mockReset();
+  });
+
+  it("sends pairing reply when DM sender is not allowlisted", async () => {
+    const button = createAgentComponentButton({
+      cfg: createCfg(),
+      accountId: "default",
+      dmPolicy: "pairing",
+    });
+    const { interaction, defer, reply } = createDmButtonInteraction();
+
+    await button.run(interaction, { componentId: "hello" } as ComponentData);
+
+    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
+    expect(reply).toHaveBeenCalledTimes(1);
+    expect(reply.mock.calls[0]?.[0]?.content).toContain("Pairing code: PAIRCODE");
+    expect(enqueueSystemEventMock).not.toHaveBeenCalled();
+  });
+
+  it("allows DM interactions when pairing store allowlist matches", async () => {
+    readAllowFromStoreMock.mockResolvedValue(["123456789"]);
+    const button = createAgentComponentButton({
+      cfg: createCfg(),
+      accountId: "default",
+      dmPolicy: "allowlist",
+    });
+    const { interaction, defer, reply } = createDmButtonInteraction();
+
+    await button.run(interaction, { componentId: "hello" } as ComponentData);
+
+    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
+    expect(reply).toHaveBeenCalledWith({ content: "✓" });
+    expect(enqueueSystemEventMock).toHaveBeenCalled();
+  });
+
+  it("matches tag-based allowlist entries for DM select menus", async () => {
+    const select = createAgentSelectMenu({
+      cfg: createCfg(),
+      accountId: "default",
+      dmPolicy: "allowlist",
+      allowFrom: ["Alice#1234"],
+    });
+    const { interaction, defer, reply } = createDmSelectInteraction();
+
+    await select.run(interaction, { componentId: "hello" } as ComponentData);
+
+    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
+    expect(reply).toHaveBeenCalledWith({ content: "✓" });
+    expect(enqueueSystemEventMock).toHaveBeenCalled();
+  });
+});
+
+describe("discord component interactions", () => {
+  const createCfg = (): OpenClawConfig =>
+    ({
+      channels: {
+        discord: {
+          replyToMode: "first",
+        },
+      },
+    }) as OpenClawConfig;
+
+  const createDiscordConfig = (overrides?: Partial<DiscordAccountConfig>): DiscordAccountConfig =>
+    ({
+      replyToMode: "first",
+      ...overrides,
+    }) as DiscordAccountConfig;
+
+  type DispatchParams = {
+    ctx: Record<string, unknown>;
+    dispatcherOptions: {
+      deliver: (payload: { text?: string }) => Promise<void> | void;
+    };
+  };
+
+  const createComponentContext = (
+    overrides?: Partial<Parameters<typeof createDiscordComponentButton>[0]>,
+  ) =>
+    ({
+      cfg: createCfg(),
+      accountId: "default",
+      dmPolicy: "allowlist",
+      allowFrom: ["123456789"],
+      discordConfig: createDiscordConfig(),
+      token: "token",
+      ...overrides,
+    }) as Parameters<typeof createDiscordComponentButton>[0];
+
+  const createComponentButtonInteraction = (overrides: Partial<ButtonInteraction> = {}) => {
+    const reply = vi.fn().mockResolvedValue(undefined);
+    const defer = vi.fn().mockResolvedValue(undefined);
+    const interaction = {
+      rawData: { channel_id: "dm-channel", id: "interaction-1" },
+      user: { id: "123456789", username: "AgentUser", discriminator: "0001" },
+      customId: "occomp:cid=btn_1",
+      message: { id: "msg-1" },
+      client: { rest: {} },
+      defer,
+      reply,
+      ...overrides,
+    } as unknown as ButtonInteraction;
+    return { interaction, defer, reply };
+  };
+
+  const createModalInteraction = (overrides: Partial<ModalInteraction> = {}) => {
+    const reply = vi.fn().mockResolvedValue(undefined);
+    const acknowledge = vi.fn().mockResolvedValue(undefined);
+    const fields = {
+      getText: (key: string) => (key === "fld_1" ? "Casey" : undefined),
+      getStringSelect: (_key: string) => undefined,
+      getRoleSelect: (_key: string) => [],
+      getUserSelect: (_key: string) => [],
+    };
+    const interaction = {
+      rawData: { channel_id: "dm-channel", id: "interaction-2" },
+      user: { id: "123456789", username: "AgentUser", discriminator: "0001" },
+      customId: "ocmodal:mid=mdl_1",
+      fields,
+      acknowledge,
+      reply,
+      client: { rest: {} },
+      ...overrides,
+    } as unknown as ModalInteraction;
+    return { interaction, acknowledge, reply };
+  };
+
+  beforeEach(() => {
+    clearDiscordComponentEntries();
+    lastDispatchCtx = undefined;
+    readAllowFromStoreMock.mockReset().mockResolvedValue([]);
+    upsertPairingRequestMock.mockReset().mockResolvedValue({ code: "PAIRCODE", created: true });
+    enqueueSystemEventMock.mockReset();
+    dispatchReplyMock.mockReset().mockImplementation(async (params: DispatchParams) => {
+      lastDispatchCtx = params.ctx;
+      await params.dispatcherOptions.deliver({ text: "ok" });
+    });
+    deliverDiscordReplyMock.mockReset();
+    recordInboundSessionMock.mockReset().mockResolvedValue(undefined);
+    readSessionUpdatedAtMock.mockReset().mockReturnValue(undefined);
+    resolveStorePathMock.mockReset().mockReturnValue("/tmp/openclaw-sessions-test.json");
+  });
+
+  it("routes button clicks with reply references", async () => {
+    registerDiscordComponentEntries({
+      entries: [
+        {
+          id: "btn_1",
+          kind: "button",
+          label: "Approve",
+          messageId: "msg-1",
+          sessionKey: "session-1",
+          agentId: "agent-1",
+          accountId: "default",
+        },
+      ],
+      modals: [],
+    });
+
+    const button = createDiscordComponentButton(createComponentContext());
+    const { interaction, reply } = createComponentButtonInteraction();
+
+    await button.run(interaction, { cid: "btn_1" } as ComponentData);
+
+    expect(reply).toHaveBeenCalledWith({ content: "✓" });
+    expect(lastDispatchCtx?.BodyForAgent).toBe('Clicked "Approve".');
+    expect(dispatchReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock.mock.calls[0]?.[0]?.replyToId).toBe("msg-1");
+    expect(resolveDiscordComponentEntry({ id: "btn_1" })).toBeNull();
+  });
+
+  it("routes modal submissions with field values", async () => {
+    registerDiscordComponentEntries({
+      entries: [],
+      modals: [
+        {
+          id: "mdl_1",
+          title: "Details",
+          messageId: "msg-2",
+          sessionKey: "session-2",
+          agentId: "agent-2",
+          accountId: "default",
+          fields: [
+            {
+              id: "fld_1",
+              name: "name",
+              label: "Name",
+              type: "text",
+            },
+          ],
+        },
+      ],
+    });
+
+    const modal = createDiscordComponentModal(
+      createComponentContext({
+        discordConfig: createDiscordConfig({ replyToMode: "all" }),
+      }),
+    );
+    const { interaction, acknowledge } = createModalInteraction();
+
+    await modal.run(interaction, { mid: "mdl_1" } as ComponentData);
+
+    expect(acknowledge).toHaveBeenCalledTimes(1);
+    expect(lastDispatchCtx?.BodyForAgent).toContain('Form "Details" submitted.');
+    expect(lastDispatchCtx?.BodyForAgent).toContain("- Name: Casey");
+    expect(dispatchReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock.mock.calls[0]?.[0]?.replyToId).toBe("msg-2");
+    expect(resolveDiscordModalEntry({ id: "mdl_1" })).toBeNull();
+  });
+});
+
+describe("resolveDiscordOwnerAllowFrom", () => {
+  it("returns undefined when no allowlist is configured", () => {
+    const result = resolveDiscordOwnerAllowFrom({
+      channelConfig: { allowed: true } as DiscordChannelConfigResolved,
+      sender: { id: "123" },
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("skips wildcard matches for owner allowFrom", () => {
+    const result = resolveDiscordOwnerAllowFrom({
+      channelConfig: { allowed: true, users: ["*"] } as DiscordChannelConfigResolved,
+      sender: { id: "123" },
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns a matching user id entry", () => {
+    const result = resolveDiscordOwnerAllowFrom({
+      channelConfig: { allowed: true, users: ["123"] } as DiscordChannelConfigResolved,
+      sender: { id: "123" },
+    });
+
+    expect(result).toEqual(["123"]);
+  });
+
+  it("returns the normalized name slug for name matches", () => {
+    const result = resolveDiscordOwnerAllowFrom({
+      channelConfig: { allowed: true, users: ["Some User"] } as DiscordChannelConfigResolved,
+      sender: { id: "999", name: "Some User" },
+    });
+
+    expect(result).toEqual(["some-user"]);
+  });
+});
+
+describe("resolveDiscordRoleAllowed", () => {
+  it("allows when no role allowlist is configured", () => {
+    const allowed = resolveDiscordRoleAllowed({
+      allowList: undefined,
+      memberRoleIds: ["role-1"],
+    });
+
+    expect(allowed).toBe(true);
+  });
+
+  it("matches role IDs only", () => {
+    const allowed = resolveDiscordRoleAllowed({
+      allowList: ["123"],
+      memberRoleIds: ["123", "456"],
+    });
+
+    expect(allowed).toBe(true);
+  });
+
+  it("does not match non-ID role entries", () => {
+    const allowed = resolveDiscordRoleAllowed({
+      allowList: ["Admin"],
+      memberRoleIds: ["Admin"],
+    });
+
+    expect(allowed).toBe(false);
+  });
+
+  it("returns false when no matching role IDs", () => {
+    const allowed = resolveDiscordRoleAllowed({
+      allowList: ["456"],
+      memberRoleIds: ["123"],
+    });
+
+    expect(allowed).toBe(false);
+  });
+});
+
+describe("resolveDiscordMemberAllowed", () => {
+  it("allows when no user or role allowlists are configured", () => {
+    const allowed = resolveDiscordMemberAllowed({
+      userAllowList: undefined,
+      roleAllowList: undefined,
+      memberRoleIds: [],
+      userId: "u1",
+    });
+
+    expect(allowed).toBe(true);
+  });
+
+  it("allows when user allowlist matches", () => {
+    const allowed = resolveDiscordMemberAllowed({
+      userAllowList: ["123"],
+      roleAllowList: ["456"],
+      memberRoleIds: ["999"],
+      userId: "123",
+    });
+
+    expect(allowed).toBe(true);
+  });
+
+  it("allows when role allowlist matches", () => {
+    const allowed = resolveDiscordMemberAllowed({
+      userAllowList: ["999"],
+      roleAllowList: ["456"],
+      memberRoleIds: ["456"],
+      userId: "123",
+    });
+
+    expect(allowed).toBe(true);
+  });
+
+  it("denies when user and role allowlists do not match", () => {
+    const allowed = resolveDiscordMemberAllowed({
+      userAllowList: ["u2"],
+      roleAllowList: ["role-2"],
+      memberRoleIds: ["role-1"],
+      userId: "u1",
+    });
+
+    expect(allowed).toBe(false);
+  });
+});
+
+describe("gateway-registry", () => {
+  type GatewayPlugin = { isConnected: boolean };
+
+  function fakeGateway(props: Partial<GatewayPlugin> = {}): GatewayPlugin {
+    return { isConnected: true, ...props };
+  }
+
+  beforeEach(() => {
+    clearGateways();
+  });
+
+  it("stores and retrieves a gateway by account", () => {
+    const gateway = fakeGateway();
+    registerGateway("account-a", gateway as never);
+    expect(getGateway("account-a")).toBe(gateway);
+    expect(getGateway("account-b")).toBeUndefined();
+  });
+
+  it("uses collision-safe key when accountId is undefined", () => {
+    const gateway = fakeGateway();
+    registerGateway(undefined, gateway as never);
+    expect(getGateway(undefined)).toBe(gateway);
+    expect(getGateway("default")).toBeUndefined();
+  });
+
+  it("unregisters a gateway", () => {
+    const gateway = fakeGateway();
+    registerGateway("account-a", gateway as never);
+    unregisterGateway("account-a");
+    expect(getGateway("account-a")).toBeUndefined();
+  });
+
+  it("clears all gateways", () => {
+    registerGateway("a", fakeGateway() as never);
+    registerGateway("b", fakeGateway() as never);
+    clearGateways();
+    expect(getGateway("a")).toBeUndefined();
+    expect(getGateway("b")).toBeUndefined();
+  });
+
+  it("overwrites existing entry for same account", () => {
+    const gateway1 = fakeGateway({ isConnected: true });
+    const gateway2 = fakeGateway({ isConnected: false });
+    registerGateway("account-a", gateway1 as never);
+    registerGateway("account-a", gateway2 as never);
+    expect(getGateway("account-a")).toBe(gateway2);
+  });
+});
+
+describe("presence-cache", () => {
+  beforeEach(() => {
+    clearPresences();
+  });
+
+  it("scopes presence entries by account", () => {
+    const presenceA = { status: "online" } as GatewayPresenceUpdate;
+    const presenceB = { status: "idle" } as GatewayPresenceUpdate;
+
+    setPresence("account-a", "user-1", presenceA);
+    setPresence("account-b", "user-1", presenceB);
+
+    expect(getPresence("account-a", "user-1")).toBe(presenceA);
+    expect(getPresence("account-b", "user-1")).toBe(presenceB);
+    expect(getPresence("account-a", "user-2")).toBeUndefined();
+  });
+
+  it("clears presence per account", () => {
+    const presence = { status: "dnd" } as GatewayPresenceUpdate;
+
+    setPresence("account-a", "user-1", presence);
+    setPresence("account-b", "user-2", presence);
+
+    clearPresences("account-a");
+
+    expect(getPresence("account-a", "user-1")).toBeUndefined();
+    expect(getPresence("account-b", "user-2")).toBe(presence);
+    expect(presenceCacheSize()).toBe(1);
+  });
+});
+
+describe("resolveDiscordPresenceUpdate", () => {
+  it("returns null when no presence config provided", () => {
+    expect(resolveDiscordPresenceUpdate({})).toBeNull();
+  });
+
+  it("returns status-only presence when activity is omitted", () => {
+    const presence = resolveDiscordPresenceUpdate({ status: "dnd" });
+    expect(presence).not.toBeNull();
+    expect(presence?.status).toBe("dnd");
+    expect(presence?.activities).toEqual([]);
+  });
+
+  it("defaults to custom activity type when activity is set without type", () => {
+    const presence = resolveDiscordPresenceUpdate({ activity: "Focus time" });
+    expect(presence).not.toBeNull();
+    expect(presence?.status).toBe("online");
+    expect(presence?.activities).toHaveLength(1);
+    expect(presence?.activities[0]).toMatchObject({
+      type: 4,
+      name: "Custom Status",
+      state: "Focus time",
+    });
+  });
+
+  it("includes streaming url when activityType is streaming", () => {
+    const presence = resolveDiscordPresenceUpdate({
+      activity: "Live",
+      activityType: 1,
+      activityUrl: "https://twitch.tv/openclaw",
+    });
+    expect(presence).not.toBeNull();
+    expect(presence?.activities).toHaveLength(1);
+    expect(presence?.activities[0]).toMatchObject({
+      type: 1,
+      name: "Live",
+      url: "https://twitch.tv/openclaw",
+    });
+  });
+});
+
+describe("resolveDiscordAutoThreadContext", () => {
+  it("returns null when no createdThreadId", () => {
+    expect(
+      resolveDiscordAutoThreadContext({
+        agentId: "agent",
+        channel: "discord",
+        messageChannelId: "parent",
+        createdThreadId: undefined,
+      }),
+    ).toBeNull();
+  });
+
+  it("re-keys session context to the created thread", () => {
+    const context = resolveDiscordAutoThreadContext({
+      agentId: "agent",
+      channel: "discord",
+      messageChannelId: "parent",
+      createdThreadId: "thread",
+    });
+    expect(context).not.toBeNull();
+    expect(context?.To).toBe("channel:thread");
+    expect(context?.From).toBe("discord:channel:thread");
+    expect(context?.OriginatingTo).toBe("channel:thread");
+    expect(context?.SessionKey).toBe(
+      buildAgentSessionKey({
+        agentId: "agent",
+        channel: "discord",
+        peer: { kind: "channel", id: "thread" },
+      }),
+    );
+    expect(context?.ParentSessionKey).toBe(
+      buildAgentSessionKey({
+        agentId: "agent",
+        channel: "discord",
+        peer: { kind: "channel", id: "parent" },
+      }),
+    );
+  });
+});
+
+describe("resolveDiscordReplyDeliveryPlan", () => {
+  it("uses reply references when posting to the original target", () => {
+    const plan = resolveDiscordReplyDeliveryPlan({
+      replyTarget: "channel:parent",
+      replyToMode: "all",
+      messageId: "m1",
+      threadChannel: null,
+      createdThreadId: null,
+    });
+    expect(plan.deliverTarget).toBe("channel:parent");
+    expect(plan.replyTarget).toBe("channel:parent");
+    expect(plan.replyReference.use()).toBe("m1");
+  });
+
+  it("disables reply references when autoThread creates a new thread", () => {
+    const plan = resolveDiscordReplyDeliveryPlan({
+      replyTarget: "channel:parent",
+      replyToMode: "all",
+      messageId: "m1",
+      threadChannel: null,
+      createdThreadId: "thread",
+    });
+    expect(plan.deliverTarget).toBe("channel:thread");
+    expect(plan.replyTarget).toBe("channel:thread");
+    expect(plan.replyReference.use()).toBeUndefined();
+  });
+
+  it("respects replyToMode off even inside a thread", () => {
+    const plan = resolveDiscordReplyDeliveryPlan({
+      replyTarget: "channel:thread",
+      replyToMode: "off",
+      messageId: "m1",
+      threadChannel: { id: "thread" },
+      createdThreadId: null,
+    });
+    expect(plan.replyReference.use()).toBeUndefined();
+  });
+
+  it("uses existingId when inside a thread with replyToMode all", () => {
+    const plan = resolveDiscordReplyDeliveryPlan({
+      replyTarget: "channel:thread",
+      replyToMode: "all",
+      messageId: "m1",
+      threadChannel: { id: "thread" },
+      createdThreadId: null,
+    });
+    expect(plan.replyReference.use()).toBe("m1");
+    expect(plan.replyReference.use()).toBe("m1");
+  });
+
+  it("uses existingId only on first call with replyToMode first inside a thread", () => {
+    const plan = resolveDiscordReplyDeliveryPlan({
+      replyTarget: "channel:thread",
+      replyToMode: "first",
+      messageId: "m1",
+      threadChannel: { id: "thread" },
+      createdThreadId: null,
+    });
+    expect(plan.replyReference.use()).toBe("m1");
+    expect(plan.replyReference.use()).toBeUndefined();
+  });
+});
+
+describe("maybeCreateDiscordAutoThread", () => {
+  it("returns existing thread ID when creation fails due to race condition", async () => {
+    const client = {
+      rest: {
+        post: async () => {
+          throw new Error("A thread has already been created on this message");
+        },
+        get: async () => ({ thread: { id: "existing-thread" } }),
+      },
+    } as unknown as Client;
+
+    const result = await maybeCreateDiscordAutoThread({
+      client,
+      message: {
+        id: "m1",
+        channelId: "parent",
+      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
+      isGuildMessage: true,
+      channelConfig: {
+        autoThread: true,
+      } as unknown as DiscordChannelConfigResolved,
+      threadChannel: null,
+      baseText: "hello",
+      combinedBody: "hello",
+    });
+
+    expect(result).toBe("existing-thread");
+  });
+
+  it("returns undefined when creation fails and no existing thread found", async () => {
+    const client = {
+      rest: {
+        post: async () => {
+          throw new Error("Some other error");
+        },
+        get: async () => ({ thread: null }),
+      },
+    } as unknown as Client;
+
+    const result = await maybeCreateDiscordAutoThread({
+      client,
+      message: {
+        id: "m1",
+        channelId: "parent",
+      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
+      isGuildMessage: true,
+      channelConfig: {
+        autoThread: true,
+      } as unknown as DiscordChannelConfigResolved,
+      threadChannel: null,
+      baseText: "hello",
+      combinedBody: "hello",
+    });
+
+    expect(result).toBeUndefined();
+  });
+});
+
+describe("resolveDiscordAutoThreadReplyPlan", () => {
+  it("switches delivery + session context to the created thread", async () => {
+    const client = {
+      rest: { post: async () => ({ id: "thread" }) },
+    } as unknown as Client;
+    const plan = await resolveDiscordAutoThreadReplyPlan({
+      client,
+      message: {
+        id: "m1",
+        channelId: "parent",
+      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
+      isGuildMessage: true,
+      channelConfig: {
+        autoThread: true,
+      } as unknown as DiscordChannelConfigResolved,
+      threadChannel: null,
+      baseText: "hello",
+      combinedBody: "hello",
+      replyToMode: "all",
+      agentId: "agent",
+      channel: "discord",
+    });
+    expect(plan.deliverTarget).toBe("channel:thread");
+    expect(plan.replyReference.use()).toBeUndefined();
+    expect(plan.autoThreadContext?.SessionKey).toBe(
+      buildAgentSessionKey({
+        agentId: "agent",
+        channel: "discord",
+        peer: { kind: "channel", id: "thread" },
+      }),
+    );
+  });
+
+  it("routes replies to an existing thread channel", async () => {
+    const client = { rest: { post: async () => ({ id: "thread" }) } } as unknown as Client;
+    const plan = await resolveDiscordAutoThreadReplyPlan({
+      client,
+      message: {
+        id: "m1",
+        channelId: "parent",
+      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
+      isGuildMessage: true,
+      channelConfig: {
+        autoThread: true,
+      } as unknown as DiscordChannelConfigResolved,
+      threadChannel: { id: "thread" },
+      baseText: "hello",
+      combinedBody: "hello",
+      replyToMode: "all",
+      agentId: "agent",
+      channel: "discord",
+    });
+    expect(plan.deliverTarget).toBe("channel:thread");
+    expect(plan.replyTarget).toBe("channel:thread");
+    expect(plan.replyReference.use()).toBe("m1");
+    expect(plan.autoThreadContext).toBeNull();
+  });
+
+  it("does nothing when autoThread is disabled", async () => {
+    const client = { rest: { post: async () => ({ id: "thread" }) } } as unknown as Client;
+    const plan = await resolveDiscordAutoThreadReplyPlan({
+      client,
+      message: {
+        id: "m1",
+        channelId: "parent",
+      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
+      isGuildMessage: true,
+      channelConfig: {
+        autoThread: false,
+      } as unknown as DiscordChannelConfigResolved,
+      threadChannel: null,
+      baseText: "hello",
+      combinedBody: "hello",
+      replyToMode: "all",
+      agentId: "agent",
+      channel: "discord",
+    });
+    expect(plan.deliverTarget).toBe("channel:parent");
+    expect(plan.autoThreadContext).toBeNull();
+  });
+});
diff --git a/src/discord/monitor/native-command.ts b/src/discord/monitor/native-command.ts
index 62e2fb03c89..65d1ab1468c 100644
--- a/src/discord/monitor/native-command.ts
+++ b/src/discord/monitor/native-command.ts
@@ -42,6 +42,7 @@ import {
 } from "../../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../../routing/resolve-route.js";
 import { buildUntrustedChannelMetadata } from "../../security/channel-metadata.js";
+import { chunkItems } from "../../utils/chunk-items.js";
 import { loadWebMedia } from "../../web/media.js";
 import { chunkDiscordTextWithMode } from "../chunk.js";
 import {
@@ -51,7 +52,7 @@ import {
   normalizeDiscordSlug,
   resolveDiscordChannelConfigWithFallback,
   resolveDiscordGuildEntry,
-  resolveDiscordMemberAllowed,
+  resolveDiscordMemberAccessState,
   resolveDiscordOwnerAllowFrom,
 } from "./allow-list.js";
 import { resolveDiscordChannelInfo } from "./message-utils.js";
@@ -146,17 +147,6 @@ function readDiscordCommandArgs(
   return Object.keys(values).length > 0 ? { values } : undefined;
 }
 
-function chunkItems<T>(items: T[], size: number): T[][] {
-  if (size <= 0) {
-    return [items];
-  }
-  const rows: T[][] = [];
-  for (let i = 0; i < items.length; i += size) {
-    rows.push(items.slice(i, i + size));
-  }
-  return rows;
-}
-
 const DISCORD_COMMAND_ARG_CUSTOM_ID_KEY = "cmdarg";
 
 function createCommandArgsWithValue(params: { argName: string; value: string }): CommandArgs {
@@ -667,18 +657,11 @@ async function dispatchDiscordCommandInteraction(params: {
     }
   }
   if (!isDirectMessage) {
-    const channelUsers = channelConfig?.users ?? guildInfo?.users;
-    const channelRoles = channelConfig?.roles ?? guildInfo?.roles;
-    const hasAccessRestrictions =
-      (Array.isArray(channelUsers) && channelUsers.length > 0) ||
-      (Array.isArray(channelRoles) && channelRoles.length > 0);
-    const memberAllowed = resolveDiscordMemberAllowed({
-      userAllowList: channelUsers,
-      roleAllowList: channelRoles,
+    const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+      channelConfig,
+      guildInfo,
       memberRoleIds,
-      userId: sender.id,
-      userName: sender.name,
-      userTag: sender.tag,
+      sender,
     });
     const authorizers = useAccessGroups
       ? [
diff --git a/src/discord/monitor/presence-cache.test.ts b/src/discord/monitor/presence-cache.test.ts
deleted file mode 100644
index e7dd04d0806..00000000000
--- a/src/discord/monitor/presence-cache.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import type { GatewayPresenceUpdate } from "discord-api-types/v10";
-import { beforeEach, describe, expect, it } from "vitest";
-import { clearPresences, getPresence, presenceCacheSize, setPresence } from "./presence-cache.js";
-
-describe("presence-cache", () => {
-  beforeEach(() => {
-    clearPresences();
-  });
-
-  it("scopes presence entries by account", () => {
-    const presenceA = { status: "online" } as GatewayPresenceUpdate;
-    const presenceB = { status: "idle" } as GatewayPresenceUpdate;
-
-    setPresence("account-a", "user-1", presenceA);
-    setPresence("account-b", "user-1", presenceB);
-
-    expect(getPresence("account-a", "user-1")).toBe(presenceA);
-    expect(getPresence("account-b", "user-1")).toBe(presenceB);
-    expect(getPresence("account-a", "user-2")).toBeUndefined();
-  });
-
-  it("clears presence per account", () => {
-    const presence = { status: "dnd" } as GatewayPresenceUpdate;
-
-    setPresence("account-a", "user-1", presence);
-    setPresence("account-b", "user-2", presence);
-
-    clearPresences("account-a");
-
-    expect(getPresence("account-a", "user-1")).toBeUndefined();
-    expect(getPresence("account-b", "user-2")).toBe(presence);
-    expect(presenceCacheSize()).toBe(1);
-  });
-});
diff --git a/src/discord/monitor/presence.test.ts b/src/discord/monitor/presence.test.ts
deleted file mode 100644
index 83fd15efaf6..00000000000
--- a/src/discord/monitor/presence.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveDiscordPresenceUpdate } from "./presence.js";
-
-describe("resolveDiscordPresenceUpdate", () => {
-  it("returns null when no presence config provided", () => {
-    expect(resolveDiscordPresenceUpdate({})).toBeNull();
-  });
-
-  it("returns status-only presence when activity is omitted", () => {
-    const presence = resolveDiscordPresenceUpdate({ status: "dnd" });
-    expect(presence).not.toBeNull();
-    expect(presence?.status).toBe("dnd");
-    expect(presence?.activities).toEqual([]);
-  });
-
-  it("defaults to custom activity type when activity is set without type", () => {
-    const presence = resolveDiscordPresenceUpdate({ activity: "Focus time" });
-    expect(presence).not.toBeNull();
-    expect(presence?.status).toBe("online");
-    expect(presence?.activities).toHaveLength(1);
-    expect(presence?.activities[0]).toMatchObject({
-      type: 4,
-      name: "Custom Status",
-      state: "Focus time",
-    });
-  });
-
-  it("includes streaming url when activityType is streaming", () => {
-    const presence = resolveDiscordPresenceUpdate({
-      activity: "Live",
-      activityType: 1,
-      activityUrl: "https://twitch.tv/openclaw",
-    });
-    expect(presence).not.toBeNull();
-    expect(presence?.activities).toHaveLength(1);
-    expect(presence?.activities[0]).toMatchObject({
-      type: 1,
-      name: "Live",
-      url: "https://twitch.tv/openclaw",
-    });
-  });
-});
diff --git a/src/discord/monitor/provider.skill-dedupe.test.ts b/src/discord/monitor/provider.skill-dedupe.test.ts
new file mode 100644
index 00000000000..06e27774010
--- /dev/null
+++ b/src/discord/monitor/provider.skill-dedupe.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { __testing } from "./provider.js";
+
+describe("dedupeSkillCommandsForDiscord", () => {
+  it("keeps first command per skillName and drops suffix duplicates", () => {
+    const input = [
+      { name: "github", skillName: "github", description: "GitHub" },
+      { name: "github_2", skillName: "github", description: "GitHub" },
+      { name: "weather", skillName: "weather", description: "Weather" },
+      { name: "weather_2", skillName: "weather", description: "Weather" },
+    ];
+
+    const output = __testing.dedupeSkillCommandsForDiscord(input);
+    expect(output.map((entry) => entry.name)).toEqual(["github", "weather"]);
+  });
+
+  it("treats skillName case-insensitively", () => {
+    const input = [
+      { name: "ClawHub", skillName: "ClawHub", description: "ClawHub" },
+      { name: "clawhub_2", skillName: "clawhub", description: "ClawHub" },
+    ];
+    const output = __testing.dedupeSkillCommandsForDiscord(input);
+    expect(output).toHaveLength(1);
+    expect(output[0]?.name).toBe("ClawHub");
+  });
+});
diff --git a/src/discord/monitor/provider.ts b/src/discord/monitor/provider.ts
index a52f8c911cb..5ee54ab68ce 100644
--- a/src/discord/monitor/provider.ts
+++ b/src/discord/monitor/provider.ts
@@ -1,5 +1,10 @@
 import type { GatewayPlugin } from "@buape/carbon/gateway";
-import { Client, ReadyListener, type BaseMessageInteractiveComponent } from "@buape/carbon";
+import {
+  Client,
+  ReadyListener,
+  type BaseMessageInteractiveComponent,
+  type Modal,
+} from "@buape/carbon";
 import { Routes } from "discord-api-types/v10";
 import { inspect } from "node:util";
 import type { HistoryEntry } from "../../auto-reply/reply/history.js";
@@ -8,6 +13,7 @@ import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { listNativeCommandSpecsForConfig } from "../../auto-reply/commands-registry.js";
 import { listSkillCommandsForAgents } from "../../auto-reply/skill-commands.js";
 import {
+  addAllowlistUserEntriesFromConfigEntry,
   buildAllowlistResolutionSummary,
   mergeAllowlist,
   resolveAllowlistIdAdditions,
@@ -32,7 +38,17 @@ import { fetchDiscordApplicationId } from "../probe.js";
 import { resolveDiscordChannelAllowlist } from "../resolve-channels.js";
 import { resolveDiscordUserAllowlist } from "../resolve-users.js";
 import { normalizeDiscordToken } from "../token.js";
-import { createAgentComponentButton, createAgentSelectMenu } from "./agent-components.js";
+import {
+  createAgentComponentButton,
+  createAgentSelectMenu,
+  createDiscordComponentButton,
+  createDiscordComponentChannelSelect,
+  createDiscordComponentMentionableSelect,
+  createDiscordComponentModal,
+  createDiscordComponentRoleSelect,
+  createDiscordComponentStringSelect,
+  createDiscordComponentUserSelect,
+} from "./agent-components.js";
 import { createExecApprovalButton, DiscordExecApprovalHandler } from "./exec-approvals.js";
 import { createDiscordGatewayPlugin } from "./gateway-plugin.js";
 import { registerGateway, unregisterGateway } from "./gateway-registry.js";
@@ -80,6 +96,26 @@ function summarizeGuilds(entries?: Record<string, unknown>) {
   return `${sample.join(", ")}${suffix}`;
 }
 
+function dedupeSkillCommandsForDiscord(
+  skillCommands: ReturnType<typeof listSkillCommandsForAgents>,
+) {
+  const seen = new Set<string>();
+  const deduped: ReturnType<typeof listSkillCommandsForAgents> = [];
+  for (const command of skillCommands) {
+    const key = command.skillName.trim().toLowerCase();
+    if (!key) {
+      deduped.push(command);
+      continue;
+    }
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(command);
+  }
+  return deduped;
+}
+
 async function deployDiscordCommands(params: {
   client: Client;
   runtime: RuntimeEnv;
@@ -278,17 +314,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
           token,
           entries: allowEntries.map((entry) => String(entry)),
         });
-        const mapping: string[] = [];
-        const unresolved: string[] = [];
-        const additions: string[] = [];
-        for (const entry of resolvedUsers) {
-          if (entry.resolved && entry.id) {
-            mapping.push(`${entry.input}→${entry.id}`);
-            additions.push(entry.id);
-          } else {
-            unresolved.push(entry.input);
-          }
-        }
+        const { mapping, unresolved, additions } = buildAllowlistResolutionSummary(resolvedUsers);
         allowFrom = mergeAllowlist({ existing: allowFrom, additions });
         summarizeMapping("discord users", mapping, unresolved, runtime);
       } catch (err) {
@@ -304,30 +330,10 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
         if (!guild || typeof guild !== "object") {
           continue;
         }
-        const users = (guild as { users?: Array<string | number> }).users;
-        if (Array.isArray(users)) {
-          for (const entry of users) {
-            const trimmed = String(entry).trim();
-            if (trimmed && trimmed !== "*") {
-              userEntries.add(trimmed);
-            }
-          }
-        }
+        addAllowlistUserEntriesFromConfigEntry(userEntries, guild);
         const channels = (guild as { channels?: Record<string, unknown> }).channels ?? {};
         for (const channel of Object.values(channels)) {
-          if (!channel || typeof channel !== "object") {
-            continue;
-          }
-          const channelUsers = (channel as { users?: Array<string | number> }).users;
-          if (!Array.isArray(channelUsers)) {
-            continue;
-          }
-          for (const entry of channelUsers) {
-            const trimmed = String(entry).trim();
-            if (trimmed && trimmed !== "*") {
-              userEntries.add(trimmed);
-            }
-          }
+          addAllowlistUserEntriesFromConfigEntry(userEntries, channel);
         }
       }
 
@@ -384,7 +390,9 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
 
   const maxDiscordCommands = 100;
   let skillCommands =
-    nativeEnabled && nativeSkillsEnabled ? listSkillCommandsForAgents({ cfg }) : [];
+    nativeEnabled && nativeSkillsEnabled
+      ? dedupeSkillCommandsForDiscord(listSkillCommandsForAgents({ cfg }))
+      : [];
   let commandSpecs = nativeEnabled
     ? listNativeCommandSpecsForConfig(cfg, { skillCommands, provider: "discord" })
     : [];
@@ -439,30 +447,32 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
       sessionPrefix,
     }),
   ];
+  const modals: Modal[] = [];
 
   if (execApprovalsHandler) {
     components.push(createExecApprovalButton({ handler: execApprovalsHandler }));
   }
 
   if (agentComponentsEnabled) {
-    components.push(
-      createAgentComponentButton({
-        cfg,
-        accountId: account.accountId,
-        guildEntries,
-        allowFrom,
-        dmPolicy,
-      }),
-    );
-    components.push(
-      createAgentSelectMenu({
-        cfg,
-        accountId: account.accountId,
-        guildEntries,
-        allowFrom,
-        dmPolicy,
-      }),
-    );
+    const componentContext = {
+      cfg,
+      discordConfig: discordCfg,
+      accountId: account.accountId,
+      guildEntries,
+      allowFrom,
+      dmPolicy,
+      runtime,
+      token,
+    };
+    components.push(createAgentComponentButton(componentContext));
+    components.push(createAgentSelectMenu(componentContext));
+    components.push(createDiscordComponentButton(componentContext));
+    components.push(createDiscordComponentStringSelect(componentContext));
+    components.push(createDiscordComponentUserSelect(componentContext));
+    components.push(createDiscordComponentRoleSelect(componentContext));
+    components.push(createDiscordComponentMentionableSelect(componentContext));
+    components.push(createDiscordComponentChannelSelect(componentContext));
+    modals.push(createDiscordComponentModal(componentContext));
   }
 
   class DiscordStatusReadyListener extends ReadyListener {
@@ -494,6 +504,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
       commands,
       listeners: [new DiscordStatusReadyListener()],
       components,
+      modals,
     },
     [createDiscordGatewayPlugin({ discordConfig: discordCfg, runtime })],
   );
@@ -677,4 +688,5 @@ async function clearDiscordNativeCommands(params: {
 
 export const __testing = {
   createDiscordGatewayPlugin,
+  dedupeSkillCommandsForDiscord,
 };
diff --git a/src/discord/monitor/reply-context.ts b/src/discord/monitor/reply-context.ts
index 69df5a2e963..16866254aee 100644
--- a/src/discord/monitor/reply-context.ts
+++ b/src/discord/monitor/reply-context.ts
@@ -43,7 +43,11 @@ export function buildDirectLabel(author: User, tagOverride?: string) {
   return `${username ?? "unknown"} user id:${author.id}`;
 }
 
-export function buildGuildLabel(params: { guild?: Guild; channelName: string; channelId: string }) {
+export function buildGuildLabel(params: {
+  guild?: Guild<true> | Guild;
+  channelName: string;
+  channelId: string;
+}) {
   const { guild, channelName, channelId } = params;
   return `${guild?.name ?? "Guild"} #${channelName} channel id:${channelId}`;
 }
diff --git a/src/discord/monitor/threading.test.ts b/src/discord/monitor/threading.test.ts
deleted file mode 100644
index 587aca8bb16..00000000000
--- a/src/discord/monitor/threading.test.ts
+++ /dev/null
@@ -1,261 +0,0 @@
-import type { Client } from "@buape/carbon";
-import { describe, expect, it } from "vitest";
-import { buildAgentSessionKey } from "../../routing/resolve-route.js";
-import {
-  maybeCreateDiscordAutoThread,
-  resolveDiscordAutoThreadContext,
-  resolveDiscordAutoThreadReplyPlan,
-  resolveDiscordReplyDeliveryPlan,
-} from "./threading.js";
-
-describe("resolveDiscordAutoThreadContext", () => {
-  it("returns null when no createdThreadId", () => {
-    expect(
-      resolveDiscordAutoThreadContext({
-        agentId: "agent",
-        channel: "discord",
-        messageChannelId: "parent",
-        createdThreadId: undefined,
-      }),
-    ).toBeNull();
-  });
-
-  it("re-keys session context to the created thread", () => {
-    const context = resolveDiscordAutoThreadContext({
-      agentId: "agent",
-      channel: "discord",
-      messageChannelId: "parent",
-      createdThreadId: "thread",
-    });
-    expect(context).not.toBeNull();
-    expect(context?.To).toBe("channel:thread");
-    expect(context?.From).toBe("discord:channel:thread");
-    expect(context?.OriginatingTo).toBe("channel:thread");
-    expect(context?.SessionKey).toBe(
-      buildAgentSessionKey({
-        agentId: "agent",
-        channel: "discord",
-        peer: { kind: "channel", id: "thread" },
-      }),
-    );
-    expect(context?.ParentSessionKey).toBe(
-      buildAgentSessionKey({
-        agentId: "agent",
-        channel: "discord",
-        peer: { kind: "channel", id: "parent" },
-      }),
-    );
-  });
-});
-
-describe("resolveDiscordReplyDeliveryPlan", () => {
-  it("uses reply references when posting to the original target", () => {
-    const plan = resolveDiscordReplyDeliveryPlan({
-      replyTarget: "channel:parent",
-      replyToMode: "all",
-      messageId: "m1",
-      threadChannel: null,
-      createdThreadId: null,
-    });
-    expect(plan.deliverTarget).toBe("channel:parent");
-    expect(plan.replyTarget).toBe("channel:parent");
-    expect(plan.replyReference.use()).toBe("m1");
-  });
-
-  it("disables reply references when autoThread creates a new thread", () => {
-    const plan = resolveDiscordReplyDeliveryPlan({
-      replyTarget: "channel:parent",
-      replyToMode: "all",
-      messageId: "m1",
-      threadChannel: null,
-      createdThreadId: "thread",
-    });
-    expect(plan.deliverTarget).toBe("channel:thread");
-    expect(plan.replyTarget).toBe("channel:thread");
-    expect(plan.replyReference.use()).toBeUndefined();
-  });
-
-  it("respects replyToMode off even inside a thread", () => {
-    const plan = resolveDiscordReplyDeliveryPlan({
-      replyTarget: "channel:thread",
-      replyToMode: "off",
-      messageId: "m1",
-      threadChannel: { id: "thread" },
-      createdThreadId: null,
-    });
-    expect(plan.replyReference.use()).toBeUndefined();
-  });
-
-  it("uses existingId when inside a thread with replyToMode all", () => {
-    const plan = resolveDiscordReplyDeliveryPlan({
-      replyTarget: "channel:thread",
-      replyToMode: "all",
-      messageId: "m1",
-      threadChannel: { id: "thread" },
-      createdThreadId: null,
-    });
-    // "all" returns the reference on every call.
-    expect(plan.replyReference.use()).toBe("m1");
-    expect(plan.replyReference.use()).toBe("m1");
-  });
-
-  it("uses existingId only on first call with replyToMode first inside a thread", () => {
-    const plan = resolveDiscordReplyDeliveryPlan({
-      replyTarget: "channel:thread",
-      replyToMode: "first",
-      messageId: "m1",
-      threadChannel: { id: "thread" },
-      createdThreadId: null,
-    });
-    // "first" returns the reference only once.
-    expect(plan.replyReference.use()).toBe("m1");
-    expect(plan.replyReference.use()).toBeUndefined();
-  });
-});
-
-describe("maybeCreateDiscordAutoThread", () => {
-  it("returns existing thread ID when creation fails due to race condition", async () => {
-    // First call succeeds (simulating another agent creating the thread)
-    const client = {
-      rest: {
-        post: async () => {
-          throw new Error("A thread has already been created on this message");
-        },
-        get: async () => {
-          // Return message with existing thread (simulating race condition resolution)
-          return { thread: { id: "existing-thread" } };
-        },
-      },
-    } as unknown as Client;
-
-    const result = await maybeCreateDiscordAutoThread({
-      client,
-      message: {
-        id: "m1",
-        channelId: "parent",
-      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
-      isGuildMessage: true,
-      channelConfig: {
-        autoThread: true,
-      } as unknown as import("./allow-list.js").DiscordChannelConfigResolved,
-      threadChannel: null,
-      baseText: "hello",
-      combinedBody: "hello",
-    });
-
-    expect(result).toBe("existing-thread");
-  });
-
-  it("returns undefined when creation fails and no existing thread found", async () => {
-    const client = {
-      rest: {
-        post: async () => {
-          throw new Error("Some other error");
-        },
-        get: async () => {
-          // Message has no thread
-          return { thread: null };
-        },
-      },
-    } as unknown as Client;
-
-    const result = await maybeCreateDiscordAutoThread({
-      client,
-      message: {
-        id: "m1",
-        channelId: "parent",
-      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
-      isGuildMessage: true,
-      channelConfig: {
-        autoThread: true,
-      } as unknown as import("./allow-list.js").DiscordChannelConfigResolved,
-      threadChannel: null,
-      baseText: "hello",
-      combinedBody: "hello",
-    });
-
-    expect(result).toBeUndefined();
-  });
-});
-
-describe("resolveDiscordAutoThreadReplyPlan", () => {
-  it("switches delivery + session context to the created thread", async () => {
-    const client = {
-      rest: { post: async () => ({ id: "thread" }) },
-    } as unknown as Client;
-    const plan = await resolveDiscordAutoThreadReplyPlan({
-      client,
-      message: {
-        id: "m1",
-        channelId: "parent",
-      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
-      isGuildMessage: true,
-      channelConfig: {
-        autoThread: true,
-      } as unknown as import("./allow-list.js").DiscordChannelConfigResolved,
-      threadChannel: null,
-      baseText: "hello",
-      combinedBody: "hello",
-      replyToMode: "all",
-      agentId: "agent",
-      channel: "discord",
-    });
-    expect(plan.deliverTarget).toBe("channel:thread");
-    expect(plan.replyReference.use()).toBeUndefined();
-    expect(plan.autoThreadContext?.SessionKey).toBe(
-      buildAgentSessionKey({
-        agentId: "agent",
-        channel: "discord",
-        peer: { kind: "channel", id: "thread" },
-      }),
-    );
-  });
-
-  it("routes replies to an existing thread channel", async () => {
-    const client = { rest: { post: async () => ({ id: "thread" }) } } as unknown as Client;
-    const plan = await resolveDiscordAutoThreadReplyPlan({
-      client,
-      message: {
-        id: "m1",
-        channelId: "parent",
-      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
-      isGuildMessage: true,
-      channelConfig: {
-        autoThread: true,
-      } as unknown as import("./allow-list.js").DiscordChannelConfigResolved,
-      threadChannel: { id: "thread" },
-      baseText: "hello",
-      combinedBody: "hello",
-      replyToMode: "all",
-      agentId: "agent",
-      channel: "discord",
-    });
-    expect(plan.deliverTarget).toBe("channel:thread");
-    expect(plan.replyTarget).toBe("channel:thread");
-    expect(plan.replyReference.use()).toBe("m1");
-    expect(plan.autoThreadContext).toBeNull();
-  });
-
-  it("does nothing when autoThread is disabled", async () => {
-    const client = { rest: { post: async () => ({ id: "thread" }) } } as unknown as Client;
-    const plan = await resolveDiscordAutoThreadReplyPlan({
-      client,
-      message: {
-        id: "m1",
-        channelId: "parent",
-      } as unknown as import("./listeners.js").DiscordMessageEvent["message"],
-      isGuildMessage: true,
-      channelConfig: {
-        autoThread: false,
-      } as unknown as import("./allow-list.js").DiscordChannelConfigResolved,
-      threadChannel: null,
-      baseText: "hello",
-      combinedBody: "hello",
-      replyToMode: "all",
-      agentId: "agent",
-      channel: "discord",
-    });
-    expect(plan.deliverTarget).toBe("channel:parent");
-    expect(plan.autoThreadContext).toBeNull();
-  });
-});
diff --git a/src/discord/monitor/threading.ts b/src/discord/monitor/threading.ts
index 41c4ab5e0df..718f1d11daf 100644
--- a/src/discord/monitor/threading.ts
+++ b/src/discord/monitor/threading.ts
@@ -7,7 +7,7 @@ import { createReplyReferencePlanner } from "../../auto-reply/reply/reply-refere
 import { logVerbose } from "../../globals.js";
 import { buildAgentSessionKey } from "../../routing/resolve-route.js";
 import { truncateUtf16Safe } from "../../utils.js";
-import { resolveDiscordChannelInfo } from "./message-utils.js";
+import { resolveDiscordChannelInfo, resolveDiscordMessageChannelId } from "./message-utils.js";
 
 export type DiscordThreadChannel = {
   id: string;
@@ -89,6 +89,7 @@ export function resolveDiscordThreadChannel(params: {
   isGuildMessage: boolean;
   message: DiscordMessageEvent["message"];
   channelInfo: import("./message-utils.js").DiscordChannelInfo | null;
+  messageChannelId?: string;
 }): DiscordThreadChannel | null {
   if (!params.isGuildMessage) {
     return null;
@@ -107,8 +108,16 @@ export function resolveDiscordThreadChannel(params: {
   if (!isDiscordThreadType(channelInfo?.type)) {
     return null;
   }
+  const messageChannelId =
+    params.messageChannelId ||
+    resolveDiscordMessageChannelId({
+      message,
+    });
+  if (!messageChannelId) {
+    return null;
+  }
   return {
-    id: message.channelId,
+    id: messageChannelId,
     name: channelInfo?.name ?? undefined,
     parentId: channelInfo?.parentId ?? undefined,
     parent: undefined,
@@ -285,6 +294,7 @@ export type DiscordAutoThreadReplyPlan = DiscordReplyDeliveryPlan & {
 export async function resolveDiscordAutoThreadReplyPlan(params: {
   client: Client;
   message: DiscordMessageEvent["message"];
+  messageChannelId?: string;
   isGuildMessage: boolean;
   channelConfig?: DiscordChannelConfigResolved | null;
   threadChannel?: DiscordThreadChannel | null;
@@ -294,12 +304,19 @@ export async function resolveDiscordAutoThreadReplyPlan(params: {
   agentId: string;
   channel: string;
 }): Promise<DiscordAutoThreadReplyPlan> {
+  const messageChannelId = (
+    params.messageChannelId ||
+    resolveDiscordMessageChannelId({
+      message: params.message,
+    })
+  ).trim();
   // Prefer the resolved thread channel ID when available so replies stay in-thread.
-  const targetChannelId = params.threadChannel?.id ?? params.message.channelId;
+  const targetChannelId = params.threadChannel?.id ?? (messageChannelId || "unknown");
   const originalReplyTarget = `channel:${targetChannelId}`;
   const createdThreadId = await maybeCreateDiscordAutoThread({
     client: params.client,
     message: params.message,
+    messageChannelId: messageChannelId || undefined,
     isGuildMessage: params.isGuildMessage,
     channelConfig: params.channelConfig,
     threadChannel: params.threadChannel,
@@ -317,7 +334,7 @@ export async function resolveDiscordAutoThreadReplyPlan(params: {
     ? resolveDiscordAutoThreadContext({
         agentId: params.agentId,
         channel: params.channel,
-        messageChannelId: params.message.channelId,
+        messageChannelId,
         createdThreadId,
       })
     : null;
@@ -327,6 +344,7 @@ export async function resolveDiscordAutoThreadReplyPlan(params: {
 export async function maybeCreateDiscordAutoThread(params: {
   client: Client;
   message: DiscordMessageEvent["message"];
+  messageChannelId?: string;
   isGuildMessage: boolean;
   channelConfig?: DiscordChannelConfigResolved | null;
   threadChannel?: DiscordThreadChannel | null;
@@ -342,13 +360,22 @@ export async function maybeCreateDiscordAutoThread(params: {
   if (params.threadChannel) {
     return undefined;
   }
+  const messageChannelId = (
+    params.messageChannelId ||
+    resolveDiscordMessageChannelId({
+      message: params.message,
+    })
+  ).trim();
+  if (!messageChannelId) {
+    return undefined;
+  }
   try {
     const threadName = sanitizeDiscordThreadName(
       params.baseText || params.combinedBody || "Thread",
       params.message.id,
     );
     const created = (await params.client.rest.post(
-      `${Routes.channelMessage(params.message.channelId, params.message.id)}/threads`,
+      `${Routes.channelMessage(messageChannelId, params.message.id)}/threads`,
       {
         body: {
           name: threadName,
@@ -360,18 +387,18 @@ export async function maybeCreateDiscordAutoThread(params: {
     return createdId || undefined;
   } catch (err) {
     logVerbose(
-      `discord: autoThread creation failed for ${params.message.channelId}/${params.message.id}: ${String(err)}`,
+      `discord: autoThread creation failed for ${messageChannelId}/${params.message.id}: ${String(err)}`,
     );
     // Race condition: another agent may have already created a thread on this
     // message. Re-fetch the message to check for an existing thread.
     try {
       const msg = (await params.client.rest.get(
-        Routes.channelMessage(params.message.channelId, params.message.id),
+        Routes.channelMessage(messageChannelId, params.message.id),
       )) as { thread?: { id?: string } };
       const existingThreadId = msg?.thread?.id ? String(msg.thread.id) : "";
       if (existingThreadId) {
         logVerbose(
-          `discord: autoThread reusing existing thread ${existingThreadId} on ${params.message.channelId}/${params.message.id}`,
+          `discord: autoThread reusing existing thread ${existingThreadId} on ${messageChannelId}/${params.message.id}`,
         );
         return existingThreadId;
       }
diff --git a/src/discord/probe.ts b/src/discord/probe.ts
index fd01cdd5446..b199e89fdd5 100644
--- a/src/discord/probe.ts
+++ b/src/discord/probe.ts
@@ -1,13 +1,12 @@
+import type { BaseProbeResult } from "../channels/plugins/types.js";
 import { resolveFetch } from "../infra/fetch.js";
 import { fetchWithTimeout } from "../utils/fetch-timeout.js";
 import { normalizeDiscordToken } from "./token.js";
 
 const DISCORD_API_BASE = "https://discord.com/api/v10";
 
-export type DiscordProbe = {
-  ok: boolean;
+export type DiscordProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs: number;
   bot?: { id?: string | null; username?: string | null };
   application?: DiscordApplicationSummary;
diff --git a/src/discord/send.components.ts b/src/discord/send.components.ts
new file mode 100644
index 00000000000..838935fedc7
--- /dev/null
+++ b/src/discord/send.components.ts
@@ -0,0 +1,169 @@
+import type { APIChannel } from "discord-api-types/v10";
+import {
+  serializePayload,
+  type MessagePayloadFile,
+  type MessagePayloadObject,
+  type RequestClient,
+} from "@buape/carbon";
+import { ChannelType, Routes } from "discord-api-types/v10";
+import type { DiscordSendResult } from "./send.types.js";
+import { loadConfig } from "../config/config.js";
+import { recordChannelActivity } from "../infra/channel-activity.js";
+import { loadWebMedia } from "../web/media.js";
+import { resolveDiscordAccount } from "./accounts.js";
+import { registerDiscordComponentEntries } from "./components-registry.js";
+import {
+  buildDiscordComponentMessage,
+  buildDiscordComponentMessageFlags,
+  resolveDiscordComponentAttachmentName,
+  type DiscordComponentMessageSpec,
+} from "./components.js";
+import {
+  buildDiscordSendError,
+  createDiscordClient,
+  parseAndResolveRecipient,
+  resolveChannelId,
+  stripUndefinedFields,
+  SUPPRESS_NOTIFICATIONS_FLAG,
+} from "./send.shared.js";
+
+const DISCORD_FORUM_LIKE_TYPES = new Set<number>([ChannelType.GuildForum, ChannelType.GuildMedia]);
+
+function extractComponentAttachmentNames(spec: DiscordComponentMessageSpec): string[] {
+  const names: string[] = [];
+  for (const block of spec.blocks ?? []) {
+    if (block.type === "file") {
+      names.push(resolveDiscordComponentAttachmentName(block.file));
+    }
+  }
+  return names;
+}
+
+type DiscordComponentSendOpts = {
+  accountId?: string;
+  token?: string;
+  rest?: RequestClient;
+  silent?: boolean;
+  replyTo?: string;
+  sessionKey?: string;
+  agentId?: string;
+  mediaUrl?: string;
+  mediaLocalRoots?: readonly string[];
+  filename?: string;
+};
+
+export async function sendDiscordComponentMessage(
+  to: string,
+  spec: DiscordComponentMessageSpec,
+  opts: DiscordComponentSendOpts = {},
+): Promise<DiscordSendResult> {
+  const cfg = loadConfig();
+  const accountInfo = resolveDiscordAccount({ cfg, accountId: opts.accountId });
+  const { token, rest, request } = createDiscordClient(opts, cfg);
+  const recipient = await parseAndResolveRecipient(to, opts.accountId);
+  const { channelId } = await resolveChannelId(rest, recipient, request);
+
+  let channelType: number | undefined;
+  try {
+    const channel = (await rest.get(Routes.channel(channelId))) as APIChannel | undefined;
+    channelType = channel?.type;
+  } catch {
+    channelType = undefined;
+  }
+
+  if (channelType && DISCORD_FORUM_LIKE_TYPES.has(channelType)) {
+    throw new Error("Discord components are not supported in forum-style channels");
+  }
+
+  const buildResult = buildDiscordComponentMessage({
+    spec,
+    sessionKey: opts.sessionKey,
+    agentId: opts.agentId,
+    accountId: accountInfo.accountId,
+  });
+  const flags = buildDiscordComponentMessageFlags(buildResult.components);
+  const finalFlags = opts.silent
+    ? (flags ?? 0) | SUPPRESS_NOTIFICATIONS_FLAG
+    : (flags ?? undefined);
+  const messageReference = opts.replyTo
+    ? { message_id: opts.replyTo, fail_if_not_exists: false }
+    : undefined;
+
+  const attachmentNames = extractComponentAttachmentNames(spec);
+  const uniqueAttachmentNames = [...new Set(attachmentNames)];
+  if (uniqueAttachmentNames.length > 1) {
+    throw new Error(
+      "Discord component attachments currently support a single file. Use media-gallery for multiple files.",
+    );
+  }
+  const expectedAttachmentName = uniqueAttachmentNames[0];
+  let files: MessagePayloadFile[] | undefined;
+  if (opts.mediaUrl) {
+    const media = await loadWebMedia(opts.mediaUrl, { localRoots: opts.mediaLocalRoots });
+    const filenameOverride = opts.filename?.trim();
+    const fileName = filenameOverride || media.fileName || "upload";
+    if (expectedAttachmentName && expectedAttachmentName !== fileName) {
+      throw new Error(
+        `Component file block expects attachment "${expectedAttachmentName}", but the uploaded file is "${fileName}". Update components.blocks[].file or provide a matching filename.`,
+      );
+    }
+    let fileData: Blob;
+    if (media.buffer instanceof Blob) {
+      fileData = media.buffer;
+    } else {
+      const arrayBuffer = new ArrayBuffer(media.buffer.byteLength);
+      new Uint8Array(arrayBuffer).set(media.buffer);
+      fileData = new Blob([arrayBuffer]);
+    }
+    files = [{ data: fileData, name: fileName }];
+  } else if (expectedAttachmentName) {
+    throw new Error(
+      "Discord component file blocks require a media attachment (media/path/filePath).",
+    );
+  }
+
+  const payload: MessagePayloadObject = {
+    components: buildResult.components,
+    ...(finalFlags ? { flags: finalFlags } : {}),
+    ...(files ? { files } : {}),
+  };
+  const body = stripUndefinedFields({
+    ...serializePayload(payload),
+    ...(messageReference ? { message_reference: messageReference } : {}),
+  });
+
+  let result: { id: string; channel_id: string };
+  try {
+    result = (await request(
+      () =>
+        rest.post(Routes.channelMessages(channelId), {
+          body,
+        }) as Promise<{ id: string; channel_id: string }>,
+      "components",
+    )) as { id: string; channel_id: string };
+  } catch (err) {
+    throw await buildDiscordSendError(err, {
+      channelId,
+      rest,
+      token,
+      hasMedia: Boolean(files?.length),
+    });
+  }
+
+  registerDiscordComponentEntries({
+    entries: buildResult.entries,
+    modals: buildResult.modals,
+    messageId: result.id,
+  });
+
+  recordChannelActivity({
+    channel: "discord",
+    accountId: accountInfo.accountId,
+    direction: "outbound",
+  });
+
+  return {
+    messageId: result.id ?? "unknown",
+    channelId: result.channel_id ?? channelId,
+  };
+}
diff --git a/src/discord/send.outbound.ts b/src/discord/send.outbound.ts
index af013ede5df..2408fa15a62 100644
--- a/src/discord/send.outbound.ts
+++ b/src/discord/send.outbound.ts
@@ -1,5 +1,5 @@
-import type { RequestClient } from "@buape/carbon";
 import type { APIChannel } from "discord-api-types/v10";
+import { serializePayload, type MessagePayloadObject, type RequestClient } from "@buape/carbon";
 import { ChannelType, Routes } from "discord-api-types/v10";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
@@ -18,6 +18,7 @@ import { extensionForMime } from "../media/mime.js";
 import { loadWebMediaRaw } from "../web/media.js";
 import { resolveDiscordAccount } from "./accounts.js";
 import {
+  buildDiscordMessagePayload,
   buildDiscordSendError,
   buildDiscordTextChunks,
   createDiscordClient,
@@ -25,9 +26,14 @@ import {
   normalizeStickerIds,
   parseAndResolveRecipient,
   resolveChannelId,
+  resolveDiscordSendComponents,
+  resolveDiscordSendEmbeds,
   sendDiscordMedia,
   sendDiscordText,
+  stripUndefinedFields,
   SUPPRESS_NOTIFICATIONS_FLAG,
+  type DiscordSendComponents,
+  type DiscordSendEmbeds,
 } from "./send.shared.js";
 import {
   ensureOggOpus,
@@ -44,7 +50,8 @@ type DiscordSendOpts = {
   rest?: RequestClient;
   replyTo?: string;
   retry?: RetryConfig;
-  embeds?: unknown[];
+  components?: DiscordSendComponents;
+  embeds?: DiscordSendEmbeds;
   silent?: boolean;
 };
 
@@ -103,7 +110,19 @@ export async function sendMessageDiscord(
       chunkMode,
     });
     const starterContent = chunks[0]?.trim() ? chunks[0] : threadName;
-    const starterEmbeds = opts.embeds?.length ? opts.embeds : undefined;
+    const starterComponents = resolveDiscordSendComponents({
+      components: opts.components,
+      text: starterContent,
+      isFirst: true,
+    });
+    const starterEmbeds = resolveDiscordSendEmbeds({ embeds: opts.embeds, isFirst: true });
+    const silentFlags = opts.silent ? 1 << 12 : undefined;
+    const starterPayload: MessagePayloadObject = buildDiscordMessagePayload({
+      text: starterContent,
+      components: starterComponents,
+      embeds: starterEmbeds,
+      flags: silentFlags,
+    });
     let threadRes: { id: string; message?: { id: string; channel_id: string } };
     try {
       threadRes = (await request(
@@ -111,10 +130,7 @@ export async function sendMessageDiscord(
           rest.post(Routes.threads(channelId), {
             body: {
               name: threadName,
-              message: {
-                content: starterContent,
-                ...(starterEmbeds ? { embeds: starterEmbeds } : {}),
-              },
+              message: stripUndefinedFields(serializePayload(starterPayload)),
             },
           }) as Promise<{ id: string; message?: { id: string; channel_id: string } }>,
         "forum-thread",
@@ -146,6 +162,7 @@ export async function sendMessageDiscord(
           request,
           accountInfo.config.maxLinesPerMessage,
           undefined,
+          undefined,
           chunkMode,
           opts.silent,
         );
@@ -158,6 +175,7 @@ export async function sendMessageDiscord(
             request,
             accountInfo.config.maxLinesPerMessage,
             undefined,
+            undefined,
             chunkMode,
             opts.silent,
           );
@@ -172,6 +190,7 @@ export async function sendMessageDiscord(
             request,
             accountInfo.config.maxLinesPerMessage,
             undefined,
+            undefined,
             chunkMode,
             opts.silent,
           );
@@ -209,6 +228,7 @@ export async function sendMessageDiscord(
         opts.replyTo,
         request,
         accountInfo.config.maxLinesPerMessage,
+        opts.components,
         opts.embeds,
         chunkMode,
         opts.silent,
@@ -221,6 +241,7 @@ export async function sendMessageDiscord(
         opts.replyTo,
         request,
         accountInfo.config.maxLinesPerMessage,
+        opts.components,
         opts.embeds,
         chunkMode,
         opts.silent,
diff --git a/src/discord/send.shared.ts b/src/discord/send.shared.ts
index 11feaaa8a0c..6423997730a 100644
--- a/src/discord/send.shared.ts
+++ b/src/discord/send.shared.ts
@@ -1,7 +1,14 @@
 import type { RESTAPIPoll } from "discord-api-types/rest/v10";
-import { RequestClient } from "@buape/carbon";
+import {
+  Embed,
+  RequestClient,
+  serializePayload,
+  type MessagePayloadFile,
+  type MessagePayloadObject,
+  type TopLevelComponents,
+} from "@buape/carbon";
 import { PollLayoutType } from "discord-api-types/payloads/v10";
-import { Routes } from "discord-api-types/v10";
+import { Routes, type APIEmbed } from "discord-api-types/v10";
 import type { ChunkMode } from "../auto-reply/chunk.js";
 import type { RetryRunner } from "../infra/retry-policy.js";
 import { loadConfig } from "../config/config.js";
@@ -23,6 +30,10 @@ const DISCORD_CANNOT_DM = 50007;
 
 type DiscordRequest = RetryRunner;
 
+export type DiscordSendComponentFactory = (text: string) => TopLevelComponents[];
+export type DiscordSendComponents = TopLevelComponents[] | DiscordSendComponentFactory;
+export type DiscordSendEmbeds = Array<APIEmbed | Embed>;
+
 type DiscordRecipient =
   | {
       kind: "user";
@@ -252,6 +263,72 @@ export function buildDiscordTextChunks(
   return chunks;
 }
 
+function hasV2Components(components?: TopLevelComponents[]): boolean {
+  return Boolean(components?.some((component) => "isV2" in component && component.isV2));
+}
+
+export function resolveDiscordSendComponents(params: {
+  components?: DiscordSendComponents;
+  text: string;
+  isFirst: boolean;
+}): TopLevelComponents[] | undefined {
+  if (!params.components || !params.isFirst) {
+    return undefined;
+  }
+  return typeof params.components === "function"
+    ? params.components(params.text)
+    : params.components;
+}
+
+function normalizeDiscordEmbeds(embeds?: DiscordSendEmbeds): Embed[] | undefined {
+  if (!embeds?.length) {
+    return undefined;
+  }
+  return embeds.map((embed) => (embed instanceof Embed ? embed : new Embed(embed)));
+}
+
+export function resolveDiscordSendEmbeds(params: {
+  embeds?: DiscordSendEmbeds;
+  isFirst: boolean;
+}): Embed[] | undefined {
+  if (!params.embeds || !params.isFirst) {
+    return undefined;
+  }
+  return normalizeDiscordEmbeds(params.embeds);
+}
+
+export function buildDiscordMessagePayload(params: {
+  text: string;
+  components?: TopLevelComponents[];
+  embeds?: Embed[];
+  flags?: number;
+  files?: MessagePayloadFile[];
+}): MessagePayloadObject {
+  const payload: MessagePayloadObject = {};
+  const hasV2 = hasV2Components(params.components);
+  const trimmed = params.text.trim();
+  if (!hasV2 && trimmed) {
+    payload.content = params.text;
+  }
+  if (params.components?.length) {
+    payload.components = params.components;
+  }
+  if (!hasV2 && params.embeds?.length) {
+    payload.embeds = params.embeds;
+  }
+  if (params.flags !== undefined) {
+    payload.flags = params.flags;
+  }
+  if (params.files?.length) {
+    payload.files = params.files;
+  }
+  return payload;
+}
+
+export function stripUndefinedFields<T extends object>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
 async function sendDiscordText(
   rest: RequestClient,
   channelId: string,
@@ -259,7 +336,8 @@ async function sendDiscordText(
   replyTo: string | undefined,
   request: DiscordRequest,
   maxLinesPerMessage?: number,
-  embeds?: unknown[],
+  components?: DiscordSendComponents,
+  embeds?: DiscordSendEmbeds,
   chunkMode?: ChunkMode,
   silent?: boolean,
 ) {
@@ -269,36 +347,38 @@ async function sendDiscordText(
   const messageReference = replyTo ? { message_id: replyTo, fail_if_not_exists: false } : undefined;
   const flags = silent ? SUPPRESS_NOTIFICATIONS_FLAG : undefined;
   const chunks = buildDiscordTextChunks(text, { maxLinesPerMessage, chunkMode });
-  if (chunks.length === 1) {
-    const res = (await request(
+  const sendChunk = async (chunk: string, isFirst: boolean) => {
+    const chunkComponents = resolveDiscordSendComponents({
+      components,
+      text: chunk,
+      isFirst,
+    });
+    const chunkEmbeds = resolveDiscordSendEmbeds({ embeds, isFirst });
+    const payload = buildDiscordMessagePayload({
+      text: chunk,
+      components: chunkComponents,
+      embeds: chunkEmbeds,
+      flags,
+    });
+    const body = stripUndefinedFields({
+      ...serializePayload(payload),
+      ...(isFirst && messageReference ? { message_reference: messageReference } : {}),
+    });
+    return (await request(
       () =>
         rest.post(Routes.channelMessages(channelId), {
-          body: {
-            content: chunks[0],
-            message_reference: messageReference,
-            ...(embeds?.length ? { embeds } : {}),
-            ...(flags ? { flags } : {}),
-          },
+          body,
         }) as Promise<{ id: string; channel_id: string }>,
       "text",
     )) as { id: string; channel_id: string };
-    return res;
+  };
+  if (chunks.length === 1) {
+    return await sendChunk(chunks[0], true);
   }
   let last: { id: string; channel_id: string } | null = null;
   let isFirst = true;
   for (const chunk of chunks) {
-    last = (await request(
-      () =>
-        rest.post(Routes.channelMessages(channelId), {
-          body: {
-            content: chunk,
-            message_reference: isFirst ? messageReference : undefined,
-            ...(isFirst && embeds?.length ? { embeds } : {}),
-            ...(flags ? { flags } : {}),
-          },
-        }) as Promise<{ id: string; channel_id: string }>,
-      "text",
-    )) as { id: string; channel_id: string };
+    last = await sendChunk(chunk, isFirst);
     isFirst = false;
   }
   if (!last) {
@@ -316,34 +396,49 @@ async function sendDiscordMedia(
   replyTo: string | undefined,
   request: DiscordRequest,
   maxLinesPerMessage?: number,
-  embeds?: unknown[],
+  components?: DiscordSendComponents,
+  embeds?: DiscordSendEmbeds,
   chunkMode?: ChunkMode,
   silent?: boolean,
 ) {
   const media = await loadWebMedia(mediaUrl, { localRoots: mediaLocalRoots });
   const chunks = text ? buildDiscordTextChunks(text, { maxLinesPerMessage, chunkMode }) : [];
   const caption = chunks[0] ?? "";
-  const hasCaption = caption.trim().length > 0;
   const messageReference = replyTo ? { message_id: replyTo, fail_if_not_exists: false } : undefined;
   const flags = silent ? SUPPRESS_NOTIFICATIONS_FLAG : undefined;
+  let fileData: Blob;
+  if (media.buffer instanceof Blob) {
+    fileData = media.buffer;
+  } else {
+    const arrayBuffer = new ArrayBuffer(media.buffer.byteLength);
+    new Uint8Array(arrayBuffer).set(media.buffer);
+    fileData = new Blob([arrayBuffer]);
+  }
+  const captionComponents = resolveDiscordSendComponents({
+    components,
+    text: caption,
+    isFirst: true,
+  });
+  const captionEmbeds = resolveDiscordSendEmbeds({ embeds, isFirst: true });
+  const payload = buildDiscordMessagePayload({
+    text: caption,
+    components: captionComponents,
+    embeds: captionEmbeds,
+    flags,
+    files: [
+      {
+        data: fileData,
+        name: media.fileName ?? "upload",
+      },
+    ],
+  });
   const res = (await request(
     () =>
       rest.post(Routes.channelMessages(channelId), {
-        body: {
-          // Only include content when there is actual text; Discord rejects
-          // media-only messages that carry an empty or undefined content field
-          // when sent as multipart/form-data. Preserve whitespace in captions.
-          ...(hasCaption ? { content: caption } : {}),
+        body: stripUndefinedFields({
+          ...serializePayload(payload),
           ...(messageReference ? { message_reference: messageReference } : {}),
-          ...(embeds?.length ? { embeds } : {}),
-          ...(flags ? { flags } : {}),
-          files: [
-            {
-              data: media.buffer,
-              name: media.fileName ?? "upload",
-            },
-          ],
-        },
+        }),
       }) as Promise<{ id: string; channel_id: string }>,
     "media",
   )) as { id: string; channel_id: string };
@@ -359,6 +454,7 @@ async function sendDiscordMedia(
       request,
       maxLinesPerMessage,
       undefined,
+      undefined,
       chunkMode,
       silent,
     );
diff --git a/src/discord/send.ts b/src/discord/send.ts
index adc27c8c17d..ee247ab6a29 100644
--- a/src/discord/send.ts
+++ b/src/discord/send.ts
@@ -43,6 +43,7 @@ export {
   sendStickerDiscord,
   sendVoiceMessageDiscord,
 } from "./send.outbound.js";
+export { sendDiscordComponentMessage } from "./send.components.js";
 export {
   fetchChannelPermissionsDiscord,
   fetchReactionsDiscord,
diff --git a/src/discord/send.voice-message.security.test.ts b/src/discord/send.voice-message.security.test.ts
deleted file mode 100644
index 9651f57c5ae..00000000000
--- a/src/discord/send.voice-message.security.test.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { sendVoiceMessageDiscord } from "./send.js";
-
-describe("sendVoiceMessageDiscord - media hardening", () => {
-  it("rejects local paths outside allowed media roots (prevents local file exfiltration)", async () => {
-    const candidate = path.join(process.cwd(), "package.json");
-    await expect(sendVoiceMessageDiscord("channel:123", candidate)).rejects.toThrow(
-      /Local media path is not under an allowed directory/,
-    );
-  });
-
-  it("blocks SSRF targets when given a private-network URL", async () => {
-    await expect(
-      sendVoiceMessageDiscord("channel:123", "http://127.0.0.1/voice.ogg"),
-    ).rejects.toThrow(/Failed to fetch media|Blocked/);
-  });
-
-  it("does not allow non-http URL schemes to reach ffmpeg/ffprobe", async () => {
-    await expect(
-      sendVoiceMessageDiscord("channel:123", "rtsp://example.com/voice.ogg"),
-    ).rejects.toThrow(/Local media path is not under an allowed directory|ENOENT|no such file/i);
-  });
-});
diff --git a/src/discord/token.ts b/src/discord/token.ts
index 2187fbc32b4..5f265994044 100644
--- a/src/discord/token.ts
+++ b/src/discord/token.ts
@@ -1,10 +1,10 @@
+import type { BaseTokenResolution } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
 
 export type DiscordTokenSource = "env" | "config" | "none";
 
-export type DiscordTokenResolution = {
-  token: string;
+export type DiscordTokenResolution = BaseTokenResolution & {
   source: DiscordTokenSource;
 };
 
diff --git a/src/discord/ui.ts b/src/discord/ui.ts
new file mode 100644
index 00000000000..e9533dbb332
--- /dev/null
+++ b/src/discord/ui.ts
@@ -0,0 +1,45 @@
+import { Container } from "@buape/carbon";
+import type { OpenClawConfig } from "../config/config.js";
+import { resolveDiscordAccount } from "./accounts.js";
+
+const DEFAULT_DISCORD_ACCENT_COLOR = "#5865F2";
+
+type DiscordContainerComponents = ConstructorParameters<typeof Container>[0];
+
+type ResolveDiscordAccentColorParams = {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+};
+
+export function normalizeDiscordAccentColor(raw?: string | null): string | null {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  const normalized = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+  if (!/^#[0-9a-fA-F]{6}$/.test(normalized)) {
+    return null;
+  }
+  return normalized.toUpperCase();
+}
+
+export function resolveDiscordAccentColor(params: ResolveDiscordAccentColorParams): string {
+  const account = resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId });
+  const configured = normalizeDiscordAccentColor(account.config.ui?.components?.accentColor);
+  return configured ?? DEFAULT_DISCORD_ACCENT_COLOR;
+}
+
+export class DiscordUiContainer extends Container {
+  constructor(params: {
+    cfg: OpenClawConfig;
+    accountId?: string | null;
+    components?: DiscordContainerComponents;
+    accentColor?: string;
+    spoiler?: boolean;
+  }) {
+    const accentOverride = normalizeDiscordAccentColor(params.accentColor);
+    const accentColor =
+      accentOverride ?? resolveDiscordAccentColor({ cfg: params.cfg, accountId: params.accountId });
+    super(params.components, { accentColor, spoiler: params.spoiler });
+  }
+}
diff --git a/src/gateway/agent-event-assistant-text.ts b/src/gateway/agent-event-assistant-text.ts
new file mode 100644
index 00000000000..6341664d7d2
--- /dev/null
+++ b/src/gateway/agent-event-assistant-text.ts
@@ -0,0 +1,7 @@
+import type { AgentEventPayload } from "../infra/agent-events.js";
+
+export function resolveAssistantStreamDeltaText(evt: AgentEventPayload): string {
+  const delta = evt.data.delta;
+  const text = evt.data.text;
+  return typeof delta === "string" ? delta : typeof text === "string" ? text : "";
+}
diff --git a/src/gateway/auth.ts b/src/gateway/auth.ts
index 5ae84ce715a..3212885c6ac 100644
--- a/src/gateway/auth.ts
+++ b/src/gateway/auth.ts
@@ -14,6 +14,7 @@ import {
 import {
   isLoopbackAddress,
   isTrustedProxyAddress,
+  resolveHostName,
   parseForwardedForClientIp,
   resolveGatewayClientIp,
 } from "./net.js";
@@ -56,21 +57,6 @@ function normalizeLogin(login: string): string {
   return login.trim().toLowerCase();
 }
 
-function getHostName(hostHeader?: string): string {
-  const host = (hostHeader ?? "").trim().toLowerCase();
-  if (!host) {
-    return "";
-  }
-  if (host.startsWith("[")) {
-    const end = host.indexOf("]");
-    if (end !== -1) {
-      return host.slice(1, end);
-    }
-  }
-  const [name] = host.split(":");
-  return name ?? "";
-}
-
 function headerValue(value: string | string[] | undefined): string | undefined {
   return Array.isArray(value) ? value[0] : value;
 }
@@ -107,7 +93,7 @@ export function isLocalDirectRequest(req?: IncomingMessage, trustedProxies?: str
     return false;
   }
 
-  const host = getHostName(req.headers?.host);
+  const host = resolveHostName(req.headers?.host);
   const hostIsLocal = host === "localhost" || host === "127.0.0.1" || host === "::1";
   const hostIsTailscaleServe = host.endsWith(".ts.net");
 
diff --git a/src/gateway/boot.test.ts b/src/gateway/boot.test.ts
index 9e6ead765b9..4c8790319f2 100644
--- a/src/gateway/boot.test.ts
+++ b/src/gateway/boot.test.ts
@@ -8,11 +8,23 @@ const agentCommand = vi.fn();
 vi.mock("../commands/agent.js", () => ({ agentCommand }));
 
 const { runBootOnce } = await import("./boot.js");
-const { resolveMainSessionKey } = await import("../config/sessions/main-session.js");
+const { resolveAgentIdFromSessionKey, resolveMainSessionKey } =
+  await import("../config/sessions/main-session.js");
+const { resolveStorePath } = await import("../config/sessions/paths.js");
+const { loadSessionStore, saveSessionStore } = await import("../config/sessions/store.js");
 
 describe("runBootOnce", () => {
-  beforeEach(() => {
+  const resolveMainStore = (cfg: { session?: { store?: string } } = {}) => {
+    const sessionKey = resolveMainSessionKey(cfg);
+    const agentId = resolveAgentIdFromSessionKey(sessionKey);
+    const storePath = resolveStorePath(cfg.session?.store, { agentId });
+    return { sessionKey, storePath };
+  };
+
+  beforeEach(async () => {
     vi.clearAllMocks();
+    const { storePath } = resolveMainStore();
+    await fs.rm(storePath, { force: true });
   });
 
   const makeDeps = () => ({
@@ -69,4 +81,115 @@ describe("runBootOnce", () => {
 
     await fs.rm(workspaceDir, { recursive: true, force: true });
   });
+
+  it("generates new session ID when no existing session exists", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-boot-"));
+    const content = "Say hello when you wake up.";
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), content, "utf-8");
+
+    agentCommand.mockResolvedValue(undefined);
+    const cfg = {};
+    await expect(runBootOnce({ cfg, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+      status: "ran",
+    });
+
+    expect(agentCommand).toHaveBeenCalledTimes(1);
+    const call = agentCommand.mock.calls[0]?.[0];
+
+    // Verify a boot-style session ID was generated (format: boot-YYYY-MM-DD_HH-MM-SS-xxx-xxxxxxxx)
+    expect(call?.sessionId).toMatch(/^boot-\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}-\d{3}-[0-9a-f]{8}$/);
+
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it("uses a fresh boot session ID even when main session mapping already exists", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-boot-"));
+    const content = "Say hello when you wake up.";
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), content, "utf-8");
+
+    const cfg = {};
+    const { sessionKey, storePath } = resolveMainStore(cfg);
+    const existingSessionId = "main-session-abc123";
+
+    await saveSessionStore(storePath, {
+      [sessionKey]: {
+        sessionId: existingSessionId,
+        updatedAt: Date.now(),
+      },
+    });
+
+    agentCommand.mockResolvedValue(undefined);
+    await expect(runBootOnce({ cfg, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+      status: "ran",
+    });
+
+    expect(agentCommand).toHaveBeenCalledTimes(1);
+    const call = agentCommand.mock.calls[0]?.[0];
+
+    expect(call?.sessionId).not.toBe(existingSessionId);
+    expect(call?.sessionId).toMatch(/^boot-\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}-\d{3}-[0-9a-f]{8}$/);
+    expect(call?.sessionKey).toBe(sessionKey);
+
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it("restores the original main session mapping after the boot run", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-boot-"));
+    const content = "Check if the system is healthy.";
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), content, "utf-8");
+
+    const cfg = {};
+    const { sessionKey, storePath } = resolveMainStore(cfg);
+    const existingSessionId = "main-session-xyz789";
+
+    await saveSessionStore(storePath, {
+      [sessionKey]: {
+        sessionId: existingSessionId,
+        updatedAt: Date.now() - 60_000, // 1 minute ago
+      },
+    });
+
+    agentCommand.mockImplementation(async (opts: { sessionId?: string }) => {
+      const current = loadSessionStore(storePath, { skipCache: true });
+      current[sessionKey] = {
+        sessionId: String(opts.sessionId),
+        updatedAt: Date.now(),
+      };
+      await saveSessionStore(storePath, current);
+    });
+    await expect(runBootOnce({ cfg, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+      status: "ran",
+    });
+
+    const restored = loadSessionStore(storePath, { skipCache: true });
+    expect(restored[sessionKey]?.sessionId).toBe(existingSessionId);
+
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it("removes a boot-created main-session mapping when none existed before", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-boot-"));
+    await fs.writeFile(path.join(workspaceDir, "BOOT.md"), "health check", "utf-8");
+
+    const cfg = {};
+    const { sessionKey, storePath } = resolveMainStore(cfg);
+
+    agentCommand.mockImplementation(async (opts: { sessionId?: string }) => {
+      const current = loadSessionStore(storePath, { skipCache: true });
+      current[sessionKey] = {
+        sessionId: String(opts.sessionId),
+        updatedAt: Date.now(),
+      };
+      await saveSessionStore(storePath, current);
+    });
+
+    await expect(runBootOnce({ cfg, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+      status: "ran",
+    });
+
+    const restored = loadSessionStore(storePath, { skipCache: true });
+    expect(restored[sessionKey]).toBeUndefined();
+
+    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
 });
diff --git a/src/gateway/boot.ts b/src/gateway/boot.ts
index bc95c2ab6c5..e9486eac32a 100644
--- a/src/gateway/boot.ts
+++ b/src/gateway/boot.ts
@@ -3,9 +3,15 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { CliDeps } from "../cli/deps.js";
 import type { OpenClawConfig } from "../config/config.js";
+import type { SessionEntry } from "../config/sessions/types.js";
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { agentCommand } from "../commands/agent.js";
-import { resolveMainSessionKey } from "../config/sessions/main-session.js";
+import {
+  resolveAgentIdFromSessionKey,
+  resolveMainSessionKey,
+} from "../config/sessions/main-session.js";
+import { resolveStorePath } from "../config/sessions/paths.js";
+import { loadSessionStore, updateSessionStore } from "../config/sessions/store.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { type RuntimeEnv, defaultRuntime } from "../runtime.js";
 
@@ -16,6 +22,14 @@ function generateBootSessionId(): string {
   return `boot-${ts}-${suffix}`;
 }
 
+type SessionMappingSnapshot = {
+  storePath: string;
+  sessionKey: string;
+  canRestore: boolean;
+  hadEntry: boolean;
+  entry?: SessionEntry;
+};
+
 const log = createSubsystemLogger("gateway/boot");
 const BOOT_FILENAME = "BOOT.md";
 
@@ -58,6 +72,68 @@ async function loadBootFile(
   }
 }
 
+function snapshotMainSessionMapping(params: {
+  cfg: OpenClawConfig;
+  sessionKey: string;
+}): SessionMappingSnapshot {
+  const agentId = resolveAgentIdFromSessionKey(params.sessionKey);
+  const storePath = resolveStorePath(params.cfg.session?.store, { agentId });
+  try {
+    const store = loadSessionStore(storePath, { skipCache: true });
+    const entry = store[params.sessionKey];
+    if (!entry) {
+      return {
+        storePath,
+        sessionKey: params.sessionKey,
+        canRestore: true,
+        hadEntry: false,
+      };
+    }
+    return {
+      storePath,
+      sessionKey: params.sessionKey,
+      canRestore: true,
+      hadEntry: true,
+      entry: structuredClone(entry),
+    };
+  } catch (err) {
+    log.debug("boot: could not snapshot main session mapping", {
+      sessionKey: params.sessionKey,
+      error: String(err),
+    });
+    return {
+      storePath,
+      sessionKey: params.sessionKey,
+      canRestore: false,
+      hadEntry: false,
+    };
+  }
+}
+
+async function restoreMainSessionMapping(
+  snapshot: SessionMappingSnapshot,
+): Promise<string | undefined> {
+  if (!snapshot.canRestore) {
+    return undefined;
+  }
+  try {
+    await updateSessionStore(
+      snapshot.storePath,
+      (store) => {
+        if (snapshot.hadEntry && snapshot.entry) {
+          store[snapshot.sessionKey] = snapshot.entry;
+          return;
+        }
+        delete store[snapshot.sessionKey];
+      },
+      { activeSessionKey: snapshot.sessionKey },
+    );
+    return undefined;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
 export async function runBootOnce(params: {
   cfg: OpenClawConfig;
   deps: CliDeps;
@@ -84,7 +160,12 @@ export async function runBootOnce(params: {
   const sessionKey = resolveMainSessionKey(params.cfg);
   const message = buildBootPrompt(result.content ?? "");
   const sessionId = generateBootSessionId();
+  const mappingSnapshot = snapshotMainSessionMapping({
+    cfg: params.cfg,
+    sessionKey,
+  });
 
+  let agentFailure: string | undefined;
   try {
     await agentCommand(
       {
@@ -96,10 +177,22 @@ export async function runBootOnce(params: {
       bootRuntime,
       params.deps,
     );
-    return { status: "ran" };
   } catch (err) {
-    const messageText = err instanceof Error ? err.message : String(err);
-    log.error(`boot: agent run failed: ${messageText}`);
-    return { status: "failed", reason: messageText };
+    agentFailure = err instanceof Error ? err.message : String(err);
+    log.error(`boot: agent run failed: ${agentFailure}`);
   }
+
+  const mappingRestoreFailure = await restoreMainSessionMapping(mappingSnapshot);
+  if (mappingRestoreFailure) {
+    log.error(`boot: failed to restore main session mapping: ${mappingRestoreFailure}`);
+  }
+
+  if (!agentFailure && !mappingRestoreFailure) {
+    return { status: "ran" };
+  }
+  const reasonParts = [
+    agentFailure ? `agent run failed: ${agentFailure}` : undefined,
+    mappingRestoreFailure ? `mapping restore failed: ${mappingRestoreFailure}` : undefined,
+  ].filter((part): part is string => Boolean(part));
+  return { status: "failed", reason: reasonParts.join("; ") };
 }
diff --git a/src/gateway/call.test.ts b/src/gateway/call.test.ts
index a4aff647ac0..f6c5afb607a 100644
--- a/src/gateway/call.test.ts
+++ b/src/gateway/call.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 
 const loadConfig = vi.fn();
 const resolveGatewayPort = vi.fn();
@@ -331,7 +332,10 @@ describe("callGateway error details", () => {
 });
 
 describe("callGateway url override auth requirements", () => {
+  let envSnapshot: ReturnType<typeof captureEnv>;
+
   beforeEach(() => {
+    envSnapshot = captureEnv(["OPENCLAW_GATEWAY_TOKEN", "OPENCLAW_GATEWAY_PASSWORD"]);
     loadConfig.mockReset();
     resolveGatewayPort.mockReset();
     pickPrimaryTailnetIPv4.mockReset();
@@ -345,8 +349,7 @@ describe("callGateway url override auth requirements", () => {
   });
 
   afterEach(() => {
-    delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    delete process.env.OPENCLAW_GATEWAY_PASSWORD;
+    envSnapshot.restore();
   });
 
   it("throws when url override is set without explicit credentials", async () => {
@@ -366,9 +369,10 @@ describe("callGateway url override auth requirements", () => {
 });
 
 describe("callGateway password resolution", () => {
-  const originalEnvPassword = process.env.OPENCLAW_GATEWAY_PASSWORD;
+  let envSnapshot: ReturnType<typeof captureEnv>;
 
   beforeEach(() => {
+    envSnapshot = captureEnv(["OPENCLAW_GATEWAY_PASSWORD"]);
     loadConfig.mockReset();
     resolveGatewayPort.mockReset();
     pickPrimaryTailnetIPv4.mockReset();
@@ -383,11 +387,7 @@ describe("callGateway password resolution", () => {
   });
 
   afterEach(() => {
-    if (originalEnvPassword == null) {
-      delete process.env.OPENCLAW_GATEWAY_PASSWORD;
-    } else {
-      process.env.OPENCLAW_GATEWAY_PASSWORD = originalEnvPassword;
-    }
+    envSnapshot.restore();
   });
 
   it("uses local config password when env is unset", async () => {
@@ -468,9 +468,10 @@ describe("callGateway password resolution", () => {
 });
 
 describe("callGateway token resolution", () => {
-  const originalEnvToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+  let envSnapshot: ReturnType<typeof captureEnv>;
 
   beforeEach(() => {
+    envSnapshot = captureEnv(["OPENCLAW_GATEWAY_TOKEN"]);
     loadConfig.mockReset();
     resolveGatewayPort.mockReset();
     pickPrimaryTailnetIPv4.mockReset();
@@ -485,11 +486,7 @@ describe("callGateway token resolution", () => {
   });
 
   afterEach(() => {
-    if (originalEnvToken == null) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = originalEnvToken;
-    }
+    envSnapshot.restore();
   });
 
   it("uses explicit token when url override is set", async () => {
diff --git a/src/gateway/chat-abort.test.ts b/src/gateway/chat-abort.test.ts
new file mode 100644
index 00000000000..9829f45c999
--- /dev/null
+++ b/src/gateway/chat-abort.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  abortChatRunById,
+  type ChatAbortOps,
+  type ChatAbortControllerEntry,
+} from "./chat-abort.js";
+
+function createActiveEntry(sessionKey: string): ChatAbortControllerEntry {
+  const now = Date.now();
+  return {
+    controller: new AbortController(),
+    sessionId: "sess-1",
+    sessionKey,
+    startedAtMs: now,
+    expiresAtMs: now + 10_000,
+  };
+}
+
+function createOps(params: {
+  runId: string;
+  entry: ChatAbortControllerEntry;
+  buffer?: string;
+}): ChatAbortOps & {
+  broadcast: ReturnType<typeof vi.fn>;
+  nodeSendToSession: ReturnType<typeof vi.fn>;
+  removeChatRun: ReturnType<typeof vi.fn>;
+} {
+  const { runId, entry, buffer } = params;
+  const broadcast = vi.fn();
+  const nodeSendToSession = vi.fn();
+  const removeChatRun = vi.fn();
+
+  return {
+    chatAbortControllers: new Map([[runId, entry]]),
+    chatRunBuffers: new Map(buffer !== undefined ? [[runId, buffer]] : []),
+    chatDeltaSentAt: new Map([[runId, Date.now()]]),
+    chatAbortedRuns: new Map(),
+    removeChatRun,
+    agentRunSeq: new Map(),
+    broadcast,
+    nodeSendToSession,
+  };
+}
+
+describe("abortChatRunById", () => {
+  it("broadcasts aborted payload with partial message when buffered text exists", () => {
+    const runId = "run-1";
+    const sessionKey = "main";
+    const entry = createActiveEntry(sessionKey);
+    const ops = createOps({ runId, entry, buffer: "  Partial reply  " });
+    ops.agentRunSeq.set(runId, 2);
+    ops.agentRunSeq.set("client-run-1", 4);
+    ops.removeChatRun.mockReturnValue({ sessionKey, clientRunId: "client-run-1" });
+
+    const result = abortChatRunById(ops, { runId, sessionKey, stopReason: "user" });
+
+    expect(result).toEqual({ aborted: true });
+    expect(entry.controller.signal.aborted).toBe(true);
+    expect(ops.chatAbortControllers.has(runId)).toBe(false);
+    expect(ops.chatRunBuffers.has(runId)).toBe(false);
+    expect(ops.chatDeltaSentAt.has(runId)).toBe(false);
+    expect(ops.removeChatRun).toHaveBeenCalledWith(runId, runId, sessionKey);
+    expect(ops.agentRunSeq.has(runId)).toBe(false);
+    expect(ops.agentRunSeq.has("client-run-1")).toBe(false);
+
+    expect(ops.broadcast).toHaveBeenCalledTimes(1);
+    const payload = ops.broadcast.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(payload).toEqual(
+      expect.objectContaining({
+        runId,
+        sessionKey,
+        seq: 3,
+        state: "aborted",
+        stopReason: "user",
+      }),
+    );
+    expect(payload.message).toEqual(
+      expect.objectContaining({
+        role: "assistant",
+        content: [{ type: "text", text: "  Partial reply  " }],
+      }),
+    );
+    expect((payload.message as { timestamp?: unknown }).timestamp).toEqual(expect.any(Number));
+    expect(ops.nodeSendToSession).toHaveBeenCalledWith(sessionKey, "chat", payload);
+  });
+
+  it("omits aborted message when buffered text is empty", () => {
+    const runId = "run-1";
+    const sessionKey = "main";
+    const entry = createActiveEntry(sessionKey);
+    const ops = createOps({ runId, entry, buffer: "   " });
+
+    const result = abortChatRunById(ops, { runId, sessionKey });
+
+    expect(result).toEqual({ aborted: true });
+    const payload = ops.broadcast.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(payload.message).toBeUndefined();
+  });
+
+  it("preserves partial message even when abort listeners clear buffers synchronously", () => {
+    const runId = "run-1";
+    const sessionKey = "main";
+    const entry = createActiveEntry(sessionKey);
+    const ops = createOps({ runId, entry, buffer: "streamed text" });
+
+    // Simulate synchronous cleanup triggered by AbortController listeners.
+    entry.controller.signal.addEventListener("abort", () => {
+      ops.chatRunBuffers.delete(runId);
+    });
+
+    const result = abortChatRunById(ops, { runId, sessionKey });
+
+    expect(result).toEqual({ aborted: true });
+    const payload = ops.broadcast.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(payload.message).toEqual(
+      expect.objectContaining({
+        role: "assistant",
+        content: [{ type: "text", text: "streamed text" }],
+      }),
+    );
+  });
+});
diff --git a/src/gateway/chat-abort.ts b/src/gateway/chat-abort.ts
index 12c47f5b189..0d544324133 100644
--- a/src/gateway/chat-abort.ts
+++ b/src/gateway/chat-abort.ts
@@ -52,15 +52,23 @@ function broadcastChatAborted(
     runId: string;
     sessionKey: string;
     stopReason?: string;
+    partialText?: string;
   },
 ) {
-  const { runId, sessionKey, stopReason } = params;
+  const { runId, sessionKey, stopReason, partialText } = params;
   const payload = {
     runId,
     sessionKey,
     seq: (ops.agentRunSeq.get(runId) ?? 0) + 1,
     state: "aborted" as const,
     stopReason,
+    message: partialText
+      ? {
+          role: "assistant",
+          content: [{ type: "text", text: partialText }],
+          timestamp: Date.now(),
+        }
+      : undefined,
   };
   ops.broadcast("chat", payload);
   ops.nodeSendToSession(sessionKey, "chat", payload);
@@ -83,13 +91,15 @@ export function abortChatRunById(
     return { aborted: false };
   }
 
+  const bufferedText = ops.chatRunBuffers.get(runId);
+  const partialText = bufferedText && bufferedText.trim() ? bufferedText : undefined;
   ops.chatAbortedRuns.set(runId, Date.now());
   active.controller.abort();
   ops.chatAbortControllers.delete(runId);
   ops.chatRunBuffers.delete(runId);
   ops.chatDeltaSentAt.delete(runId);
   const removed = ops.removeChatRun(runId, runId, sessionKey);
-  broadcastChatAborted(ops, { runId, sessionKey, stopReason });
+  broadcastChatAborted(ops, { runId, sessionKey, stopReason, partialText });
   ops.agentRunSeq.delete(runId);
   if (removed?.clientRunId) {
     ops.agentRunSeq.delete(removed.clientRunId);
diff --git a/src/gateway/client.maxpayload.test.ts b/src/gateway/client.maxpayload.test.ts
deleted file mode 100644
index acd23da179e..00000000000
--- a/src/gateway/client.maxpayload.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, test, vi } from "vitest";
-import { GatewayClient } from "./client.js";
-
-const wsMockState = vi.hoisted(() => ({
-  last: null as { url: unknown; opts: unknown } | null,
-}));
-
-vi.mock("ws", () => ({
-  WebSocket: class MockWebSocket {
-    on = vi.fn();
-    close = vi.fn();
-    send = vi.fn();
-
-    constructor(url: unknown, opts: unknown) {
-      wsMockState.last = { url, opts };
-    }
-  },
-}));
-
-describe("GatewayClient", () => {
-  test("uses a large maxPayload for node snapshots", () => {
-    wsMockState.last = null;
-    const client = new GatewayClient({ url: "ws://127.0.0.1:1" });
-    client.start();
-
-    expect(wsMockState.last?.url).toBe("ws://127.0.0.1:1");
-    expect(wsMockState.last?.opts).toEqual(
-      expect.objectContaining({ maxPayload: 25 * 1024 * 1024 }),
-    );
-  });
-});
diff --git a/src/gateway/control-ui-contract.ts b/src/gateway/control-ui-contract.ts
new file mode 100644
index 00000000000..654835e0424
--- /dev/null
+++ b/src/gateway/control-ui-contract.ts
@@ -0,0 +1,8 @@
+export const CONTROL_UI_BOOTSTRAP_CONFIG_PATH = "/__openclaw/control-ui-config.json";
+
+export type ControlUiBootstrapConfig = {
+  basePath: string;
+  assistantName: string;
+  assistantAvatar: string;
+  assistantAgentId: string;
+};
diff --git a/src/gateway/control-ui-csp.test.ts b/src/gateway/control-ui-csp.test.ts
new file mode 100644
index 00000000000..012c826656c
--- /dev/null
+++ b/src/gateway/control-ui-csp.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { buildControlUiCspHeader } from "./control-ui-csp.js";
+
+describe("buildControlUiCspHeader", () => {
+  it("blocks inline scripts while allowing inline styles", () => {
+    const csp = buildControlUiCspHeader();
+    expect(csp).toContain("frame-ancestors 'none'");
+    expect(csp).toContain("script-src 'self'");
+    expect(csp).not.toContain("script-src 'self' 'unsafe-inline'");
+    expect(csp).toContain("style-src 'self' 'unsafe-inline'");
+  });
+});
diff --git a/src/gateway/control-ui-csp.ts b/src/gateway/control-ui-csp.ts
new file mode 100644
index 00000000000..31cd98bd673
--- /dev/null
+++ b/src/gateway/control-ui-csp.ts
@@ -0,0 +1,15 @@
+export function buildControlUiCspHeader(): string {
+  // Control UI: block framing, block inline scripts, keep styles permissive
+  // (UI uses a lot of inline style attributes in templates).
+  return [
+    "default-src 'self'",
+    "base-uri 'none'",
+    "object-src 'none'",
+    "frame-ancestors 'none'",
+    "script-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: https:",
+    "font-src 'self'",
+    "connect-src 'self' ws: wss:",
+  ].join("; ");
+}
diff --git a/src/gateway/control-ui.http.test.ts b/src/gateway/control-ui.http.test.ts
new file mode 100644
index 00000000000..af5a377180f
--- /dev/null
+++ b/src/gateway/control-ui.http.test.ts
@@ -0,0 +1,140 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { CONTROL_UI_BOOTSTRAP_CONFIG_PATH } from "./control-ui-contract.js";
+import { handleControlUiHttpRequest } from "./control-ui.js";
+
+const makeResponse = (): {
+  res: ServerResponse;
+  setHeader: ReturnType<typeof vi.fn>;
+  end: ReturnType<typeof vi.fn>;
+} => {
+  const setHeader = vi.fn();
+  const end = vi.fn();
+  const res = {
+    headersSent: false,
+    statusCode: 200,
+    setHeader,
+    end,
+  } as unknown as ServerResponse;
+  return { res, setHeader, end };
+};
+
+describe("handleControlUiHttpRequest", () => {
+  it("sets security headers for Control UI responses", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
+    try {
+      await fs.writeFile(path.join(tmp, "index.html"), "<html></html>\n");
+      const { res, setHeader } = makeResponse();
+      const handled = handleControlUiHttpRequest(
+        { url: "/", method: "GET" } as IncomingMessage,
+        res,
+        {
+          root: { kind: "resolved", path: tmp },
+        },
+      );
+      expect(handled).toBe(true);
+      expect(setHeader).toHaveBeenCalledWith("X-Frame-Options", "DENY");
+      const csp = setHeader.mock.calls.find((call) => call[0] === "Content-Security-Policy")?.[1];
+      expect(typeof csp).toBe("string");
+      expect(String(csp)).toContain("frame-ancestors 'none'");
+      expect(String(csp)).toContain("script-src 'self'");
+      expect(String(csp)).not.toContain("script-src 'self' 'unsafe-inline'");
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("does not inject inline scripts into index.html", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
+    try {
+      const html = "<html><head></head><body>Hello</body></html>\n";
+      await fs.writeFile(path.join(tmp, "index.html"), html);
+      const { res, end } = makeResponse();
+      const handled = handleControlUiHttpRequest(
+        { url: "/", method: "GET" } as IncomingMessage,
+        res,
+        {
+          root: { kind: "resolved", path: tmp },
+          config: {
+            agents: { defaults: { workspace: tmp } },
+            ui: { assistant: { name: "</script><script>alert(1)//", avatar: "evil.png" } },
+          },
+        },
+      );
+      expect(handled).toBe(true);
+      expect(end).toHaveBeenCalledWith(html);
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("serves bootstrap config JSON", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
+    try {
+      await fs.writeFile(path.join(tmp, "index.html"), "<html></html>\n");
+      const { res, end } = makeResponse();
+      const handled = handleControlUiHttpRequest(
+        { url: CONTROL_UI_BOOTSTRAP_CONFIG_PATH, method: "GET" } as IncomingMessage,
+        res,
+        {
+          root: { kind: "resolved", path: tmp },
+          config: {
+            agents: { defaults: { workspace: tmp } },
+            ui: { assistant: { name: "</script><script>alert(1)//", avatar: "</script>.png" } },
+          },
+        },
+      );
+      expect(handled).toBe(true);
+      const payload = String(end.mock.calls[0]?.[0] ?? "");
+      const parsed = JSON.parse(payload) as {
+        basePath: string;
+        assistantName: string;
+        assistantAvatar: string;
+        assistantAgentId: string;
+      };
+      expect(parsed.basePath).toBe("");
+      expect(parsed.assistantName).toBe("</script><script>alert(1)//");
+      expect(parsed.assistantAvatar).toBe("/avatar/main");
+      expect(parsed.assistantAgentId).toBe("main");
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("serves bootstrap config JSON under basePath", async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
+    try {
+      await fs.writeFile(path.join(tmp, "index.html"), "<html></html>\n");
+      const { res, end } = makeResponse();
+      const handled = handleControlUiHttpRequest(
+        { url: `/openclaw${CONTROL_UI_BOOTSTRAP_CONFIG_PATH}`, method: "GET" } as IncomingMessage,
+        res,
+        {
+          basePath: "/openclaw",
+          root: { kind: "resolved", path: tmp },
+          config: {
+            agents: { defaults: { workspace: tmp } },
+            ui: { assistant: { name: "Ops", avatar: "ops.png" } },
+          },
+        },
+      );
+      expect(handled).toBe(true);
+      const payload = String(end.mock.calls[0]?.[0] ?? "");
+      const parsed = JSON.parse(payload) as {
+        basePath: string;
+        assistantName: string;
+        assistantAvatar: string;
+        assistantAgentId: string;
+      };
+      expect(parsed.basePath).toBe("/openclaw");
+      expect(parsed.assistantName).toBe("Ops");
+      expect(parsed.assistantAvatar).toBe("/openclaw/avatar/main");
+      expect(parsed.assistantAgentId).toBe("main");
+    } finally {
+      await fs.rm(tmp, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/gateway/control-ui.test.ts b/src/gateway/control-ui.test.ts
deleted file mode 100644
index 13dd3020bf6..00000000000
--- a/src/gateway/control-ui.test.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
-import { handleControlUiHttpRequest } from "./control-ui.js";
-
-const makeResponse = (): {
-  res: ServerResponse;
-  setHeader: ReturnType<typeof vi.fn>;
-  end: ReturnType<typeof vi.fn>;
-} => {
-  const setHeader = vi.fn();
-  const end = vi.fn();
-  const res = {
-    headersSent: false,
-    statusCode: 200,
-    setHeader,
-    end,
-  } as unknown as ServerResponse;
-  return { res, setHeader, end };
-};
-
-describe("handleControlUiHttpRequest", () => {
-  it("sets anti-clickjacking headers for Control UI responses", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
-    try {
-      await fs.writeFile(path.join(tmp, "index.html"), "<html></html>\n");
-      const { res, setHeader } = makeResponse();
-      const handled = handleControlUiHttpRequest(
-        { url: "/", method: "GET" } as IncomingMessage,
-        res,
-        {
-          root: { kind: "resolved", path: tmp },
-        },
-      );
-      expect(handled).toBe(true);
-      expect(setHeader).toHaveBeenCalledWith("X-Frame-Options", "DENY");
-      expect(setHeader).toHaveBeenCalledWith("Content-Security-Policy", "frame-ancestors 'none'");
-    } finally {
-      await fs.rm(tmp, { recursive: true, force: true });
-    }
-  });
-});
diff --git a/src/gateway/control-ui.ts b/src/gateway/control-ui.ts
index 4484bf26e52..1256a3e5f94 100644
--- a/src/gateway/control-ui.ts
+++ b/src/gateway/control-ui.ts
@@ -4,6 +4,11 @@ import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveControlUiRootSync } from "../infra/control-ui-assets.js";
 import { DEFAULT_ASSISTANT_IDENTITY, resolveAssistantIdentity } from "./assistant-identity.js";
+import {
+  CONTROL_UI_BOOTSTRAP_CONFIG_PATH,
+  type ControlUiBootstrapConfig,
+} from "./control-ui-contract.js";
+import { buildControlUiCspHeader } from "./control-ui-csp.js";
 import {
   buildControlUiAvatarUrl,
   CONTROL_UI_AVATAR_PREFIX,
@@ -68,8 +73,9 @@ type ControlUiAvatarMeta = {
 
 function applyControlUiSecurityHeaders(res: ServerResponse) {
   res.setHeader("X-Frame-Options", "DENY");
-  res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+  res.setHeader("Content-Security-Policy", buildControlUiCspHeader());
   res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("Referrer-Policy", "no-referrer");
 }
 
 function sendJson(res: ServerResponse, status: number, body: unknown) {
@@ -160,66 +166,10 @@ function serveFile(res: ServerResponse, filePath: string) {
   res.end(fs.readFileSync(filePath));
 }
 
-interface ControlUiInjectionOpts {
-  basePath: string;
-  assistantName?: string;
-  assistantAvatar?: string;
-}
-
-function injectControlUiConfig(html: string, opts: ControlUiInjectionOpts): string {
-  const { basePath, assistantName, assistantAvatar } = opts;
-  const script =
-    `<script>` +
-    `window.__OPENCLAW_CONTROL_UI_BASE_PATH__=${JSON.stringify(basePath)};` +
-    `window.__OPENCLAW_ASSISTANT_NAME__=${JSON.stringify(
-      assistantName ?? DEFAULT_ASSISTANT_IDENTITY.name,
-    )};` +
-    `window.__OPENCLAW_ASSISTANT_AVATAR__=${JSON.stringify(
-      assistantAvatar ?? DEFAULT_ASSISTANT_IDENTITY.avatar,
-    )};` +
-    `</script>`;
-  // Check if already injected
-  if (html.includes("__OPENCLAW_ASSISTANT_NAME__")) {
-    return html;
-  }
-  const headClose = html.indexOf("</head>");
-  if (headClose !== -1) {
-    return `${html.slice(0, headClose)}${script}${html.slice(headClose)}`;
-  }
-  return `${script}${html}`;
-}
-
-interface ServeIndexHtmlOpts {
-  basePath: string;
-  config?: OpenClawConfig;
-  agentId?: string;
-}
-
-function serveIndexHtml(res: ServerResponse, indexPath: string, opts: ServeIndexHtmlOpts) {
-  const { basePath, config, agentId } = opts;
-  const identity = config
-    ? resolveAssistantIdentity({ cfg: config, agentId })
-    : DEFAULT_ASSISTANT_IDENTITY;
-  const resolvedAgentId =
-    typeof (identity as { agentId?: string }).agentId === "string"
-      ? (identity as { agentId?: string }).agentId
-      : agentId;
-  const avatarValue =
-    resolveAssistantAvatarUrl({
-      avatar: identity.avatar,
-      agentId: resolvedAgentId,
-      basePath,
-    }) ?? identity.avatar;
+function serveIndexHtml(res: ServerResponse, indexPath: string) {
   res.setHeader("Content-Type", "text/html; charset=utf-8");
   res.setHeader("Cache-Control", "no-cache");
-  const raw = fs.readFileSync(indexPath, "utf8");
-  res.end(
-    injectControlUiConfig(raw, {
-      basePath,
-      assistantName: identity.name,
-      assistantAvatar: avatarValue,
-    }),
-  );
+  res.end(fs.readFileSync(indexPath, "utf8"));
 }
 
 function isSafeRelativePath(relPath: string) {
@@ -279,6 +229,35 @@ export function handleControlUiHttpRequest(
 
   applyControlUiSecurityHeaders(res);
 
+  const bootstrapConfigPath = basePath
+    ? `${basePath}${CONTROL_UI_BOOTSTRAP_CONFIG_PATH}`
+    : CONTROL_UI_BOOTSTRAP_CONFIG_PATH;
+  if (pathname === bootstrapConfigPath) {
+    const config = opts?.config;
+    const identity = config
+      ? resolveAssistantIdentity({ cfg: config, agentId: opts?.agentId })
+      : DEFAULT_ASSISTANT_IDENTITY;
+    const avatarValue = resolveAssistantAvatarUrl({
+      avatar: identity.avatar,
+      agentId: identity.agentId,
+      basePath,
+    });
+    if (req.method === "HEAD") {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "application/json; charset=utf-8");
+      res.setHeader("Cache-Control", "no-cache");
+      res.end();
+      return true;
+    }
+    sendJson(res, 200, {
+      basePath,
+      assistantName: identity.name,
+      assistantAvatar: avatarValue ?? identity.avatar,
+      assistantAgentId: identity.agentId,
+    } satisfies ControlUiBootstrapConfig);
+    return true;
+  }
+
   const rootState = opts?.root;
   if (rootState?.kind === "invalid") {
     res.statusCode = 503;
@@ -341,11 +320,7 @@ export function handleControlUiHttpRequest(
 
   if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
     if (path.basename(filePath) === "index.html") {
-      serveIndexHtml(res, filePath, {
-        basePath,
-        config: opts?.config,
-        agentId: opts?.agentId,
-      });
+      serveIndexHtml(res, filePath);
       return true;
     }
     serveFile(res, filePath);
@@ -355,11 +330,7 @@ export function handleControlUiHttpRequest(
   // SPA fallback (client-side router): serve index.html for unknown paths.
   const indexPath = path.join(root, "index.html");
   if (fs.existsSync(indexPath)) {
-    serveIndexHtml(res, indexPath, {
-      basePath,
-      config: opts?.config,
-      agentId: opts?.agentId,
-    });
+    serveIndexHtml(res, indexPath);
     return true;
   }
 
diff --git a/src/gateway/gateway-config-prompts.shared.ts b/src/gateway/gateway-config-prompts.shared.ts
new file mode 100644
index 00000000000..e32d7ec0be8
--- /dev/null
+++ b/src/gateway/gateway-config-prompts.shared.ts
@@ -0,0 +1,27 @@
+export const TAILSCALE_EXPOSURE_OPTIONS = [
+  { value: "off", label: "Off", hint: "No Tailscale exposure" },
+  {
+    value: "serve",
+    label: "Serve",
+    hint: "Private HTTPS for your tailnet (devices on Tailscale)",
+  },
+  {
+    value: "funnel",
+    label: "Funnel",
+    hint: "Public HTTPS via Tailscale Funnel (internet)",
+  },
+] as const;
+
+export const TAILSCALE_MISSING_BIN_NOTE_LINES = [
+  "Tailscale binary not found in PATH or /Applications.",
+  "Ensure Tailscale is installed from:",
+  "  https://tailscale.com/download/mac",
+  "",
+  "You can continue setup, but serve/funnel will fail at runtime.",
+] as const;
+
+export const TAILSCALE_DOCS_LINES = [
+  "Docs:",
+  "https://docs.openclaw.ai/gateway/tailscale",
+  "https://docs.openclaw.ai/web",
+] as const;
diff --git a/src/gateway/gateway-misc.test.ts b/src/gateway/gateway-misc.test.ts
new file mode 100644
index 00000000000..c39a0256b0e
--- /dev/null
+++ b/src/gateway/gateway-misc.test.ts
@@ -0,0 +1,266 @@
+import { describe, expect, it, test, vi } from "vitest";
+import type { RequestFrame } from "./protocol/index.js";
+import type { GatewayClient as GatewayMethodClient } from "./server-methods/types.js";
+import type { GatewayRequestContext, RespondFn } from "./server-methods/types.js";
+import type { GatewayWsClient } from "./server/ws-types.js";
+import { defaultVoiceWakeTriggers } from "../infra/voicewake.js";
+import { GatewayClient } from "./client.js";
+import {
+  DEFAULT_DANGEROUS_NODE_COMMANDS,
+  resolveNodeCommandAllowlist,
+} from "./node-command-policy.js";
+import { createGatewayBroadcaster } from "./server-broadcast.js";
+import { createChatRunRegistry } from "./server-chat.js";
+import { handleNodeInvokeResult } from "./server-methods/nodes.handlers.invoke-result.js";
+import { createNodeSubscriptionManager } from "./server-node-subscriptions.js";
+import { formatError, normalizeVoiceWakeTriggers } from "./server-utils.js";
+
+const wsMockState = vi.hoisted(() => ({
+  last: null as { url: unknown; opts: unknown } | null,
+}));
+
+vi.mock("ws", () => ({
+  WebSocket: class MockWebSocket {
+    on = vi.fn();
+    close = vi.fn();
+    send = vi.fn();
+
+    constructor(url: unknown, opts: unknown) {
+      wsMockState.last = { url, opts };
+    }
+  },
+}));
+
+describe("GatewayClient", () => {
+  test("uses a large maxPayload for node snapshots", () => {
+    wsMockState.last = null;
+    const client = new GatewayClient({ url: "ws://127.0.0.1:1" });
+    client.start();
+
+    expect(wsMockState.last?.url).toBe("ws://127.0.0.1:1");
+    expect(wsMockState.last?.opts).toEqual(
+      expect.objectContaining({ maxPayload: 25 * 1024 * 1024 }),
+    );
+  });
+});
+
+type TestSocket = {
+  bufferedAmount: number;
+  send: (payload: string) => void;
+  close: (code: number, reason: string) => void;
+};
+
+describe("gateway broadcaster", () => {
+  it("filters approval and pairing events by scope", () => {
+    const approvalsSocket: TestSocket = {
+      bufferedAmount: 0,
+      send: vi.fn(),
+      close: vi.fn(),
+    };
+    const pairingSocket: TestSocket = {
+      bufferedAmount: 0,
+      send: vi.fn(),
+      close: vi.fn(),
+    };
+    const readSocket: TestSocket = {
+      bufferedAmount: 0,
+      send: vi.fn(),
+      close: vi.fn(),
+    };
+
+    const clients = new Set<GatewayWsClient>([
+      {
+        socket: approvalsSocket as unknown as GatewayWsClient["socket"],
+        connect: { role: "operator", scopes: ["operator.approvals"] } as GatewayWsClient["connect"],
+        connId: "c-approvals",
+      },
+      {
+        socket: pairingSocket as unknown as GatewayWsClient["socket"],
+        connect: { role: "operator", scopes: ["operator.pairing"] } as GatewayWsClient["connect"],
+        connId: "c-pairing",
+      },
+      {
+        socket: readSocket as unknown as GatewayWsClient["socket"],
+        connect: { role: "operator", scopes: ["operator.read"] } as GatewayWsClient["connect"],
+        connId: "c-read",
+      },
+    ]);
+
+    const { broadcast, broadcastToConnIds } = createGatewayBroadcaster({ clients });
+
+    broadcast("exec.approval.requested", { id: "1" });
+    broadcast("device.pair.requested", { requestId: "r1" });
+
+    expect(approvalsSocket.send).toHaveBeenCalledTimes(1);
+    expect(pairingSocket.send).toHaveBeenCalledTimes(1);
+    expect(readSocket.send).toHaveBeenCalledTimes(0);
+
+    broadcastToConnIds("tick", { ts: 1 }, new Set(["c-read"]));
+    expect(readSocket.send).toHaveBeenCalledTimes(1);
+    expect(approvalsSocket.send).toHaveBeenCalledTimes(1);
+    expect(pairingSocket.send).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("chat run registry", () => {
+  test("queues and removes runs per session", () => {
+    const registry = createChatRunRegistry();
+
+    registry.add("s1", { sessionKey: "main", clientRunId: "c1" });
+    registry.add("s1", { sessionKey: "main", clientRunId: "c2" });
+
+    expect(registry.peek("s1")?.clientRunId).toBe("c1");
+    expect(registry.shift("s1")?.clientRunId).toBe("c1");
+    expect(registry.peek("s1")?.clientRunId).toBe("c2");
+
+    expect(registry.remove("s1", "c2")?.clientRunId).toBe("c2");
+    expect(registry.peek("s1")).toBeUndefined();
+  });
+});
+
+describe("late-arriving invoke results", () => {
+  test("returns success for unknown invoke ids for both success and error payloads", async () => {
+    const nodeId = "node-123";
+    const cases = [
+      {
+        id: "unknown-invoke-id-12345",
+        ok: true,
+        payloadJSON: JSON.stringify({ result: "late" }),
+      },
+      {
+        id: "another-unknown-invoke-id",
+        ok: false,
+        error: { code: "FAILED", message: "test error" },
+      },
+    ] as const;
+
+    for (const params of cases) {
+      const respond = vi.fn<RespondFn>();
+      const context = {
+        nodeRegistry: { handleInvokeResult: () => false },
+        logGateway: { debug: vi.fn() },
+      } as unknown as GatewayRequestContext;
+      const client = {
+        connect: { device: { id: nodeId } },
+      } as unknown as GatewayMethodClient;
+
+      await handleNodeInvokeResult({
+        req: { method: "node.invoke.result" } as unknown as RequestFrame,
+        params: { ...params, nodeId } as unknown as Record<string, unknown>,
+        client,
+        isWebchatConnect: () => false,
+        respond,
+        context,
+      });
+
+      const [ok, payload, error] = respond.mock.lastCall ?? [];
+
+      // Late-arriving results return success instead of error to reduce log noise.
+      expect(ok).toBe(true);
+      expect(error).toBeUndefined();
+      expect(payload?.ok).toBe(true);
+      expect(payload?.ignored).toBe(true);
+    }
+  });
+});
+
+describe("node subscription manager", () => {
+  test("routes events to subscribed nodes", () => {
+    const manager = createNodeSubscriptionManager();
+    const sent: Array<{
+      nodeId: string;
+      event: string;
+      payloadJSON?: string | null;
+    }> = [];
+    const sendEvent = (evt: { nodeId: string; event: string; payloadJSON?: string | null }) =>
+      sent.push(evt);
+
+    manager.subscribe("node-a", "main");
+    manager.subscribe("node-b", "main");
+    manager.sendToSession("main", "chat", { ok: true }, sendEvent);
+
+    expect(sent).toHaveLength(2);
+    expect(sent.map((s) => s.nodeId).toSorted()).toEqual(["node-a", "node-b"]);
+    expect(sent[0].event).toBe("chat");
+  });
+
+  test("unsubscribeAll clears session mappings", () => {
+    const manager = createNodeSubscriptionManager();
+    const sent: string[] = [];
+    const sendEvent = (evt: { nodeId: string; event: string }) =>
+      sent.push(`${evt.nodeId}:${evt.event}`);
+
+    manager.subscribe("node-a", "main");
+    manager.subscribe("node-a", "secondary");
+    manager.unsubscribeAll("node-a");
+    manager.sendToSession("main", "tick", {}, sendEvent);
+    manager.sendToSession("secondary", "tick", {}, sendEvent);
+
+    expect(sent).toEqual([]);
+  });
+});
+
+describe("resolveNodeCommandAllowlist", () => {
+  it("includes iOS service commands by default", () => {
+    const allow = resolveNodeCommandAllowlist(
+      {},
+      {
+        platform: "ios 26.0",
+        deviceFamily: "iPhone",
+      },
+    );
+
+    expect(allow.has("device.info")).toBe(true);
+    expect(allow.has("device.status")).toBe(true);
+    expect(allow.has("system.notify")).toBe(true);
+    expect(allow.has("contacts.search")).toBe(true);
+    expect(allow.has("calendar.events")).toBe(true);
+    expect(allow.has("reminders.list")).toBe(true);
+    expect(allow.has("photos.latest")).toBe(true);
+    expect(allow.has("motion.activity")).toBe(true);
+
+    for (const cmd of DEFAULT_DANGEROUS_NODE_COMMANDS) {
+      expect(allow.has(cmd)).toBe(false);
+    }
+  });
+
+  it("can explicitly allow dangerous commands via allowCommands", () => {
+    const allow = resolveNodeCommandAllowlist(
+      {
+        gateway: {
+          nodes: {
+            allowCommands: ["camera.snap", "screen.record"],
+          },
+        },
+      },
+      { platform: "ios", deviceFamily: "iPhone" },
+    );
+    expect(allow.has("camera.snap")).toBe(true);
+    expect(allow.has("screen.record")).toBe(true);
+    expect(allow.has("camera.clip")).toBe(false);
+  });
+});
+
+describe("normalizeVoiceWakeTriggers", () => {
+  test("returns defaults when input is empty", () => {
+    expect(normalizeVoiceWakeTriggers([])).toEqual(defaultVoiceWakeTriggers());
+    expect(normalizeVoiceWakeTriggers(null)).toEqual(defaultVoiceWakeTriggers());
+  });
+
+  test("trims and limits entries", () => {
+    const result = normalizeVoiceWakeTriggers(["  hello  ", "", "world"]);
+    expect(result).toEqual(["hello", "world"]);
+  });
+});
+
+describe("formatError", () => {
+  test("prefers message for Error", () => {
+    expect(formatError(new Error("boom"))).toBe("boom");
+  });
+
+  test("handles status/code", () => {
+    expect(formatError({ status: 500, code: "EPIPE" })).toBe("status=500 code=EPIPE");
+    expect(formatError({ status: 404 })).toBe("status=404 code=unknown");
+    expect(formatError({ code: "ENOENT" })).toBe("status=unknown code=ENOENT");
+  });
+});
diff --git a/src/gateway/net.ts b/src/gateway/net.ts
index 977102eb766..20f54265169 100644
--- a/src/gateway/net.ts
+++ b/src/gateway/net.ts
@@ -25,6 +25,25 @@ export function pickPrimaryLanIPv4(): string | undefined {
   return undefined;
 }
 
+export function normalizeHostHeader(hostHeader?: string): string {
+  return (hostHeader ?? "").trim().toLowerCase();
+}
+
+export function resolveHostName(hostHeader?: string): string {
+  const host = normalizeHostHeader(hostHeader);
+  if (!host) {
+    return "";
+  }
+  if (host.startsWith("[")) {
+    const end = host.indexOf("]");
+    if (end !== -1) {
+      return host.slice(1, end);
+    }
+  }
+  const [name] = host.split(":");
+  return name ?? "";
+}
+
 export function isLoopbackAddress(ip: string | undefined): boolean {
   if (!ip) {
     return false;
diff --git a/src/gateway/node-command-policy.test.ts b/src/gateway/node-command-policy.test.ts
deleted file mode 100644
index f96bd0eaf16..00000000000
--- a/src/gateway/node-command-policy.test.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_DANGEROUS_NODE_COMMANDS,
-  resolveNodeCommandAllowlist,
-} from "./node-command-policy.js";
-
-describe("resolveNodeCommandAllowlist", () => {
-  it("includes iOS service commands by default", () => {
-    const allow = resolveNodeCommandAllowlist(
-      {},
-      {
-        platform: "ios 26.0",
-        deviceFamily: "iPhone",
-      },
-    );
-
-    expect(allow.has("device.info")).toBe(true);
-    expect(allow.has("device.status")).toBe(true);
-    expect(allow.has("system.notify")).toBe(true);
-    expect(allow.has("contacts.search")).toBe(true);
-    expect(allow.has("calendar.events")).toBe(true);
-    expect(allow.has("reminders.list")).toBe(true);
-    expect(allow.has("photos.latest")).toBe(true);
-    expect(allow.has("motion.activity")).toBe(true);
-
-    for (const cmd of DEFAULT_DANGEROUS_NODE_COMMANDS) {
-      expect(allow.has(cmd)).toBe(false);
-    }
-  });
-
-  it("can explicitly allow dangerous commands via allowCommands", () => {
-    const allow = resolveNodeCommandAllowlist(
-      {
-        gateway: {
-          nodes: {
-            allowCommands: ["camera.snap", "screen.record"],
-          },
-        },
-      },
-      { platform: "ios", deviceFamily: "iPhone" },
-    );
-    expect(allow.has("camera.snap")).toBe(true);
-    expect(allow.has("screen.record")).toBe(true);
-    expect(allow.has("camera.clip")).toBe(false);
-  });
-});
diff --git a/src/gateway/openai-http.e2e.test.ts b/src/gateway/openai-http.e2e.test.ts
index 154b771d683..e1a3af00dc5 100644
--- a/src/gateway/openai-http.e2e.test.ts
+++ b/src/gateway/openai-http.e2e.test.ts
@@ -2,7 +2,13 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { HISTORY_CONTEXT_MARKER } from "../auto-reply/reply/history.js";
 import { CURRENT_MESSAGE_MARKER } from "../auto-reply/reply/mentions.js";
 import { emitAgentEvent } from "../infra/agent-events.js";
-import { agentCommand, getFreePort, installGatewayTestHooks, testState } from "./test-helpers.js";
+import {
+  agentCommand,
+  getFreePort,
+  installGatewayTestHooks,
+  testState,
+  withGatewayServer,
+} from "./test-helpers.js";
 
 installGatewayTestHooks({ scope: "suite" });
 
@@ -345,46 +351,46 @@ describe("OpenAI-compatible HTTP API (e2e)", () => {
   });
 
   it("returns 429 for repeated failed auth when gateway.auth.rateLimit is configured", async () => {
-    const { startGatewayServer } = await import("./server.js");
     testState.gatewayAuth = {
       mode: "token",
       token: "secret",
       rateLimit: { maxAttempts: 1, windowMs: 60_000, lockoutMs: 60_000, exemptLoopback: false },
       // oxlint-disable-next-line typescript/no-explicit-any
     } as any;
-    const port = await getFreePort();
-    const server = await startGatewayServer(port, {
-      host: "127.0.0.1",
-      controlUiEnabled: false,
-      openAiChatCompletionsEnabled: true,
-    });
-    try {
-      const headers = {
-        "content-type": "application/json",
-        authorization: "Bearer wrong",
-      };
-      const body = {
-        model: "openclaw",
-        messages: [{ role: "user", content: "hi" }],
-      };
+    await withGatewayServer(
+      async ({ port }) => {
+        const headers = {
+          "content-type": "application/json",
+          authorization: "Bearer wrong",
+        };
+        const body = {
+          model: "openclaw",
+          messages: [{ role: "user", content: "hi" }],
+        };
 
-      const first = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-      });
-      expect(first.status).toBe(401);
+        const first = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+        });
+        expect(first.status).toBe(401);
 
-      const second = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-      });
-      expect(second.status).toBe(429);
-      expect(second.headers.get("retry-after")).toBeTruthy();
-    } finally {
-      await server.close({ reason: "rate-limit auth test done" });
-    }
+        const second = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+        });
+        expect(second.status).toBe(429);
+        expect(second.headers.get("retry-after")).toBeTruthy();
+      },
+      {
+        serverOptions: {
+          host: "127.0.0.1",
+          controlUiEnabled: false,
+          openAiChatCompletionsEnabled: true,
+        },
+      },
+    );
   });
 
   it("streams SSE chunks when stream=true", async () => {
diff --git a/src/gateway/openai-http.ts b/src/gateway/openai-http.ts
index 038dc3540db..12d80cdfac8 100644
--- a/src/gateway/openai-http.ts
+++ b/src/gateway/openai-http.ts
@@ -7,6 +7,7 @@ import { agentCommand } from "../commands/agent.js";
 import { emitAgentEvent, onAgentEvent } from "../infra/agent-events.js";
 import { logWarn } from "../logger.js";
 import { defaultRuntime } from "../runtime.js";
+import { resolveAssistantStreamDeltaText } from "./agent-event-assistant-text.js";
 import {
   buildAgentMessageFromConversationEntries,
   type ConversationEntry,
@@ -243,9 +244,7 @@ export async function handleOpenAiHttpRequest(
     }
 
     if (evt.stream === "assistant") {
-      const delta = evt.data?.delta;
-      const text = evt.data?.text;
-      const content = typeof delta === "string" ? delta : typeof text === "string" ? text : "";
+      const content = resolveAssistantStreamDeltaText(evt);
       if (!content) {
         return;
       }
diff --git a/src/gateway/openresponses-http.e2e.test.ts b/src/gateway/openresponses-http.e2e.test.ts
index 0c484a56366..9747280d693 100644
--- a/src/gateway/openresponses-http.e2e.test.ts
+++ b/src/gateway/openresponses-http.e2e.test.ts
@@ -13,30 +13,26 @@ let enabledPort: number;
 
 beforeAll(async () => {
   enabledPort = await getFreePort();
-  enabledServer = await startServer(enabledPort);
+  enabledServer = await startServer(enabledPort, { openResponsesEnabled: true });
 });
 
 afterAll(async () => {
   await enabledServer.close({ reason: "openresponses enabled suite done" });
 });
 
-async function startServerWithDefaultConfig(port: number) {
-  const { startGatewayServer } = await import("./server.js");
-  return await startGatewayServer(port, {
-    host: "127.0.0.1",
-    auth: { mode: "token", token: "secret" },
-    controlUiEnabled: false,
-  });
-}
-
 async function startServer(port: number, opts?: { openResponsesEnabled?: boolean }) {
   const { startGatewayServer } = await import("./server.js");
-  return await startGatewayServer(port, {
+  const serverOpts = {
     host: "127.0.0.1",
     auth: { mode: "token", token: "secret" },
     controlUiEnabled: false,
-    openResponsesEnabled: opts?.openResponsesEnabled ?? true,
-  });
+  } as const;
+  return await startGatewayServer(
+    port,
+    opts?.openResponsesEnabled === undefined
+      ? serverOpts
+      : { ...serverOpts, openResponsesEnabled: opts.openResponsesEnabled },
+  );
 }
 
 async function writeGatewayConfig(config: Record<string, unknown>) {
@@ -96,7 +92,7 @@ async function ensureResponseConsumed(res: Response) {
 describe("OpenResponses HTTP API (e2e)", () => {
   it("rejects when disabled (default + config)", { timeout: 120_000 }, async () => {
     const port = await getFreePort();
-    const _server = await startServerWithDefaultConfig(port);
+    const _server = await startServer(port);
     try {
       const res = await postResponses(port, {
         model: "openclaw",
diff --git a/src/gateway/openresponses-http.ts b/src/gateway/openresponses-http.ts
index 896ae9b184f..0ce1189d5c4 100644
--- a/src/gateway/openresponses-http.ts
+++ b/src/gateway/openresponses-http.ts
@@ -36,6 +36,7 @@ import {
   type InputImageSource,
 } from "../media/input-files.js";
 import { defaultRuntime } from "../runtime.js";
+import { resolveAssistantStreamDeltaText } from "./agent-event-assistant-text.js";
 import {
   buildAgentMessageFromConversationEntries,
   type ConversationEntry,
@@ -727,9 +728,7 @@ export async function handleOpenResponsesHttpRequest(
     }
 
     if (evt.stream === "assistant") {
-      const delta = evt.data?.delta;
-      const text = evt.data?.text;
-      const content = typeof delta === "string" ? delta : typeof text === "string" ? text : "";
+      const content = resolveAssistantStreamDeltaText(evt);
       if (!content) {
         return;
       }
diff --git a/src/gateway/origin-check.ts b/src/gateway/origin-check.ts
index 0648bd7393e..50aea0315ec 100644
--- a/src/gateway/origin-check.ts
+++ b/src/gateway/origin-check.ts
@@ -1,26 +1,7 @@
-import { isLoopbackHost } from "./net.js";
+import { isLoopbackHost, normalizeHostHeader, resolveHostName } from "./net.js";
 
 type OriginCheckResult = { ok: true } | { ok: false; reason: string };
 
-function normalizeHostHeader(hostHeader?: string): string {
-  return (hostHeader ?? "").trim().toLowerCase();
-}
-
-function resolveHostName(hostHeader?: string): string {
-  const host = normalizeHostHeader(hostHeader);
-  if (!host) {
-    return "";
-  }
-  if (host.startsWith("[")) {
-    const end = host.indexOf("]");
-    if (end !== -1) {
-      return host.slice(1, end);
-    }
-  }
-  const [name] = host.split(":");
-  return name ?? "";
-}
-
 function parseOrigin(
   originRaw?: string,
 ): { origin: string; host: string; hostname: string } | null {
diff --git a/src/gateway/protocol/schema/config.ts b/src/gateway/protocol/schema/config.ts
index eb7389a4d1d..78587d34abe 100644
--- a/src/gateway/protocol/schema/config.ts
+++ b/src/gateway/protocol/schema/config.ts
@@ -11,7 +11,7 @@ export const ConfigSetParamsSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export const ConfigApplyParamsSchema = Type.Object(
+const ConfigApplyLikeParamsSchema = Type.Object(
   {
     raw: NonEmptyString,
     baseHash: Type.Optional(NonEmptyString),
@@ -22,16 +22,8 @@ export const ConfigApplyParamsSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export const ConfigPatchParamsSchema = Type.Object(
-  {
-    raw: NonEmptyString,
-    baseHash: Type.Optional(NonEmptyString),
-    sessionKey: Type.Optional(Type.String()),
-    note: Type.Optional(Type.String()),
-    restartDelayMs: Type.Optional(Type.Integer({ minimum: 0 })),
-  },
-  { additionalProperties: false },
-);
+export const ConfigApplyParamsSchema = ConfigApplyLikeParamsSchema;
+export const ConfigPatchParamsSchema = ConfigApplyLikeParamsSchema;
 
 export const ConfigSchemaParamsSchema = Type.Object({}, { additionalProperties: false });
 
diff --git a/src/gateway/protocol/schema/cron.ts b/src/gateway/protocol/schema/cron.ts
index 345690c8327..b4ce3469708 100644
--- a/src/gateway/protocol/schema/cron.ts
+++ b/src/gateway/protocol/schema/cron.ts
@@ -1,6 +1,24 @@
-import { Type } from "@sinclair/typebox";
+import { Type, type TSchema } from "@sinclair/typebox";
 import { NonEmptyString } from "./primitives.js";
 
+function cronAgentTurnPayloadSchema(params: { message: TSchema }) {
+  return Type.Object(
+    {
+      kind: Type.Literal("agentTurn"),
+      message: params.message,
+      model: Type.Optional(Type.String()),
+      thinking: Type.Optional(Type.String()),
+      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
+      allowUnsafeExternalContent: Type.Optional(Type.Boolean()),
+      deliver: Type.Optional(Type.Boolean()),
+      channel: Type.Optional(Type.String()),
+      to: Type.Optional(Type.String()),
+      bestEffortDeliver: Type.Optional(Type.Boolean()),
+    },
+    { additionalProperties: false },
+  );
+}
+
 export const CronScheduleSchema = Type.Union([
   Type.Object(
     {
@@ -35,21 +53,7 @@ export const CronPayloadSchema = Type.Union([
     },
     { additionalProperties: false },
   ),
-  Type.Object(
-    {
-      kind: Type.Literal("agentTurn"),
-      message: NonEmptyString,
-      model: Type.Optional(Type.String()),
-      thinking: Type.Optional(Type.String()),
-      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
-      allowUnsafeExternalContent: Type.Optional(Type.Boolean()),
-      deliver: Type.Optional(Type.Boolean()),
-      channel: Type.Optional(Type.String()),
-      to: Type.Optional(Type.String()),
-      bestEffortDeliver: Type.Optional(Type.Boolean()),
-    },
-    { additionalProperties: false },
-  ),
+  cronAgentTurnPayloadSchema({ message: NonEmptyString }),
 ]);
 
 export const CronPayloadPatchSchema = Type.Union([
@@ -60,39 +64,54 @@ export const CronPayloadPatchSchema = Type.Union([
     },
     { additionalProperties: false },
   ),
-  Type.Object(
-    {
-      kind: Type.Literal("agentTurn"),
-      message: Type.Optional(NonEmptyString),
-      model: Type.Optional(Type.String()),
-      thinking: Type.Optional(Type.String()),
-      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
-      allowUnsafeExternalContent: Type.Optional(Type.Boolean()),
-      deliver: Type.Optional(Type.Boolean()),
-      channel: Type.Optional(Type.String()),
-      to: Type.Optional(Type.String()),
-      bestEffortDeliver: Type.Optional(Type.Boolean()),
-    },
-    { additionalProperties: false },
-  ),
+  cronAgentTurnPayloadSchema({ message: Type.Optional(NonEmptyString) }),
 ]);
 
-export const CronDeliverySchema = Type.Object(
+const CronDeliverySharedProperties = {
+  channel: Type.Optional(Type.Union([Type.Literal("last"), NonEmptyString])),
+  bestEffort: Type.Optional(Type.Boolean()),
+};
+
+const CronDeliveryNoopSchema = Type.Object(
   {
-    mode: Type.Union([Type.Literal("none"), Type.Literal("announce")]),
-    channel: Type.Optional(Type.Union([Type.Literal("last"), NonEmptyString])),
+    mode: Type.Literal("none"),
+    ...CronDeliverySharedProperties,
     to: Type.Optional(Type.String()),
-    bestEffort: Type.Optional(Type.Boolean()),
   },
   { additionalProperties: false },
 );
 
+const CronDeliveryAnnounceSchema = Type.Object(
+  {
+    mode: Type.Literal("announce"),
+    ...CronDeliverySharedProperties,
+    to: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
+const CronDeliveryWebhookSchema = Type.Object(
+  {
+    mode: Type.Literal("webhook"),
+    ...CronDeliverySharedProperties,
+    to: NonEmptyString,
+  },
+  { additionalProperties: false },
+);
+
+export const CronDeliverySchema = Type.Union([
+  CronDeliveryNoopSchema,
+  CronDeliveryAnnounceSchema,
+  CronDeliveryWebhookSchema,
+]);
+
 export const CronDeliveryPatchSchema = Type.Object(
   {
-    mode: Type.Optional(Type.Union([Type.Literal("none"), Type.Literal("announce")])),
-    channel: Type.Optional(Type.Union([Type.Literal("last"), NonEmptyString])),
+    mode: Type.Optional(
+      Type.Union([Type.Literal("none"), Type.Literal("announce"), Type.Literal("webhook")]),
+    ),
+    ...CronDeliverySharedProperties,
     to: Type.Optional(Type.String()),
-    bestEffort: Type.Optional(Type.Boolean()),
   },
   { additionalProperties: false },
 );
diff --git a/src/gateway/server-broadcast.test.ts b/src/gateway/server-broadcast.test.ts
deleted file mode 100644
index 2cb5855a98e..00000000000
--- a/src/gateway/server-broadcast.test.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { GatewayWsClient } from "./server/ws-types.js";
-import { createGatewayBroadcaster } from "./server-broadcast.js";
-
-type TestSocket = {
-  bufferedAmount: number;
-  send: (payload: string) => void;
-  close: (code: number, reason: string) => void;
-};
-
-describe("gateway broadcaster", () => {
-  it("filters approval and pairing events by scope", () => {
-    const approvalsSocket: TestSocket = {
-      bufferedAmount: 0,
-      send: vi.fn(),
-      close: vi.fn(),
-    };
-    const pairingSocket: TestSocket = {
-      bufferedAmount: 0,
-      send: vi.fn(),
-      close: vi.fn(),
-    };
-    const readSocket: TestSocket = {
-      bufferedAmount: 0,
-      send: vi.fn(),
-      close: vi.fn(),
-    };
-
-    const clients = new Set<GatewayWsClient>([
-      {
-        socket: approvalsSocket as unknown as GatewayWsClient["socket"],
-        connect: { role: "operator", scopes: ["operator.approvals"] } as GatewayWsClient["connect"],
-        connId: "c-approvals",
-      },
-      {
-        socket: pairingSocket as unknown as GatewayWsClient["socket"],
-        connect: { role: "operator", scopes: ["operator.pairing"] } as GatewayWsClient["connect"],
-        connId: "c-pairing",
-      },
-      {
-        socket: readSocket as unknown as GatewayWsClient["socket"],
-        connect: { role: "operator", scopes: ["operator.read"] } as GatewayWsClient["connect"],
-        connId: "c-read",
-      },
-    ]);
-
-    const { broadcast, broadcastToConnIds } = createGatewayBroadcaster({ clients });
-
-    broadcast("exec.approval.requested", { id: "1" });
-    broadcast("device.pair.requested", { requestId: "r1" });
-
-    expect(approvalsSocket.send).toHaveBeenCalledTimes(1);
-    expect(pairingSocket.send).toHaveBeenCalledTimes(1);
-    expect(readSocket.send).toHaveBeenCalledTimes(0);
-
-    broadcastToConnIds("tick", { ts: 1 }, new Set(["c-read"]));
-    expect(readSocket.send).toHaveBeenCalledTimes(1);
-    expect(approvalsSocket.send).toHaveBeenCalledTimes(1);
-    expect(pairingSocket.send).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/gateway/server-chat-registry.test.ts b/src/gateway/server-chat-registry.test.ts
deleted file mode 100644
index 631b5bb5ee8..00000000000
--- a/src/gateway/server-chat-registry.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { createChatRunRegistry } from "./server-chat.js";
-
-describe("chat run registry", () => {
-  test("queues and removes runs per session", () => {
-    const registry = createChatRunRegistry();
-
-    registry.add("s1", { sessionKey: "main", clientRunId: "c1" });
-    registry.add("s1", { sessionKey: "main", clientRunId: "c2" });
-
-    expect(registry.peek("s1")?.clientRunId).toBe("c1");
-    expect(registry.shift("s1")?.clientRunId).toBe("c1");
-    expect(registry.peek("s1")?.clientRunId).toBe("c2");
-
-    expect(registry.remove("s1", "c2")?.clientRunId).toBe("c2");
-    expect(registry.peek("s1")).toBeUndefined();
-  });
-});
diff --git a/src/gateway/server-cron.ts b/src/gateway/server-cron.ts
index 51865d1d0a4..a5d1c711b3e 100644
--- a/src/gateway/server-cron.ts
+++ b/src/gateway/server-cron.ts
@@ -7,6 +7,7 @@ import { runCronIsolatedAgentTurn } from "../cron/isolated-agent.js";
 import { appendCronRunLog, resolveCronRunLogPath } from "../cron/run-log.js";
 import { CronService } from "../cron/service.js";
 import { resolveCronStorePath } from "../cron/store.js";
+import { normalizeHttpWebhookUrl } from "../cron/webhook-url.js";
 import { runHeartbeatOnce } from "../infra/heartbeat-runner.js";
 import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
@@ -20,6 +21,43 @@ export type GatewayCronState = {
   cronEnabled: boolean;
 };
 
+const CRON_WEBHOOK_TIMEOUT_MS = 10_000;
+
+function redactWebhookUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return "<invalid-webhook-url>";
+  }
+}
+
+type CronWebhookTarget = {
+  url: string;
+  source: "delivery" | "legacy";
+};
+
+function resolveCronWebhookTarget(params: {
+  delivery?: { mode?: string; to?: string };
+  legacyNotify?: boolean;
+  legacyWebhook?: string;
+}): CronWebhookTarget | null {
+  const mode = params.delivery?.mode?.trim().toLowerCase();
+  if (mode === "webhook") {
+    const url = normalizeHttpWebhookUrl(params.delivery?.to);
+    return url ? { url, source: "delivery" } : null;
+  }
+
+  if (params.legacyNotify) {
+    const legacyUrl = normalizeHttpWebhookUrl(params.legacyWebhook);
+    if (legacyUrl) {
+      return { url: legacyUrl, source: "legacy" };
+    }
+  }
+
+  return null;
+}
+
 export function buildGatewayCronService(params: {
   cfg: ReturnType<typeof loadConfig>;
   deps: CliDeps;
@@ -50,6 +88,7 @@ export function buildGatewayCronService(params: {
       agentId: agentId ?? defaultAgentId,
     });
   const sessionStorePath = resolveSessionStorePath(defaultAgentId);
+  const warnedLegacyWebhookJobs = new Set<string>();
 
   const cron = new CronService({
     storePath,
@@ -93,6 +132,71 @@ export function buildGatewayCronService(params: {
     onEvent: (evt) => {
       params.broadcast("cron", evt, { dropIfSlow: true });
       if (evt.action === "finished") {
+        const webhookToken = params.cfg.cron?.webhookToken?.trim();
+        const legacyWebhook = params.cfg.cron?.webhook?.trim();
+        const job = cron.getJob(evt.jobId);
+        const legacyNotify = (job as { notify?: unknown } | undefined)?.notify === true;
+        const webhookTarget = resolveCronWebhookTarget({
+          delivery:
+            job?.delivery && typeof job.delivery.mode === "string"
+              ? { mode: job.delivery.mode, to: job.delivery.to }
+              : undefined,
+          legacyNotify,
+          legacyWebhook,
+        });
+
+        if (!webhookTarget && job?.delivery?.mode === "webhook") {
+          cronLogger.warn(
+            {
+              jobId: evt.jobId,
+              deliveryTo: job.delivery.to,
+            },
+            "cron: skipped webhook delivery, delivery.to must be a valid http(s) URL",
+          );
+        }
+
+        if (webhookTarget?.source === "legacy" && !warnedLegacyWebhookJobs.has(evt.jobId)) {
+          warnedLegacyWebhookJobs.add(evt.jobId);
+          cronLogger.warn(
+            {
+              jobId: evt.jobId,
+              legacyWebhook: redactWebhookUrl(webhookTarget.url),
+            },
+            "cron: deprecated notify+cron.webhook fallback in use, migrate to delivery.mode=webhook with delivery.to",
+          );
+        }
+
+        if (webhookTarget && evt.summary) {
+          const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+          };
+          if (webhookToken) {
+            headers.Authorization = `Bearer ${webhookToken}`;
+          }
+          const abortController = new AbortController();
+          const timeout = setTimeout(() => {
+            abortController.abort();
+          }, CRON_WEBHOOK_TIMEOUT_MS);
+          void fetch(webhookTarget.url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(evt),
+            signal: abortController.signal,
+          })
+            .catch((err) => {
+              cronLogger.warn(
+                {
+                  err: String(err),
+                  jobId: evt.jobId,
+                  webhookUrl: redactWebhookUrl(webhookTarget.url),
+                },
+                "cron: webhook delivery failed",
+              );
+            })
+            .finally(() => {
+              clearTimeout(timeout);
+            });
+        }
         const logPath = resolveCronRunLogPath({
           storePath,
           jobId: evt.jobId,
diff --git a/src/gateway/server-methods/agent-job.test.ts b/src/gateway/server-methods/agent-job.test.ts
deleted file mode 100644
index d696d9e0830..00000000000
--- a/src/gateway/server-methods/agent-job.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { emitAgentEvent } from "../../infra/agent-events.js";
-import { waitForAgentJob } from "./agent-job.js";
-
-describe("waitForAgentJob", () => {
-  it("maps lifecycle end events with aborted=true to timeout", async () => {
-    const runId = `run-timeout-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
-
-    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "start", startedAt: 100 } });
-    emitAgentEvent({
-      runId,
-      stream: "lifecycle",
-      data: { phase: "end", endedAt: 200, aborted: true },
-    });
-
-    const snapshot = await waitPromise;
-    expect(snapshot).not.toBeNull();
-    expect(snapshot?.status).toBe("timeout");
-    expect(snapshot?.startedAt).toBe(100);
-    expect(snapshot?.endedAt).toBe(200);
-  });
-
-  it("keeps non-aborted lifecycle end events as ok", async () => {
-    const runId = `run-ok-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
-
-    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "start", startedAt: 300 } });
-    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "end", endedAt: 400 } });
-
-    const snapshot = await waitPromise;
-    expect(snapshot).not.toBeNull();
-    expect(snapshot?.status).toBe("ok");
-    expect(snapshot?.startedAt).toBe(300);
-    expect(snapshot?.endedAt).toBe(400);
-  });
-});
diff --git a/src/gateway/server-methods/agent-timestamp.test.ts b/src/gateway/server-methods/agent-timestamp.test.ts
deleted file mode 100644
index 1482194c2eb..00000000000
--- a/src/gateway/server-methods/agent-timestamp.test.ts
+++ /dev/null
@@ -1,143 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { formatZonedTimestamp } from "../../infra/format-time/format-datetime.js";
-import { injectTimestamp, timestampOptsFromConfig } from "./agent-timestamp.js";
-
-describe("injectTimestamp", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    // Wednesday, January 28, 2026 at 8:30 PM EST (01:30 UTC Jan 29)
-    vi.setSystemTime(new Date("2026-01-29T01:30:00.000Z"));
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("prepends a compact timestamp matching formatZonedTimestamp", () => {
-    const result = injectTimestamp("Is it the weekend?", {
-      timezone: "America/New_York",
-    });
-
-    expect(result).toMatch(/^\[Wed 2026-01-28 20:30 EST\] Is it the weekend\?$/);
-  });
-
-  it("uses channel envelope format with DOW prefix", () => {
-    const now = new Date();
-    const expected = formatZonedTimestamp(now, { timeZone: "America/New_York" });
-
-    const result = injectTimestamp("hello", { timezone: "America/New_York" });
-
-    // DOW prefix + formatZonedTimestamp format
-    expect(result).toBe(`[Wed ${expected}] hello`);
-  });
-
-  it("always uses 24-hour format", () => {
-    const result = injectTimestamp("hello", { timezone: "America/New_York" });
-
-    expect(result).toContain("20:30");
-    expect(result).not.toContain("PM");
-    expect(result).not.toContain("AM");
-  });
-
-  it("uses the configured timezone", () => {
-    const result = injectTimestamp("hello", { timezone: "America/Chicago" });
-
-    // 8:30 PM EST = 7:30 PM CST = 19:30
-    expect(result).toMatch(/^\[Wed 2026-01-28 19:30 CST\]/);
-  });
-
-  it("defaults to UTC when no timezone specified", () => {
-    const result = injectTimestamp("hello", {});
-
-    // 2026-01-29T01:30:00Z
-    expect(result).toMatch(/^\[Thu 2026-01-29 01:30/);
-  });
-
-  it("returns empty/whitespace messages unchanged", () => {
-    expect(injectTimestamp("", { timezone: "UTC" })).toBe("");
-    expect(injectTimestamp("   ", { timezone: "UTC" })).toBe("   ");
-  });
-
-  it("does NOT double-stamp messages with channel envelope timestamps", () => {
-    const enveloped = "[Discord user1 2026-01-28 20:30 EST] hello there";
-    const result = injectTimestamp(enveloped, { timezone: "America/New_York" });
-
-    expect(result).toBe(enveloped);
-  });
-
-  it("does NOT double-stamp messages already injected by us", () => {
-    const alreadyStamped = "[Wed 2026-01-28 20:30 EST] hello there";
-    const result = injectTimestamp(alreadyStamped, { timezone: "America/New_York" });
-
-    expect(result).toBe(alreadyStamped);
-  });
-
-  it("does NOT double-stamp messages with cron-injected timestamps", () => {
-    const cronMessage =
-      "[cron:abc123 my-job] do the thing\nCurrent time: Wednesday, January 28th, 2026 — 8:30 PM (America/New_York)";
-    const result = injectTimestamp(cronMessage, { timezone: "America/New_York" });
-
-    expect(result).toBe(cronMessage);
-  });
-
-  it("handles midnight correctly", () => {
-    vi.setSystemTime(new Date("2026-02-01T05:00:00.000Z")); // midnight EST
-
-    const result = injectTimestamp("hello", { timezone: "America/New_York" });
-
-    expect(result).toMatch(/^\[Sun 2026-02-01 00:00 EST\]/);
-  });
-
-  it("handles date boundaries (just before midnight)", () => {
-    vi.setSystemTime(new Date("2026-02-01T04:59:00.000Z")); // 23:59 Jan 31 EST
-
-    const result = injectTimestamp("hello", { timezone: "America/New_York" });
-
-    expect(result).toMatch(/^\[Sat 2026-01-31 23:59 EST\]/);
-  });
-
-  it("handles DST correctly (same UTC hour, different local time)", () => {
-    // EST (winter): UTC-5 → 2026-01-15T05:00Z = midnight Jan 15
-    vi.setSystemTime(new Date("2026-01-15T05:00:00.000Z"));
-    const winter = injectTimestamp("winter", { timezone: "America/New_York" });
-    expect(winter).toMatch(/^\[Thu 2026-01-15 00:00 EST\]/);
-
-    // EDT (summer): UTC-4 → 2026-07-15T04:00Z = midnight Jul 15
-    vi.setSystemTime(new Date("2026-07-15T04:00:00.000Z"));
-    const summer = injectTimestamp("summer", { timezone: "America/New_York" });
-    expect(summer).toMatch(/^\[Wed 2026-07-15 00:00 EDT\]/);
-  });
-
-  it("accepts a custom now date", () => {
-    const customDate = new Date("2025-07-04T16:00:00.000Z"); // July 4, noon ET
-
-    const result = injectTimestamp("fireworks?", {
-      timezone: "America/New_York",
-      now: customDate,
-    });
-
-    expect(result).toMatch(/^\[Fri 2025-07-04 12:00 EDT\]/);
-  });
-});
-
-describe("timestampOptsFromConfig", () => {
-  it("extracts timezone from config", () => {
-    const opts = timestampOptsFromConfig({
-      agents: {
-        defaults: {
-          userTimezone: "America/Chicago",
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any);
-
-    expect(opts.timezone).toBe("America/Chicago");
-  });
-
-  it("falls back gracefully with empty config", () => {
-    // oxlint-disable-next-line typescript/no-explicit-any
-    const opts = timestampOptsFromConfig({} as any);
-
-    expect(opts.timezone).toBeDefined(); // resolveUserTimezone provides a default
-  });
-});
diff --git a/src/gateway/server-methods/agents-mutate.test.ts b/src/gateway/server-methods/agents-mutate.test.ts
index bd5cc5cc3cc..eb13cc1da85 100644
--- a/src/gateway/server-methods/agents-mutate.test.ts
+++ b/src/gateway/server-methods/agents-mutate.test.ts
@@ -25,6 +25,8 @@ const mocks = vi.hoisted(() => ({
   fsAccess: vi.fn(async () => {}),
   fsMkdir: vi.fn(async () => undefined),
   fsAppendFile: vi.fn(async () => {}),
+  fsReadFile: vi.fn(async () => ""),
+  fsStat: vi.fn(async () => null),
 }));
 
 vi.mock("../../config/config.js", () => ({
@@ -81,6 +83,8 @@ vi.mock("node:fs/promises", async () => {
     access: mocks.fsAccess,
     mkdir: mocks.fsMkdir,
     appendFile: mocks.fsAppendFile,
+    readFile: mocks.fsReadFile,
+    stat: mocks.fsStat,
   };
   return { ...patched, default: patched };
 });
@@ -109,6 +113,27 @@ function makeCall(method: keyof typeof agentsHandlers, params: Record<string, un
   return { respond, promise };
 }
 
+function createEnoentError() {
+  const err = new Error("ENOENT") as NodeJS.ErrnoException;
+  err.code = "ENOENT";
+  return err;
+}
+
+function createErrnoError(code: string) {
+  const err = new Error(code) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
+beforeEach(() => {
+  mocks.fsReadFile.mockImplementation(async () => {
+    throw createEnoentError();
+  });
+  mocks.fsStat.mockImplementation(async () => {
+    throw createEnoentError();
+  });
+});
+
 /* ------------------------------------------------------------------ */
 /* Tests                                                              */
 /* ------------------------------------------------------------------ */
@@ -371,3 +396,53 @@ describe("agents.delete", () => {
     );
   });
 });
+
+describe("agents.files.list", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.loadConfigReturn = {};
+  });
+
+  it("includes BOOTSTRAP.md when onboarding has not completed", async () => {
+    const { respond, promise } = makeCall("agents.files.list", { agentId: "main" });
+    await promise;
+
+    const [, result] = respond.mock.calls[0] ?? [];
+    const files = (result as { files: Array<{ name: string }> }).files;
+    expect(files.some((file) => file.name === "BOOTSTRAP.md")).toBe(true);
+  });
+
+  it("hides BOOTSTRAP.md when workspace onboarding is complete", async () => {
+    mocks.fsReadFile.mockImplementation(async (filePath: string | URL | number) => {
+      if (String(filePath).endsWith("workspace-state.json")) {
+        return JSON.stringify({
+          onboardingCompletedAt: "2026-02-15T14:00:00.000Z",
+        });
+      }
+      throw createEnoentError();
+    });
+
+    const { respond, promise } = makeCall("agents.files.list", { agentId: "main" });
+    await promise;
+
+    const [, result] = respond.mock.calls[0] ?? [];
+    const files = (result as { files: Array<{ name: string }> }).files;
+    expect(files.some((file) => file.name === "BOOTSTRAP.md")).toBe(false);
+  });
+
+  it("falls back to showing BOOTSTRAP.md when workspace state cannot be read", async () => {
+    mocks.fsReadFile.mockImplementation(async (filePath: string | URL | number) => {
+      if (String(filePath).endsWith("workspace-state.json")) {
+        throw createErrnoError("EACCES");
+      }
+      throw createEnoentError();
+    });
+
+    const { respond, promise } = makeCall("agents.files.list", { agentId: "main" });
+    await promise;
+
+    const [, result] = respond.mock.calls[0] ?? [];
+    const files = (result as { files: Array<{ name: string }> }).files;
+    expect(files.some((file) => file.name === "BOOTSTRAP.md")).toBe(true);
+  });
+});
diff --git a/src/gateway/server-methods/agents.ts b/src/gateway/server-methods/agents.ts
index eb4262e43fd..2fbb07fd96c 100644
--- a/src/gateway/server-methods/agents.ts
+++ b/src/gateway/server-methods/agents.ts
@@ -17,6 +17,7 @@ import {
   DEFAULT_TOOLS_FILENAME,
   DEFAULT_USER_FILENAME,
   ensureAgentWorkspace,
+  isWorkspaceOnboardingCompleted,
 } from "../../agents/workspace.js";
 import { movePathToTrash } from "../../browser/trash.js";
 import {
@@ -52,6 +53,9 @@ const BOOTSTRAP_FILE_NAMES = [
   DEFAULT_HEARTBEAT_FILENAME,
   DEFAULT_BOOTSTRAP_FILENAME,
 ] as const;
+const BOOTSTRAP_FILE_NAMES_POST_ONBOARDING = BOOTSTRAP_FILE_NAMES.filter(
+  (name) => name !== DEFAULT_BOOTSTRAP_FILENAME,
+);
 
 const MEMORY_FILE_NAMES = [DEFAULT_MEMORY_FILENAME, DEFAULT_MEMORY_ALT_FILENAME] as const;
 
@@ -108,7 +112,7 @@ async function statFile(filePath: string): Promise<FileMeta | null> {
   }
 }
 
-async function listAgentFiles(workspaceDir: string) {
+async function listAgentFiles(workspaceDir: string, options?: { hideBootstrap?: boolean }) {
   const files: Array<{
     name: string;
     path: string;
@@ -117,7 +121,10 @@ async function listAgentFiles(workspaceDir: string) {
     updatedAtMs?: number;
   }> = [];
 
-  for (const name of BOOTSTRAP_FILE_NAMES) {
+  const bootstrapFileNames = options?.hideBootstrap
+    ? BOOTSTRAP_FILE_NAMES_POST_ONBOARDING
+    : BOOTSTRAP_FILE_NAMES;
+  for (const name of bootstrapFileNames) {
     const filePath = path.join(workspaceDir, name);
     const meta = await statFile(filePath);
     if (meta) {
@@ -417,7 +424,13 @@ export const agentsHandlers: GatewayRequestHandlers = {
       return;
     }
     const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
-    const files = await listAgentFiles(workspaceDir);
+    let hideBootstrap = false;
+    try {
+      hideBootstrap = await isWorkspaceOnboardingCompleted(workspaceDir);
+    } catch {
+      // Fall back to showing BOOTSTRAP if workspace state cannot be read.
+    }
+    const files = await listAgentFiles(workspaceDir, { hideBootstrap });
     respond(true, { agentId, workspace: workspaceDir, files }, undefined);
   },
   "agents.files.get": async ({ params, respond }) => {
diff --git a/src/gateway/server-methods/attachment-normalize.test.ts b/src/gateway/server-methods/attachment-normalize.test.ts
deleted file mode 100644
index 159bae80492..00000000000
--- a/src/gateway/server-methods/attachment-normalize.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeRpcAttachmentsToChatAttachments } from "./attachment-normalize.js";
-
-describe("normalizeRpcAttachmentsToChatAttachments", () => {
-  it("passes through string content", () => {
-    const res = normalizeRpcAttachmentsToChatAttachments([
-      { type: "file", mimeType: "image/png", fileName: "a.png", content: "Zm9v" },
-    ]);
-    expect(res).toEqual([
-      { type: "file", mimeType: "image/png", fileName: "a.png", content: "Zm9v" },
-    ]);
-  });
-
-  it("converts Uint8Array content to base64", () => {
-    const bytes = new TextEncoder().encode("foo");
-    const res = normalizeRpcAttachmentsToChatAttachments([{ content: bytes }]);
-    expect(res[0]?.content).toBe("Zm9v");
-  });
-});
diff --git a/src/gateway/server-methods/base-hash.ts b/src/gateway/server-methods/base-hash.ts
new file mode 100644
index 00000000000..c4c3db54580
--- /dev/null
+++ b/src/gateway/server-methods/base-hash.ts
@@ -0,0 +1,8 @@
+export function resolveBaseHashParam(params: unknown): string | null {
+  const raw = (params as { baseHash?: unknown })?.baseHash;
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed ? trimmed : null;
+}
diff --git a/src/gateway/server-methods/browser.ts b/src/gateway/server-methods/browser.ts
index 80e13e7ec00..a2624327764 100644
--- a/src/gateway/server-methods/browser.ts
+++ b/src/gateway/server-methods/browser.ts
@@ -10,7 +10,7 @@ import { createBrowserRouteDispatcher } from "../../browser/routes/dispatcher.js
 import { loadConfig } from "../../config/config.js";
 import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
 import { ErrorCodes, errorShape } from "../protocol/index.js";
-import { safeParseJson } from "./nodes.helpers.js";
+import { respondUnavailableOnNodeInvokeError, safeParseJson } from "./nodes.helpers.js";
 
 type BrowserRequestParams = {
   method?: string;
@@ -194,14 +194,7 @@ export const browserHandlers: GatewayRequestHandlers = {
         timeoutMs,
         idempotencyKey: crypto.randomUUID(),
       });
-      if (!res.ok) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-            details: { nodeError: res.error ?? null },
-          }),
-        );
+      if (!respondUnavailableOnNodeInvokeError(respond, res)) {
         return;
       }
       const payload = res.payloadJSON ? safeParseJson(res.payloadJSON) : res.payload;
diff --git a/src/gateway/server-methods/chat.abort-persistence.test.ts b/src/gateway/server-methods/chat.abort-persistence.test.ts
new file mode 100644
index 00000000000..bee1382e073
--- /dev/null
+++ b/src/gateway/server-methods/chat.abort-persistence.test.ts
@@ -0,0 +1,259 @@
+import { CURRENT_SESSION_VERSION } from "@mariozechner/pi-coding-agent";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+type TranscriptLine = {
+  message?: Record<string, unknown>;
+};
+
+const sessionEntryState = vi.hoisted(() => ({
+  transcriptPath: "",
+  sessionId: "",
+}));
+
+vi.mock("../session-utils.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../session-utils.js")>();
+  return {
+    ...original,
+    loadSessionEntry: () => ({
+      cfg: {},
+      storePath: path.join(path.dirname(sessionEntryState.transcriptPath), "sessions.json"),
+      entry: {
+        sessionId: sessionEntryState.sessionId,
+        sessionFile: sessionEntryState.transcriptPath,
+      },
+      canonicalKey: "main",
+    }),
+  };
+});
+
+const { chatHandlers } = await import("./chat.js");
+
+function createActiveRun(sessionKey: string, sessionId: string) {
+  const now = Date.now();
+  return {
+    controller: new AbortController(),
+    sessionId,
+    sessionKey,
+    startedAtMs: now,
+    expiresAtMs: now + 30_000,
+  };
+}
+
+async function writeTranscriptHeader(transcriptPath: string, sessionId: string) {
+  const header = {
+    type: "session",
+    version: CURRENT_SESSION_VERSION,
+    id: sessionId,
+    timestamp: new Date(0).toISOString(),
+    cwd: "/tmp",
+  };
+  await fs.writeFile(transcriptPath, `${JSON.stringify(header)}\n`, "utf-8");
+}
+
+async function readTranscriptLines(transcriptPath: string): Promise<TranscriptLine[]> {
+  const raw = await fs.readFile(transcriptPath, "utf-8");
+  return raw
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as TranscriptLine;
+      } catch {
+        return {};
+      }
+    });
+}
+
+function setMockSessionEntry(transcriptPath: string, sessionId: string) {
+  sessionEntryState.transcriptPath = transcriptPath;
+  sessionEntryState.sessionId = sessionId;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("chat abort transcript persistence", () => {
+  it("persists run-scoped abort partial with rpc metadata and idempotency", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chat-abort-run-"));
+    const transcriptPath = path.join(dir, "sess-main.jsonl");
+    const sessionId = "sess-main";
+    const runId = "idem-abort-run-1";
+    await writeTranscriptHeader(transcriptPath, sessionId);
+
+    setMockSessionEntry(transcriptPath, sessionId);
+    const respond = vi.fn();
+    const context = {
+      chatAbortControllers: new Map([[runId, createActiveRun("main", sessionId)]]),
+      chatRunBuffers: new Map([[runId, "Partial from run abort"]]),
+      chatDeltaSentAt: new Map([[runId, Date.now()]]),
+      chatAbortedRuns: new Map<string, number>(),
+      removeChatRun: vi
+        .fn()
+        .mockReturnValue({ sessionKey: "main", clientRunId: "client-idem-abort-run-1" }),
+      agentRunSeq: new Map<string, number>([
+        [runId, 2],
+        ["client-idem-abort-run-1", 3],
+      ]),
+      broadcast: vi.fn(),
+      nodeSendToSession: vi.fn(),
+      logGateway: { warn: vi.fn() },
+    };
+
+    await chatHandlers["chat.abort"]({
+      params: { sessionKey: "main", runId },
+      respond,
+      context: context as never,
+    });
+
+    const [ok1, payload1] = respond.mock.calls.at(-1) ?? [];
+    expect(ok1).toBe(true);
+    expect(payload1).toMatchObject({ aborted: true, runIds: [runId] });
+
+    context.chatAbortControllers.set(runId, createActiveRun("main", sessionId));
+    context.chatRunBuffers.set(runId, "Partial from run abort");
+    context.chatDeltaSentAt.set(runId, Date.now());
+
+    await chatHandlers["chat.abort"]({
+      params: { sessionKey: "main", runId },
+      respond,
+      context: context as never,
+    });
+
+    const lines = await readTranscriptLines(transcriptPath);
+    const persisted = lines
+      .map((line) => line.message)
+      .filter(
+        (message): message is Record<string, unknown> =>
+          Boolean(message) && message?.idempotencyKey === `${runId}:assistant`,
+      );
+
+    expect(persisted).toHaveLength(1);
+    expect(persisted[0]).toMatchObject({
+      stopReason: "stop",
+      idempotencyKey: `${runId}:assistant`,
+      openclawAbort: {
+        aborted: true,
+        origin: "rpc",
+        runId,
+      },
+    });
+  });
+
+  it("persists session-scoped abort partials with rpc metadata", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chat-abort-session-"));
+    const transcriptPath = path.join(dir, "sess-main.jsonl");
+    const sessionId = "sess-main";
+    await writeTranscriptHeader(transcriptPath, sessionId);
+
+    setMockSessionEntry(transcriptPath, sessionId);
+    const respond = vi.fn();
+    const context = {
+      chatAbortControllers: new Map([
+        ["run-a", createActiveRun("main", sessionId)],
+        ["run-b", createActiveRun("main", sessionId)],
+      ]),
+      chatRunBuffers: new Map([
+        ["run-a", "Session abort partial"],
+        ["run-b", "   "],
+      ]),
+      chatDeltaSentAt: new Map([
+        ["run-a", Date.now()],
+        ["run-b", Date.now()],
+      ]),
+      chatAbortedRuns: new Map<string, number>(),
+      removeChatRun: vi
+        .fn()
+        .mockImplementation((run: string) => ({ sessionKey: "main", clientRunId: run })),
+      agentRunSeq: new Map<string, number>(),
+      broadcast: vi.fn(),
+      nodeSendToSession: vi.fn(),
+      logGateway: { warn: vi.fn() },
+    };
+
+    await chatHandlers["chat.abort"]({
+      params: { sessionKey: "main" },
+      respond,
+      context: context as never,
+    });
+
+    const [ok, payload] = respond.mock.calls.at(-1) ?? [];
+    expect(ok).toBe(true);
+    expect(payload).toMatchObject({ aborted: true });
+    expect(payload.runIds).toEqual(expect.arrayContaining(["run-a", "run-b"]));
+
+    const lines = await readTranscriptLines(transcriptPath);
+    const runAPersisted = lines
+      .map((line) => line.message)
+      .find((message) => message?.idempotencyKey === "run-a:assistant");
+    const runBPersisted = lines
+      .map((line) => line.message)
+      .find((message) => message?.idempotencyKey === "run-b:assistant");
+
+    expect(runAPersisted).toMatchObject({
+      idempotencyKey: "run-a:assistant",
+      openclawAbort: {
+        aborted: true,
+        origin: "rpc",
+        runId: "run-a",
+      },
+    });
+    expect(runBPersisted).toBeUndefined();
+  });
+
+  it("persists /stop partials with stop-command metadata", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chat-stop-"));
+    const transcriptPath = path.join(dir, "sess-main.jsonl");
+    const sessionId = "sess-main";
+    await writeTranscriptHeader(transcriptPath, sessionId);
+
+    setMockSessionEntry(transcriptPath, sessionId);
+    const respond = vi.fn();
+    const context = {
+      chatAbortControllers: new Map([["run-stop-1", createActiveRun("main", sessionId)]]),
+      chatRunBuffers: new Map([["run-stop-1", "Partial from /stop"]]),
+      chatDeltaSentAt: new Map([["run-stop-1", Date.now()]]),
+      chatAbortedRuns: new Map<string, number>(),
+      removeChatRun: vi.fn().mockReturnValue({ sessionKey: "main", clientRunId: "client-stop-1" }),
+      agentRunSeq: new Map<string, number>([["run-stop-1", 1]]),
+      broadcast: vi.fn(),
+      nodeSendToSession: vi.fn(),
+      logGateway: { warn: vi.fn() },
+      dedupe: {
+        get: vi.fn(),
+      },
+    };
+
+    await chatHandlers["chat.send"]({
+      params: {
+        sessionKey: "main",
+        message: "/stop",
+        idempotencyKey: "idem-stop-req",
+      },
+      respond,
+      context: context as never,
+      client: undefined,
+    });
+
+    const [ok, payload] = respond.mock.calls.at(-1) ?? [];
+    expect(ok).toBe(true);
+    expect(payload).toMatchObject({ aborted: true, runIds: ["run-stop-1"] });
+
+    const lines = await readTranscriptLines(transcriptPath);
+    const persisted = lines
+      .map((line) => line.message)
+      .find((message) => message?.idempotencyKey === "run-stop-1:assistant");
+
+    expect(persisted).toMatchObject({
+      idempotencyKey: "run-stop-1:assistant",
+      openclawAbort: {
+        aborted: true,
+        origin: "stop-command",
+        runId: "run-stop-1",
+      },
+    });
+  });
+});
diff --git a/src/gateway/server-methods/chat.sanitize-message.test.ts b/src/gateway/server-methods/chat.sanitize-message.test.ts
deleted file mode 100644
index dd41d4c883e..00000000000
--- a/src/gateway/server-methods/chat.sanitize-message.test.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { sanitizeChatSendMessageInput } from "./chat.js";
-
-describe("sanitizeChatSendMessageInput", () => {
-  it("rejects null bytes", () => {
-    expect(sanitizeChatSendMessageInput("before\u0000after")).toEqual({
-      ok: false,
-      error: "message must not contain null bytes",
-    });
-  });
-
-  it("strips unsafe control characters while preserving tab/newline/carriage return", () => {
-    const result = sanitizeChatSendMessageInput("a\u0001b\tc\nd\re\u0007f\u007f");
-    expect(result).toEqual({ ok: true, message: "ab\tc\nd\ref" });
-  });
-
-  it("normalizes unicode to NFC", () => {
-    expect(sanitizeChatSendMessageInput("Cafe\u0301")).toEqual({ ok: true, message: "Café" });
-  });
-});
diff --git a/src/gateway/server-methods/chat.transcript-writes.guardrail.test.ts b/src/gateway/server-methods/chat.transcript-writes.guardrail.test.ts
deleted file mode 100644
index d6b098dc28f..00000000000
--- a/src/gateway/server-methods/chat.transcript-writes.guardrail.test.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import fs from "node:fs";
-import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
-
-// Guardrail: the "empty post-compaction context" regression came from gateway code appending
-// Pi transcript message entries as raw JSONL without `parentId`.
-//
-// This test is intentionally simple and file-local: if someone reintroduces direct JSONL appends
-// against `transcriptPath`, Pi's SessionManager parent chain can break again.
-describe("gateway chat transcript writes (guardrail)", () => {
-  it("does not append transcript messages via raw fs.appendFileSync(transcriptPath, ...)", () => {
-    const chatTs = fileURLToPath(new URL("./chat.ts", import.meta.url));
-    const src = fs.readFileSync(chatTs, "utf-8");
-
-    // Disallow raw appends against the resolved transcript path variable.
-    // (The transcript header creation via writeFileSync is OK; the bug class is raw message appends.)
-    expect(src.includes("fs.appendFileSync(transcriptPath")).toBe(false);
-
-    // Ensure we keep using SessionManager for transcript message appends.
-    expect(src).toContain("SessionManager.open(transcriptPath)");
-    expect(src).toContain("appendMessage(");
-  });
-});
diff --git a/src/gateway/server-methods/chat.ts b/src/gateway/server-methods/chat.ts
index 52225dc0bb7..55b0d97dc6b 100644
--- a/src/gateway/server-methods/chat.ts
+++ b/src/gateway/server-methods/chat.ts
@@ -15,6 +15,8 @@ import { INTERNAL_MESSAGE_CHANNEL } from "../../utils/message-channel.js";
 import {
   abortChatRunById,
   abortChatRunsForSessionKey,
+  type ChatAbortControllerEntry,
+  type ChatAbortOps,
   isChatStopCommandText,
   resolveChatRunExpiresAtMs,
 } from "../chat-abort.js";
@@ -49,6 +51,14 @@ type TranscriptAppendResult = {
 };
 
 type AppendMessageArg = Parameters<SessionManager["appendMessage"]>[0];
+type AbortOrigin = "rpc" | "stop-command";
+
+type AbortedPartialSnapshot = {
+  runId: string;
+  sessionId: string;
+  text: string;
+  abortOrigin: AbortOrigin;
+};
 
 function stripDisallowedChatControlChars(message: string): string {
   let output = "";
@@ -116,6 +126,24 @@ function ensureTranscriptFile(params: { transcriptPath: string; sessionId: strin
   }
 }
 
+function transcriptHasIdempotencyKey(transcriptPath: string, idempotencyKey: string): boolean {
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf-8").split(/\r?\n/);
+    for (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+      const parsed = JSON.parse(line) as { message?: { idempotencyKey?: unknown } };
+      if (parsed?.message?.idempotencyKey === idempotencyKey) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 function appendAssistantTranscriptMessage(params: {
   message: string;
   label?: string;
@@ -124,6 +152,12 @@ function appendAssistantTranscriptMessage(params: {
   sessionFile?: string;
   agentId?: string;
   createIfMissing?: boolean;
+  idempotencyKey?: string;
+  abortMeta?: {
+    aborted: true;
+    origin: AbortOrigin;
+    runId: string;
+  };
 }): TranscriptAppendResult {
   const transcriptPath = resolveTranscriptPath({
     sessionId: params.sessionId,
@@ -148,6 +182,10 @@ function appendAssistantTranscriptMessage(params: {
     }
   }
 
+  if (params.idempotencyKey && transcriptHasIdempotencyKey(transcriptPath, params.idempotencyKey)) {
+    return { ok: true };
+  }
+
   const now = Date.now();
   const labelPrefix = params.label ? `[${params.label}]\n\n` : "";
   const usage = {
@@ -176,6 +214,16 @@ function appendAssistantTranscriptMessage(params: {
     api: "openai-responses",
     provider: "openclaw",
     model: "gateway-injected",
+    ...(params.idempotencyKey ? { idempotencyKey: params.idempotencyKey } : {}),
+    ...(params.abortMeta
+      ? {
+          openclawAbort: {
+            aborted: true,
+            origin: params.abortMeta.origin,
+            runId: params.abortMeta.runId,
+          },
+        }
+      : {}),
   };
 
   try {
@@ -189,6 +237,103 @@ function appendAssistantTranscriptMessage(params: {
   }
 }
 
+function collectSessionAbortPartials(params: {
+  chatAbortControllers: Map<string, ChatAbortControllerEntry>;
+  chatRunBuffers: Map<string, string>;
+  sessionKey: string;
+  abortOrigin: AbortOrigin;
+}): AbortedPartialSnapshot[] {
+  const out: AbortedPartialSnapshot[] = [];
+  for (const [runId, active] of params.chatAbortControllers) {
+    if (active.sessionKey !== params.sessionKey) {
+      continue;
+    }
+    const text = params.chatRunBuffers.get(runId);
+    if (!text || !text.trim()) {
+      continue;
+    }
+    out.push({
+      runId,
+      sessionId: active.sessionId,
+      text,
+      abortOrigin: params.abortOrigin,
+    });
+  }
+  return out;
+}
+
+function persistAbortedPartials(params: {
+  context: Pick<GatewayRequestContext, "logGateway">;
+  sessionKey: string;
+  snapshots: AbortedPartialSnapshot[];
+}) {
+  if (params.snapshots.length === 0) {
+    return;
+  }
+  const { storePath, entry } = loadSessionEntry(params.sessionKey);
+  for (const snapshot of params.snapshots) {
+    const sessionId = entry?.sessionId ?? snapshot.sessionId ?? snapshot.runId;
+    const appended = appendAssistantTranscriptMessage({
+      message: snapshot.text,
+      sessionId,
+      storePath,
+      sessionFile: entry?.sessionFile,
+      createIfMissing: true,
+      idempotencyKey: `${snapshot.runId}:assistant`,
+      abortMeta: {
+        aborted: true,
+        origin: snapshot.abortOrigin,
+        runId: snapshot.runId,
+      },
+    });
+    if (!appended.ok) {
+      params.context.logGateway.warn(
+        `chat.abort transcript append failed: ${appended.error ?? "unknown error"}`,
+      );
+    }
+  }
+}
+
+function createChatAbortOps(context: GatewayRequestContext): ChatAbortOps {
+  return {
+    chatAbortControllers: context.chatAbortControllers,
+    chatRunBuffers: context.chatRunBuffers,
+    chatDeltaSentAt: context.chatDeltaSentAt,
+    chatAbortedRuns: context.chatAbortedRuns,
+    removeChatRun: context.removeChatRun,
+    agentRunSeq: context.agentRunSeq,
+    broadcast: context.broadcast,
+    nodeSendToSession: context.nodeSendToSession,
+  };
+}
+
+function abortChatRunsForSessionKeyWithPartials(params: {
+  context: GatewayRequestContext;
+  ops: ChatAbortOps;
+  sessionKey: string;
+  abortOrigin: AbortOrigin;
+  stopReason?: string;
+}) {
+  const snapshots = collectSessionAbortPartials({
+    chatAbortControllers: params.context.chatAbortControllers,
+    chatRunBuffers: params.context.chatRunBuffers,
+    sessionKey: params.sessionKey,
+    abortOrigin: params.abortOrigin,
+  });
+  const res = abortChatRunsForSessionKey(params.ops, {
+    sessionKey: params.sessionKey,
+    stopReason: params.stopReason,
+  });
+  if (res.aborted) {
+    persistAbortedPartials({
+      context: params.context,
+      sessionKey: params.sessionKey,
+      snapshots,
+    });
+  }
+  return res;
+}
+
 function nextChatSeq(context: { agentRunSeq: Map<string, number> }, runId: string) {
   const next = (context.agentRunSeq.get(runId) ?? 0) + 1;
   context.agentRunSeq.set(runId, next);
@@ -299,25 +444,19 @@ export const chatHandlers: GatewayRequestHandlers = {
       );
       return;
     }
-    const { sessionKey, runId } = params as {
+    const { sessionKey: rawSessionKey, runId } = params as {
       sessionKey: string;
       runId?: string;
     };
 
-    const ops = {
-      chatAbortControllers: context.chatAbortControllers,
-      chatRunBuffers: context.chatRunBuffers,
-      chatDeltaSentAt: context.chatDeltaSentAt,
-      chatAbortedRuns: context.chatAbortedRuns,
-      removeChatRun: context.removeChatRun,
-      agentRunSeq: context.agentRunSeq,
-      broadcast: context.broadcast,
-      nodeSendToSession: context.nodeSendToSession,
-    };
+    const ops = createChatAbortOps(context);
 
     if (!runId) {
-      const res = abortChatRunsForSessionKey(ops, {
-        sessionKey,
+      const res = abortChatRunsForSessionKeyWithPartials({
+        context,
+        ops,
+        sessionKey: rawSessionKey,
+        abortOrigin: "rpc",
         stopReason: "rpc",
       });
       respond(true, { ok: true, aborted: res.aborted, runIds: res.runIds });
@@ -329,7 +468,7 @@ export const chatHandlers: GatewayRequestHandlers = {
       respond(true, { ok: true, aborted: false, runIds: [] });
       return;
     }
-    if (active.sessionKey !== sessionKey) {
+    if (active.sessionKey !== rawSessionKey) {
       respond(
         false,
         undefined,
@@ -338,11 +477,26 @@ export const chatHandlers: GatewayRequestHandlers = {
       return;
     }
 
+    const partialText = context.chatRunBuffers.get(runId);
     const res = abortChatRunById(ops, {
       runId,
-      sessionKey,
+      sessionKey: rawSessionKey,
       stopReason: "rpc",
     });
+    if (res.aborted && partialText && partialText.trim()) {
+      persistAbortedPartials({
+        context,
+        sessionKey: rawSessionKey,
+        snapshots: [
+          {
+            runId,
+            sessionId: active.sessionId,
+            text: partialText,
+            abortOrigin: "rpc",
+          },
+        ],
+      });
+    }
     respond(true, {
       ok: true,
       aborted: res.aborted,
@@ -437,19 +591,13 @@ export const chatHandlers: GatewayRequestHandlers = {
     }
 
     if (stopCommand) {
-      const res = abortChatRunsForSessionKey(
-        {
-          chatAbortControllers: context.chatAbortControllers,
-          chatRunBuffers: context.chatRunBuffers,
-          chatDeltaSentAt: context.chatDeltaSentAt,
-          chatAbortedRuns: context.chatAbortedRuns,
-          removeChatRun: context.removeChatRun,
-          agentRunSeq: context.agentRunSeq,
-          broadcast: context.broadcast,
-          nodeSendToSession: context.nodeSendToSession,
-        },
-        { sessionKey: rawSessionKey, stopReason: "stop" },
-      );
+      const res = abortChatRunsForSessionKeyWithPartials({
+        context,
+        ops: createChatAbortOps(context),
+        sessionKey: rawSessionKey,
+        abortOrigin: "stop-command",
+        stopReason: "stop",
+      });
       respond(true, { ok: true, aborted: res.aborted, runIds: res.runIds });
       return;
     }
diff --git a/src/gateway/server-methods/config.ts b/src/gateway/server-methods/config.ts
index 9fb740e99ce..e0bc6c89164 100644
--- a/src/gateway/server-methods/config.ts
+++ b/src/gateway/server-methods/config.ts
@@ -31,22 +31,15 @@ import { loadOpenClawPlugins } from "../../plugins/loader.js";
 import {
   ErrorCodes,
   errorShape,
-  formatValidationErrors,
   validateConfigApplyParams,
   validateConfigGetParams,
   validateConfigPatchParams,
   validateConfigSchemaParams,
   validateConfigSetParams,
 } from "../protocol/index.js";
-
-function resolveBaseHash(params: unknown): string | null {
-  const raw = (params as { baseHash?: unknown })?.baseHash;
-  if (typeof raw !== "string") {
-    return null;
-  }
-  const trimmed = raw.trim();
-  return trimmed ? trimmed : null;
-}
+import { resolveBaseHashParam } from "./base-hash.js";
+import { parseRestartRequestParams } from "./restart-request.js";
+import { assertValidParams } from "./validation.js";
 
 function requireConfigBaseHash(
   params: unknown,
@@ -68,7 +61,7 @@ function requireConfigBaseHash(
     );
     return false;
   }
-  const baseHash = resolveBaseHash(params);
+  const baseHash = resolveBaseHashParam(params);
   if (!baseHash) {
     respond(
       false,
@@ -160,19 +153,7 @@ function resolveConfigRestartRequest(params: unknown): {
   deliveryContext: ReturnType<typeof extractDeliveryInfo>["deliveryContext"];
   threadId: ReturnType<typeof extractDeliveryInfo>["threadId"];
 } {
-  const sessionKey =
-    typeof (params as { sessionKey?: unknown }).sessionKey === "string"
-      ? (params as { sessionKey?: string }).sessionKey?.trim() || undefined
-      : undefined;
-  const note =
-    typeof (params as { note?: unknown }).note === "string"
-      ? (params as { note?: string }).note?.trim() || undefined
-      : undefined;
-  const restartDelayMsRaw = (params as { restartDelayMs?: unknown }).restartDelayMs;
-  const restartDelayMs =
-    typeof restartDelayMsRaw === "number" && Number.isFinite(restartDelayMsRaw)
-      ? Math.max(0, Math.floor(restartDelayMsRaw))
-      : undefined;
+  const { sessionKey, note, restartDelayMs } = parseRestartRequestParams(params);
 
   // Extract deliveryContext + threadId for routing after restart
   // Supports both :thread: (most channels) and :topic: (Telegram)
@@ -258,15 +239,7 @@ function loadSchemaWithPlugins(): ConfigSchemaResponse {
 
 export const configHandlers: GatewayRequestHandlers = {
   "config.get": async ({ params, respond }) => {
-    if (!validateConfigGetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid config.get params: ${formatValidationErrors(validateConfigGetParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateConfigGetParams, "config.get", respond)) {
       return;
     }
     const snapshot = await readConfigFileSnapshot();
@@ -274,29 +247,13 @@ export const configHandlers: GatewayRequestHandlers = {
     respond(true, redactConfigSnapshot(snapshot, schema.uiHints), undefined);
   },
   "config.schema": ({ params, respond }) => {
-    if (!validateConfigSchemaParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid config.schema params: ${formatValidationErrors(validateConfigSchemaParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateConfigSchemaParams, "config.schema", respond)) {
       return;
     }
     respond(true, loadSchemaWithPlugins(), undefined);
   },
   "config.set": async ({ params, respond }) => {
-    if (!validateConfigSetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid config.set params: ${formatValidationErrors(validateConfigSetParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateConfigSetParams, "config.set", respond)) {
       return;
     }
     const { snapshot, writeOptions } = await readConfigFileSnapshotForWrite();
@@ -319,15 +276,7 @@ export const configHandlers: GatewayRequestHandlers = {
     );
   },
   "config.patch": async ({ params, respond }) => {
-    if (!validateConfigPatchParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid config.patch params: ${formatValidationErrors(validateConfigPatchParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateConfigPatchParams, "config.patch", respond)) {
       return;
     }
     const { snapshot, writeOptions } = await readConfigFileSnapshotForWrite();
@@ -433,15 +382,7 @@ export const configHandlers: GatewayRequestHandlers = {
     );
   },
   "config.apply": async ({ params, respond }) => {
-    if (!validateConfigApplyParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid config.apply params: ${formatValidationErrors(validateConfigApplyParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateConfigApplyParams, "config.apply", respond)) {
       return;
     }
     const { snapshot, writeOptions } = await readConfigFileSnapshotForWrite();
diff --git a/src/gateway/server-methods/exec-approval.test.ts b/src/gateway/server-methods/exec-approval.test.ts
deleted file mode 100644
index ac0373343b0..00000000000
--- a/src/gateway/server-methods/exec-approval.test.ts
+++ /dev/null
@@ -1,285 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { ExecApprovalManager } from "../exec-approval-manager.js";
-import { validateExecApprovalRequestParams } from "../protocol/index.js";
-import { createExecApprovalHandlers } from "./exec-approval.js";
-
-const noop = () => {};
-
-describe("exec approval handlers", () => {
-  describe("ExecApprovalRequestParams validation", () => {
-    it("accepts request with resolvedPath omitted", () => {
-      const params = {
-        command: "echo hi",
-        cwd: "/tmp",
-        host: "node",
-      };
-      expect(validateExecApprovalRequestParams(params)).toBe(true);
-    });
-
-    it("accepts request with resolvedPath as string", () => {
-      const params = {
-        command: "echo hi",
-        cwd: "/tmp",
-        host: "node",
-        resolvedPath: "/usr/bin/echo",
-      };
-      expect(validateExecApprovalRequestParams(params)).toBe(true);
-    });
-
-    it("accepts request with resolvedPath as undefined", () => {
-      const params = {
-        command: "echo hi",
-        cwd: "/tmp",
-        host: "node",
-        resolvedPath: undefined,
-      };
-      expect(validateExecApprovalRequestParams(params)).toBe(true);
-    });
-
-    // Fixed: null is now accepted (Type.Union([Type.String(), Type.Null()]))
-    // This matches the calling code in bash-tools.exec.ts which passes null.
-    it("accepts request with resolvedPath as null", () => {
-      const params = {
-        command: "echo hi",
-        cwd: "/tmp",
-        host: "node",
-        resolvedPath: null,
-      };
-      expect(validateExecApprovalRequestParams(params)).toBe(true);
-    });
-  });
-
-  it("broadcasts request + resolve", async () => {
-    const manager = new ExecApprovalManager();
-    const handlers = createExecApprovalHandlers(manager);
-    const broadcasts: Array<{ event: string; payload: unknown }> = [];
-
-    const respond = vi.fn();
-    const context = {
-      broadcast: (event: string, payload: unknown) => {
-        broadcasts.push({ event, payload });
-      },
-    };
-
-    const requestPromise = handlers["exec.approval.request"]({
-      params: {
-        command: "echo ok",
-        cwd: "/tmp",
-        host: "node",
-        timeoutMs: 2000,
-        twoPhase: true,
-      },
-      respond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.request"]
-      >[0]["context"],
-      client: null,
-      req: { id: "req-1", type: "req", method: "exec.approval.request" },
-      isWebchatConnect: noop,
-    });
-
-    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
-    expect(requested).toBeTruthy();
-    const id = (requested?.payload as { id?: string })?.id ?? "";
-    expect(id).not.toBe("");
-
-    // First response should be "accepted" (registration confirmation)
-    expect(respond).toHaveBeenCalledWith(
-      true,
-      expect.objectContaining({ status: "accepted", id }),
-      undefined,
-    );
-
-    const resolveRespond = vi.fn();
-    await handlers["exec.approval.resolve"]({
-      params: { id, decision: "allow-once" },
-      respond: resolveRespond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.resolve"]
-      >[0]["context"],
-      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
-      req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
-      isWebchatConnect: noop,
-    });
-
-    await requestPromise;
-
-    expect(resolveRespond).toHaveBeenCalledWith(true, { ok: true }, undefined);
-    // Second response should contain the decision
-    expect(respond).toHaveBeenCalledWith(
-      true,
-      expect.objectContaining({ id, decision: "allow-once" }),
-      undefined,
-    );
-    expect(broadcasts.some((entry) => entry.event === "exec.approval.resolved")).toBe(true);
-  });
-
-  it("accepts resolve during broadcast", async () => {
-    const manager = new ExecApprovalManager();
-    const handlers = createExecApprovalHandlers(manager);
-    const respond = vi.fn();
-    const resolveRespond = vi.fn();
-
-    const resolveContext = {
-      broadcast: () => {},
-    };
-
-    const context = {
-      broadcast: (event: string, payload: unknown) => {
-        if (event !== "exec.approval.requested") {
-          return;
-        }
-        const id = (payload as { id?: string })?.id ?? "";
-        void handlers["exec.approval.resolve"]({
-          params: { id, decision: "allow-once" },
-          respond: resolveRespond,
-          context: resolveContext as unknown as Parameters<
-            (typeof handlers)["exec.approval.resolve"]
-          >[0]["context"],
-          client: { connect: { client: { id: "cli", displayName: "CLI" } } },
-          req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
-          isWebchatConnect: noop,
-        });
-      },
-    };
-
-    await handlers["exec.approval.request"]({
-      params: {
-        command: "echo ok",
-        cwd: "/tmp",
-        host: "node",
-        timeoutMs: 2000,
-      },
-      respond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.request"]
-      >[0]["context"],
-      client: null,
-      req: { id: "req-1", type: "req", method: "exec.approval.request" },
-      isWebchatConnect: noop,
-    });
-
-    expect(resolveRespond).toHaveBeenCalledWith(true, { ok: true }, undefined);
-    expect(respond).toHaveBeenCalledWith(
-      true,
-      expect.objectContaining({ decision: "allow-once" }),
-      undefined,
-    );
-  });
-
-  it("accepts explicit approval ids", async () => {
-    const manager = new ExecApprovalManager();
-    const handlers = createExecApprovalHandlers(manager);
-    const broadcasts: Array<{ event: string; payload: unknown }> = [];
-
-    const respond = vi.fn();
-    const context = {
-      broadcast: (event: string, payload: unknown) => {
-        broadcasts.push({ event, payload });
-      },
-    };
-
-    const requestPromise = handlers["exec.approval.request"]({
-      params: {
-        id: "approval-123",
-        command: "echo ok",
-        cwd: "/tmp",
-        host: "gateway",
-        timeoutMs: 2000,
-      },
-      respond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.request"]
-      >[0]["context"],
-      client: null,
-      req: { id: "req-1", type: "req", method: "exec.approval.request" },
-      isWebchatConnect: noop,
-    });
-
-    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
-    const id = (requested?.payload as { id?: string })?.id ?? "";
-    expect(id).toBe("approval-123");
-
-    const resolveRespond = vi.fn();
-    await handlers["exec.approval.resolve"]({
-      params: { id, decision: "allow-once" },
-      respond: resolveRespond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.resolve"]
-      >[0]["context"],
-      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
-      req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
-      isWebchatConnect: noop,
-    });
-
-    await requestPromise;
-    expect(respond).toHaveBeenCalledWith(
-      true,
-      expect.objectContaining({ id: "approval-123", decision: "allow-once" }),
-      undefined,
-    );
-  });
-
-  it("rejects duplicate approval ids", async () => {
-    const manager = new ExecApprovalManager();
-    const handlers = createExecApprovalHandlers(manager);
-    const respondA = vi.fn();
-    const respondB = vi.fn();
-    const broadcasts: Array<{ event: string; payload: unknown }> = [];
-    const context = {
-      broadcast: (event: string, payload: unknown) => {
-        broadcasts.push({ event, payload });
-      },
-    };
-
-    const requestPromise = handlers["exec.approval.request"]({
-      params: {
-        id: "dup-1",
-        command: "echo ok",
-      },
-      respond: respondA,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.request"]
-      >[0]["context"],
-      client: null,
-      req: { id: "req-1", type: "req", method: "exec.approval.request" },
-      isWebchatConnect: noop,
-    });
-
-    await handlers["exec.approval.request"]({
-      params: {
-        id: "dup-1",
-        command: "echo again",
-      },
-      respond: respondB,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.request"]
-      >[0]["context"],
-      client: null,
-      req: { id: "req-2", type: "req", method: "exec.approval.request" },
-      isWebchatConnect: noop,
-    });
-
-    expect(respondB).toHaveBeenCalledWith(
-      false,
-      undefined,
-      expect.objectContaining({ message: "approval id already pending" }),
-    );
-
-    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
-    const id = (requested?.payload as { id?: string })?.id ?? "";
-    const resolveRespond = vi.fn();
-    await handlers["exec.approval.resolve"]({
-      params: { id, decision: "deny" },
-      respond: resolveRespond,
-      context: context as unknown as Parameters<
-        (typeof handlers)["exec.approval.resolve"]
-      >[0]["context"],
-      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
-      req: { id: "req-3", type: "req", method: "exec.approval.resolve" },
-      isWebchatConnect: noop,
-    });
-
-    await requestPromise;
-  });
-});
diff --git a/src/gateway/server-methods/exec-approvals.ts b/src/gateway/server-methods/exec-approvals.ts
index df015745993..a4c510395bc 100644
--- a/src/gateway/server-methods/exec-approvals.ts
+++ b/src/gateway/server-methods/exec-approvals.ts
@@ -1,9 +1,9 @@
 import type { GatewayRequestHandlers, RespondFn } from "./types.js";
 import {
   ensureExecApprovals,
+  mergeExecApprovalsSocketDefaults,
   normalizeExecApprovals,
   readExecApprovalsSnapshot,
-  resolveExecApprovalsSocketPath,
   saveExecApprovals,
   type ExecApprovalsFile,
   type ExecApprovalsSnapshot,
@@ -11,22 +11,18 @@ import {
 import {
   ErrorCodes,
   errorShape,
-  formatValidationErrors,
   validateExecApprovalsGetParams,
   validateExecApprovalsNodeGetParams,
   validateExecApprovalsNodeSetParams,
   validateExecApprovalsSetParams,
 } from "../protocol/index.js";
-import { respondUnavailableOnThrow, safeParseJson } from "./nodes.helpers.js";
-
-function resolveBaseHash(params: unknown): string | null {
-  const raw = (params as { baseHash?: unknown })?.baseHash;
-  if (typeof raw !== "string") {
-    return null;
-  }
-  const trimmed = raw.trim();
-  return trimmed ? trimmed : null;
-}
+import { resolveBaseHashParam } from "./base-hash.js";
+import {
+  respondUnavailableOnNodeInvokeError,
+  respondUnavailableOnThrow,
+  safeParseJson,
+} from "./nodes.helpers.js";
+import { assertValidParams } from "./validation.js";
 
 function requireApprovalsBaseHash(
   params: unknown,
@@ -47,7 +43,7 @@ function requireApprovalsBaseHash(
     );
     return false;
   }
-  const baseHash = resolveBaseHash(params);
+  const baseHash = resolveBaseHashParam(params);
   if (!baseHash) {
     respond(
       false,
@@ -83,15 +79,7 @@ function redactExecApprovals(file: ExecApprovalsFile): ExecApprovalsFile {
 
 export const execApprovalsHandlers: GatewayRequestHandlers = {
   "exec.approvals.get": ({ params, respond }) => {
-    if (!validateExecApprovalsGetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid exec.approvals.get params: ${formatValidationErrors(validateExecApprovalsGetParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateExecApprovalsGetParams, "exec.approvals.get", respond)) {
       return;
     }
     ensureExecApprovals();
@@ -108,15 +96,7 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
     );
   },
   "exec.approvals.set": ({ params, respond }) => {
-    if (!validateExecApprovalsSetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid exec.approvals.set params: ${formatValidationErrors(validateExecApprovalsSetParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateExecApprovalsSetParams, "exec.approvals.set", respond)) {
       return;
     }
     ensureExecApprovals();
@@ -134,18 +114,7 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
       return;
     }
     const normalized = normalizeExecApprovals(incoming as ExecApprovalsFile);
-    const currentSocketPath = snapshot.file.socket?.path?.trim();
-    const currentToken = snapshot.file.socket?.token?.trim();
-    const socketPath =
-      normalized.socket?.path?.trim() ?? currentSocketPath ?? resolveExecApprovalsSocketPath();
-    const token = normalized.socket?.token?.trim() ?? currentToken ?? "";
-    const next: ExecApprovalsFile = {
-      ...normalized,
-      socket: {
-        path: socketPath,
-        token,
-      },
-    };
+    const next = mergeExecApprovalsSocketDefaults({ normalized, current: snapshot.file });
     saveExecApprovals(next);
     const nextSnapshot = readExecApprovalsSnapshot();
     respond(
@@ -160,15 +129,14 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
     );
   },
   "exec.approvals.node.get": async ({ params, respond, context }) => {
-    if (!validateExecApprovalsNodeGetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid exec.approvals.node.get params: ${formatValidationErrors(validateExecApprovalsNodeGetParams.errors)}`,
-        ),
-      );
+    if (
+      !assertValidParams(
+        params,
+        validateExecApprovalsNodeGetParams,
+        "exec.approvals.node.get",
+        respond,
+      )
+    ) {
       return;
     }
     const { nodeId } = params as { nodeId: string };
@@ -183,14 +151,7 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
         command: "system.execApprovals.get",
         params: {},
       });
-      if (!res.ok) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-            details: { nodeError: res.error ?? null },
-          }),
-        );
+      if (!respondUnavailableOnNodeInvokeError(respond, res)) {
         return;
       }
       const payload = res.payloadJSON ? safeParseJson(res.payloadJSON) : res.payload;
@@ -198,15 +159,14 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
     });
   },
   "exec.approvals.node.set": async ({ params, respond, context }) => {
-    if (!validateExecApprovalsNodeSetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid exec.approvals.node.set params: ${formatValidationErrors(validateExecApprovalsNodeSetParams.errors)}`,
-        ),
-      );
+    if (
+      !assertValidParams(
+        params,
+        validateExecApprovalsNodeSetParams,
+        "exec.approvals.node.set",
+        respond,
+      )
+    ) {
       return;
     }
     const { nodeId, file, baseHash } = params as {
@@ -225,14 +185,7 @@ export const execApprovalsHandlers: GatewayRequestHandlers = {
         command: "system.execApprovals.set",
         params: { file, baseHash },
       });
-      if (!res.ok) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-            details: { nodeError: res.error ?? null },
-          }),
-        );
+      if (!respondUnavailableOnNodeInvokeError(respond, res)) {
         return;
       }
       const payload = safeParseJson(res.payloadJSON ?? null);
diff --git a/src/gateway/server-methods/health.status-scope.test.ts b/src/gateway/server-methods/health.status-scope.test.ts
deleted file mode 100644
index f8a83aa1974..00000000000
--- a/src/gateway/server-methods/health.status-scope.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { getStatusSummary } from "../../commands/status.js";
-import { healthHandlers } from "./health.js";
-
-vi.mock("../../commands/status.js", () => ({
-  getStatusSummary: vi.fn().mockResolvedValue({ ok: true }),
-}));
-
-describe("gateway healthHandlers.status scope handling", () => {
-  it("requests redacted status for non-admin clients", async () => {
-    const respond = vi.fn();
-    await healthHandlers.status({
-      respond,
-      client: { connect: { role: "operator", scopes: ["operator.read"] } },
-    } as Parameters<(typeof healthHandlers)["status"]>[0]);
-
-    expect(vi.mocked(getStatusSummary)).toHaveBeenCalledWith({ includeSensitive: false });
-    expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
-  });
-
-  it("requests full status for admin clients", async () => {
-    const respond = vi.fn();
-    await healthHandlers.status({
-      respond,
-      client: { connect: { role: "operator", scopes: ["operator.admin"] } },
-    } as Parameters<(typeof healthHandlers)["status"]>[0]);
-
-    expect(vi.mocked(getStatusSummary)).toHaveBeenCalledWith({ includeSensitive: true });
-    expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
-  });
-});
diff --git a/src/gateway/server-methods/logs.test.ts b/src/gateway/server-methods/logs.test.ts
deleted file mode 100644
index fd9a46f920b..00000000000
--- a/src/gateway/server-methods/logs.test.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { resetLogger, setLoggerOverride } from "../../logging.js";
-import { logsHandlers } from "./logs.js";
-
-const noop = () => false;
-
-describe("logs.tail", () => {
-  afterEach(() => {
-    resetLogger();
-    setLoggerOverride(null);
-  });
-
-  it("falls back to latest rolling log file when today is missing", async () => {
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-logs-"));
-    const older = path.join(tempDir, "openclaw-2026-01-20.log");
-    const newer = path.join(tempDir, "openclaw-2026-01-21.log");
-
-    await fs.writeFile(older, '{"msg":"old"}\n');
-    await fs.writeFile(newer, '{"msg":"new"}\n');
-    await fs.utimes(older, new Date(0), new Date(0));
-    await fs.utimes(newer, new Date(), new Date());
-
-    setLoggerOverride({ file: path.join(tempDir, "openclaw-2026-01-22.log") });
-
-    const respond = vi.fn();
-    await logsHandlers["logs.tail"]({
-      params: {},
-      respond,
-      context: {} as unknown as Parameters<(typeof logsHandlers)["logs.tail"]>[0]["context"],
-      client: null,
-      req: { id: "req-1", type: "req", method: "logs.tail" },
-      isWebchatConnect: noop,
-    });
-
-    expect(respond).toHaveBeenCalledWith(
-      true,
-      expect.objectContaining({
-        file: newer,
-        lines: ['{"msg":"new"}'],
-      }),
-      undefined,
-    );
-
-    await fs.rm(tempDir, { recursive: true, force: true });
-  });
-});
diff --git a/src/gateway/server-methods/nodes.helpers.ts b/src/gateway/server-methods/nodes.helpers.ts
index 5f77112e14c..33192193d62 100644
--- a/src/gateway/server-methods/nodes.helpers.ts
+++ b/src/gateway/server-methods/nodes.helpers.ts
@@ -51,3 +51,28 @@ export function safeParseJson(value: string | null | undefined): unknown {
     return { payloadJSON: value };
   }
 }
+
+export function respondUnavailableOnNodeInvokeError<T extends { ok: boolean; error?: unknown }>(
+  respond: RespondFn,
+  res: T,
+): res is T & { ok: true } {
+  if (res.ok) {
+    return true;
+  }
+  const message =
+    res.error && typeof res.error === "object" && "message" in res.error
+      ? (res.error as { message?: unknown }).message
+      : null;
+  respond(
+    false,
+    undefined,
+    errorShape(
+      ErrorCodes.UNAVAILABLE,
+      typeof message === "string" ? message : "node invoke failed",
+      {
+        details: { nodeError: res.error ?? null },
+      },
+    ),
+  );
+  return false;
+}
diff --git a/src/gateway/server-methods/nodes.ts b/src/gateway/server-methods/nodes.ts
index 6edb38887b5..c300ea2f732 100644
--- a/src/gateway/server-methods/nodes.ts
+++ b/src/gateway/server-methods/nodes.ts
@@ -28,6 +28,7 @@ import {
 import { handleNodeInvokeResult } from "./nodes.handlers.invoke-result.js";
 import {
   respondInvalidParams,
+  respondUnavailableOnNodeInvokeError,
   respondUnavailableOnThrow,
   safeParseJson,
   uniqueSortedStrings,
@@ -433,14 +434,7 @@ export const nodeHandlers: GatewayRequestHandlers = {
         timeoutMs: p.timeoutMs,
         idempotencyKey: p.idempotencyKey,
       });
-      if (!res.ok) {
-        respond(
-          false,
-          undefined,
-          errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-            details: { nodeError: res.error ?? null },
-          }),
-        );
+      if (!respondUnavailableOnNodeInvokeError(respond, res)) {
         return;
       }
       const payload = res.payloadJSON ? safeParseJson(res.payloadJSON) : res.payload;
diff --git a/src/gateway/server-methods/restart-request.ts b/src/gateway/server-methods/restart-request.ts
new file mode 100644
index 00000000000..f8b2ddb8c0d
--- /dev/null
+++ b/src/gateway/server-methods/restart-request.ts
@@ -0,0 +1,20 @@
+export function parseRestartRequestParams(params: unknown): {
+  sessionKey: string | undefined;
+  note: string | undefined;
+  restartDelayMs: number | undefined;
+} {
+  const sessionKey =
+    typeof (params as { sessionKey?: unknown }).sessionKey === "string"
+      ? (params as { sessionKey?: string }).sessionKey?.trim() || undefined
+      : undefined;
+  const note =
+    typeof (params as { note?: unknown }).note === "string"
+      ? (params as { note?: string }).note?.trim() || undefined
+      : undefined;
+  const restartDelayMsRaw = (params as { restartDelayMs?: unknown }).restartDelayMs;
+  const restartDelayMs =
+    typeof restartDelayMsRaw === "number" && Number.isFinite(restartDelayMsRaw)
+      ? Math.max(0, Math.floor(restartDelayMsRaw))
+      : undefined;
+  return { sessionKey, note, restartDelayMs };
+}
diff --git a/src/gateway/server-methods/server-methods.test.ts b/src/gateway/server-methods/server-methods.test.ts
new file mode 100644
index 00000000000..fe666dcbca9
--- /dev/null
+++ b/src/gateway/server-methods/server-methods.test.ts
@@ -0,0 +1,533 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { emitAgentEvent } from "../../infra/agent-events.js";
+import { formatZonedTimestamp } from "../../infra/format-time/format-datetime.js";
+import { resetLogger, setLoggerOverride } from "../../logging.js";
+import { ExecApprovalManager } from "../exec-approval-manager.js";
+import { validateExecApprovalRequestParams } from "../protocol/index.js";
+import { waitForAgentJob } from "./agent-job.js";
+import { injectTimestamp, timestampOptsFromConfig } from "./agent-timestamp.js";
+import { normalizeRpcAttachmentsToChatAttachments } from "./attachment-normalize.js";
+import { sanitizeChatSendMessageInput } from "./chat.js";
+import { createExecApprovalHandlers } from "./exec-approval.js";
+import { logsHandlers } from "./logs.js";
+
+vi.mock("../../commands/status.js", () => ({
+  getStatusSummary: vi.fn().mockResolvedValue({ ok: true }),
+}));
+
+type HealthStatusHandlerParams = Parameters<
+  (typeof import("./health.js"))["healthHandlers"]["status"]
+>[0];
+
+describe("waitForAgentJob", () => {
+  it("maps lifecycle end events with aborted=true to timeout", async () => {
+    const runId = `run-timeout-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
+
+    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "start", startedAt: 100 } });
+    emitAgentEvent({
+      runId,
+      stream: "lifecycle",
+      data: { phase: "end", endedAt: 200, aborted: true },
+    });
+
+    const snapshot = await waitPromise;
+    expect(snapshot).not.toBeNull();
+    expect(snapshot?.status).toBe("timeout");
+    expect(snapshot?.startedAt).toBe(100);
+    expect(snapshot?.endedAt).toBe(200);
+  });
+
+  it("keeps non-aborted lifecycle end events as ok", async () => {
+    const runId = `run-ok-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const waitPromise = waitForAgentJob({ runId, timeoutMs: 1_000 });
+
+    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "start", startedAt: 300 } });
+    emitAgentEvent({ runId, stream: "lifecycle", data: { phase: "end", endedAt: 400 } });
+
+    const snapshot = await waitPromise;
+    expect(snapshot).not.toBeNull();
+    expect(snapshot?.status).toBe("ok");
+    expect(snapshot?.startedAt).toBe(300);
+    expect(snapshot?.endedAt).toBe(400);
+  });
+});
+
+describe("injectTimestamp", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-29T01:30:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("prepends a compact timestamp matching formatZonedTimestamp", () => {
+    const result = injectTimestamp("Is it the weekend?", {
+      timezone: "America/New_York",
+    });
+
+    expect(result).toMatch(/^\[Wed 2026-01-28 20:30 EST\] Is it the weekend\?$/);
+  });
+
+  it("uses channel envelope format with DOW prefix", () => {
+    const now = new Date();
+    const expected = formatZonedTimestamp(now, { timeZone: "America/New_York" });
+
+    const result = injectTimestamp("hello", { timezone: "America/New_York" });
+
+    expect(result).toBe(`[Wed ${expected}] hello`);
+  });
+
+  it("always uses 24-hour format", () => {
+    const result = injectTimestamp("hello", { timezone: "America/New_York" });
+
+    expect(result).toContain("20:30");
+    expect(result).not.toContain("PM");
+    expect(result).not.toContain("AM");
+  });
+
+  it("uses the configured timezone", () => {
+    const result = injectTimestamp("hello", { timezone: "America/Chicago" });
+
+    expect(result).toMatch(/^\[Wed 2026-01-28 19:30 CST\]/);
+  });
+
+  it("defaults to UTC when no timezone specified", () => {
+    const result = injectTimestamp("hello", {});
+
+    expect(result).toMatch(/^\[Thu 2026-01-29 01:30/);
+  });
+
+  it("returns empty/whitespace messages unchanged", () => {
+    expect(injectTimestamp("", { timezone: "UTC" })).toBe("");
+    expect(injectTimestamp("   ", { timezone: "UTC" })).toBe("   ");
+  });
+
+  it("does NOT double-stamp messages with channel envelope timestamps", () => {
+    const enveloped = "[Discord user1 2026-01-28 20:30 EST] hello there";
+    const result = injectTimestamp(enveloped, { timezone: "America/New_York" });
+
+    expect(result).toBe(enveloped);
+  });
+
+  it("does NOT double-stamp messages already injected by us", () => {
+    const alreadyStamped = "[Wed 2026-01-28 20:30 EST] hello there";
+    const result = injectTimestamp(alreadyStamped, { timezone: "America/New_York" });
+
+    expect(result).toBe(alreadyStamped);
+  });
+
+  it("does NOT double-stamp messages with cron-injected timestamps", () => {
+    const cronMessage =
+      "[cron:abc123 my-job] do the thing\nCurrent time: Wednesday, January 28th, 2026 — 8:30 PM (America/New_York)";
+    const result = injectTimestamp(cronMessage, { timezone: "America/New_York" });
+
+    expect(result).toBe(cronMessage);
+  });
+
+  it("handles midnight correctly", () => {
+    vi.setSystemTime(new Date("2026-02-01T05:00:00.000Z"));
+
+    const result = injectTimestamp("hello", { timezone: "America/New_York" });
+
+    expect(result).toMatch(/^\[Sun 2026-02-01 00:00 EST\]/);
+  });
+
+  it("handles date boundaries (just before midnight)", () => {
+    vi.setSystemTime(new Date("2026-02-01T04:59:00.000Z"));
+
+    const result = injectTimestamp("hello", { timezone: "America/New_York" });
+
+    expect(result).toMatch(/^\[Sat 2026-01-31 23:59 EST\]/);
+  });
+
+  it("handles DST correctly (same UTC hour, different local time)", () => {
+    vi.setSystemTime(new Date("2026-01-15T05:00:00.000Z"));
+    const winter = injectTimestamp("winter", { timezone: "America/New_York" });
+    expect(winter).toMatch(/^\[Thu 2026-01-15 00:00 EST\]/);
+
+    vi.setSystemTime(new Date("2026-07-15T04:00:00.000Z"));
+    const summer = injectTimestamp("summer", { timezone: "America/New_York" });
+    expect(summer).toMatch(/^\[Wed 2026-07-15 00:00 EDT\]/);
+  });
+
+  it("accepts a custom now date", () => {
+    const customDate = new Date("2025-07-04T16:00:00.000Z");
+
+    const result = injectTimestamp("fireworks?", {
+      timezone: "America/New_York",
+      now: customDate,
+    });
+
+    expect(result).toMatch(/^\[Fri 2025-07-04 12:00 EDT\]/);
+  });
+});
+
+describe("timestampOptsFromConfig", () => {
+  it("extracts timezone from config", () => {
+    const opts = timestampOptsFromConfig({
+      agents: {
+        defaults: {
+          userTimezone: "America/Chicago",
+        },
+      },
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any);
+
+    expect(opts.timezone).toBe("America/Chicago");
+  });
+
+  it("falls back gracefully with empty config", () => {
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const opts = timestampOptsFromConfig({} as any);
+
+    expect(opts.timezone).toBeDefined();
+  });
+});
+
+describe("normalizeRpcAttachmentsToChatAttachments", () => {
+  it("passes through string content", () => {
+    const res = normalizeRpcAttachmentsToChatAttachments([
+      { type: "file", mimeType: "image/png", fileName: "a.png", content: "Zm9v" },
+    ]);
+    expect(res).toEqual([
+      { type: "file", mimeType: "image/png", fileName: "a.png", content: "Zm9v" },
+    ]);
+  });
+
+  it("converts Uint8Array content to base64", () => {
+    const bytes = new TextEncoder().encode("foo");
+    const res = normalizeRpcAttachmentsToChatAttachments([{ content: bytes }]);
+    expect(res[0]?.content).toBe("Zm9v");
+  });
+});
+
+describe("sanitizeChatSendMessageInput", () => {
+  it("rejects null bytes", () => {
+    expect(sanitizeChatSendMessageInput("before\u0000after")).toEqual({
+      ok: false,
+      error: "message must not contain null bytes",
+    });
+  });
+
+  it("strips unsafe control characters while preserving tab/newline/carriage return", () => {
+    const result = sanitizeChatSendMessageInput("a\u0001b\tc\nd\re\u0007f\u007f");
+    expect(result).toEqual({ ok: true, message: "ab\tc\nd\ref" });
+  });
+
+  it("normalizes unicode to NFC", () => {
+    expect(sanitizeChatSendMessageInput("Cafe\u0301")).toEqual({ ok: true, message: "Café" });
+  });
+});
+
+describe("gateway chat transcript writes (guardrail)", () => {
+  it("does not append transcript messages via raw fs.appendFileSync(transcriptPath, ...)", () => {
+    const chatTs = fileURLToPath(new URL("./chat.ts", import.meta.url));
+    const src = fs.readFileSync(chatTs, "utf-8");
+
+    expect(src.includes("fs.appendFileSync(transcriptPath")).toBe(false);
+
+    expect(src).toContain("SessionManager.open(transcriptPath)");
+    expect(src).toContain("appendMessage(");
+  });
+});
+
+describe("exec approval handlers", () => {
+  const execApprovalNoop = () => {};
+
+  describe("ExecApprovalRequestParams validation", () => {
+    it("accepts request with resolvedPath omitted", () => {
+      const params = {
+        command: "echo hi",
+        cwd: "/tmp",
+        host: "node",
+      };
+      expect(validateExecApprovalRequestParams(params)).toBe(true);
+    });
+
+    it("accepts request with resolvedPath as string", () => {
+      const params = {
+        command: "echo hi",
+        cwd: "/tmp",
+        host: "node",
+        resolvedPath: "/usr/bin/echo",
+      };
+      expect(validateExecApprovalRequestParams(params)).toBe(true);
+    });
+
+    it("accepts request with resolvedPath as undefined", () => {
+      const params = {
+        command: "echo hi",
+        cwd: "/tmp",
+        host: "node",
+        resolvedPath: undefined,
+      };
+      expect(validateExecApprovalRequestParams(params)).toBe(true);
+    });
+
+    it("accepts request with resolvedPath as null", () => {
+      const params = {
+        command: "echo hi",
+        cwd: "/tmp",
+        host: "node",
+        resolvedPath: null,
+      };
+      expect(validateExecApprovalRequestParams(params)).toBe(true);
+    });
+  });
+
+  it("broadcasts request + resolve", async () => {
+    const manager = new ExecApprovalManager();
+    const handlers = createExecApprovalHandlers(manager);
+    const broadcasts: Array<{ event: string; payload: unknown }> = [];
+
+    const respond = vi.fn();
+    const context = {
+      broadcast: (event: string, payload: unknown) => {
+        broadcasts.push({ event, payload });
+      },
+    };
+
+    const requestPromise = handlers["exec.approval.request"]({
+      params: {
+        command: "echo ok",
+        cwd: "/tmp",
+        host: "node",
+        timeoutMs: 2000,
+        twoPhase: true,
+      },
+      respond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: execApprovalNoop,
+    });
+
+    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
+    expect(requested).toBeTruthy();
+    const id = (requested?.payload as { id?: string })?.id ?? "";
+    expect(id).not.toBe("");
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ status: "accepted", id }),
+      undefined,
+    );
+
+    const resolveRespond = vi.fn();
+    await handlers["exec.approval.resolve"]({
+      params: { id, decision: "allow-once" },
+      respond: resolveRespond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.resolve"]
+      >[0]["context"],
+      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
+      req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
+      isWebchatConnect: execApprovalNoop,
+    });
+
+    await requestPromise;
+
+    expect(resolveRespond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ id, decision: "allow-once" }),
+      undefined,
+    );
+    expect(broadcasts.some((entry) => entry.event === "exec.approval.resolved")).toBe(true);
+  });
+
+  it("accepts resolve during broadcast", async () => {
+    const manager = new ExecApprovalManager();
+    const handlers = createExecApprovalHandlers(manager);
+    const respond = vi.fn();
+    const resolveRespond = vi.fn();
+
+    const resolveContext = {
+      broadcast: () => {},
+    };
+
+    const context = {
+      broadcast: (event: string, payload: unknown) => {
+        if (event !== "exec.approval.requested") {
+          return;
+        }
+        const id = (payload as { id?: string })?.id ?? "";
+        void handlers["exec.approval.resolve"]({
+          params: { id, decision: "allow-once" },
+          respond: resolveRespond,
+          context: resolveContext as unknown as Parameters<
+            (typeof handlers)["exec.approval.resolve"]
+          >[0]["context"],
+          client: { connect: { client: { id: "cli", displayName: "CLI" } } },
+          req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
+          isWebchatConnect: execApprovalNoop,
+        });
+      },
+    };
+
+    await handlers["exec.approval.request"]({
+      params: {
+        command: "echo ok",
+        cwd: "/tmp",
+        host: "node",
+        timeoutMs: 2000,
+      },
+      respond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: execApprovalNoop,
+    });
+
+    expect(resolveRespond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ decision: "allow-once" }),
+      undefined,
+    );
+  });
+
+  it("accepts explicit approval ids", async () => {
+    const manager = new ExecApprovalManager();
+    const handlers = createExecApprovalHandlers(manager);
+    const broadcasts: Array<{ event: string; payload: unknown }> = [];
+
+    const respond = vi.fn();
+    const context = {
+      broadcast: (event: string, payload: unknown) => {
+        broadcasts.push({ event, payload });
+      },
+    };
+
+    const requestPromise = handlers["exec.approval.request"]({
+      params: {
+        id: "approval-123",
+        command: "echo ok",
+        cwd: "/tmp",
+        host: "gateway",
+        timeoutMs: 2000,
+      },
+      respond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.request"]
+      >[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "exec.approval.request" },
+      isWebchatConnect: execApprovalNoop,
+    });
+
+    const requested = broadcasts.find((entry) => entry.event === "exec.approval.requested");
+    const id = (requested?.payload as { id?: string })?.id ?? "";
+    expect(id).toBe("approval-123");
+
+    const resolveRespond = vi.fn();
+    await handlers["exec.approval.resolve"]({
+      params: { id, decision: "allow-once" },
+      respond: resolveRespond,
+      context: context as unknown as Parameters<
+        (typeof handlers)["exec.approval.resolve"]
+      >[0]["context"],
+      client: { connect: { client: { id: "cli", displayName: "CLI" } } },
+      req: { id: "req-2", type: "req", method: "exec.approval.resolve" },
+      isWebchatConnect: execApprovalNoop,
+    });
+
+    await requestPromise;
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ id: "approval-123", decision: "allow-once" }),
+      undefined,
+    );
+    expect(resolveRespond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+  });
+});
+
+describe("gateway healthHandlers.status scope handling", () => {
+  beforeEach(async () => {
+    const status = await import("../../commands/status.js");
+    vi.mocked(status.getStatusSummary).mockClear();
+  });
+
+  it("requests redacted status for non-admin clients", async () => {
+    const respond = vi.fn();
+    const status = await import("../../commands/status.js");
+    const { healthHandlers } = await import("./health.js");
+
+    await healthHandlers.status({
+      respond,
+      client: { connect: { role: "operator", scopes: ["operator.read"] } },
+    } as HealthStatusHandlerParams);
+
+    expect(vi.mocked(status.getStatusSummary)).toHaveBeenCalledWith({ includeSensitive: false });
+    expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+  });
+
+  it("requests full status for admin clients", async () => {
+    const respond = vi.fn();
+    const status = await import("../../commands/status.js");
+    const { healthHandlers } = await import("./health.js");
+
+    await healthHandlers.status({
+      respond,
+      client: { connect: { role: "operator", scopes: ["operator.admin"] } },
+    } as HealthStatusHandlerParams);
+
+    expect(vi.mocked(status.getStatusSummary)).toHaveBeenCalledWith({ includeSensitive: true });
+    expect(respond).toHaveBeenCalledWith(true, { ok: true }, undefined);
+  });
+});
+
+describe("logs.tail", () => {
+  const logsNoop = () => false;
+
+  afterEach(() => {
+    resetLogger();
+    setLoggerOverride(null);
+  });
+
+  it("falls back to latest rolling log file when today is missing", async () => {
+    const tempDir = await fsPromises.mkdtemp(path.join(os.tmpdir(), "openclaw-logs-"));
+    const older = path.join(tempDir, "openclaw-2026-01-20.log");
+    const newer = path.join(tempDir, "openclaw-2026-01-21.log");
+
+    await fsPromises.writeFile(older, '{"msg":"old"}\n');
+    await fsPromises.writeFile(newer, '{"msg":"new"}\n');
+    await fsPromises.utimes(older, new Date(0), new Date(0));
+    await fsPromises.utimes(newer, new Date(), new Date());
+
+    setLoggerOverride({ file: path.join(tempDir, "openclaw-2026-01-22.log") });
+
+    const respond = vi.fn();
+    await logsHandlers["logs.tail"]({
+      params: {},
+      respond,
+      context: {} as unknown as Parameters<(typeof logsHandlers)["logs.tail"]>[0]["context"],
+      client: null,
+      req: { id: "req-1", type: "req", method: "logs.tail" },
+      isWebchatConnect: logsNoop,
+    });
+
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({
+        file: newer,
+        lines: ['{"msg":"new"}'],
+      }),
+      undefined,
+    );
+
+    await fsPromises.rm(tempDir, { recursive: true, force: true });
+  });
+});
diff --git a/src/gateway/server-methods/sessions.ts b/src/gateway/server-methods/sessions.ts
index c10f825d45f..eadbdef2ba7 100644
--- a/src/gateway/server-methods/sessions.ts
+++ b/src/gateway/server-methods/sessions.ts
@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import type { GatewayRequestHandlers } from "./types.js";
+import type { GatewayRequestHandlers, RespondFn } from "./types.js";
 import { resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { abortEmbeddedPiRun, waitForEmbeddedPiRunEnd } from "../../agents/pi-embedded.js";
 import { stopSubagentsForRequester } from "../../auto-reply/reply/abort.js";
@@ -18,7 +18,6 @@ import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-ke
 import {
   ErrorCodes,
   errorShape,
-  formatValidationErrors,
   validateSessionsCompactParams,
   validateSessionsDeleteParams,
   validateSessionsListParams,
@@ -44,6 +43,30 @@ import {
 } from "../session-utils.js";
 import { applySessionsPatchToStore } from "../sessions-patch.js";
 import { resolveSessionKeyFromResolveParams } from "../sessions-resolve.js";
+import { assertValidParams } from "./validation.js";
+
+function requireSessionKey(key: unknown, respond: RespondFn): string | null {
+  const raw =
+    typeof key === "string"
+      ? key
+      : typeof key === "number"
+        ? String(key)
+        : typeof key === "bigint"
+          ? String(key)
+          : "";
+  const normalized = raw.trim();
+  if (!normalized) {
+    respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "key required"));
+    return null;
+  }
+  return normalized;
+}
+
+function resolveGatewaySessionTargetFromKey(key: string) {
+  const cfg = loadConfig();
+  const target = resolveGatewaySessionStoreTarget({ cfg, key });
+  return { cfg, target, storePath: target.storePath };
+}
 
 function migrateAndPruneSessionStoreKey(params: {
   cfg: ReturnType<typeof loadConfig>;
@@ -118,15 +141,7 @@ async function ensureSessionRuntimeCleanup(params: {
 
 export const sessionsHandlers: GatewayRequestHandlers = {
   "sessions.list": ({ params, respond }) => {
-    if (!validateSessionsListParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.list params: ${formatValidationErrors(validateSessionsListParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsListParams, "sessions.list", respond)) {
       return;
     }
     const p = params;
@@ -141,17 +156,7 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, result, undefined);
   },
   "sessions.preview": ({ params, respond }) => {
-    if (!validateSessionsPreviewParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.preview params: ${formatValidationErrors(
-            validateSessionsPreviewParams.errors,
-          )}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsPreviewParams, "sessions.preview", respond)) {
       return;
     }
     const p = params;
@@ -213,15 +218,7 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, { ts: Date.now(), previews } satisfies SessionsPreviewResult, undefined);
   },
   "sessions.resolve": async ({ params, respond }) => {
-    if (!validateSessionsResolveParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.resolve params: ${formatValidationErrors(validateSessionsResolveParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsResolveParams, "sessions.resolve", respond)) {
       return;
     }
     const p = params;
@@ -235,27 +232,16 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, { ok: true, key: resolved.key }, undefined);
   },
   "sessions.patch": async ({ params, respond, context }) => {
-    if (!validateSessionsPatchParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.patch params: ${formatValidationErrors(validateSessionsPatchParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsPatchParams, "sessions.patch", respond)) {
       return;
     }
     const p = params;
-    const key = String(p.key ?? "").trim();
+    const key = requireSessionKey(p.key, respond);
     if (!key) {
-      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "key required"));
       return;
     }
 
-    const cfg = loadConfig();
-    const target = resolveGatewaySessionStoreTarget({ cfg, key });
-    const storePath = target.storePath;
+    const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
     const applied = await updateSessionStore(storePath, async (store) => {
       const { primaryKey } = migrateAndPruneSessionStoreKey({ cfg, key, store });
       return await applySessionsPatchToStore({
@@ -286,26 +272,16 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, result, undefined);
   },
   "sessions.reset": async ({ params, respond }) => {
-    if (!validateSessionsResetParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.reset params: ${formatValidationErrors(validateSessionsResetParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsResetParams, "sessions.reset", respond)) {
       return;
     }
     const p = params;
-    const key = String(p.key ?? "").trim();
+    const key = requireSessionKey(p.key, respond);
     if (!key) {
-      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "key required"));
       return;
     }
 
-    const cfg = loadConfig();
-    const target = resolveGatewaySessionStoreTarget({ cfg, key });
+    const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
     const { entry } = loadSessionEntry(key);
     const commandReason = p.reason === "new" ? "new" : "reset";
     const hookEvent = createInternalHookEvent(
@@ -326,7 +302,6 @@ export const sessionsHandlers: GatewayRequestHandlers = {
       respond(false, undefined, cleanupError);
       return;
     }
-    const storePath = target.storePath;
     let oldSessionId: string | undefined;
     let oldSessionFile: string | undefined;
     const next = await updateSessionStore(storePath, (store) => {
@@ -372,27 +347,17 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, { ok: true, key: target.canonicalKey, entry: next }, undefined);
   },
   "sessions.delete": async ({ params, respond }) => {
-    if (!validateSessionsDeleteParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.delete params: ${formatValidationErrors(validateSessionsDeleteParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsDeleteParams, "sessions.delete", respond)) {
       return;
     }
     const p = params;
-    const key = String(p.key ?? "").trim();
+    const key = requireSessionKey(p.key, respond);
     if (!key) {
-      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "key required"));
       return;
     }
 
-    const cfg = loadConfig();
+    const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
     const mainKey = resolveMainSessionKey(cfg);
-    const target = resolveGatewaySessionStoreTarget({ cfg, key });
     if (target.canonicalKey === mainKey) {
       respond(
         false,
@@ -404,7 +369,6 @@ export const sessionsHandlers: GatewayRequestHandlers = {
 
     const deleteTranscript = typeof p.deleteTranscript === "boolean" ? p.deleteTranscript : true;
 
-    const storePath = target.storePath;
     const { entry } = loadSessionEntry(key);
     const sessionId = entry?.sessionId;
     const existed = Boolean(entry);
@@ -433,21 +397,12 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     respond(true, { ok: true, key: target.canonicalKey, deleted: existed, archived }, undefined);
   },
   "sessions.compact": async ({ params, respond }) => {
-    if (!validateSessionsCompactParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid sessions.compact params: ${formatValidationErrors(validateSessionsCompactParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateSessionsCompactParams, "sessions.compact", respond)) {
       return;
     }
     const p = params;
-    const key = String(p.key ?? "").trim();
+    const key = requireSessionKey(p.key, respond);
     if (!key) {
-      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "key required"));
       return;
     }
 
@@ -456,9 +411,7 @@ export const sessionsHandlers: GatewayRequestHandlers = {
         ? Math.max(1, Math.floor(p.maxLines))
         : 400;
 
-    const cfg = loadConfig();
-    const target = resolveGatewaySessionStoreTarget({ cfg, key });
-    const storePath = target.storePath;
+    const { cfg, target, storePath } = resolveGatewaySessionTargetFromKey(key);
     // Lock + read in a short critical section; transcript work happens outside.
     const compactTarget = await updateSessionStore(storePath, (store) => {
       const { entry, primaryKey } = migrateAndPruneSessionStoreKey({ cfg, key, store });
diff --git a/src/gateway/server-methods/update.ts b/src/gateway/server-methods/update.ts
index fa887c944c3..411077444b3 100644
--- a/src/gateway/server-methods/update.ts
+++ b/src/gateway/server-methods/update.ts
@@ -9,39 +9,16 @@ import {
 import { scheduleGatewaySigusr1Restart } from "../../infra/restart.js";
 import { normalizeUpdateChannel } from "../../infra/update-channels.js";
 import { runGatewayUpdate } from "../../infra/update-runner.js";
-import {
-  ErrorCodes,
-  errorShape,
-  formatValidationErrors,
-  validateUpdateRunParams,
-} from "../protocol/index.js";
+import { validateUpdateRunParams } from "../protocol/index.js";
+import { parseRestartRequestParams } from "./restart-request.js";
+import { assertValidParams } from "./validation.js";
 
 export const updateHandlers: GatewayRequestHandlers = {
   "update.run": async ({ params, respond }) => {
-    if (!validateUpdateRunParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid update.run params: ${formatValidationErrors(validateUpdateRunParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateUpdateRunParams, "update.run", respond)) {
       return;
     }
-    const sessionKey =
-      typeof (params as { sessionKey?: unknown }).sessionKey === "string"
-        ? (params as { sessionKey?: string }).sessionKey?.trim() || undefined
-        : undefined;
-    const note =
-      typeof (params as { note?: unknown }).note === "string"
-        ? (params as { note?: string }).note?.trim() || undefined
-        : undefined;
-    const restartDelayMsRaw = (params as { restartDelayMs?: unknown }).restartDelayMs;
-    const restartDelayMs =
-      typeof restartDelayMsRaw === "number" && Number.isFinite(restartDelayMsRaw)
-        ? Math.max(0, Math.floor(restartDelayMsRaw))
-        : undefined;
+    const { sessionKey, note, restartDelayMs } = parseRestartRequestParams(params);
     const timeoutMsRaw = (params as { timeoutMs?: unknown }).timeoutMs;
     const timeoutMs =
       typeof timeoutMsRaw === "number" && Number.isFinite(timeoutMsRaw)
diff --git a/src/gateway/server-methods/usage.sessions-usage.test.ts b/src/gateway/server-methods/usage.sessions-usage.test.ts
index efdeb9a1647..3731bdd4e08 100644
--- a/src/gateway/server-methods/usage.sessions-usage.test.ts
+++ b/src/gateway/server-methods/usage.sessions-usage.test.ts
@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../../test-utils/env.js";
 
 vi.mock("../../config/config.js", () => {
   return {
@@ -118,7 +119,7 @@ describe("sessions.usage", () => {
   it("resolves store entries by sessionId when queried via discovered agent-prefixed key", async () => {
     const storeKey = "agent:opus:slack:dm:u123";
     const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-usage-test-"));
-    const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+    const envSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
     process.env.OPENCLAW_STATE_DIR = stateDir;
 
     try {
@@ -163,11 +164,7 @@ describe("sessions.usage", () => {
         vi.mocked(loadSessionCostSummary).mock.calls.some((call) => call[0]?.agentId === "opus"),
       ).toBe(true);
     } finally {
-      if (previousStateDir === undefined) {
-        delete process.env.OPENCLAW_STATE_DIR;
-      } else {
-        process.env.OPENCLAW_STATE_DIR = previousStateDir;
-      }
+      envSnapshot.restore();
       fs.rmSync(stateDir, { recursive: true, force: true });
     }
   });
diff --git a/src/gateway/server-methods/validation.ts b/src/gateway/server-methods/validation.ts
new file mode 100644
index 00000000000..90c663d26cd
--- /dev/null
+++ b/src/gateway/server-methods/validation.ts
@@ -0,0 +1,27 @@
+import type { ErrorObject } from "ajv";
+import type { RespondFn } from "./types.js";
+import { ErrorCodes, errorShape, formatValidationErrors } from "../protocol/index.js";
+
+export type Validator<T> = ((params: unknown) => params is T) & {
+  errors?: ErrorObject[] | null;
+};
+
+export function assertValidParams<T>(
+  params: unknown,
+  validate: Validator<T>,
+  method: string,
+  respond: RespondFn,
+): params is T {
+  if (validate(params)) {
+    return true;
+  }
+  respond(
+    false,
+    undefined,
+    errorShape(
+      ErrorCodes.INVALID_REQUEST,
+      `invalid ${method} params: ${formatValidationErrors(validate.errors)}`,
+    ),
+  );
+  return false;
+}
diff --git a/src/gateway/server-methods/wizard.ts b/src/gateway/server-methods/wizard.ts
index 8585a066cb5..310ae27db21 100644
--- a/src/gateway/server-methods/wizard.ts
+++ b/src/gateway/server-methods/wizard.ts
@@ -5,25 +5,24 @@ import { WizardSession } from "../../wizard/session.js";
 import {
   ErrorCodes,
   errorShape,
-  formatValidationErrors,
   validateWizardCancelParams,
   validateWizardNextParams,
   validateWizardStartParams,
   validateWizardStatusParams,
 } from "../protocol/index.js";
 import { formatForLog } from "../ws-log.js";
+import { assertValidParams } from "./validation.js";
+
+function readWizardStatus(session: WizardSession) {
+  return {
+    status: session.getStatus(),
+    error: session.getError(),
+  };
+}
 
 export const wizardHandlers: GatewayRequestHandlers = {
   "wizard.start": async ({ params, respond, context }) => {
-    if (!validateWizardStartParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid wizard.start params: ${formatValidationErrors(validateWizardStartParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateWizardStartParams, "wizard.start", respond)) {
       return;
     }
     const running = context.findRunningWizard();
@@ -47,15 +46,7 @@ export const wizardHandlers: GatewayRequestHandlers = {
     respond(true, { sessionId, ...result }, undefined);
   },
   "wizard.next": async ({ params, respond, context }) => {
-    if (!validateWizardNextParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid wizard.next params: ${formatValidationErrors(validateWizardNextParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateWizardNextParams, "wizard.next", respond)) {
       return;
     }
     const sessionId = params.sessionId;
@@ -84,15 +75,7 @@ export const wizardHandlers: GatewayRequestHandlers = {
     respond(true, result, undefined);
   },
   "wizard.cancel": ({ params, respond, context }) => {
-    if (!validateWizardCancelParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid wizard.cancel params: ${formatValidationErrors(validateWizardCancelParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateWizardCancelParams, "wizard.cancel", respond)) {
       return;
     }
     const sessionId = params.sessionId;
@@ -102,23 +85,12 @@ export const wizardHandlers: GatewayRequestHandlers = {
       return;
     }
     session.cancel();
-    const status = {
-      status: session.getStatus(),
-      error: session.getError(),
-    };
+    const status = readWizardStatus(session);
     context.wizardSessions.delete(sessionId);
     respond(true, status, undefined);
   },
   "wizard.status": ({ params, respond, context }) => {
-    if (!validateWizardStatusParams(params)) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid wizard.status params: ${formatValidationErrors(validateWizardStatusParams.errors)}`,
-        ),
-      );
+    if (!assertValidParams(params, validateWizardStatusParams, "wizard.status", respond)) {
       return;
     }
     const sessionId = params.sessionId;
@@ -127,10 +99,7 @@ export const wizardHandlers: GatewayRequestHandlers = {
       respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "wizard not found"));
       return;
     }
-    const status = {
-      status: session.getStatus(),
-      error: session.getError(),
-    };
+    const status = readWizardStatus(session);
     if (status.status !== "running") {
       context.wizardSessions.delete(sessionId);
     }
diff --git a/src/gateway/server-node-events.ts b/src/gateway/server-node-events.ts
index 8dc56262bda..360cde40bb8 100644
--- a/src/gateway/server-node-events.ts
+++ b/src/gateway/server-node-events.ts
@@ -69,6 +69,21 @@ async function touchSessionStore(params: {
   });
 }
 
+function parseSessionKeyFromPayloadJSON(payloadJSON: string): string | null {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(payloadJSON) as unknown;
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null) {
+    return null;
+  }
+  const obj = payload as Record<string, unknown>;
+  const sessionKey = typeof obj.sessionKey === "string" ? obj.sessionKey.trim() : "";
+  return sessionKey.length > 0 ? sessionKey : null;
+}
+
 export const handleNodeEvent = async (ctx: NodeEventContext, nodeId: string, evt: NodeEvent) => {
   switch (evt.event) {
     case "voice.transcript": {
@@ -187,15 +202,7 @@ export const handleNodeEvent = async (ctx: NodeEventContext, nodeId: string, evt
       if (!evt.payloadJSON) {
         return;
       }
-      let payload: unknown;
-      try {
-        payload = JSON.parse(evt.payloadJSON) as unknown;
-      } catch {
-        return;
-      }
-      const obj =
-        typeof payload === "object" && payload !== null ? (payload as Record<string, unknown>) : {};
-      const sessionKey = typeof obj.sessionKey === "string" ? obj.sessionKey.trim() : "";
+      const sessionKey = parseSessionKeyFromPayloadJSON(evt.payloadJSON);
       if (!sessionKey) {
         return;
       }
@@ -206,15 +213,7 @@ export const handleNodeEvent = async (ctx: NodeEventContext, nodeId: string, evt
       if (!evt.payloadJSON) {
         return;
       }
-      let payload: unknown;
-      try {
-        payload = JSON.parse(evt.payloadJSON) as unknown;
-      } catch {
-        return;
-      }
-      const obj =
-        typeof payload === "object" && payload !== null ? (payload as Record<string, unknown>) : {};
-      const sessionKey = typeof obj.sessionKey === "string" ? obj.sessionKey.trim() : "";
+      const sessionKey = parseSessionKeyFromPayloadJSON(evt.payloadJSON);
       if (!sessionKey) {
         return;
       }
diff --git a/src/gateway/server-node-subscriptions.test.ts b/src/gateway/server-node-subscriptions.test.ts
deleted file mode 100644
index 776e5a048f8..00000000000
--- a/src/gateway/server-node-subscriptions.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { createNodeSubscriptionManager } from "./server-node-subscriptions.js";
-
-describe("node subscription manager", () => {
-  test("routes events to subscribed nodes", () => {
-    const manager = createNodeSubscriptionManager();
-    const sent: Array<{
-      nodeId: string;
-      event: string;
-      payloadJSON?: string | null;
-    }> = [];
-    const sendEvent = (evt: { nodeId: string; event: string; payloadJSON?: string | null }) =>
-      sent.push(evt);
-
-    manager.subscribe("node-a", "main");
-    manager.subscribe("node-b", "main");
-    manager.sendToSession("main", "chat", { ok: true }, sendEvent);
-
-    expect(sent).toHaveLength(2);
-    expect(sent.map((s) => s.nodeId).toSorted()).toEqual(["node-a", "node-b"]);
-    expect(sent[0].event).toBe("chat");
-  });
-
-  test("unsubscribeAll clears session mappings", () => {
-    const manager = createNodeSubscriptionManager();
-    const sent: string[] = [];
-    const sendEvent = (evt: { nodeId: string; event: string }) =>
-      sent.push(`${evt.nodeId}:${evt.event}`);
-
-    manager.subscribe("node-a", "main");
-    manager.subscribe("node-a", "secondary");
-    manager.unsubscribeAll("node-a");
-    manager.sendToSession("main", "tick", {}, sendEvent);
-    manager.sendToSession("secondary", "tick", {}, sendEvent);
-
-    expect(sent).toEqual([]);
-  });
-});
diff --git a/src/gateway/server-reload.config-during-reply.test.ts b/src/gateway/server-reload.config-during-reply.test.ts
deleted file mode 100644
index 3d8be89749b..00000000000
--- a/src/gateway/server-reload.config-during-reply.test.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-/**
- * E2E test for config reload during active reply sending.
- * Tests that gateway restart is properly deferred until replies are sent.
- */
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  clearAllDispatchers,
-  getTotalPendingReplies,
-} from "../auto-reply/reply/dispatcher-registry.js";
-import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js";
-import { getTotalQueueSize } from "../process/command-queue.js";
-
-// Helper to flush all pending microtasks
-async function flushMicrotasks() {
-  for (let i = 0; i < 10; i++) {
-    await Promise.resolve();
-  }
-}
-
-describe("gateway config reload during reply", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(async () => {
-    vi.restoreAllMocks();
-    // Wait for any pending microtasks (from markComplete()) to complete
-    await flushMicrotasks();
-    clearAllDispatchers();
-  });
-
-  it("should defer restart until reply dispatcher completes", async () => {
-    // Create a dispatcher (simulating message handling)
-    let deliveredReplies: string[] = [];
-    const dispatcher = createReplyDispatcher({
-      deliver: async (payload) => {
-        // Keep delivery asynchronous without real wall-clock delay.
-        await Promise.resolve();
-        deliveredReplies.push(payload.text ?? "");
-      },
-      onError: (err) => {
-        throw err;
-      },
-    });
-
-    // Initially: pending=1 (reservation)
-    expect(getTotalPendingReplies()).toBe(1);
-
-    // Simulate command finishing and enqueuing reply
-    dispatcher.sendFinalReply({ text: "Configuration updated successfully!" });
-
-    // Now: pending=2 (reservation + 1 enqueued reply)
-    expect(getTotalPendingReplies()).toBe(2);
-
-    // Mark dispatcher complete (flags reservation for cleanup on last delivery)
-    dispatcher.markComplete();
-
-    // Reservation is still counted until the delivery .finally() clears it,
-    // but the important invariant is pending > 0 while delivery is in flight.
-    expect(getTotalPendingReplies()).toBeGreaterThan(0);
-
-    // At this point, if gateway restart was requested, it should defer
-    // because getTotalPendingReplies() > 0
-
-    // Wait for reply to be delivered
-    await dispatcher.waitForIdle();
-
-    // Now: pending=0 (reply sent)
-    expect(getTotalPendingReplies()).toBe(0);
-    expect(deliveredReplies).toEqual(["Configuration updated successfully!"]);
-
-    // Now restart can proceed safely
-    expect(getTotalQueueSize()).toBe(0);
-    expect(getTotalPendingReplies()).toBe(0);
-  });
-
-  it("should handle dispatcher reservation correctly when no replies sent", async () => {
-    const { createReplyDispatcher } = await import("../auto-reply/reply/reply-dispatcher.js");
-
-    let deliverCalled = false;
-    const dispatcher = createReplyDispatcher({
-      deliver: async () => {
-        deliverCalled = true;
-      },
-    });
-
-    // Initially: pending=1 (reservation)
-    expect(getTotalPendingReplies()).toBe(1);
-
-    // Mark complete without sending any replies
-    dispatcher.markComplete();
-
-    // Reservation is cleared via microtask — flush it
-    await flushMicrotasks();
-
-    // Now: pending=0 (reservation cleared, no replies were enqueued)
-    expect(getTotalPendingReplies()).toBe(0);
-
-    // Wait for idle (should resolve immediately since no replies)
-    await dispatcher.waitForIdle();
-
-    expect(deliverCalled).toBe(false);
-    expect(getTotalPendingReplies()).toBe(0);
-  });
-});
diff --git a/src/gateway/server-reload.integration.test.ts b/src/gateway/server-reload.integration.test.ts
deleted file mode 100644
index 9d788ad4947..00000000000
--- a/src/gateway/server-reload.integration.test.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-/**
- * Integration test simulating full message handling + config change + reply flow.
- * This tests the complete scenario where a user configures an adapter via chat
- * and ensures they get a reply before the gateway restarts.
- */
-import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
-import {
-  clearAllDispatchers,
-  getTotalPendingReplies,
-} from "../auto-reply/reply/dispatcher-registry.js";
-import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js";
-import { getTotalQueueSize } from "../process/command-queue.js";
-
-describe("gateway restart deferral integration", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(async () => {
-    vi.restoreAllMocks();
-    // Wait for any pending microtasks (from markComplete()) to complete
-    await Promise.resolve();
-    clearAllDispatchers();
-  });
-
-  it("should defer restart until dispatcher completes with reply", async () => {
-    const events: string[] = [];
-
-    // T=0: Message received — dispatcher created (pending=1 reservation)
-    events.push("message-received");
-    const deliveredReplies: Array<{ text: string; timestamp: number }> = [];
-    const dispatcher = createReplyDispatcher({
-      deliver: async (payload) => {
-        // Keep delivery asynchronous without real wall-clock delay.
-        await Promise.resolve();
-        deliveredReplies.push({
-          text: payload.text ?? "",
-          timestamp: Date.now(),
-        });
-        events.push(`reply-delivered: ${payload.text}`);
-      },
-    });
-    events.push("dispatcher-created");
-
-    // T=1: Config change detected
-    events.push("config-change-detected");
-
-    // Check if restart should be deferred
-    const queueSize = getTotalQueueSize();
-    const pendingReplies = getTotalPendingReplies();
-    const totalActive = queueSize + pendingReplies;
-
-    events.push(`defer-check: queue=${queueSize} pending=${pendingReplies} total=${totalActive}`);
-
-    // Should defer because dispatcher has reservation
-    expect(totalActive).toBeGreaterThan(0);
-    expect(pendingReplies).toBe(1); // reservation
-
-    if (totalActive > 0) {
-      events.push("restart-deferred");
-    }
-
-    // T=2: Command finishes, enqueue replies
-    dispatcher.sendFinalReply({ text: "Adapter configured successfully!" });
-    dispatcher.sendFinalReply({ text: "Gateway will restart to apply changes." });
-    events.push("replies-enqueued");
-
-    // Now pending should be 3 (reservation + 2 replies)
-    expect(getTotalPendingReplies()).toBe(3);
-
-    // Mark command complete (flags reservation for cleanup on last delivery)
-    dispatcher.markComplete();
-    events.push("command-complete");
-
-    // Reservation still counted until delivery .finally() clears it,
-    // but the important invariant is pending > 0 while deliveries are in flight.
-    expect(getTotalPendingReplies()).toBeGreaterThan(0);
-
-    // T=3: Wait for replies to be delivered
-    await dispatcher.waitForIdle();
-    events.push("dispatcher-idle");
-
-    // Replies should be delivered
-    expect(deliveredReplies).toHaveLength(2);
-    expect(deliveredReplies[0].text).toBe("Adapter configured successfully!");
-    expect(deliveredReplies[1].text).toBe("Gateway will restart to apply changes.");
-
-    // Pending should be 0
-    expect(getTotalPendingReplies()).toBe(0);
-
-    // T=4: Check if restart can proceed
-    const finalQueueSize = getTotalQueueSize();
-    const finalPendingReplies = getTotalPendingReplies();
-    const finalTotalActive = finalQueueSize + finalPendingReplies;
-
-    events.push(
-      `restart-check: queue=${finalQueueSize} pending=${finalPendingReplies} total=${finalTotalActive}`,
-    );
-
-    // Everything should be idle now
-    expect(finalTotalActive).toBe(0);
-    events.push("restart-can-proceed");
-
-    // Verify event sequence
-    expect(events).toEqual([
-      "message-received",
-      "dispatcher-created",
-      "config-change-detected",
-      "defer-check: queue=0 pending=1 total=1",
-      "restart-deferred",
-      "replies-enqueued",
-      "command-complete",
-      "reply-delivered: Adapter configured successfully!",
-      "reply-delivered: Gateway will restart to apply changes.",
-      "dispatcher-idle",
-      "restart-check: queue=0 pending=0 total=0",
-      "restart-can-proceed",
-    ]);
-  });
-});
diff --git a/src/gateway/server-reload.real-scenario.test.ts b/src/gateway/server-restart-deferral.test.ts
similarity index 56%
rename from src/gateway/server-reload.real-scenario.test.ts
rename to src/gateway/server-restart-deferral.test.ts
index f26f660dc79..787e6d55d02 100644
--- a/src/gateway/server-reload.real-scenario.test.ts
+++ b/src/gateway/server-restart-deferral.test.ts
@@ -1,13 +1,17 @@
-/**
- * REAL scenario test - simulates actual message handling with config changes.
- * This test MUST fail if "imsg rpc not running" would occur in production.
- */
-import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   clearAllDispatchers,
   getTotalPendingReplies,
 } from "../auto-reply/reply/dispatcher-registry.js";
 import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js";
+import { getTotalQueueSize } from "../process/command-queue.js";
+
+async function flushMicrotasks(count = 10): Promise<void> {
+  for (let i = 0; i < count; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+}
 
 function createDeferred<T = void>() {
   let resolve!: (value: T | PromiseLike<T>) => void;
@@ -19,7 +23,7 @@ function createDeferred<T = void>() {
   return { promise, resolve, reject };
 }
 
-describe("real scenario: config change during message processing", () => {
+describe("gateway restart deferral", () => {
   let replyErrors: string[] = [];
 
   beforeEach(() => {
@@ -29,12 +33,11 @@ describe("real scenario: config change during message processing", () => {
 
   afterEach(async () => {
     vi.restoreAllMocks();
-    // Wait for any pending microtasks (from markComplete()) to complete
-    await Promise.resolve();
+    await flushMicrotasks();
     clearAllDispatchers();
   });
 
-  it("should NOT restart gateway while reply delivery is in flight", async () => {
+  it("defers restart while reply delivery is in flight", async () => {
     let rpcConnected = true;
     const deliveredReplies: string[] = [];
     const deliveryStarted = createDeferred();
@@ -53,7 +56,7 @@ describe("real scenario: config change during message processing", () => {
         deliveredReplies.push(payload.text ?? "");
       },
       onError: () => {
-        // Swallow delivery errors so the test can assert on replyErrors
+        // Swallow delivery errors so the test can assert on replyErrors.
       },
     });
 
@@ -64,15 +67,11 @@ describe("real scenario: config change during message processing", () => {
     dispatcher.markComplete();
     await deliveryStarted.promise;
 
-    // At this point: markComplete flagged, delivery is in flight.
-    // pending > 0 because the in-flight delivery keeps it alive.
-    const pendingDuringDelivery = getTotalPendingReplies();
-    expect(pendingDuringDelivery).toBeGreaterThan(0);
+    // At this point: delivery is in flight; pending > 0 prevents restart.
+    expect(getTotalPendingReplies()).toBeGreaterThan(0);
 
-    // Simulate restart checks while delivery is in progress.
-    // If the tracking is broken, pending would be 0 and we'd restart.
     let restartTriggered = false;
-    for (let i = 0; i < 3; i++) {
+    for (let i = 0; i < 3; i += 1) {
       await Promise.resolve();
       const pending = getTotalPendingReplies();
       if (pending === 0) {
@@ -83,54 +82,83 @@ describe("real scenario: config change during message processing", () => {
     }
 
     allowDelivery.resolve();
-    // Wait for delivery to complete
     await dispatcher.waitForIdle();
 
-    // Now pending should be 0 — restart can proceed
     expect(getTotalPendingReplies()).toBe(0);
-
-    // CRITICAL: delivery must have succeeded without RPC being killed
     expect(restartTriggered).toBe(false);
     expect(replyErrors).toEqual([]);
     expect(deliveredReplies).toEqual(["Configuration updated!"]);
   });
 
-  it("should keep pending > 0 until reply is actually enqueued", async () => {
+  it("keeps pending > 0 until the reply is actually enqueued", async () => {
     const allowDelivery = createDeferred();
 
     const dispatcher = createReplyDispatcher({
-      deliver: async (_payload) => {
+      deliver: async () => {
         await allowDelivery.promise;
       },
     });
 
-    // Initially: pending=1 (reservation)
     expect(getTotalPendingReplies()).toBe(1);
 
-    // Simulate command processing delay BEFORE reply is enqueued
     await Promise.resolve();
-
-    // During this delay, pending should STILL be 1 (reservation active)
     expect(getTotalPendingReplies()).toBe(1);
 
-    // Now enqueue reply
     dispatcher.sendFinalReply({ text: "Reply" });
-
-    // Now pending should be 2 (reservation + reply)
     expect(getTotalPendingReplies()).toBe(2);
 
-    // Mark complete
     dispatcher.markComplete();
-
-    // After markComplete, pending should still be > 0 if reply hasn't sent yet
-    const pendingAfterMarkComplete = getTotalPendingReplies();
-    expect(pendingAfterMarkComplete).toBeGreaterThan(0);
+    expect(getTotalPendingReplies()).toBeGreaterThan(0);
 
     allowDelivery.resolve();
-    // Wait for reply to send
+    await dispatcher.waitForIdle();
+    expect(getTotalPendingReplies()).toBe(0);
+  });
+
+  it("defers restart until reply dispatcher completes", async () => {
+    const deliveredReplies: string[] = [];
+    const dispatcher = createReplyDispatcher({
+      deliver: async (payload) => {
+        await Promise.resolve();
+        deliveredReplies.push(payload.text ?? "");
+      },
+      onError: (err) => {
+        throw err;
+      },
+    });
+
+    expect(getTotalPendingReplies()).toBe(1);
+
+    dispatcher.sendFinalReply({ text: "Configuration updated successfully!" });
+    expect(getTotalPendingReplies()).toBe(2);
+
+    dispatcher.markComplete();
+    expect(getTotalPendingReplies()).toBeGreaterThan(0);
+
     await dispatcher.waitForIdle();
 
-    // Now pending should be 0
+    expect(getTotalPendingReplies()).toBe(0);
+    expect(deliveredReplies).toEqual(["Configuration updated successfully!"]);
+    expect(getTotalQueueSize()).toBe(0);
+  });
+
+  it("clears dispatcher reservation when no replies were sent", async () => {
+    let deliverCalled = false;
+    const dispatcher = createReplyDispatcher({
+      deliver: async () => {
+        deliverCalled = true;
+      },
+    });
+
+    expect(getTotalPendingReplies()).toBe(1);
+
+    dispatcher.markComplete();
+    await flushMicrotasks();
+
+    expect(getTotalPendingReplies()).toBe(0);
+    await dispatcher.waitForIdle();
+
+    expect(deliverCalled).toBe(false);
     expect(getTotalPendingReplies()).toBe(0);
   });
 });
diff --git a/src/gateway/server-utils.test.ts b/src/gateway/server-utils.test.ts
deleted file mode 100644
index 830868a2193..00000000000
--- a/src/gateway/server-utils.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { defaultVoiceWakeTriggers } from "../infra/voicewake.js";
-import { formatError, normalizeVoiceWakeTriggers } from "./server-utils.js";
-
-describe("normalizeVoiceWakeTriggers", () => {
-  test("returns defaults when input is empty", () => {
-    expect(normalizeVoiceWakeTriggers([])).toEqual(defaultVoiceWakeTriggers());
-    expect(normalizeVoiceWakeTriggers(null)).toEqual(defaultVoiceWakeTriggers());
-  });
-
-  test("trims and limits entries", () => {
-    const result = normalizeVoiceWakeTriggers(["  hello  ", "", "world"]);
-    expect(result).toEqual(["hello", "world"]);
-  });
-});
-
-describe("formatError", () => {
-  test("prefers message for Error", () => {
-    expect(formatError(new Error("boom"))).toBe("boom");
-  });
-
-  test("handles status/code", () => {
-    expect(formatError({ status: 500, code: "EPIPE" })).toBe("status=500 code=EPIPE");
-    expect(formatError({ status: 404 })).toBe("status=404 code=unknown");
-    expect(formatError({ code: "ENOENT" })).toBe("status=unknown code=ENOENT");
-  });
-});
diff --git a/src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts b/src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts
index ed6b9d4cce2..6a6f2f74ed7 100644
--- a/src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts
+++ b/src/gateway/server.agent.gateway-server-agent-a.e2e.test.ts
@@ -3,8 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
-import type { PluginRegistry } from "../plugins/registry.js";
 import { setRegistry } from "./server.agent.gateway-server-agent.mocks.js";
+import { createRegistry } from "./server.e2e-registry-helpers.js";
 import {
   agentCommand,
   connectOk,
@@ -42,19 +42,6 @@ function expectChannels(call: Record<string, unknown>, channel: string) {
   expect(runContext?.messageChannel).toBe(channel);
 }
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
 const createStubChannelPlugin = (params: {
   id: ChannelPlugin["id"];
   label: string;
diff --git a/src/gateway/server.agent.gateway-server-agent-b.e2e.test.ts b/src/gateway/server.agent.gateway-server-agent-b.e2e.test.ts
index 2bbe39ecf02..362f3fb7d17 100644
--- a/src/gateway/server.agent.gateway-server-agent-b.e2e.test.ts
+++ b/src/gateway/server.agent.gateway-server-agent-b.e2e.test.ts
@@ -4,22 +4,21 @@ import path from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
 import { WebSocket } from "ws";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
-import type { PluginRegistry } from "../plugins/registry.js";
 import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
 import { BARE_SESSION_RESET_PROMPT } from "../auto-reply/reply/session-reset-prompt.js";
 import { emitAgentEvent, registerAgentRunContext } from "../infra/agent-events.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
 import { setRegistry } from "./server.agent.gateway-server-agent.mocks.js";
+import { createRegistry } from "./server.e2e-registry-helpers.js";
 import {
   agentCommand,
   connectOk,
-  getFreePort,
   installGatewayTestHooks,
   onceMessage,
   rpcReq,
-  startGatewayServer,
   startServerWithClient,
   testState,
+  withGatewayServer,
   writeSessionStore,
 } from "./test-helpers.js";
 
@@ -42,22 +41,6 @@ afterAll(async () => {
   await server.close();
 });
 
-const _BASE_IMAGE_PNG =
-  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+X3mIAAAAASUVORK5CYII=";
-
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
 const createMSTeamsPlugin = (params?: { aliases?: string[] }): ChannelPlugin => ({
   id: "msteams",
   meta: {
@@ -342,52 +325,50 @@ describe("gateway server agent", () => {
   });
 
   test("agent dedupe survives reconnect", { timeout: 60_000 }, async () => {
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
+    await withGatewayServer(async ({ port }) => {
+      const dial = async () => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+        await new Promise<void>((resolve) => ws.once("open", resolve));
+        await connectOk(ws);
+        return ws;
+      };
 
-    const dial = async () => {
-      const ws = new WebSocket(`ws://127.0.0.1:${port}`);
-      await new Promise<void>((resolve) => ws.once("open", resolve));
-      await connectOk(ws);
-      return ws;
-    };
+      const idem = "reconnect-agent";
+      const ws1 = await dial();
+      const final1P = onceMessage(
+        ws1,
+        (o) => o.type === "res" && o.id === "ag1" && o.payload?.status !== "accepted",
+        6000,
+      );
+      ws1.send(
+        JSON.stringify({
+          type: "req",
+          id: "ag1",
+          method: "agent",
+          params: { message: "hi", idempotencyKey: idem },
+        }),
+      );
+      const final1 = await final1P;
+      ws1.close();
 
-    const idem = "reconnect-agent";
-    const ws1 = await dial();
-    const final1P = onceMessage(
-      ws1,
-      (o) => o.type === "res" && o.id === "ag1" && o.payload?.status !== "accepted",
-      6000,
-    );
-    ws1.send(
-      JSON.stringify({
-        type: "req",
-        id: "ag1",
-        method: "agent",
-        params: { message: "hi", idempotencyKey: idem },
-      }),
-    );
-    const final1 = await final1P;
-    ws1.close();
-
-    const ws2 = await dial();
-    const final2P = onceMessage(
-      ws2,
-      (o) => o.type === "res" && o.id === "ag2" && o.payload?.status !== "accepted",
-      6000,
-    );
-    ws2.send(
-      JSON.stringify({
-        type: "req",
-        id: "ag2",
-        method: "agent",
-        params: { message: "hi again", idempotencyKey: idem },
-      }),
-    );
-    const res = await final2P;
-    expect(res.payload).toEqual(final1.payload);
-    ws2.close();
-    await server.close();
+      const ws2 = await dial();
+      const final2P = onceMessage(
+        ws2,
+        (o) => o.type === "res" && o.id === "ag2" && o.payload?.status !== "accepted",
+        6000,
+      );
+      ws2.send(
+        JSON.stringify({
+          type: "req",
+          id: "ag2",
+          method: "agent",
+          params: { message: "hi again", idempotencyKey: idem },
+        }),
+      );
+      const res = await final2P;
+      expect(res.payload).toEqual(final1.payload);
+      ws2.close();
+    });
   });
 
   test("agent events stream to webchat clients when run context is registered", async () => {
diff --git a/src/gateway/server.auth.e2e.test.ts b/src/gateway/server.auth.e2e.test.ts
index 91fb4cefcd9..71acddfc3cf 100644
--- a/src/gateway/server.auth.e2e.test.ts
+++ b/src/gateway/server.auth.e2e.test.ts
@@ -14,6 +14,7 @@ import {
   startServerWithClient,
   testTailscaleWhois,
   testState,
+  withGatewayServer,
 } from "./test-helpers.js";
 
 installGatewayTestHooks({ scope: "suite" });
@@ -596,62 +597,64 @@ describe("gateway server auth/connect", () => {
     } as any);
     const prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
     process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
-      headers: {
-        origin: "https://localhost",
-        "x-forwarded-for": "203.0.113.10",
-      },
-    });
-    const challengePromise = onceMessage<{ payload?: unknown }>(
-      ws,
-      (o) => o.type === "event" && o.event === "connect.challenge",
-    );
-    await new Promise<void>((resolve) => ws.once("open", resolve));
-    const challenge = await challengePromise;
-    const nonce = (challenge.payload as { nonce?: unknown } | undefined)?.nonce;
-    expect(typeof nonce).toBe("string");
-    const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
-      await import("../infra/device-identity.js");
-    const identity = loadOrCreateDeviceIdentity();
-    const scopes = ["operator.admin", "operator.approvals", "operator.pairing"];
-    const signedAtMs = Date.now();
-    const payload = buildDeviceAuthPayload({
-      deviceId: identity.deviceId,
-      clientId: GATEWAY_CLIENT_NAMES.CONTROL_UI,
-      clientMode: GATEWAY_CLIENT_MODES.WEBCHAT,
-      role: "operator",
-      scopes,
-      signedAtMs,
-      token: "secret",
-      nonce: String(nonce),
-    });
-    const device = {
-      id: identity.deviceId,
-      publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
-      signature: signDevicePayload(identity.privateKeyPem, payload),
-      signedAt: signedAtMs,
-      nonce: String(nonce),
-    };
-    const res = await connectReq(ws, {
-      token: "secret",
-      scopes,
-      device,
-      client: {
-        id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
-        version: "1.0.0",
-        platform: "web",
-        mode: GATEWAY_CLIENT_MODES.WEBCHAT,
-      },
-    });
-    expect(res.ok).toBe(true);
-    ws.close();
-    await server.close();
-    if (prevToken === undefined) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
+    try {
+      await withGatewayServer(async ({ port }) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
+          headers: {
+            origin: "https://localhost",
+            "x-forwarded-for": "203.0.113.10",
+          },
+        });
+        const challengePromise = onceMessage<{ payload?: unknown }>(
+          ws,
+          (o) => o.type === "event" && o.event === "connect.challenge",
+        );
+        await new Promise<void>((resolve) => ws.once("open", resolve));
+        const challenge = await challengePromise;
+        const nonce = (challenge.payload as { nonce?: unknown } | undefined)?.nonce;
+        expect(typeof nonce).toBe("string");
+        const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
+          await import("../infra/device-identity.js");
+        const identity = loadOrCreateDeviceIdentity();
+        const scopes = ["operator.admin", "operator.approvals", "operator.pairing"];
+        const signedAtMs = Date.now();
+        const payload = buildDeviceAuthPayload({
+          deviceId: identity.deviceId,
+          clientId: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+          clientMode: GATEWAY_CLIENT_MODES.WEBCHAT,
+          role: "operator",
+          scopes,
+          signedAtMs,
+          token: "secret",
+          nonce: String(nonce),
+        });
+        const device = {
+          id: identity.deviceId,
+          publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
+          signature: signDevicePayload(identity.privateKeyPem, payload),
+          signedAt: signedAtMs,
+          nonce: String(nonce),
+        };
+        const res = await connectReq(ws, {
+          token: "secret",
+          scopes,
+          device,
+          client: {
+            id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+            version: "1.0.0",
+            platform: "web",
+            mode: GATEWAY_CLIENT_MODES.WEBCHAT,
+          },
+        });
+        expect(res.ok).toBe(true);
+        ws.close();
+      });
+    } finally {
+      if (prevToken === undefined) {
+        delete process.env.OPENCLAW_GATEWAY_TOKEN;
+      } else {
+        process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
+      }
     }
   });
 
@@ -660,46 +663,51 @@ describe("gateway server auth/connect", () => {
     testState.gatewayAuth = { mode: "token", token: "secret" };
     const prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
     process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    const ws = await openWs(port, { origin: originForPort(port) });
-    const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
-      await import("../infra/device-identity.js");
-    const identity = loadOrCreateDeviceIdentity();
-    const signedAtMs = Date.now() - 60 * 60 * 1000;
-    const payload = buildDeviceAuthPayload({
-      deviceId: identity.deviceId,
-      clientId: GATEWAY_CLIENT_NAMES.CONTROL_UI,
-      clientMode: GATEWAY_CLIENT_MODES.WEBCHAT,
-      role: "operator",
-      scopes: [],
-      signedAtMs,
-      token: "secret",
-    });
-    const device = {
-      id: identity.deviceId,
-      publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
-      signature: signDevicePayload(identity.privateKeyPem, payload),
-      signedAt: signedAtMs,
-    };
-    const res = await connectReq(ws, {
-      token: "secret",
-      device,
-      client: {
-        id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
-        version: "1.0.0",
-        platform: "web",
-        mode: GATEWAY_CLIENT_MODES.WEBCHAT,
-      },
-    });
-    expect(res.ok).toBe(true);
-    expect((res.payload as { auth?: unknown } | undefined)?.auth).toBeUndefined();
-    ws.close();
-    await server.close();
-    if (prevToken === undefined) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
+    try {
+      await withGatewayServer(async ({ port }) => {
+        const ws = await openWs(port, { origin: originForPort(port) });
+        const { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload } =
+          await import("../infra/device-identity.js");
+        const identity = loadOrCreateDeviceIdentity();
+        const signedAtMs = Date.now() - 60 * 60 * 1000;
+        const payload = buildDeviceAuthPayload({
+          deviceId: identity.deviceId,
+          clientId: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+          clientMode: GATEWAY_CLIENT_MODES.WEBCHAT,
+          role: "operator",
+          scopes: [],
+          signedAtMs,
+          token: "secret",
+        });
+        const device = {
+          id: identity.deviceId,
+          publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
+          signature: signDevicePayload(identity.privateKeyPem, payload),
+          signedAt: signedAtMs,
+        };
+        const res = await connectReq(ws, {
+          token: "secret",
+          scopes: ["operator.read"],
+          device,
+          client: {
+            id: GATEWAY_CLIENT_NAMES.CONTROL_UI,
+            version: "1.0.0",
+            platform: "web",
+            mode: GATEWAY_CLIENT_MODES.WEBCHAT,
+          },
+        });
+        expect(res.ok).toBe(true);
+        expect((res.payload as { auth?: unknown } | undefined)?.auth).toBeUndefined();
+        const health = await rpcReq(ws, "health");
+        expect(health.ok).toBe(true);
+        ws.close();
+      });
+    } finally {
+      if (prevToken === undefined) {
+        delete process.env.OPENCLAW_GATEWAY_TOKEN;
+      } else {
+        process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
+      }
     }
   });
 
diff --git a/src/gateway/server.channels.e2e.test.ts b/src/gateway/server.channels.e2e.test.ts
index c65b87c103a..87661d846b3 100644
--- a/src/gateway/server.channels.e2e.test.ts
+++ b/src/gateway/server.channels.e2e.test.ts
@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import type { PluginRegistry } from "../plugins/registry.js";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
+import { createRegistry } from "./server.e2e-registry-helpers.js";
 import {
   connectOk,
   installGatewayTestHooks,
@@ -41,19 +42,6 @@ vi.mock("./server-plugins.js", async () => {
   };
 });
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
 const createStubChannelPlugin = (params: {
   id: ChannelPlugin["id"];
   label: string;
diff --git a/src/gateway/server.cron.e2e.test.ts b/src/gateway/server.cron.e2e.test.ts
index 94e52d99b4d..cd05a3b96ad 100644
--- a/src/gateway/server.cron.e2e.test.ts
+++ b/src/gateway/server.cron.e2e.test.ts
@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import {
   connectOk,
+  cronIsolatedRun,
   installGatewayTestHooks,
   rpcReq,
   startServerWithClient,
@@ -50,6 +51,20 @@ async function waitForNonEmptyFile(pathname: string, timeoutMs = 2000) {
   }
 }
 
+async function waitForCondition(check: () => boolean, timeoutMs = 2000) {
+  const startedAt = process.hrtime.bigint();
+  for (;;) {
+    if (check()) {
+      return;
+    }
+    const elapsedMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
+    if (elapsedMs >= timeoutMs) {
+      throw new Error("timeout waiting for condition");
+    }
+    await yieldToEventLoop();
+  }
+}
+
 describe("gateway server cron", () => {
   test("handles cron CRUD, normalization, and patch semantics", { timeout: 120_000 }, async () => {
     const prevSkipCron = process.env.OPENCLAW_SKIP_CRON;
@@ -72,6 +87,7 @@ describe("gateway server cron", () => {
         sessionTarget: "main",
         wakeMode: "next-heartbeat",
         payload: { kind: "systemEvent", text: "hello" },
+        delivery: { mode: "webhook", to: "https://example.invalid/cron-finished" },
       });
       expect(addRes.ok).toBe(true);
       expect(typeof (addRes.payload as { id?: unknown } | null)?.id).toBe("string");
@@ -84,6 +100,9 @@ describe("gateway server cron", () => {
       expect(Array.isArray(jobs)).toBe(true);
       expect((jobs as unknown[]).length).toBe(1);
       expect(((jobs as Array<{ name?: unknown }>)[0]?.name as string) ?? "").toBe("daily");
+      expect(
+        ((jobs as Array<{ delivery?: { mode?: unknown } }>)[0]?.delivery?.mode as string) ?? "",
+      ).toBe("webhook");
 
       const routeAtMs = Date.now() - 1;
       const routeRes = await rpcReq(ws, "cron.add", {
@@ -403,4 +422,182 @@ describe("gateway server cron", () => {
       }
     }
   }, 45_000);
+
+  test("posts webhooks for delivery mode and legacy notify fallback only when summary exists", async () => {
+    const prevSkipCron = process.env.OPENCLAW_SKIP_CRON;
+    process.env.OPENCLAW_SKIP_CRON = "0";
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-gw-cron-webhook-"));
+    testState.cronStorePath = path.join(dir, "cron", "jobs.json");
+    testState.cronEnabled = false;
+    await fs.mkdir(path.dirname(testState.cronStorePath), { recursive: true });
+
+    const legacyNotifyJob = {
+      id: "legacy-notify-job",
+      name: "legacy notify job",
+      enabled: true,
+      notify: true,
+      createdAtMs: Date.now(),
+      updatedAtMs: Date.now(),
+      schedule: { kind: "every", everyMs: 60_000 },
+      sessionTarget: "main",
+      wakeMode: "next-heartbeat",
+      payload: { kind: "systemEvent", text: "legacy webhook" },
+      state: {},
+    };
+    await fs.writeFile(
+      testState.cronStorePath,
+      JSON.stringify({ version: 1, jobs: [legacyNotifyJob] }),
+    );
+
+    const configPath = process.env.OPENCLAW_CONFIG_PATH;
+    expect(typeof configPath).toBe("string");
+    await fs.mkdir(path.dirname(configPath as string), { recursive: true });
+    await fs.writeFile(
+      configPath as string,
+      JSON.stringify(
+        {
+          cron: {
+            webhook: "https://legacy.example.invalid/cron-finished",
+            webhookToken: "cron-webhook-token",
+          },
+        },
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+
+    const fetchMock = vi.fn(async () => new Response("ok", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws);
+
+    try {
+      const invalidWebhookRes = await rpcReq(ws, "cron.add", {
+        name: "invalid webhook",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "invalid" },
+        delivery: { mode: "webhook", to: "ftp://example.invalid/cron-finished" },
+      });
+      expect(invalidWebhookRes.ok).toBe(false);
+
+      const notifyRes = await rpcReq(ws, "cron.add", {
+        name: "webhook enabled",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "send webhook" },
+        delivery: { mode: "webhook", to: "https://example.invalid/cron-finished" },
+      });
+      expect(notifyRes.ok).toBe(true);
+      const notifyJobIdValue = (notifyRes.payload as { id?: unknown } | null)?.id;
+      const notifyJobId = typeof notifyJobIdValue === "string" ? notifyJobIdValue : "";
+      expect(notifyJobId.length > 0).toBe(true);
+
+      const notifyRunRes = await rpcReq(ws, "cron.run", { id: notifyJobId, mode: "force" }, 20_000);
+      expect(notifyRunRes.ok).toBe(true);
+
+      await waitForCondition(() => fetchMock.mock.calls.length === 1, 5000);
+      const [notifyUrl, notifyInit] = fetchMock.mock.calls[0] as [
+        string,
+        {
+          method?: string;
+          headers?: Record<string, string>;
+          body?: string;
+        },
+      ];
+      expect(notifyUrl).toBe("https://example.invalid/cron-finished");
+      expect(notifyInit.method).toBe("POST");
+      expect(notifyInit.headers?.Authorization).toBe("Bearer cron-webhook-token");
+      expect(notifyInit.headers?.["Content-Type"]).toBe("application/json");
+      const notifyBody = JSON.parse(notifyInit.body ?? "{}");
+      expect(notifyBody.action).toBe("finished");
+      expect(notifyBody.jobId).toBe(notifyJobId);
+
+      const legacyRunRes = await rpcReq(
+        ws,
+        "cron.run",
+        { id: "legacy-notify-job", mode: "force" },
+        20_000,
+      );
+      expect(legacyRunRes.ok).toBe(true);
+      await waitForCondition(() => fetchMock.mock.calls.length === 2, 5000);
+      const [legacyUrl, legacyInit] = fetchMock.mock.calls[1] as [
+        string,
+        {
+          method?: string;
+          headers?: Record<string, string>;
+          body?: string;
+        },
+      ];
+      expect(legacyUrl).toBe("https://legacy.example.invalid/cron-finished");
+      expect(legacyInit.method).toBe("POST");
+      expect(legacyInit.headers?.Authorization).toBe("Bearer cron-webhook-token");
+      const legacyBody = JSON.parse(legacyInit.body ?? "{}");
+      expect(legacyBody.action).toBe("finished");
+      expect(legacyBody.jobId).toBe("legacy-notify-job");
+
+      const silentRes = await rpcReq(ws, "cron.add", {
+        name: "webhook disabled",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "do not send" },
+      });
+      expect(silentRes.ok).toBe(true);
+      const silentJobIdValue = (silentRes.payload as { id?: unknown } | null)?.id;
+      const silentJobId = typeof silentJobIdValue === "string" ? silentJobIdValue : "";
+      expect(silentJobId.length > 0).toBe(true);
+
+      const silentRunRes = await rpcReq(ws, "cron.run", { id: silentJobId, mode: "force" }, 20_000);
+      expect(silentRunRes.ok).toBe(true);
+      await yieldToEventLoop();
+      await yieldToEventLoop();
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      cronIsolatedRun.mockResolvedValueOnce({ status: "ok" });
+      const noSummaryRes = await rpcReq(ws, "cron.add", {
+        name: "webhook no summary",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 60_000 },
+        sessionTarget: "isolated",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "agentTurn", message: "test" },
+        delivery: { mode: "webhook", to: "https://example.invalid/cron-finished" },
+      });
+      expect(noSummaryRes.ok).toBe(true);
+      const noSummaryJobIdValue = (noSummaryRes.payload as { id?: unknown } | null)?.id;
+      const noSummaryJobId = typeof noSummaryJobIdValue === "string" ? noSummaryJobIdValue : "";
+      expect(noSummaryJobId.length > 0).toBe(true);
+
+      const noSummaryRunRes = await rpcReq(
+        ws,
+        "cron.run",
+        { id: noSummaryJobId, mode: "force" },
+        20_000,
+      );
+      expect(noSummaryRunRes.ok).toBe(true);
+      await yieldToEventLoop();
+      await yieldToEventLoop();
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    } finally {
+      ws.close();
+      await server.close();
+      await rmTempDir(dir);
+      vi.unstubAllGlobals();
+      testState.cronStorePath = undefined;
+      testState.cronEnabled = undefined;
+      if (prevSkipCron === undefined) {
+        delete process.env.OPENCLAW_SKIP_CRON;
+      } else {
+        process.env.OPENCLAW_SKIP_CRON = prevSkipCron;
+      }
+    }
+  }, 60_000);
 });
diff --git a/src/gateway/server.e2e-registry-helpers.ts b/src/gateway/server.e2e-registry-helpers.ts
new file mode 100644
index 00000000000..148d3fe8227
--- /dev/null
+++ b/src/gateway/server.e2e-registry-helpers.ts
@@ -0,0 +1,17 @@
+import type { PluginRegistry } from "../plugins/registry.js";
+
+export const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
+  plugins: [],
+  tools: [],
+  hooks: [],
+  typedHooks: [],
+  channels,
+  providers: [],
+  gatewayHandlers: {},
+  httpHandlers: [],
+  httpRoutes: [],
+  cliRegistrars: [],
+  services: [],
+  commands: [],
+  diagnostics: [],
+});
diff --git a/src/gateway/server.e2e-ws-harness.ts b/src/gateway/server.e2e-ws-harness.ts
new file mode 100644
index 00000000000..ab585d56f41
--- /dev/null
+++ b/src/gateway/server.e2e-ws-harness.ts
@@ -0,0 +1,36 @@
+import { WebSocket } from "ws";
+import { captureEnv } from "../test-utils/env.js";
+import { connectOk, getFreePort, startGatewayServer } from "./test-helpers.js";
+
+export type GatewayWsClient = {
+  ws: WebSocket;
+  hello: unknown;
+};
+
+export type GatewayServerHarness = {
+  port: number;
+  server: Awaited<ReturnType<typeof startGatewayServer>>;
+  openClient: (opts?: Parameters<typeof connectOk>[1]) => Promise<GatewayWsClient>;
+  close: () => Promise<void>;
+};
+
+export async function startGatewayServerHarness(): Promise<GatewayServerHarness> {
+  const envSnapshot = captureEnv(["OPENCLAW_GATEWAY_TOKEN"]);
+  delete process.env.OPENCLAW_GATEWAY_TOKEN;
+  const port = await getFreePort();
+  const server = await startGatewayServer(port);
+
+  const openClient = async (opts?: Parameters<typeof connectOk>[1]): Promise<GatewayWsClient> => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve) => ws.once("open", resolve));
+    const hello = await connectOk(ws, opts);
+    return { ws, hello };
+  };
+
+  const close = async () => {
+    await server.close();
+    envSnapshot.restore();
+  };
+
+  return { port, server, openClient, close };
+}
diff --git a/src/gateway/server.health.e2e.test.ts b/src/gateway/server.health.e2e.test.ts
index adab0dfd1a5..f42e7b78b3e 100644
--- a/src/gateway/server.health.e2e.test.ts
+++ b/src/gateway/server.health.e2e.test.ts
@@ -1,58 +1,26 @@
 import { randomUUID } from "node:crypto";
-import os from "node:os";
-import path from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
-import { WebSocket } from "ws";
 import { emitAgentEvent } from "../infra/agent-events.js";
-import {
-  loadOrCreateDeviceIdentity,
-  publicKeyRawBase64UrlFromPem,
-  signDevicePayload,
-} from "../infra/device-identity.js";
 import { emitHeartbeatEvent } from "../infra/heartbeat-events.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
-import { buildDeviceAuthPayload } from "./device-auth.js";
-import {
-  connectOk,
-  getFreePort,
-  installGatewayTestHooks,
-  onceMessage,
-  startGatewayServer,
-  startServerWithClient,
-} from "./test-helpers.js";
+import { startGatewayServerHarness, type GatewayServerHarness } from "./server.e2e-ws-harness.js";
+import { installGatewayTestHooks, onceMessage } from "./test-helpers.js";
 
 installGatewayTestHooks({ scope: "suite" });
 
-let server: Awaited<ReturnType<typeof startGatewayServer>>;
-let port = 0;
-let previousToken: string | undefined;
+let harness: GatewayServerHarness;
 
 beforeAll(async () => {
-  previousToken = process.env.OPENCLAW_GATEWAY_TOKEN;
-  delete process.env.OPENCLAW_GATEWAY_TOKEN;
-  port = await getFreePort();
-  server = await startGatewayServer(port);
+  harness = await startGatewayServerHarness();
 });
 
 afterAll(async () => {
-  await server.close();
-  if (previousToken === undefined) {
-    delete process.env.OPENCLAW_GATEWAY_TOKEN;
-  } else {
-    process.env.OPENCLAW_GATEWAY_TOKEN = previousToken;
-  }
+  await harness.close();
 });
 
-const openClient = async (opts?: Parameters<typeof connectOk>[1]) => {
-  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
-  await new Promise<void>((resolve) => ws.once("open", resolve));
-  await connectOk(ws, opts);
-  return ws;
-};
-
 describe("gateway server health/presence", () => {
   test("connect + health + presence + status succeed", { timeout: 60_000 }, async () => {
-    const ws = await openClient();
+    const { ws } = await harness.openClient();
 
     const healthP = onceMessage(ws, (o) => o.type === "res" && o.id === "health1");
     const statusP = onceMessage(ws, (o) => o.type === "res" && o.id === "status1");
@@ -101,7 +69,7 @@ describe("gateway server health/presence", () => {
       payload?: unknown;
     };
 
-    const ws = await openClient();
+    const { ws } = await harness.openClient();
 
     const waitHeartbeat = onceMessage<EventFrame>(
       ws,
@@ -144,7 +112,7 @@ describe("gateway server health/presence", () => {
   });
 
   test("presence events carry seq + stateVersion", { timeout: 8000 }, async () => {
-    const ws = await openClient();
+    const { ws } = await harness.openClient();
 
     const presenceEventP = onceMessage(ws, (o) => o.type === "event" && o.event === "presence");
     ws.send(
@@ -165,7 +133,7 @@ describe("gateway server health/presence", () => {
   });
 
   test("agent events stream with seq", { timeout: 8000 }, async () => {
-    const ws = await openClient();
+    const { ws } = await harness.openClient();
 
     const runId = randomUUID();
     const evtPromise = onceMessage(
@@ -186,21 +154,24 @@ describe("gateway server health/presence", () => {
   });
 
   test("shutdown event is broadcast on close", { timeout: 8000 }, async () => {
-    const { server, ws } = await startServerWithClient();
-    await connectOk(ws);
-
+    const localHarness = await startGatewayServerHarness();
+    const { ws } = await localHarness.openClient();
     const shutdownP = onceMessage(ws, (o) => o.type === "event" && o.event === "shutdown", 5000);
-    await server.close();
+    await localHarness.close();
     const evt = await shutdownP;
     expect(evt.payload?.reason).toBeDefined();
   });
 
   test("presence broadcast reaches multiple clients", { timeout: 8000 }, async () => {
-    const clients = await Promise.all([openClient(), openClient(), openClient()]);
-    const waits = clients.map((c) =>
-      onceMessage(c, (o) => o.type === "event" && o.event === "presence"),
+    const clients = await Promise.all([
+      harness.openClient(),
+      harness.openClient(),
+      harness.openClient(),
+    ]);
+    const waits = clients.map(({ ws }) =>
+      onceMessage(ws, (o) => o.type === "event" && o.event === "presence"),
     );
-    clients[0].send(
+    clients[0].ws.send(
       JSON.stringify({
         type: "req",
         id: "broadcast",
@@ -213,31 +184,17 @@ describe("gateway server health/presence", () => {
       expect(evt.payload?.presence?.length).toBeGreaterThan(0);
       expect(typeof evt.seq).toBe("number");
     }
-    for (const c of clients) {
-      c.close();
+    for (const { ws } of clients) {
+      ws.close();
     }
   });
 
   test("presence includes client fingerprint", async () => {
-    const identityPath = path.join(os.tmpdir(), `openclaw-device-${randomUUID()}.json`);
-    const identity = loadOrCreateDeviceIdentity(identityPath);
-    const token = process.env.OPENCLAW_GATEWAY_TOKEN?.trim() || undefined;
     const role = "operator";
     const scopes: string[] = ["operator.admin"];
-    const signedAtMs = Date.now();
-    const payload = buildDeviceAuthPayload({
-      deviceId: identity.deviceId,
-      clientId: GATEWAY_CLIENT_NAMES.FINGERPRINT,
-      clientMode: GATEWAY_CLIENT_MODES.UI,
+    const { ws } = await harness.openClient({
       role,
       scopes,
-      signedAtMs,
-      token: token ?? null,
-    });
-    const ws = await openClient({
-      role,
-      scopes,
-      token,
       client: {
         id: GATEWAY_CLIENT_NAMES.FINGERPRINT,
         version: "9.9.9",
@@ -247,12 +204,6 @@ describe("gateway server health/presence", () => {
         mode: GATEWAY_CLIENT_MODES.UI,
         instanceId: "abc",
       },
-      device: {
-        id: identity.deviceId,
-        publicKey: publicKeyRawBase64UrlFromPem(identity.publicKeyPem),
-        signature: signDevicePayload(identity.privateKeyPem, payload),
-        signedAt: signedAtMs,
-      },
     });
 
     const presenceP = onceMessage(ws, (o) => o.type === "res" && o.id === "fingerprint", 4000);
@@ -286,7 +237,7 @@ describe("gateway server health/presence", () => {
 
   test("cli connections are not tracked as instances", async () => {
     const cliId = `cli-${randomUUID()}`;
-    const ws = await openClient({
+    const { ws } = await harness.openClient({
       client: {
         id: GATEWAY_CLIENT_NAMES.CLI,
         version: "dev",
diff --git a/src/gateway/server.hooks.e2e.test.ts b/src/gateway/server.hooks.e2e.test.ts
index 3056858496f..7e0a8a484da 100644
--- a/src/gateway/server.hooks.e2e.test.ts
+++ b/src/gateway/server.hooks.e2e.test.ts
@@ -3,10 +3,9 @@ import { resolveMainSessionKeyFromConfig } from "../config/sessions.js";
 import { drainSystemEvents, peekSystemEvents } from "../infra/system-events.js";
 import {
   cronIsolatedRun,
-  getFreePort,
   installGatewayTestHooks,
-  startGatewayServer,
   testState,
+  withGatewayServer,
   waitForSystemEvent,
 } from "./test-helpers.js";
 
@@ -20,9 +19,7 @@ describe("gateway server hooks", () => {
     testState.agentsConfig = {
       list: [{ id: "main", default: true }, { id: "hooks" }],
     };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       const resNoAuth = await fetch(`http://127.0.0.1:${port}/hooks/wake`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -194,16 +191,12 @@ describe("gateway server hooks", () => {
         body: "{",
       });
       expect(resBadJson.status).toBe(400);
-    } finally {
-      await server.close();
-    }
+    });
   });
 
   test("rejects request sessionKey unless hooks.allowRequestSessionKey is enabled", async () => {
     testState.hooksConfig = { enabled: true, token: "hook-secret" };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       const denied = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
         method: "POST",
         headers: {
@@ -218,9 +211,7 @@ describe("gateway server hooks", () => {
       expect(denied.status).toBe(400);
       const deniedBody = (await denied.json()) as { error?: string };
       expect(deniedBody.error).toContain("hooks.allowRequestSessionKey");
-    } finally {
-      await server.close();
-    }
+    });
   });
 
   test("respects hooks session policy for request + mapping session keys", async () => {
@@ -245,9 +236,7 @@ describe("gateway server hooks", () => {
         },
       ],
     };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       cronIsolatedRun.mockReset();
       cronIsolatedRun.mockResolvedValue({ status: "ok", summary: "done" });
 
@@ -303,9 +292,7 @@ describe("gateway server hooks", () => {
         body: JSON.stringify({ subject: "hello" }),
       });
       expect(mappedBadPrefix.status).toBe(400);
-    } finally {
-      await server.close();
-    }
+    });
   });
 
   test("enforces hooks.allowedAgentIds for explicit agent routing", async () => {
@@ -325,9 +312,7 @@ describe("gateway server hooks", () => {
     testState.agentsConfig = {
       list: [{ id: "main", default: true }, { id: "hooks" }],
     };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       cronIsolatedRun.mockReset();
       cronIsolatedRun.mockResolvedValueOnce({
         status: "ok",
@@ -394,9 +379,7 @@ describe("gateway server hooks", () => {
       const mappedDeniedBody = (await resMappedDenied.json()) as { error?: string };
       expect(mappedDeniedBody.error).toContain("hooks.allowedAgentIds");
       expect(peekSystemEvents(resolveMainKey()).length).toBe(0);
-    } finally {
-      await server.close();
-    }
+    });
   });
 
   test("denies explicit agentId when hooks.allowedAgentIds is empty", async () => {
@@ -408,9 +391,7 @@ describe("gateway server hooks", () => {
     testState.agentsConfig = {
       list: [{ id: "main", default: true }, { id: "hooks" }],
     };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       const resDenied = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
         method: "POST",
         headers: {
@@ -423,16 +404,12 @@ describe("gateway server hooks", () => {
       const deniedBody = (await resDenied.json()) as { error?: string };
       expect(deniedBody.error).toContain("hooks.allowedAgentIds");
       expect(peekSystemEvents(resolveMainKey()).length).toBe(0);
-    } finally {
-      await server.close();
-    }
+    });
   });
 
   test("throttles repeated hook auth failures and resets after success", async () => {
     testState.hooksConfig = { enabled: true, token: "hook-secret" };
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
-    try {
+    await withGatewayServer(async ({ port }) => {
       const firstFail = await fetch(`http://127.0.0.1:${port}/hooks/wake`, {
         method: "POST",
         headers: {
@@ -478,8 +455,6 @@ describe("gateway server hooks", () => {
         body: JSON.stringify({ text: "blocked" }),
       });
       expect(failAfterSuccess.status).toBe(401);
-    } finally {
-      await server.close();
-    }
+    });
   });
 });
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
index 553131377ec..0e70546467b 100644
--- a/src/gateway/server.impl.ts
+++ b/src/gateway/server.impl.ts
@@ -1,6 +1,5 @@
 import path from "node:path";
 import type { CanvasHostServer } from "../canvas-host/server.js";
-import type { PluginRegistry } from "../plugins/registry.js";
 import type { PluginServicesHandle } from "../plugins/services.js";
 import type { RuntimeEnv } from "../runtime.js";
 import type { ControlUiRootState } from "./control-ui.js";
@@ -45,6 +44,7 @@ import { scheduleGatewayUpdateCheck } from "../infra/update-startup.js";
 import { startDiagnosticHeartbeat, stopDiagnosticHeartbeat } from "../logging/diagnostic.js";
 import { createSubsystemLogger, runtimeForLogger } from "../logging/subsystem.js";
 import { getGlobalHookRunner, runGlobalGatewayStopSafely } from "../plugins/hook-runner-global.js";
+import { createEmptyPluginRegistry } from "../plugins/registry.js";
 import { getTotalQueueSize } from "../process/command-queue.js";
 import { runOnboardingWizard } from "../wizard/onboarding.js";
 import { createAuthRateLimiter, type AuthRateLimiter } from "./auth-rate-limit.js";
@@ -239,21 +239,7 @@ export async function startGatewayServer(
   const defaultAgentId = resolveDefaultAgentId(cfgAtStart);
   const defaultWorkspaceDir = resolveAgentWorkspaceDir(cfgAtStart, defaultAgentId);
   const baseMethods = listGatewayMethods();
-  const emptyPluginRegistry: PluginRegistry = {
-    plugins: [],
-    tools: [],
-    hooks: [],
-    typedHooks: [],
-    channels: [],
-    providers: [],
-    gatewayHandlers: {},
-    httpHandlers: [],
-    httpRoutes: [],
-    cliRegistrars: [],
-    services: [],
-    commands: [],
-    diagnostics: [],
-  };
+  const emptyPluginRegistry = createEmptyPluginRegistry();
   const { pluginRegistry, gatewayMethods: baseGatewayMethods } = minimalTestGateway
     ? { pluginRegistry: emptyPluginRegistry, gatewayMethods: baseMethods }
     : loadGatewayPlugins({
diff --git a/src/gateway/server.ios-client-id.e2e.test.ts b/src/gateway/server.ios-client-id.e2e.test.ts
index 37966798db7..2dfba6b42ce 100644
--- a/src/gateway/server.ios-client-id.e2e.test.ts
+++ b/src/gateway/server.ios-client-id.e2e.test.ts
@@ -61,30 +61,14 @@ function connectReq(
   );
 }
 
-test("accepts openclaw-ios as a valid gateway client id", async () => {
+test.each([
+  { clientId: "openclaw-ios", platform: "ios" },
+  { clientId: "openclaw-android", platform: "android" },
+])("accepts $clientId as a valid gateway client id", async ({ clientId, platform }) => {
   const ws = new WebSocket(`ws://127.0.0.1:${port}`);
   await new Promise<void>((resolve) => ws.once("open", resolve));
 
-  const res = await connectReq(ws, { clientId: "openclaw-ios", platform: "ios" });
-  // We don't care if auth fails here; we only care that schema validation accepts the client id.
-  // A schema rejection would close the socket before sending a response.
-  if (!res.ok) {
-    // allow unauthorized error when gateway requires auth
-    // but reject schema validation errors
-    const message = String(res.error?.message ?? "");
-    if (message.includes("invalid connect params")) {
-      throw new Error(message);
-    }
-  }
-
-  ws.close();
-});
-
-test("accepts openclaw-android as a valid gateway client id", async () => {
-  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
-  await new Promise<void>((resolve) => ws.once("open", resolve));
-
-  const res = await connectReq(ws, { clientId: "openclaw-android", platform: "android" });
+  const res = await connectReq(ws, { clientId, platform });
   // We don't care if auth fails here; we only care that schema validation accepts the client id.
   // A schema rejection would close the socket before sending a response.
   if (!res.ok) {
diff --git a/src/gateway/server.models-voicewake-misc.e2e.test.ts b/src/gateway/server.models-voicewake-misc.e2e.test.ts
index 27ae4237a5d..a89e9250270 100644
--- a/src/gateway/server.models-voicewake-misc.e2e.test.ts
+++ b/src/gateway/server.models-voicewake-misc.e2e.test.ts
@@ -5,13 +5,14 @@ import path from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { WebSocket } from "ws";
 import type { ChannelOutboundAdapter } from "../channels/plugins/types.js";
-import type { PluginRegistry } from "../plugins/registry.js";
 import { getChannelPlugin } from "../channels/plugins/index.js";
 import { resolveCanvasHostUrl } from "../infra/canvas-host-url.js";
 import { GatewayLockError } from "../infra/gateway-lock.js";
 import { getActivePluginRegistry, setActivePluginRegistry } from "../plugins/runtime.js";
 import { createOutboundTestPlugin } from "../test-utils/channel-plugins.js";
+import { captureEnv } from "../test-utils/env.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
+import { createRegistry } from "./server.e2e-registry-helpers.js";
 import {
   connectOk,
   getFreePort,
@@ -67,19 +68,6 @@ const whatsappPlugin = createOutboundTestPlugin({
   label: "WhatsApp",
 });
 
-const createRegistry = (channels: PluginRegistry["channels"]): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  channels,
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  diagnostics: [],
-});
-
 const whatsappRegistry = createRegistry([
   {
     pluginId: "whatsapp",
@@ -314,31 +302,24 @@ describe("gateway server models + voicewake", () => {
 
 describe("gateway server misc", () => {
   test("hello-ok advertises the gateway port for canvas host", async () => {
-    const prevToken = process.env.OPENCLAW_GATEWAY_TOKEN;
-    const prevCanvasPort = process.env.OPENCLAW_CANVAS_HOST_PORT;
-    process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
-    testTailnetIPv4.value = "100.64.0.1";
-    testState.gatewayBind = "lan";
-    const canvasPort = await getFreePort();
-    testState.canvasHostPort = canvasPort;
-    process.env.OPENCLAW_CANVAS_HOST_PORT = String(canvasPort);
+    const envSnapshot = captureEnv(["OPENCLAW_CANVAS_HOST_PORT", "OPENCLAW_GATEWAY_TOKEN"]);
+    try {
+      process.env.OPENCLAW_GATEWAY_TOKEN = "secret";
+      testTailnetIPv4.value = "100.64.0.1";
+      testState.gatewayBind = "lan";
+      const canvasPort = await getFreePort();
+      testState.canvasHostPort = canvasPort;
+      process.env.OPENCLAW_CANVAS_HOST_PORT = String(canvasPort);
 
-    const testPort = await getFreePort();
-    const canvasHostUrl = resolveCanvasHostUrl({
-      canvasPort,
-      requestHost: `100.64.0.1:${testPort}`,
-      localAddress: "127.0.0.1",
-    });
-    expect(canvasHostUrl).toBe(`http://100.64.0.1:${canvasPort}`);
-    if (prevToken === undefined) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
-    }
-    if (prevCanvasPort === undefined) {
-      delete process.env.OPENCLAW_CANVAS_HOST_PORT;
-    } else {
-      process.env.OPENCLAW_CANVAS_HOST_PORT = prevCanvasPort;
+      const testPort = await getFreePort();
+      const canvasHostUrl = resolveCanvasHostUrl({
+        canvasPort,
+        requestHost: `100.64.0.1:${testPort}`,
+        localAddress: "127.0.0.1",
+      });
+      expect(canvasHostUrl).toBe(`http://100.64.0.1:${canvasPort}`);
+    } finally {
+      envSnapshot.restore();
     }
   });
 
diff --git a/src/gateway/server.nodes.late-invoke.test.ts b/src/gateway/server.nodes.late-invoke.test.ts
deleted file mode 100644
index e6b2fd5f2a1..00000000000
--- a/src/gateway/server.nodes.late-invoke.test.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { describe, expect, test, vi } from "vitest";
-import type { RequestFrame } from "./protocol/index.js";
-import type { GatewayClient, GatewayRequestContext, RespondFn } from "./server-methods/types.js";
-import { handleNodeInvokeResult } from "./server-methods/nodes.handlers.invoke-result.js";
-
-describe("late-arriving invoke results", () => {
-  test("returns success for unknown invoke ids for both success and error payloads", async () => {
-    const nodeId = "node-123";
-    const cases = [
-      {
-        id: "unknown-invoke-id-12345",
-        ok: true,
-        payloadJSON: JSON.stringify({ result: "late" }),
-      },
-      {
-        id: "another-unknown-invoke-id",
-        ok: false,
-        error: { code: "FAILED", message: "test error" },
-      },
-    ] as const;
-
-    for (const params of cases) {
-      const respond = vi.fn<RespondFn>();
-      const context = {
-        nodeRegistry: { handleInvokeResult: () => false },
-        logGateway: { debug: vi.fn() },
-      } as unknown as GatewayRequestContext;
-      const client = {
-        connect: { device: { id: nodeId } },
-      } as unknown as GatewayClient;
-
-      await handleNodeInvokeResult({
-        req: { method: "node.invoke.result" } as unknown as RequestFrame,
-        params: { ...params, nodeId } as unknown as Record<string, unknown>,
-        client,
-        isWebchatConnect: () => false,
-        respond,
-        context,
-      });
-
-      const [ok, payload, error] = respond.mock.lastCall ?? [];
-
-      // Late-arriving results return success instead of error to reduce log noise.
-      expect(ok).toBe(true);
-      expect(error).toBeUndefined();
-      expect(payload?.ok).toBe(true);
-      expect(payload?.ignored).toBe(true);
-    }
-  });
-});
diff --git a/src/gateway/server.reload.e2e.test.ts b/src/gateway/server.reload.e2e.test.ts
index 7092d130e76..f3ddec1d113 100644
--- a/src/gateway/server.reload.e2e.test.ts
+++ b/src/gateway/server.reload.e2e.test.ts
@@ -1,11 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   connectOk,
-  getFreePort,
   installGatewayTestHooks,
   rpcReq,
-  startGatewayServer,
   startServerWithClient,
+  withGatewayServer,
 } from "./test-helpers.js";
 
 const hoisted = vi.hoisted(() => {
@@ -200,110 +199,107 @@ describe("gateway hot reload", () => {
   });
 
   it("applies hot reload actions and emits restart signal", async () => {
-    const port = await getFreePort();
-    const server = await startGatewayServer(port);
+    await withGatewayServer(async () => {
+      const onHotReload = hoisted.getOnHotReload();
+      expect(onHotReload).toBeTypeOf("function");
 
-    const onHotReload = hoisted.getOnHotReload();
-    expect(onHotReload).toBeTypeOf("function");
+      const nextConfig = {
+        hooks: {
+          enabled: true,
+          token: "secret",
+          gmail: { account: "me@example.com" },
+        },
+        cron: { enabled: true, store: "/tmp/cron.json" },
+        agents: { defaults: { heartbeat: { every: "1m" }, maxConcurrent: 2 } },
+        browser: { enabled: true },
+        web: { enabled: true },
+        channels: {
+          telegram: { botToken: "token" },
+          discord: { token: "token" },
+          signal: { account: "+15550000000" },
+          imessage: { enabled: true },
+        },
+      };
 
-    const nextConfig = {
-      hooks: {
-        enabled: true,
-        token: "secret",
-        gmail: { account: "me@example.com" },
-      },
-      cron: { enabled: true, store: "/tmp/cron.json" },
-      agents: { defaults: { heartbeat: { every: "1m" }, maxConcurrent: 2 } },
-      browser: { enabled: true },
-      web: { enabled: true },
-      channels: {
-        telegram: { botToken: "token" },
-        discord: { token: "token" },
-        signal: { account: "+15550000000" },
-        imessage: { enabled: true },
-      },
-    };
+      await onHotReload?.(
+        {
+          changedPaths: [
+            "hooks.gmail.account",
+            "cron.enabled",
+            "agents.defaults.heartbeat.every",
+            "browser.enabled",
+            "web.enabled",
+            "channels.telegram.botToken",
+            "channels.discord.token",
+            "channels.signal.account",
+            "channels.imessage.enabled",
+          ],
+          restartGateway: false,
+          restartReasons: [],
+          hotReasons: ["web.enabled"],
+          reloadHooks: true,
+          restartGmailWatcher: true,
+          restartBrowserControl: true,
+          restartCron: true,
+          restartHeartbeat: true,
+          restartChannels: new Set(["whatsapp", "telegram", "discord", "signal", "imessage"]),
+          noopPaths: [],
+        },
+        nextConfig,
+      );
 
-    await onHotReload?.(
-      {
-        changedPaths: [
-          "hooks.gmail.account",
-          "cron.enabled",
-          "agents.defaults.heartbeat.every",
-          "browser.enabled",
-          "web.enabled",
-          "channels.telegram.botToken",
-          "channels.discord.token",
-          "channels.signal.account",
-          "channels.imessage.enabled",
-        ],
-        restartGateway: false,
-        restartReasons: [],
-        hotReasons: ["web.enabled"],
-        reloadHooks: true,
-        restartGmailWatcher: true,
-        restartBrowserControl: true,
-        restartCron: true,
-        restartHeartbeat: true,
-        restartChannels: new Set(["whatsapp", "telegram", "discord", "signal", "imessage"]),
-        noopPaths: [],
-      },
-      nextConfig,
-    );
+      expect(hoisted.stopGmailWatcher).toHaveBeenCalled();
+      expect(hoisted.startGmailWatcher).toHaveBeenCalledWith(nextConfig);
 
-    expect(hoisted.stopGmailWatcher).toHaveBeenCalled();
-    expect(hoisted.startGmailWatcher).toHaveBeenCalledWith(nextConfig);
+      expect(hoisted.browserStop).toHaveBeenCalledTimes(1);
+      expect(hoisted.startBrowserControlServerIfEnabled).toHaveBeenCalledTimes(2);
 
-    expect(hoisted.browserStop).toHaveBeenCalledTimes(1);
-    expect(hoisted.startBrowserControlServerIfEnabled).toHaveBeenCalledTimes(2);
+      expect(hoisted.startHeartbeatRunner).toHaveBeenCalledTimes(1);
+      expect(hoisted.heartbeatUpdateConfig).toHaveBeenCalledTimes(1);
+      expect(hoisted.heartbeatUpdateConfig).toHaveBeenCalledWith(nextConfig);
 
-    expect(hoisted.startHeartbeatRunner).toHaveBeenCalledTimes(1);
-    expect(hoisted.heartbeatUpdateConfig).toHaveBeenCalledTimes(1);
-    expect(hoisted.heartbeatUpdateConfig).toHaveBeenCalledWith(nextConfig);
+      expect(hoisted.cronInstances.length).toBe(2);
+      expect(hoisted.cronInstances[0].stop).toHaveBeenCalledTimes(1);
+      expect(hoisted.cronInstances[1].start).toHaveBeenCalledTimes(1);
 
-    expect(hoisted.cronInstances.length).toBe(2);
-    expect(hoisted.cronInstances[0].stop).toHaveBeenCalledTimes(1);
-    expect(hoisted.cronInstances[1].start).toHaveBeenCalledTimes(1);
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledTimes(5);
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledTimes(5);
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("whatsapp");
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("whatsapp");
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("telegram");
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("telegram");
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("discord");
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("discord");
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("signal");
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("signal");
+      expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("imessage");
+      expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("imessage");
 
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledTimes(5);
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledTimes(5);
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("whatsapp");
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("whatsapp");
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("telegram");
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("telegram");
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("discord");
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("discord");
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("signal");
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("signal");
-    expect(hoisted.providerManager.stopChannel).toHaveBeenCalledWith("imessage");
-    expect(hoisted.providerManager.startChannel).toHaveBeenCalledWith("imessage");
+      const onRestart = hoisted.getOnRestart();
+      expect(onRestart).toBeTypeOf("function");
 
-    const onRestart = hoisted.getOnRestart();
-    expect(onRestart).toBeTypeOf("function");
+      const signalSpy = vi.fn();
+      process.once("SIGUSR1", signalSpy);
 
-    const signalSpy = vi.fn();
-    process.once("SIGUSR1", signalSpy);
+      onRestart?.(
+        {
+          changedPaths: ["gateway.port"],
+          restartGateway: true,
+          restartReasons: ["gateway.port"],
+          hotReasons: [],
+          reloadHooks: false,
+          restartGmailWatcher: false,
+          restartBrowserControl: false,
+          restartCron: false,
+          restartHeartbeat: false,
+          restartChannels: new Set(),
+          noopPaths: [],
+        },
+        {},
+      );
 
-    onRestart?.(
-      {
-        changedPaths: ["gateway.port"],
-        restartGateway: true,
-        restartReasons: ["gateway.port"],
-        hotReasons: [],
-        reloadHooks: false,
-        restartGmailWatcher: false,
-        restartBrowserControl: false,
-        restartCron: false,
-        restartHeartbeat: false,
-        restartChannels: new Set(),
-        noopPaths: [],
-      },
-      {},
-    );
-
-    expect(signalSpy).toHaveBeenCalledTimes(1);
-
-    await server.close();
+      expect(signalSpy).toHaveBeenCalledTimes(1);
+    });
   });
 });
 
diff --git a/src/gateway/server.sessions-send.e2e.test.ts b/src/gateway/server.sessions-send.e2e.test.ts
index 58f7d65b19e..dd72f28995d 100644
--- a/src/gateway/server.sessions-send.e2e.test.ts
+++ b/src/gateway/server.sessions-send.e2e.test.ts
@@ -1,9 +1,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-import { createOpenClawTools } from "../agents/openclaw-tools.js";
 import { resolveSessionTranscriptPath } from "../config/sessions.js";
 import { emitAgentEvent } from "../infra/agent-events.js";
+import { captureEnv } from "../test-utils/env.js";
 import {
   agentCommand,
   getFreePort,
@@ -12,17 +12,17 @@ import {
   testState,
 } from "./test-helpers.js";
 
+const { createOpenClawTools } = await import("../agents/openclaw-tools.js");
+
 installGatewayTestHooks({ scope: "suite" });
 
 let server: Awaited<ReturnType<typeof startGatewayServer>>;
 let gatewayPort: number;
-let prevGatewayPort: string | undefined;
-let prevGatewayToken: string | undefined;
 const gatewayToken = "test-token";
+let envSnapshot: ReturnType<typeof captureEnv>;
 
 beforeAll(async () => {
-  prevGatewayPort = process.env.OPENCLAW_GATEWAY_PORT;
-  prevGatewayToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+  envSnapshot = captureEnv(["OPENCLAW_GATEWAY_PORT", "OPENCLAW_GATEWAY_TOKEN"]);
   gatewayPort = await getFreePort();
   testState.gatewayAuth = { mode: "token", token: gatewayToken };
   process.env.OPENCLAW_GATEWAY_PORT = String(gatewayPort);
@@ -32,16 +32,7 @@ beforeAll(async () => {
 
 afterAll(async () => {
   await server.close();
-  if (prevGatewayPort === undefined) {
-    delete process.env.OPENCLAW_GATEWAY_PORT;
-  } else {
-    process.env.OPENCLAW_GATEWAY_PORT = prevGatewayPort;
-  }
-  if (prevGatewayToken === undefined) {
-    delete process.env.OPENCLAW_GATEWAY_TOKEN;
-  } else {
-    process.env.OPENCLAW_GATEWAY_TOKEN = prevGatewayToken;
-  }
+  envSnapshot.restore();
 });
 
 describe("sessions_send gateway loopback", () => {
@@ -121,6 +112,18 @@ describe("sessions_send gateway loopback", () => {
 
 describe("sessions_send label lookup", () => {
   it("finds session by label and sends message", { timeout: 60_000 }, async () => {
+    // This is an operator feature; enable broader session tool targeting for this test.
+    const configPath = process.env.OPENCLAW_CONFIG_PATH;
+    if (!configPath) {
+      throw new Error("OPENCLAW_CONFIG_PATH missing in gateway test environment");
+    }
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(
+      configPath,
+      JSON.stringify({ tools: { sessions: { visibility: "all" } } }, null, 2) + "\n",
+      "utf-8",
+    );
+
     const spy = vi.mocked(agentCommand);
     spy.mockImplementation(async (opts) => {
       const params = opts as {
diff --git a/src/gateway/server.sessions.gateway-server-sessions-a.e2e.test.ts b/src/gateway/server.sessions.gateway-server-sessions-a.e2e.test.ts
index 9d387c8ac6e..16df39522c1 100644
--- a/src/gateway/server.sessions.gateway-server-sessions-a.e2e.test.ts
+++ b/src/gateway/server.sessions.gateway-server-sessions-a.e2e.test.ts
@@ -2,16 +2,14 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
-import { WebSocket } from "ws";
 import { DEFAULT_PROVIDER } from "../agents/defaults.js";
+import { startGatewayServerHarness, type GatewayServerHarness } from "./server.e2e-ws-harness.js";
 import {
   connectOk,
   embeddedRunMock,
-  getFreePort,
   installGatewayTestHooks,
   piSdkMock,
   rpcReq,
-  startGatewayServer,
   testState,
   writeSessionStore,
 } from "./test-helpers.js";
@@ -57,32 +55,17 @@ vi.mock("../hooks/internal-hooks.js", async () => {
 
 installGatewayTestHooks({ scope: "suite" });
 
-let server: Awaited<ReturnType<typeof startGatewayServer>>;
-let port = 0;
-let previousToken: string | undefined;
+let harness: GatewayServerHarness;
 
 beforeAll(async () => {
-  previousToken = process.env.OPENCLAW_GATEWAY_TOKEN;
-  delete process.env.OPENCLAW_GATEWAY_TOKEN;
-  port = await getFreePort();
-  server = await startGatewayServer(port);
+  harness = await startGatewayServerHarness();
 });
 
 afterAll(async () => {
-  await server.close();
-  if (previousToken === undefined) {
-    delete process.env.OPENCLAW_GATEWAY_TOKEN;
-  } else {
-    process.env.OPENCLAW_GATEWAY_TOKEN = previousToken;
-  }
+  await harness.close();
 });
 
-const openClient = async (opts?: Parameters<typeof connectOk>[1]) => {
-  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
-  await new Promise<void>((resolve) => ws.once("open", resolve));
-  const hello = await connectOk(ws, opts);
-  return { ws, hello };
-};
+const openClient = async (opts?: Parameters<typeof connectOk>[1]) => await harness.openClient(opts);
 
 describe("gateway server sessions", () => {
   beforeEach(() => {
@@ -143,7 +126,7 @@ describe("gateway server sessions", () => {
     });
 
     const { ws, hello } = await openClient();
-    expect((hello as unknown as { features?: { methods?: string[] } }).features?.methods).toEqual(
+    expect((hello as { features?: { methods?: string[] } }).features?.methods).toEqual(
       expect.arrayContaining([
         "sessions.list",
         "sessions.preview",
diff --git a/src/gateway/server.skills-status.e2e.test.ts b/src/gateway/server.skills-status.e2e.test.ts
index c7446e04615..f4ff52faa96 100644
--- a/src/gateway/server.skills-status.e2e.test.ts
+++ b/src/gateway/server.skills-status.e2e.test.ts
@@ -1,5 +1,6 @@
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import {
   connectOk,
   installGatewayTestHooks,
@@ -12,23 +13,19 @@ installGatewayTestHooks({ scope: "suite" });
 async function withServer<T>(
   run: (ws: Awaited<ReturnType<typeof startServerWithClient>>["ws"]) => Promise<T>,
 ) {
-  const { server, ws, prevToken } = await startServerWithClient("secret");
+  const { server, ws, envSnapshot } = await startServerWithClient("secret");
   try {
     return await run(ws);
   } finally {
     ws.close();
     await server.close();
-    if (prevToken === undefined) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
-    }
+    envSnapshot.restore();
   }
 }
 
 describe("gateway skills.status", () => {
   it("does not expose raw config values to operator.read clients", async () => {
-    const prevBundledSkillsDir = process.env.OPENCLAW_BUNDLED_SKILLS_DIR;
+    const envSnapshot = captureEnv(["OPENCLAW_BUNDLED_SKILLS_DIR"]);
     process.env.OPENCLAW_BUNDLED_SKILLS_DIR = path.join(process.cwd(), "skills");
     const secret = "discord-token-secret-abc";
     const { writeConfigFile } = await import("../config/config.js");
@@ -62,11 +59,7 @@ describe("gateway skills.status", () => {
         expect(check && "value" in check).toBe(false);
       });
     } finally {
-      if (prevBundledSkillsDir === undefined) {
-        delete process.env.OPENCLAW_BUNDLED_SKILLS_DIR;
-      } else {
-        process.env.OPENCLAW_BUNDLED_SKILLS_DIR = prevBundledSkillsDir;
-      }
+      envSnapshot.restore();
     }
   });
 });
diff --git a/src/gateway/server.talk-config.e2e.test.ts b/src/gateway/server.talk-config.e2e.test.ts
index 4cbea64747a..e6023d9e54d 100644
--- a/src/gateway/server.talk-config.e2e.test.ts
+++ b/src/gateway/server.talk-config.e2e.test.ts
@@ -11,17 +11,13 @@ installGatewayTestHooks({ scope: "suite" });
 async function withServer<T>(
   run: (ws: Awaited<ReturnType<typeof startServerWithClient>>["ws"]) => Promise<T>,
 ) {
-  const { server, ws, prevToken } = await startServerWithClient("secret");
+  const { server, ws, envSnapshot } = await startServerWithClient("secret");
   try {
     return await run(ws);
   } finally {
     ws.close();
     await server.close();
-    if (prevToken === undefined) {
-      delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    } else {
-      process.env.OPENCLAW_GATEWAY_TOKEN = prevToken;
-    }
+    envSnapshot.restore();
   }
 }
 
diff --git a/src/gateway/server/__tests__/test-utils.ts b/src/gateway/server/__tests__/test-utils.ts
index bfc6a687170..6adf47d9fb9 100644
--- a/src/gateway/server/__tests__/test-utils.ts
+++ b/src/gateway/server/__tests__/test-utils.ts
@@ -1,22 +1,7 @@
-import type { PluginRegistry } from "../../../plugins/registry.js";
+import { createEmptyPluginRegistry, type PluginRegistry } from "../../../plugins/registry.js";
 
 export const createTestRegistry = (overrides: Partial<PluginRegistry> = {}): PluginRegistry => {
-  const base: PluginRegistry = {
-    plugins: [],
-    tools: [],
-    hooks: [],
-    typedHooks: [],
-    channels: [],
-    providers: [],
-    gatewayHandlers: {},
-    httpHandlers: [],
-    httpRoutes: [],
-    cliRegistrars: [],
-    services: [],
-    commands: [],
-    diagnostics: [],
-  };
-  const merged = { ...base, ...overrides };
+  const merged = { ...createEmptyPluginRegistry(), ...overrides };
   return {
     ...merged,
     gatewayHandlers: merged.gatewayHandlers ?? {},
diff --git a/src/gateway/server/ws-connection/auth-messages.ts b/src/gateway/server/ws-connection/auth-messages.ts
index 12b167fb2c8..c4900a6eaef 100644
--- a/src/gateway/server/ws-connection/auth-messages.ts
+++ b/src/gateway/server/ws-connection/auth-messages.ts
@@ -4,21 +4,6 @@ import { GATEWAY_CLIENT_IDS } from "../../protocol/client-info.js";
 
 export type AuthProvidedKind = "token" | "password" | "none";
 
-export function resolveHostName(hostHeader?: string): string {
-  const host = (hostHeader ?? "").trim().toLowerCase();
-  if (!host) {
-    return "";
-  }
-  if (host.startsWith("[")) {
-    const end = host.indexOf("]");
-    if (end !== -1) {
-      return host.slice(1, end);
-    }
-  }
-  const [name] = host.split(":");
-  return name ?? "";
-}
-
 export function formatGatewayAuthFailureMessage(params: {
   authMode: ResolvedGatewayAuth["mode"];
   authProvided: AuthProvidedKind;
diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts
index 345c304779a..a49640652e9 100644
--- a/src/gateway/server/ws-connection/message-handler.ts
+++ b/src/gateway/server/ws-connection/message-handler.ts
@@ -33,6 +33,7 @@ import {
 import { authorizeGatewayConnect, isLocalDirectRequest } from "../../auth.js";
 import { buildDeviceAuthPayload } from "../../device-auth.js";
 import { isLoopbackAddress, isTrustedProxyAddress, resolveGatewayClientIp } from "../../net.js";
+import { resolveHostName } from "../../net.js";
 import { resolveNodeCommandAllowlist } from "../../node-command-policy.js";
 import { checkBrowserOrigin } from "../../origin-check.js";
 import { GATEWAY_CLIENT_IDS } from "../../protocol/client-info.js";
@@ -58,11 +59,7 @@ import {
   incrementPresenceVersion,
   refreshGatewayHealthSnapshot,
 } from "../health-state.js";
-import {
-  formatGatewayAuthFailureMessage,
-  resolveHostName,
-  type AuthProvidedKind,
-} from "./auth-messages.js";
+import { formatGatewayAuthFailureMessage, type AuthProvidedKind } from "./auth-messages.js";
 
 type SubsystemLogger = ReturnType<typeof createSubsystemLogger>;
 
@@ -430,7 +427,7 @@ export function attachGatewayWsMessageHandler(params: {
           close(1008, truncateCloseReason(authMessage));
         };
         if (!device) {
-          if (scopes.length > 0) {
+          if (scopes.length > 0 && !allowControlUiBypass) {
             scopes = [];
             connectParams.scopes = scopes;
           }
diff --git a/src/gateway/session-utils.fs.test.ts b/src/gateway/session-utils.fs.test.ts
index d7cf781f5ff..8f088545aaf 100644
--- a/src/gateway/session-utils.fs.test.ts
+++ b/src/gateway/session-utils.fs.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from "vitest";
 import {
   archiveSessionTranscripts,
   readFirstUserMessageFromTranscript,
@@ -16,12 +16,12 @@ describe("readFirstUserMessageFromTranscript", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-session-fs-test-"));
     storePath = path.join(tmpDir, "sessions.json");
   });
 
-  afterEach(() => {
+  afterAll(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -183,12 +183,12 @@ describe("readLastMessagePreviewFromTranscript", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-session-fs-test-"));
     storePath = path.join(tmpDir, "sessions.json");
   });
 
-  afterEach(() => {
+  afterAll(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -345,7 +345,7 @@ describe("readLastMessagePreviewFromTranscript", () => {
     const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
     const padding = JSON.stringify({ message: { role: "user", content: "x".repeat(500) } });
     const lines: string[] = [];
-    for (let i = 0; i < 50; i++) {
+    for (let i = 0; i < 30; i++) {
       lines.push(padding);
     }
     lines.push(JSON.stringify({ message: { role: "assistant", content: "Last in large file" } }));
@@ -372,12 +372,12 @@ describe("readSessionTitleFieldsFromTranscript cache", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-session-fs-test-"));
     storePath = path.join(tmpDir, "sessions.json");
   });
 
-  afterEach(() => {
+  afterAll(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -400,6 +400,7 @@ describe("readSessionTitleFieldsFromTranscript cache", () => {
     const second = readSessionTitleFieldsFromTranscript(sessionId, storePath);
     expect(second).toEqual(first);
     expect(readSpy.mock.calls.length).toBe(readsAfterFirst);
+    readSpy.mockRestore();
   });
 
   test("invalidates cache when transcript changes", () => {
@@ -427,6 +428,7 @@ describe("readSessionTitleFieldsFromTranscript cache", () => {
     const second = readSessionTitleFieldsFromTranscript(sessionId, storePath);
     expect(second.lastMessagePreview).toBe("New");
     expect(readSpy.mock.calls.length).toBeGreaterThan(readsAfterFirst);
+    readSpy.mockRestore();
   });
 });
 
@@ -434,12 +436,12 @@ describe("readSessionMessages", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-session-fs-test-"));
     storePath = path.join(tmpDir, "sessions.json");
   });
 
-  afterEach(() => {
+  afterAll(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -533,12 +535,12 @@ describe("readSessionPreviewItemsFromTranscript", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-session-preview-test-"));
     storePath = path.join(tmpDir, "sessions.json");
   });
 
-  afterEach(() => {
+  afterAll(() => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -690,13 +692,13 @@ describe("archiveSessionTranscripts", () => {
   let tmpDir: string;
   let storePath: string;
 
-  beforeEach(() => {
+  beforeAll(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-archive-test-"));
     storePath = path.join(tmpDir, "sessions.json");
     vi.stubEnv("OPENCLAW_HOME", tmpDir);
   });
 
-  afterEach(() => {
+  afterAll(() => {
     vi.unstubAllEnvs();
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
diff --git a/src/gateway/session-utils.fs.ts b/src/gateway/session-utils.fs.ts
index d9987e8f225..550641d5dc9 100644
--- a/src/gateway/session-utils.fs.ts
+++ b/src/gateway/session-utils.fs.ts
@@ -306,32 +306,7 @@ export function readSessionTitleFieldsFromTranscript(
     // Tail (last message preview)
     let lastMessagePreview: string | null = null;
     try {
-      const readStart = Math.max(0, size - LAST_MSG_MAX_BYTES);
-      const readLen = Math.min(size, LAST_MSG_MAX_BYTES);
-      const buf = Buffer.alloc(readLen);
-      fs.readSync(fd, buf, 0, readLen, readStart);
-
-      const chunk = buf.toString("utf-8");
-      const lines = chunk.split(/\r?\n/).filter((l) => l.trim());
-      const tailLines = lines.slice(-LAST_MSG_MAX_LINES);
-
-      for (let i = tailLines.length - 1; i >= 0; i--) {
-        const line = tailLines[i];
-        try {
-          const parsed = JSON.parse(line);
-          const msg = parsed?.message as TranscriptMessage | undefined;
-          if (msg?.role !== "user" && msg?.role !== "assistant") {
-            continue;
-          }
-          const text = extractTextFromContent(msg.content);
-          if (text) {
-            lastMessagePreview = text;
-            break;
-          }
-        } catch {
-          // skip malformed
-        }
-      }
+      lastMessagePreview = readLastMessagePreviewFromOpenTranscript({ fd, size });
     } catch {
       // ignore tail read errors
     }
@@ -430,6 +405,38 @@ export function readFirstUserMessageFromTranscript(
 const LAST_MSG_MAX_BYTES = 16384;
 const LAST_MSG_MAX_LINES = 20;
 
+function readLastMessagePreviewFromOpenTranscript(params: {
+  fd: number;
+  size: number;
+}): string | null {
+  const readStart = Math.max(0, params.size - LAST_MSG_MAX_BYTES);
+  const readLen = Math.min(params.size, LAST_MSG_MAX_BYTES);
+  const buf = Buffer.alloc(readLen);
+  fs.readSync(params.fd, buf, 0, readLen, readStart);
+
+  const chunk = buf.toString("utf-8");
+  const lines = chunk.split(/\r?\n/).filter((l) => l.trim());
+  const tailLines = lines.slice(-LAST_MSG_MAX_LINES);
+
+  for (let i = tailLines.length - 1; i >= 0; i--) {
+    const line = tailLines[i];
+    try {
+      const parsed = JSON.parse(line);
+      const msg = parsed?.message as TranscriptMessage | undefined;
+      if (msg?.role !== "user" && msg?.role !== "assistant") {
+        continue;
+      }
+      const text = extractTextFromContent(msg.content);
+      if (text) {
+        return text;
+      }
+    } catch {
+      // skip malformed
+    }
+  }
+  return null;
+}
+
 export function readLastMessagePreviewFromTranscript(
   sessionId: string,
   storePath: string | undefined,
@@ -450,31 +457,7 @@ export function readLastMessagePreviewFromTranscript(
     if (size === 0) {
       return null;
     }
-
-    const readStart = Math.max(0, size - LAST_MSG_MAX_BYTES);
-    const readLen = Math.min(size, LAST_MSG_MAX_BYTES);
-    const buf = Buffer.alloc(readLen);
-    fs.readSync(fd, buf, 0, readLen, readStart);
-
-    const chunk = buf.toString("utf-8");
-    const lines = chunk.split(/\r?\n/).filter((l) => l.trim());
-    const tailLines = lines.slice(-LAST_MSG_MAX_LINES);
-
-    for (let i = tailLines.length - 1; i >= 0; i--) {
-      const line = tailLines[i];
-      try {
-        const parsed = JSON.parse(line);
-        const msg = parsed?.message as TranscriptMessage | undefined;
-        if (msg?.role === "user" || msg?.role === "assistant") {
-          const text = extractTextFromContent(msg.content);
-          if (text) {
-            return text;
-          }
-        }
-      } catch {
-        // skip malformed
-      }
-    }
+    return readLastMessagePreviewFromOpenTranscript({ fd, size });
   } catch {
     // file error
   } finally {
diff --git a/src/gateway/test-helpers.server.ts b/src/gateway/test-helpers.server.ts
index 29683bcafac..509c30773f4 100644
--- a/src/gateway/test-helpers.server.ts
+++ b/src/gateway/test-helpers.server.ts
@@ -16,6 +16,7 @@ import { drainSystemEvents, peekSystemEvents } from "../infra/system-events.js";
 import { rawDataToString } from "../infra/ws.js";
 import { resetLogger, setLoggerOverride } from "../logging.js";
 import { DEFAULT_AGENT_ID, toAgentStoreSessionKey } from "../routing/session-key.js";
+import { captureEnv } from "../test-utils/env.js";
 import { getDeterministicFreePortBlock } from "../test-utils/ports.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
 import { buildDeviceAuthPayload } from "./device-auth.js";
@@ -331,12 +332,50 @@ export async function startGatewayServer(port: number, opts?: GatewayServerOptio
   return await mod.startGatewayServer(port, resolvedOpts);
 }
 
+async function startGatewayServerWithRetries(params: {
+  port: number;
+  opts?: GatewayServerOptions;
+}): Promise<{ port: number; server: Awaited<ReturnType<typeof startGatewayServer>> }> {
+  let port = params.port;
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try {
+      return {
+        port,
+        server: await startGatewayServer(port, params.opts),
+      };
+    } catch (err) {
+      const code = (err as { cause?: { code?: string } }).cause?.code;
+      if (code !== "EADDRINUSE") {
+        throw err;
+      }
+      port = await getFreePort();
+    }
+  }
+  throw new Error("failed to start gateway server after retries");
+}
+
+export async function withGatewayServer<T>(
+  fn: (ctx: { port: number; server: Awaited<ReturnType<typeof startGatewayServer>> }) => Promise<T>,
+  opts?: { port?: number; serverOptions?: GatewayServerOptions },
+): Promise<T> {
+  const started = await startGatewayServerWithRetries({
+    port: opts?.port ?? (await getFreePort()),
+    opts: opts?.serverOptions,
+  });
+  try {
+    return await fn({ port: started.port, server: started.server });
+  } finally {
+    await started.server.close();
+  }
+}
+
 export async function startServerWithClient(
   token?: string,
   opts?: GatewayServerOptions & { wsHeaders?: Record<string, string> },
 ) {
   const { wsHeaders, ...gatewayOpts } = opts ?? {};
   let port = await getFreePort();
+  const envSnapshot = captureEnv(["OPENCLAW_GATEWAY_TOKEN"]);
   const prev = process.env.OPENCLAW_GATEWAY_TOKEN;
   if (typeof token === "string") {
     testState.gatewayAuth = { mode: "token", token };
@@ -352,22 +391,9 @@ export async function startServerWithClient(
     process.env.OPENCLAW_GATEWAY_TOKEN = fallbackToken;
   }
 
-  let server: Awaited<ReturnType<typeof startGatewayServer>> | null = null;
-  for (let attempt = 0; attempt < 10; attempt++) {
-    try {
-      server = await startGatewayServer(port, gatewayOpts);
-      break;
-    } catch (err) {
-      const code = (err as { cause?: { code?: string } }).cause?.code;
-      if (code !== "EADDRINUSE") {
-        throw err;
-      }
-      port = await getFreePort();
-    }
-  }
-  if (!server) {
-    throw new Error("failed to start gateway server after retries");
-  }
+  const started = await startGatewayServerWithRetries({ port, opts: gatewayOpts });
+  port = started.port;
+  const server = started.server;
 
   const ws = new WebSocket(
     `ws://127.0.0.1:${port}`,
@@ -397,7 +423,7 @@ export async function startServerWithClient(
     ws.once("error", onError);
     ws.once("close", onClose);
   });
-  return { server, ws, port, prevToken: prev };
+  return { server, ws, port, prevToken: prev, envSnapshot };
 }
 
 type ConnectResponse = {
diff --git a/src/gateway/tools-invoke-http.ts b/src/gateway/tools-invoke-http.ts
index 222b883f27e..91a03f3f32b 100644
--- a/src/gateway/tools-invoke-http.ts
+++ b/src/gateway/tools-invoke-http.ts
@@ -10,7 +10,11 @@ import {
   applyToolPolicyPipeline,
   buildDefaultToolPolicyPipelineSteps,
 } from "../agents/tool-policy-pipeline.js";
-import { collectExplicitAllowlist, resolveToolProfilePolicy } from "../agents/tool-policy.js";
+import {
+  collectExplicitAllowlist,
+  mergeAlsoAllowPolicy,
+  resolveToolProfilePolicy,
+} from "../agents/tool-policy.js";
 import { ToolInputError } from "../agents/tools/common.js";
 import { loadConfig } from "../config/config.js";
 import { resolveMainSessionKey } from "../config/sessions.js";
@@ -215,15 +219,8 @@ export async function handleToolsInvokeHttpRequest(
   const profilePolicy = resolveToolProfilePolicy(profile);
   const providerProfilePolicy = resolveToolProfilePolicy(providerProfile);
 
-  const mergeAlsoAllow = (policy: typeof profilePolicy, alsoAllow?: string[]) => {
-    if (!policy?.allow || !Array.isArray(alsoAllow) || alsoAllow.length === 0) {
-      return policy;
-    }
-    return { ...policy, allow: Array.from(new Set([...policy.allow, ...alsoAllow])) };
-  };
-
-  const profilePolicyWithAlsoAllow = mergeAlsoAllow(profilePolicy, profileAlsoAllow);
-  const providerProfilePolicyWithAlsoAllow = mergeAlsoAllow(
+  const profilePolicyWithAlsoAllow = mergeAlsoAllowPolicy(profilePolicy, profileAlsoAllow);
+  const providerProfilePolicyWithAlsoAllow = mergeAlsoAllowPolicy(
     providerProfilePolicy,
     providerProfileAlsoAllow,
   );
diff --git a/src/globals.test.ts b/src/globals.test.ts
deleted file mode 100644
index 9b6e309b20f..00000000000
--- a/src/globals.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { isVerbose, isYes, logVerbose, setVerbose, setYes } from "./globals.js";
-
-describe("globals", () => {
-  afterEach(() => {
-    setVerbose(false);
-    setYes(false);
-    vi.restoreAllMocks();
-  });
-
-  it("toggles verbose flag and logs when enabled", () => {
-    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
-    setVerbose(false);
-    logVerbose("hidden");
-    expect(logSpy).not.toHaveBeenCalled();
-
-    setVerbose(true);
-    logVerbose("shown");
-    expect(isVerbose()).toBe(true);
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("shown"));
-  });
-
-  it("stores yes flag", () => {
-    setYes(true);
-    expect(isYes()).toBe(true);
-    setYes(false);
-    expect(isYes()).toBe(false);
-  });
-});
diff --git a/src/hooks/frontmatter.ts b/src/hooks/frontmatter.ts
index 801da9a1d5d..3cfc1d67e27 100644
--- a/src/hooks/frontmatter.ts
+++ b/src/hooks/frontmatter.ts
@@ -11,6 +11,9 @@ import {
   normalizeStringList,
   parseFrontmatterBool,
   resolveOpenClawManifestBlock,
+  resolveOpenClawManifestInstall,
+  resolveOpenClawManifestOs,
+  resolveOpenClawManifestRequires,
 } from "../shared/frontmatter.js";
 
 export function parseFrontmatter(content: string): ParsedHookFrontmatter {
@@ -60,15 +63,9 @@ export function resolveOpenClawMetadata(
   if (!metadataObj) {
     return undefined;
   }
-  const requiresRaw =
-    typeof metadataObj.requires === "object" && metadataObj.requires !== null
-      ? (metadataObj.requires as Record<string, unknown>)
-      : undefined;
-  const installRaw = Array.isArray(metadataObj.install) ? (metadataObj.install as unknown[]) : [];
-  const install = installRaw
-    .map((entry) => parseInstallSpec(entry))
-    .filter((entry): entry is HookInstallSpec => Boolean(entry));
-  const osRaw = normalizeStringList(metadataObj.os);
+  const requires = resolveOpenClawManifestRequires(metadataObj);
+  const install = resolveOpenClawManifestInstall(metadataObj, parseInstallSpec);
+  const osRaw = resolveOpenClawManifestOs(metadataObj);
   const eventsRaw = normalizeStringList(metadataObj.events);
   return {
     always: typeof metadataObj.always === "boolean" ? metadataObj.always : undefined,
@@ -78,14 +75,7 @@ export function resolveOpenClawMetadata(
     export: typeof metadataObj.export === "string" ? metadataObj.export : undefined,
     os: osRaw.length > 0 ? osRaw : undefined,
     events: eventsRaw.length > 0 ? eventsRaw : [],
-    requires: requiresRaw
-      ? {
-          bins: normalizeStringList(requiresRaw.bins),
-          anyBins: normalizeStringList(requiresRaw.anyBins),
-          env: normalizeStringList(requiresRaw.env),
-          config: normalizeStringList(requiresRaw.config),
-        }
-      : undefined,
+    requires: requires,
     install: install.length > 0 ? install : undefined,
   };
 }
diff --git a/src/hooks/gmail-watcher.test.ts b/src/hooks/gmail-watcher.test.ts
deleted file mode 100644
index 8fb42247804..00000000000
--- a/src/hooks/gmail-watcher.test.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isAddressInUseError } from "./gmail-watcher.js";
-
-describe("gmail watcher", () => {
-  it("detects address already in use errors", () => {
-    expect(isAddressInUseError("listen tcp 127.0.0.1:8788: bind: address already in use")).toBe(
-      true,
-    );
-    expect(isAddressInUseError("EADDRINUSE: address already in use")).toBe(true);
-    expect(isAddressInUseError("some other error")).toBe(false);
-  });
-});
diff --git a/src/hooks/hooks-status.ts b/src/hooks/hooks-status.ts
index b8db68abbfe..af7cacd5a0a 100644
--- a/src/hooks/hooks-status.ts
+++ b/src/hooks/hooks-status.ts
@@ -1,16 +1,13 @@
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
+import type { RequirementConfigCheck, Requirements } from "../shared/requirements.js";
 import type { HookEligibilityContext, HookEntry, HookInstallSpec } from "./types.js";
-import { resolveEmojiAndHomepage } from "../shared/entry-metadata.js";
-import { evaluateRequirementsFromMetadataWithRemote } from "../shared/requirements.js";
+import { evaluateEntryMetadataRequirements } from "../shared/entry-status.js";
 import { CONFIG_DIR } from "../utils.js";
 import { hasBinary, isConfigPathTruthy, resolveHookConfig } from "./config.js";
 import { loadWorkspaceHookEntries } from "./workspace.js";
 
-export type HookStatusConfigCheck = {
-  path: string;
-  satisfied: boolean;
-};
+export type HookStatusConfigCheck = RequirementConfigCheck;
 
 export type HookInstallOption = {
   id: string;
@@ -35,20 +32,8 @@ export type HookStatusEntry = {
   disabled: boolean;
   eligible: boolean;
   managedByPlugin: boolean;
-  requirements: {
-    bins: string[];
-    anyBins: string[];
-    env: string[];
-    config: string[];
-    os: string[];
-  };
-  missing: {
-    bins: string[];
-    anyBins: string[];
-    env: string[];
-    config: string[];
-    os: string[];
-  };
+  requirements: Requirements;
+  missing: Requirements;
   configChecks: HookStatusConfigCheck[];
   install: HookInstallOption[];
 };
@@ -101,26 +86,19 @@ function buildHookStatus(
   const managedByPlugin = entry.hook.source === "openclaw-plugin";
   const disabled = managedByPlugin ? false : hookConfig?.enabled === false;
   const always = entry.metadata?.always === true;
-  const { emoji, homepage } = resolveEmojiAndHomepage({
-    metadata: entry.metadata,
-    frontmatter: entry.frontmatter,
-  });
   const events = entry.metadata?.events ?? [];
 
-  const {
-    required,
-    missing,
-    eligible: requirementsSatisfied,
-    configChecks,
-  } = evaluateRequirementsFromMetadataWithRemote({
-    always,
-    metadata: entry.metadata,
-    hasLocalBin: hasBinary,
-    localPlatform: process.platform,
-    remote: eligibility?.remote,
-    isEnvSatisfied: (envName) => Boolean(process.env[envName] || hookConfig?.env?.[envName]),
-    isConfigSatisfied: (pathStr) => isConfigPathTruthy(config, pathStr),
-  });
+  const { emoji, homepage, required, missing, requirementsSatisfied, configChecks } =
+    evaluateEntryMetadataRequirements({
+      always,
+      metadata: entry.metadata,
+      frontmatter: entry.frontmatter,
+      hasLocalBin: hasBinary,
+      localPlatform: process.platform,
+      remote: eligibility?.remote,
+      isEnvSatisfied: (envName) => Boolean(process.env[envName] || hookConfig?.env?.[envName]),
+      isConfigSatisfied: (pathStr) => isConfigPathTruthy(config, pathStr),
+    });
 
   const eligible = !disabled && requirementsSatisfied;
 
diff --git a/src/hooks/install.test.ts b/src/hooks/install.test.ts
index 579bff41726..4b862a35769 100644
--- a/src/hooks/install.test.ts
+++ b/src/hooks/install.test.ts
@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { isAddressInUseError } from "./gmail-watcher.js";
 
 const fixtureRoot = path.join(os.tmpdir(), `openclaw-hook-install-${randomUUID()}`);
 let tempDirIndex = 0;
@@ -296,3 +297,13 @@ describe("installHooksFromNpmSpec", () => {
     expect(result.error).toContain("unsupported npm spec");
   });
 });
+
+describe("gmail watcher", () => {
+  it("detects address already in use errors", () => {
+    expect(isAddressInUseError("listen tcp 127.0.0.1:8788: bind: address already in use")).toBe(
+      true,
+    );
+    expect(isAddressInUseError("EADDRINUSE: address already in use")).toBe(true);
+    expect(isAddressInUseError("some other error")).toBe(false);
+  });
+});
diff --git a/src/hooks/internal-hooks.test.ts b/src/hooks/internal-hooks.test.ts
index e01e5bc3cda..dd5353866ad 100644
--- a/src/hooks/internal-hooks.test.ts
+++ b/src/hooks/internal-hooks.test.ts
@@ -8,7 +8,6 @@ import {
   triggerInternalHook,
   unregisterInternalHook,
   type AgentBootstrapHookContext,
-  type InternalHookEvent,
 } from "./internal-hooks.js";
 
 describe("hooks", () => {
@@ -211,37 +210,4 @@ describe("hooks", () => {
       expect(keys).toEqual([]);
     });
   });
-
-  describe("integration", () => {
-    it("should handle a complete hook lifecycle", async () => {
-      const results: InternalHookEvent[] = [];
-      const handler = vi.fn((event: InternalHookEvent) => {
-        results.push(event);
-      });
-
-      // Register
-      registerInternalHook("command:new", handler);
-
-      // Trigger
-      const event1 = createInternalHookEvent("command", "new", "session-1");
-      await triggerInternalHook(event1);
-
-      const event2 = createInternalHookEvent("command", "new", "session-2");
-      await triggerInternalHook(event2);
-
-      // Verify
-      expect(results).toHaveLength(2);
-      expect(results[0].sessionKey).toBe("session-1");
-      expect(results[1].sessionKey).toBe("session-2");
-
-      // Unregister
-      unregisterInternalHook("command:new", handler);
-
-      // Trigger again - should not call handler
-      const event3 = createInternalHookEvent("command", "new", "session-3");
-      await triggerInternalHook(event3);
-
-      expect(results).toHaveLength(2);
-    });
-  });
 });
diff --git a/src/hooks/loader.test.ts b/src/hooks/loader.test.ts
index 3f7dbe64339..e9299b491f9 100644
--- a/src/hooks/loader.test.ts
+++ b/src/hooks/loader.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
   clearInternalHooks,
@@ -12,13 +12,19 @@ import {
 import { loadInternalHooks } from "./loader.js";
 
 describe("loader", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
   let tmpDir: string;
   let originalBundledDir: string | undefined;
 
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hooks-loader-"));
+  });
+
   beforeEach(async () => {
     clearInternalHooks();
     // Create a temp directory for test modules
-    tmpDir = path.join(os.tmpdir(), `openclaw-test-${Date.now()}`);
+    tmpDir = path.join(fixtureRoot, `case-${caseId++}`);
     await fs.mkdir(tmpDir, { recursive: true });
 
     // Disable bundled hooks during tests by setting env var to non-existent directory
@@ -34,12 +40,13 @@ describe("loader", () => {
     } else {
       process.env.OPENCLAW_BUNDLED_HOOKS_DIR = originalBundledDir;
     }
-    // Clean up temp directory
-    try {
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    } catch {
-      // Ignore cleanup errors
+  });
+
+  afterAll(async () => {
+    if (!fixtureRoot) {
+      return;
     }
+    await fs.rm(fixtureRoot, { recursive: true, force: true });
   });
 
   describe("loadInternalHooks", () => {
diff --git a/src/imessage/client.test.ts b/src/imessage/client.test.ts
deleted file mode 100644
index b755b060e37..00000000000
--- a/src/imessage/client.test.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const spawnMock = vi.hoisted(() => vi.fn());
-
-vi.mock("node:child_process", () => ({
-  spawn: (...args: unknown[]) => spawnMock(...args),
-}));
-
-describe("createIMessageRpcClient", () => {
-  beforeEach(() => {
-    spawnMock.mockReset();
-    vi.stubEnv("VITEST", "true");
-  });
-
-  it("refuses to spawn imsg rpc in test environments", async () => {
-    const { createIMessageRpcClient } = await import("./client.js");
-    await expect(createIMessageRpcClient()).rejects.toThrow(
-      /Refusing to start imsg rpc in test environment/i,
-    );
-    expect(spawnMock).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/imessage/monitor.gating.test.ts b/src/imessage/monitor.gating.test.ts
new file mode 100644
index 00000000000..16068b38ea3
--- /dev/null
+++ b/src/imessage/monitor.gating.test.ts
@@ -0,0 +1,355 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import type { IMessagePayload } from "./monitor/types.js";
+import {
+  buildIMessageInboundContext,
+  resolveIMessageInboundDecision,
+} from "./monitor/inbound-processing.js";
+import { parseIMessageNotification } from "./monitor/parse-notification.js";
+
+function baseCfg(): OpenClawConfig {
+  return {
+    channels: {
+      imessage: {
+        dmPolicy: "open",
+        allowFrom: ["*"],
+        groupPolicy: "open",
+        groups: { "*": { requireMention: true } },
+      },
+    },
+    session: { mainKey: "main" },
+    messages: {
+      groupChat: { mentionPatterns: ["@openclaw"] },
+    },
+  } as unknown as OpenClawConfig;
+}
+
+function resolve(params: {
+  cfg?: OpenClawConfig;
+  message: IMessagePayload;
+  storeAllowFrom?: string[];
+}) {
+  const cfg = params.cfg ?? baseCfg();
+  const groupHistories = new Map();
+  return resolveIMessageInboundDecision({
+    cfg,
+    accountId: "default",
+    message: params.message,
+    opts: {},
+    messageText: (params.message.text ?? "").trim(),
+    bodyText: (params.message.text ?? "").trim(),
+    allowFrom: ["*"],
+    groupAllowFrom: [],
+    groupPolicy: cfg.channels?.imessage?.groupPolicy ?? "open",
+    dmPolicy: cfg.channels?.imessage?.dmPolicy ?? "pairing",
+    storeAllowFrom: params.storeAllowFrom ?? [],
+    historyLimit: 0,
+    groupHistories,
+  });
+}
+
+describe("imessage monitor gating + envelope builders", () => {
+  it("parseIMessageNotification rejects malformed payloads", () => {
+    expect(
+      parseIMessageNotification({
+        message: { chat_id: 1, sender: { nested: "nope" } },
+      }),
+    ).toBeNull();
+  });
+
+  it("drops group messages without mention by default", () => {
+    const decision = resolve({
+      message: {
+        id: 1,
+        chat_id: 99,
+        sender: "+15550001111",
+        is_from_me: false,
+        text: "hello group",
+        is_group: true,
+      },
+    });
+    expect(decision.kind).toBe("drop");
+    if (decision.kind !== "drop") {
+      throw new Error("expected drop decision");
+    }
+    expect(decision.reason).toBe("no mention");
+  });
+
+  it("dispatches group messages with mention and builds a group envelope", () => {
+    const cfg = baseCfg();
+    const groupHistories = new Map();
+    const message: IMessagePayload = {
+      id: 3,
+      chat_id: 42,
+      sender: "+15550002222",
+      is_from_me: false,
+      text: "@openclaw ping",
+      is_group: true,
+      chat_name: "Lobster Squad",
+      participants: ["+1555", "+1556"],
+    };
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message,
+      opts: {},
+      messageText: message.text,
+      bodyText: message.text,
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "open",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("dispatch");
+
+    const { ctxPayload } = buildIMessageInboundContext({
+      cfg,
+      decision,
+      message,
+      historyLimit: 0,
+      groupHistories,
+    });
+
+    expect(ctxPayload.ChatType).toBe("group");
+    expect(ctxPayload.SessionKey).toBe("agent:main:imessage:group:42");
+    expect(String(ctxPayload.Body ?? "")).toContain("+15550002222:");
+    expect(String(ctxPayload.Body ?? "")).not.toContain("[from:");
+    expect(ctxPayload.To).toBe("chat_id:42");
+  });
+
+  it("includes reply-to context fields + suffix", () => {
+    const cfg = baseCfg();
+    const groupHistories = new Map();
+    const message: IMessagePayload = {
+      id: 5,
+      chat_id: 55,
+      sender: "+15550001111",
+      is_from_me: false,
+      text: "replying now",
+      is_group: false,
+      reply_to_id: 9001,
+      reply_to_text: "original message",
+      reply_to_sender: "+15559998888",
+    };
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message,
+      opts: {},
+      messageText: message.text,
+      bodyText: message.text,
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "open",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("dispatch");
+
+    const { ctxPayload } = buildIMessageInboundContext({
+      cfg,
+      decision,
+      message,
+      historyLimit: 0,
+      groupHistories,
+    });
+
+    expect(ctxPayload.ReplyToId).toBe("9001");
+    expect(ctxPayload.ReplyToBody).toBe("original message");
+    expect(ctxPayload.ReplyToSender).toBe("+15559998888");
+    expect(String(ctxPayload.Body ?? "")).toContain("[Replying to +15559998888 id:9001]");
+    expect(String(ctxPayload.Body ?? "")).toContain("original message");
+  });
+
+  it("treats configured chat_id as a group session even when is_group is false", () => {
+    const cfg = baseCfg();
+    cfg.channels ??= {};
+    cfg.channels.imessage ??= {};
+    cfg.channels.imessage.groups = { "2": { requireMention: false } };
+
+    const groupHistories = new Map();
+    const message: IMessagePayload = {
+      id: 14,
+      chat_id: 2,
+      sender: "+15550001111",
+      is_from_me: false,
+      text: "hello",
+      is_group: false,
+    };
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message,
+      opts: {},
+      messageText: message.text,
+      bodyText: message.text,
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "open",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("dispatch");
+    expect(decision.isGroup).toBe(true);
+    expect(decision.route.sessionKey).toBe("agent:main:imessage:group:2");
+  });
+
+  it("allows group messages when requireMention is true but no mentionPatterns exist", () => {
+    const cfg = baseCfg();
+    cfg.messages ??= {};
+    cfg.messages.groupChat ??= {};
+    cfg.messages.groupChat.mentionPatterns = [];
+
+    const groupHistories = new Map();
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message: {
+        id: 12,
+        chat_id: 777,
+        sender: "+15550001111",
+        is_from_me: false,
+        text: "hello group",
+        is_group: true,
+      },
+      opts: {},
+      messageText: "hello group",
+      bodyText: "hello group",
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "open",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("dispatch");
+  });
+
+  it("blocks group messages when imessage.groups is set without a wildcard", () => {
+    const cfg = baseCfg();
+    cfg.channels ??= {};
+    cfg.channels.imessage ??= {};
+    cfg.channels.imessage.groups = { "99": { requireMention: false } };
+
+    const groupHistories = new Map();
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message: {
+        id: 13,
+        chat_id: 123,
+        sender: "+15550001111",
+        is_from_me: false,
+        text: "@openclaw hello",
+        is_group: true,
+      },
+      opts: {},
+      messageText: "@openclaw hello",
+      bodyText: "@openclaw hello",
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "open",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("drop");
+  });
+
+  it("honors group allowlist and ignores pairing-store senders in groups", () => {
+    const cfg = baseCfg();
+    cfg.channels ??= {};
+    cfg.channels.imessage ??= {};
+    cfg.channels.imessage.groupPolicy = "allowlist";
+
+    const groupHistories = new Map();
+    const denied = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message: {
+        id: 3,
+        chat_id: 202,
+        sender: "+15550003333",
+        is_from_me: false,
+        text: "@openclaw hi",
+        is_group: true,
+      },
+      opts: {},
+      messageText: "@openclaw hi",
+      bodyText: "@openclaw hi",
+      allowFrom: ["*"],
+      groupAllowFrom: ["chat_id:101"],
+      groupPolicy: "allowlist",
+      dmPolicy: "pairing",
+      storeAllowFrom: ["+15550003333"],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(denied.kind).toBe("drop");
+
+    const allowed = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message: {
+        id: 33,
+        chat_id: 101,
+        sender: "+15550003333",
+        is_from_me: false,
+        text: "@openclaw ok",
+        is_group: true,
+      },
+      opts: {},
+      messageText: "@openclaw ok",
+      bodyText: "@openclaw ok",
+      allowFrom: ["*"],
+      groupAllowFrom: ["chat_id:101"],
+      groupPolicy: "allowlist",
+      dmPolicy: "pairing",
+      storeAllowFrom: ["+15550003333"],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(allowed.kind).toBe("dispatch");
+  });
+
+  it("blocks group messages when groupPolicy is disabled", () => {
+    const cfg = baseCfg();
+    cfg.channels ??= {};
+    cfg.channels.imessage ??= {};
+    cfg.channels.imessage.groupPolicy = "disabled";
+
+    const groupHistories = new Map();
+    const decision = resolveIMessageInboundDecision({
+      cfg,
+      accountId: "default",
+      message: {
+        id: 10,
+        chat_id: 303,
+        sender: "+15550003333",
+        is_from_me: false,
+        text: "@openclaw hi",
+        is_group: true,
+      },
+      opts: {},
+      messageText: "@openclaw hi",
+      bodyText: "@openclaw hi",
+      allowFrom: ["*"],
+      groupAllowFrom: [],
+      groupPolicy: "disabled",
+      dmPolicy: "open",
+      storeAllowFrom: [],
+      historyLimit: 0,
+      groupHistories,
+    });
+    expect(decision.kind).toBe("drop");
+  });
+});
diff --git a/src/imessage/monitor.shutdown.unhandled-rejection.test.ts b/src/imessage/monitor.shutdown.unhandled-rejection.test.ts
new file mode 100644
index 00000000000..ecc85991a41
--- /dev/null
+++ b/src/imessage/monitor.shutdown.unhandled-rejection.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { attachIMessageMonitorAbortHandler } from "./monitor/abort-handler.js";
+
+describe("monitorIMessageProvider", () => {
+  it("does not trigger unhandledRejection when aborting during shutdown", async () => {
+    const abortController = new AbortController();
+    let subscriptionId: number | null = 1;
+    const requestMock = vi.fn((method: string, _params?: Record<string, unknown>) => {
+      if (method === "watch.unsubscribe") {
+        return Promise.reject(new Error("imsg rpc closed"));
+      }
+      return Promise.resolve({});
+    });
+    const stopMock = vi.fn(async () => {});
+
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown) => {
+      unhandled.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandled);
+
+    try {
+      const detach = attachIMessageMonitorAbortHandler({
+        abortSignal: abortController.signal,
+        client: {
+          request: requestMock,
+          stop: stopMock,
+        },
+        getSubscriptionId: () => subscriptionId,
+      });
+      abortController.abort();
+      // Give the event loop a turn to surface any unhandledRejection, if present.
+      await new Promise<void>((resolve) => {
+        if (typeof setImmediate === "function") {
+          setImmediate(resolve);
+          return;
+        }
+        setTimeout(resolve, 0);
+      });
+      detach();
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+
+    expect(unhandled).toHaveLength(0);
+    expect(stopMock).toHaveBeenCalled();
+    expect(requestMock).toHaveBeenCalledWith("watch.unsubscribe", { subscription: 1 });
+  });
+});
diff --git a/src/imessage/monitor.skips-group-messages-without-mention-by-default.test.ts b/src/imessage/monitor.skips-group-messages-without-mention-by-default.test.ts
deleted file mode 100644
index ae85c17e042..00000000000
--- a/src/imessage/monitor.skips-group-messages-without-mention-by-default.test.ts
+++ /dev/null
@@ -1,546 +0,0 @@
-import { beforeAll, describe, expect, it } from "vitest";
-import {
-  flush,
-  getCloseResolve,
-  getConfigMock,
-  getReadAllowFromStoreMock,
-  getNotificationHandler,
-  getReplyMock,
-  getRequestMock,
-  getSendMock,
-  getStopMock,
-  getUpsertPairingRequestMock,
-  getUpdateLastRouteMock,
-  installMonitorIMessageProviderTestHooks,
-  setConfigMock,
-  waitForSubscribe,
-} from "./monitor.test-harness.js";
-
-installMonitorIMessageProviderTestHooks();
-
-let monitorIMessageProvider: typeof import("./monitor.js").monitorIMessageProvider;
-
-beforeAll(async () => {
-  ({ monitorIMessageProvider } = await import("./monitor.js"));
-});
-
-function startMonitor() {
-  return monitorIMessageProvider();
-}
-const replyMock = getReplyMock();
-const requestMock = getRequestMock();
-const sendMock = getSendMock();
-const readAllowFromStoreMock = getReadAllowFromStoreMock();
-const stopMock = getStopMock();
-const upsertPairingRequestMock = getUpsertPairingRequestMock();
-const updateLastRouteMock = getUpdateLastRouteMock();
-
-type TestConfig = {
-  channels: Record<string, unknown> & { imessage: Record<string, unknown> };
-  messages: Record<string, unknown>;
-  session: Record<string, unknown>;
-  [k: string]: unknown;
-};
-
-function getConfig(): TestConfig {
-  return getConfigMock() as unknown as TestConfig;
-}
-
-function notifyMessage(message: unknown) {
-  getNotificationHandler()?.({
-    method: "message",
-    params: { message },
-  });
-}
-
-async function closeMonitor() {
-  for (let i = 0; i < 50; i += 1) {
-    const close = getCloseResolve();
-    if (close) {
-      close();
-      return;
-    }
-    await Promise.resolve();
-  }
-  for (let i = 0; i < 5; i += 1) {
-    const close = getCloseResolve();
-    if (close) {
-      close();
-      return;
-    }
-    await flush();
-  }
-  throw new Error("imessage test harness: closeResolve not set");
-}
-
-describe("monitorIMessageProvider", () => {
-  it("handles default config gating, formatting, and reply context", async () => {
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 1,
-      sender: { nested: "not-a-string" },
-      text: "hello",
-    });
-    await flush();
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(sendMock).not.toHaveBeenCalled();
-    replyMock.mockClear();
-    sendMock.mockClear();
-
-    notifyMessage({
-      id: 2,
-      chat_id: 99,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello group",
-      is_group: true,
-    });
-    await flush();
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(sendMock).not.toHaveBeenCalled();
-    replyMock.mockClear();
-    sendMock.mockClear();
-
-    replyMock.mockResolvedValueOnce({ text: "yo" });
-    notifyMessage({
-      id: 3,
-      chat_id: 42,
-      sender: "+15550002222",
-      is_from_me: false,
-      text: "@openclaw ping",
-      is_group: true,
-      chat_name: "Lobster Squad",
-      participants: ["+1555", "+1556"],
-    });
-    await flush();
-    expect(replyMock).toHaveBeenCalledOnce();
-    {
-      const ctx = replyMock.mock.calls[0]?.[0] as { Body?: string; ChatType?: string };
-      expect(ctx.ChatType).toBe("group");
-      // Sender should appear as prefix in group messages (no redundant [from:] suffix)
-      expect(String(ctx.Body ?? "")).toContain("+15550002222:");
-      expect(String(ctx.Body ?? "")).not.toContain("[from:");
-    }
-    expect(sendMock).toHaveBeenCalledWith(
-      "chat_id:42",
-      "yo",
-      expect.objectContaining({ client: expect.any(Object) }),
-    );
-    replyMock.mockClear();
-    sendMock.mockClear();
-
-    notifyMessage({
-      id: 4,
-      chat_id: 99,
-      chat_name: "Test Group",
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "@openclaw hi",
-      is_group: true,
-      created_at: "2026-01-17T00:00:00Z",
-    });
-    await flush();
-    expect(replyMock).toHaveBeenCalled();
-    {
-      const ctx = replyMock.mock.calls[0]?.[0];
-      const body = ctx?.Body ?? "";
-      expect(body).toContain("Test Group id:99");
-      expect(body).toContain("+15550001111: @openclaw hi");
-    }
-    replyMock.mockClear();
-    sendMock.mockClear();
-
-    notifyMessage({
-      id: 5,
-      chat_id: 55,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "replying now",
-      is_group: false,
-      reply_to_id: 9001,
-      reply_to_text: "original message",
-      reply_to_sender: "+15559998888",
-    });
-    await flush();
-    expect(replyMock).toHaveBeenCalled();
-    {
-      const ctx = replyMock.mock.calls[0]?.[0] as {
-        Body?: string;
-        ReplyToId?: string;
-        ReplyToBody?: string;
-        ReplyToSender?: string;
-      };
-      expect(ctx.ReplyToId).toBe("9001");
-      expect(ctx.ReplyToBody).toBe("original message");
-      expect(ctx.ReplyToSender).toBe("+15559998888");
-      expect(String(ctx.Body ?? "")).toContain("[Replying to +15559998888 id:9001]");
-      expect(String(ctx.Body ?? "")).toContain("original message");
-    }
-    expect(updateLastRouteMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        deliveryContext: expect.objectContaining({
-          channel: "imessage",
-          to: "+15550001111",
-        }),
-      }),
-    );
-
-    await closeMonitor();
-    await run;
-  });
-
-  it("allows group messages when imessage groups default disables mention gating", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 11,
-      chat_id: 123,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello group",
-      is_group: true,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).toHaveBeenCalled();
-  });
-
-  it("allows group messages when requireMention is true but no mentionPatterns exist", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      messages: {
-        ...config.messages,
-        groupChat: { mentionPatterns: [] },
-      },
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 12,
-      chat_id: 777,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello group",
-      is_group: true,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).toHaveBeenCalled();
-  });
-
-  it("blocks group messages when imessage.groups is set without a wildcard", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          groups: { "99": { requireMention: false } },
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 13,
-      chat_id: 123,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "@openclaw hello",
-      is_group: true,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(sendMock).not.toHaveBeenCalled();
-  });
-
-  it("treats configured chat_id as a group session even when is_group is false", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          dmPolicy: "open",
-          allowFrom: ["*"],
-          groups: { "2": { requireMention: false } },
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 14,
-      chat_id: 2,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello",
-      is_group: false,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).toHaveBeenCalled();
-    const ctx = replyMock.mock.calls[0]?.[0] as {
-      ChatType?: string;
-      SessionKey?: string;
-    };
-    expect(ctx.ChatType).toBe("group");
-    expect(ctx.SessionKey).toBe("agent:main:imessage:group:2");
-  });
-
-  it("prefixes final replies with responsePrefix", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      messages: {
-        ...config.messages,
-        responsePrefix: "PFX",
-      },
-    });
-    replyMock.mockResolvedValue({ text: "final reply" });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 7,
-      chat_id: 77,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello",
-      is_group: false,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(sendMock.mock.calls[0][1]).toBe("PFX final reply");
-  });
-
-  it("defaults to dmPolicy=pairing behavior when allowFrom is empty", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          dmPolicy: "pairing",
-          allowFrom: [],
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 99,
-      chat_id: 77,
-      sender: "+15550001111",
-      is_from_me: false,
-      text: "hello",
-      is_group: false,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(upsertPairingRequestMock).toHaveBeenCalled();
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain(
-      "Your iMessage sender id: +15550001111",
-    );
-    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain("Pairing code: PAIRCODE");
-  });
-
-  it("honors group allowlist and ignores pairing-store senders in groups", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          dmPolicy: "pairing",
-          allowFrom: [],
-          groupPolicy: "allowlist",
-          groupAllowFrom: ["chat_id:101"],
-        },
-      },
-    });
-    readAllowFromStoreMock.mockResolvedValue(["+15550003333"]);
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    replyMock.mockClear();
-    sendMock.mockClear();
-    notifyMessage({
-      id: 3,
-      chat_id: 202,
-      sender: "+15550003333",
-      is_from_me: false,
-      text: "@openclaw hi",
-      is_group: true,
-    });
-
-    await flush();
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(sendMock).not.toHaveBeenCalled();
-
-    replyMock.mockClear();
-    sendMock.mockClear();
-    notifyMessage({
-      id: 31,
-      chat_id: 202,
-      sender: "+15550003333",
-      is_from_me: false,
-      text: "/status",
-      is_group: true,
-    });
-
-    await flush();
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(sendMock).not.toHaveBeenCalled();
-
-    replyMock.mockClear();
-    sendMock.mockClear();
-    notifyMessage({
-      id: 33,
-      chat_id: 101,
-      sender: "+15550003333",
-      is_from_me: false,
-      text: "@openclaw ok",
-      is_group: true,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).toHaveBeenCalled();
-    expect(sendMock).toHaveBeenCalled();
-  });
-
-  it("blocks group messages when groupPolicy is disabled", async () => {
-    const config = getConfig();
-    setConfigMock({
-      ...config,
-      channels: {
-        ...config.channels,
-        imessage: {
-          ...config.channels.imessage,
-          groupPolicy: "disabled",
-        },
-      },
-    });
-
-    const run = startMonitor();
-    await waitForSubscribe();
-
-    notifyMessage({
-      id: 10,
-      chat_id: 303,
-      sender: "+15550003333",
-      is_from_me: false,
-      text: "@openclaw hi",
-      is_group: true,
-    });
-
-    await flush();
-    await closeMonitor();
-    await run;
-
-    expect(replyMock).not.toHaveBeenCalled();
-  });
-
-  it("does not trigger unhandledRejection when aborting during shutdown", async () => {
-    requestMock.mockImplementation((method: string) => {
-      if (method === "watch.subscribe") {
-        return Promise.resolve({ subscription: 1 });
-      }
-      if (method === "watch.unsubscribe") {
-        return Promise.reject(new Error("imsg rpc closed"));
-      }
-      return Promise.resolve({});
-    });
-
-    const abortController = new AbortController();
-    const unhandled: unknown[] = [];
-    const onUnhandled = (reason: unknown) => {
-      unhandled.push(reason);
-    };
-    process.on("unhandledRejection", onUnhandled);
-
-    try {
-      const run = monitorIMessageProvider({
-        abortSignal: abortController.signal,
-      });
-      await waitForSubscribe();
-      await flush();
-
-      abortController.abort();
-      await flush();
-
-      await closeMonitor();
-      await run;
-    } finally {
-      process.off("unhandledRejection", onUnhandled);
-    }
-
-    expect(unhandled).toHaveLength(0);
-    expect(stopMock).toHaveBeenCalled();
-  });
-});
diff --git a/src/imessage/monitor.test-harness.ts b/src/imessage/monitor.test-harness.ts
deleted file mode 100644
index 2233c21bee1..00000000000
--- a/src/imessage/monitor.test-harness.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-import { beforeEach, vi } from "vitest";
-
-type NotificationHandler = (msg: { method: string; params?: unknown }) => void;
-
-// Avoid exporting vitest mock types (TS2742 under pnpm + d.ts emit).
-// oxlint-disable-next-line typescript/no-explicit-any
-type AnyMock = any;
-
-const state = vi.hoisted(() => ({
-  requestMock: vi.fn(),
-  stopMock: vi.fn(),
-  sendMock: vi.fn(),
-  replyMock: vi.fn(),
-  updateLastRouteMock: vi.fn(),
-  readAllowFromStoreMock: vi.fn(),
-  upsertPairingRequestMock: vi.fn(),
-  config: {} as Record<string, unknown>,
-  notificationHandler: undefined as NotificationHandler | undefined,
-  closeResolve: undefined as (() => void) | undefined,
-}));
-
-export function getRequestMock(): AnyMock {
-  return state.requestMock;
-}
-
-export function getStopMock(): AnyMock {
-  return state.stopMock;
-}
-
-export function getSendMock(): AnyMock {
-  return state.sendMock;
-}
-
-export function getReplyMock(): AnyMock {
-  return state.replyMock;
-}
-
-export function getUpdateLastRouteMock(): AnyMock {
-  return state.updateLastRouteMock;
-}
-
-export function getReadAllowFromStoreMock(): AnyMock {
-  return state.readAllowFromStoreMock;
-}
-
-export function getUpsertPairingRequestMock(): AnyMock {
-  return state.upsertPairingRequestMock;
-}
-
-export function getNotificationHandler(): NotificationHandler | undefined {
-  return state.notificationHandler;
-}
-
-export function getCloseResolve(): (() => void) | undefined {
-  return state.closeResolve;
-}
-
-export function setConfigMock(next: Record<string, unknown>) {
-  state.config = next;
-}
-
-export function getConfigMock() {
-  return state.config;
-}
-
-vi.mock("../config/config.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../config/config.js")>();
-  return {
-    ...actual,
-    loadConfig: () => state.config,
-  };
-});
-
-vi.mock("../auto-reply/reply.js", () => ({
-  getReplyFromConfig: (...args: unknown[]) => state.replyMock(...args),
-}));
-
-vi.mock("./send.js", () => ({
-  sendMessageIMessage: (...args: unknown[]) => state.sendMock(...args),
-}));
-
-vi.mock("../pairing/pairing-store.js", () => ({
-  readChannelAllowFromStore: (...args: unknown[]) => state.readAllowFromStoreMock(...args),
-  upsertChannelPairingRequest: (...args: unknown[]) => state.upsertPairingRequestMock(...args),
-}));
-
-vi.mock("../config/sessions.js", () => ({
-  resolveStorePath: vi.fn(() => "/tmp/openclaw-sessions.json"),
-  updateLastRoute: (...args: unknown[]) => state.updateLastRouteMock(...args),
-  readSessionUpdatedAt: vi.fn(() => undefined),
-  recordSessionMetaFromInbound: vi.fn().mockResolvedValue(undefined),
-}));
-
-vi.mock("./client.js", () => ({
-  createIMessageRpcClient: vi.fn(async (opts: { onNotification?: NotificationHandler }) => {
-    state.notificationHandler = opts.onNotification;
-    return {
-      request: (...args: unknown[]) => state.requestMock(...args),
-      waitForClose: () =>
-        new Promise<void>((resolve) => {
-          state.closeResolve = resolve;
-        }),
-      stop: (...args: unknown[]) => state.stopMock(...args),
-    };
-  }),
-}));
-
-vi.mock("./probe.js", () => ({
-  probeIMessage: vi.fn(async () => ({ ok: true })),
-}));
-
-export const flush = () =>
-  new Promise<void>((resolve) => {
-    if (typeof setImmediate === "function") {
-      setImmediate(resolve);
-      return;
-    }
-    setTimeout(resolve, 0);
-  });
-
-export async function waitForSubscribe() {
-  for (let i = 0; i < 25; i += 1) {
-    if (state.requestMock.mock.calls.some((call) => call[0] === "watch.subscribe")) {
-      return;
-    }
-    // Prefer microtask turns over timers for speed.
-    await Promise.resolve();
-  }
-  for (let i = 0; i < 5; i += 1) {
-    if (state.requestMock.mock.calls.some((call) => call[0] === "watch.subscribe")) {
-      return;
-    }
-    await flush();
-  }
-  throw new Error("imessage test harness: watch.subscribe not observed");
-}
-
-export function installMonitorIMessageProviderTestHooks() {
-  beforeEach(() => {
-    state.config = {
-      channels: {
-        imessage: {
-          dmPolicy: "open",
-          allowFrom: ["*"],
-          groups: { "*": { requireMention: true } },
-        },
-      },
-      session: { mainKey: "main" },
-      messages: {
-        groupChat: { mentionPatterns: ["@openclaw"] },
-      },
-    };
-    state.requestMock.mockReset().mockImplementation((method: string) => {
-      if (method === "watch.subscribe") {
-        return Promise.resolve({ subscription: 1 });
-      }
-      return Promise.resolve({});
-    });
-    state.stopMock.mockReset().mockResolvedValue(undefined);
-    state.sendMock.mockReset().mockResolvedValue({ messageId: "ok" });
-    state.replyMock.mockReset().mockResolvedValue({ text: "ok" });
-    state.updateLastRouteMock.mockReset();
-    state.readAllowFromStoreMock.mockReset().mockResolvedValue([]);
-    state.upsertPairingRequestMock
-      .mockReset()
-      .mockResolvedValue({ code: "PAIRCODE", created: true });
-    state.notificationHandler = undefined;
-    state.closeResolve = undefined;
-  });
-}
diff --git a/src/imessage/monitor/abort-handler.ts b/src/imessage/monitor/abort-handler.ts
new file mode 100644
index 00000000000..bd5388260df
--- /dev/null
+++ b/src/imessage/monitor/abort-handler.ts
@@ -0,0 +1,34 @@
+export type IMessageMonitorClient = {
+  request: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+  stop: () => Promise<void>;
+};
+
+export function attachIMessageMonitorAbortHandler(params: {
+  abortSignal?: AbortSignal;
+  client: IMessageMonitorClient;
+  getSubscriptionId: () => number | null;
+}): () => void {
+  const abort = params.abortSignal;
+  if (!abort) {
+    return () => {};
+  }
+
+  const onAbort = () => {
+    const subscriptionId = params.getSubscriptionId();
+    if (subscriptionId) {
+      void params.client
+        .request("watch.unsubscribe", {
+          subscription: subscriptionId,
+        })
+        .catch(() => {
+          // Ignore disconnect errors during shutdown.
+        });
+    }
+    void params.client.stop().catch(() => {
+      // Ignore disconnect errors during shutdown.
+    });
+  };
+
+  abort.addEventListener("abort", onAbort, { once: true });
+  return () => abort.removeEventListener("abort", onAbort);
+}
diff --git a/src/imessage/monitor/inbound-processing.ts b/src/imessage/monitor/inbound-processing.ts
new file mode 100644
index 00000000000..df8549c0734
--- /dev/null
+++ b/src/imessage/monitor/inbound-processing.ts
@@ -0,0 +1,483 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { MonitorIMessageOpts, IMessagePayload } from "./types.js";
+import { hasControlCommand } from "../../auto-reply/command-detection.js";
+import {
+  formatInboundEnvelope,
+  formatInboundFromLabel,
+  resolveEnvelopeFormatOptions,
+  type EnvelopeFormatOptions,
+} from "../../auto-reply/envelope.js";
+import {
+  buildPendingHistoryContextFromMap,
+  recordPendingHistoryEntryIfEnabled,
+  type HistoryEntry,
+} from "../../auto-reply/reply/history.js";
+import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
+import { buildMentionRegexes, matchesMentionPatterns } from "../../auto-reply/reply/mentions.js";
+import { resolveControlCommandGate } from "../../channels/command-gating.js";
+import { logInboundDrop } from "../../channels/logging.js";
+import {
+  resolveChannelGroupPolicy,
+  resolveChannelGroupRequireMention,
+} from "../../config/group-policy.js";
+import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { truncateUtf16Safe } from "../../utils.js";
+import {
+  formatIMessageChatTarget,
+  isAllowedIMessageSender,
+  normalizeIMessageHandle,
+} from "../targets.js";
+
+type IMessageReplyContext = {
+  id?: string;
+  body: string;
+  sender?: string;
+};
+
+function normalizeReplyField(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  return undefined;
+}
+
+function describeReplyContext(message: IMessagePayload): IMessageReplyContext | null {
+  const body = normalizeReplyField(message.reply_to_text);
+  if (!body) {
+    return null;
+  }
+  const id = normalizeReplyField(message.reply_to_id);
+  const sender = normalizeReplyField(message.reply_to_sender);
+  return { body, id, sender };
+}
+
+export type IMessageInboundDispatchDecision = {
+  kind: "dispatch";
+  isGroup: boolean;
+  chatId?: number;
+  chatGuid?: string;
+  chatIdentifier?: string;
+  groupId?: string;
+  historyKey?: string;
+  sender: string;
+  senderNormalized: string;
+  route: ReturnType<typeof resolveAgentRoute>;
+  bodyText: string;
+  createdAt?: number;
+  replyContext: IMessageReplyContext | null;
+  effectiveWasMentioned: boolean;
+  commandAuthorized: boolean;
+  // Used for allowlist checks for control commands.
+  effectiveDmAllowFrom: string[];
+  effectiveGroupAllowFrom: string[];
+};
+
+export type IMessageInboundDecision =
+  | { kind: "drop"; reason: string }
+  | { kind: "pairing"; senderId: string }
+  | IMessageInboundDispatchDecision;
+
+export function resolveIMessageInboundDecision(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  message: IMessagePayload;
+  opts?: Pick<MonitorIMessageOpts, "requireMention">;
+  messageText: string;
+  bodyText: string;
+  allowFrom: string[];
+  groupAllowFrom: string[];
+  groupPolicy: string;
+  dmPolicy: string;
+  storeAllowFrom: string[];
+  historyLimit: number;
+  groupHistories: Map<string, HistoryEntry[]>;
+  echoCache?: { has: (scope: string, text: string) => boolean };
+  logVerbose?: (msg: string) => void;
+}): IMessageInboundDecision {
+  const senderRaw = params.message.sender ?? "";
+  const sender = senderRaw.trim();
+  if (!sender) {
+    return { kind: "drop", reason: "missing sender" };
+  }
+  const senderNormalized = normalizeIMessageHandle(sender);
+  if (params.message.is_from_me) {
+    return { kind: "drop", reason: "from me" };
+  }
+
+  const chatId = params.message.chat_id ?? undefined;
+  const chatGuid = params.message.chat_guid ?? undefined;
+  const chatIdentifier = params.message.chat_identifier ?? undefined;
+
+  const groupIdCandidate = chatId !== undefined ? String(chatId) : undefined;
+  const groupListPolicy = groupIdCandidate
+    ? resolveChannelGroupPolicy({
+        cfg: params.cfg,
+        channel: "imessage",
+        accountId: params.accountId,
+        groupId: groupIdCandidate,
+      })
+    : {
+        allowlistEnabled: false,
+        allowed: true,
+        groupConfig: undefined,
+        defaultConfig: undefined,
+      };
+
+  // If the owner explicitly configures a chat_id under imessage.groups, treat that thread as a
+  // "group" for permission gating + session isolation, even when is_group=false.
+  const treatAsGroupByConfig = Boolean(
+    groupIdCandidate && groupListPolicy.allowlistEnabled && groupListPolicy.groupConfig,
+  );
+  const isGroup = Boolean(params.message.is_group) || treatAsGroupByConfig;
+  if (isGroup && !chatId) {
+    return { kind: "drop", reason: "group without chat_id" };
+  }
+
+  const groupId = isGroup ? groupIdCandidate : undefined;
+  const effectiveDmAllowFrom = Array.from(new Set([...params.allowFrom, ...params.storeAllowFrom]))
+    .map((v) => String(v).trim())
+    .filter(Boolean);
+  // Keep DM pairing-store authorization scoped to DMs; group access must come from explicit group allowlist config.
+  const effectiveGroupAllowFrom = Array.from(new Set(params.groupAllowFrom))
+    .map((v) => String(v).trim())
+    .filter(Boolean);
+
+  if (isGroup) {
+    if (params.groupPolicy === "disabled") {
+      params.logVerbose?.("Blocked iMessage group message (groupPolicy: disabled)");
+      return { kind: "drop", reason: "groupPolicy disabled" };
+    }
+    if (params.groupPolicy === "allowlist") {
+      if (effectiveGroupAllowFrom.length === 0) {
+        params.logVerbose?.(
+          "Blocked iMessage group message (groupPolicy: allowlist, no groupAllowFrom)",
+        );
+        return { kind: "drop", reason: "groupPolicy allowlist (empty groupAllowFrom)" };
+      }
+      const allowed = isAllowedIMessageSender({
+        allowFrom: effectiveGroupAllowFrom,
+        sender,
+        chatId,
+        chatGuid,
+        chatIdentifier,
+      });
+      if (!allowed) {
+        params.logVerbose?.(`Blocked iMessage sender ${sender} (not in groupAllowFrom)`);
+        return { kind: "drop", reason: "not in groupAllowFrom" };
+      }
+    }
+    if (groupListPolicy.allowlistEnabled && !groupListPolicy.allowed) {
+      params.logVerbose?.(
+        `imessage: skipping group message (${groupId ?? "unknown"}) not in allowlist`,
+      );
+      return { kind: "drop", reason: "group id not in allowlist" };
+    }
+  }
+
+  const dmHasWildcard = effectiveDmAllowFrom.includes("*");
+  const dmAuthorized =
+    params.dmPolicy === "open"
+      ? true
+      : dmHasWildcard ||
+        (effectiveDmAllowFrom.length > 0 &&
+          isAllowedIMessageSender({
+            allowFrom: effectiveDmAllowFrom,
+            sender,
+            chatId,
+            chatGuid,
+            chatIdentifier,
+          }));
+
+  if (!isGroup) {
+    if (params.dmPolicy === "disabled") {
+      return { kind: "drop", reason: "dmPolicy disabled" };
+    }
+    if (!dmAuthorized) {
+      if (params.dmPolicy === "pairing") {
+        return { kind: "pairing", senderId: senderNormalized };
+      }
+      params.logVerbose?.(`Blocked iMessage sender ${sender} (dmPolicy=${params.dmPolicy})`);
+      return { kind: "drop", reason: "dmPolicy blocked" };
+    }
+  }
+
+  const route = resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "imessage",
+    accountId: params.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: isGroup ? String(chatId ?? "unknown") : senderNormalized,
+    },
+  });
+  const mentionRegexes = buildMentionRegexes(params.cfg, route.agentId);
+  const messageText = params.messageText.trim();
+  const bodyText = params.bodyText.trim();
+  if (!bodyText) {
+    return { kind: "drop", reason: "empty body" };
+  }
+
+  // Echo detection: check if the received message matches a recently sent message (within 5 seconds).
+  // Scope by conversation so same text in different chats is not conflated.
+  if (params.echoCache && messageText) {
+    const echoScope = buildIMessageEchoScope({
+      accountId: params.accountId,
+      isGroup,
+      chatId,
+      sender,
+    });
+    if (params.echoCache.has(echoScope, messageText)) {
+      params.logVerbose?.(describeIMessageEchoDropLog({ messageText }));
+      return { kind: "drop", reason: "echo" };
+    }
+  }
+
+  const replyContext = describeReplyContext(params.message);
+  const createdAt = params.message.created_at ? Date.parse(params.message.created_at) : undefined;
+  const historyKey = isGroup
+    ? String(chatId ?? chatGuid ?? chatIdentifier ?? "unknown")
+    : undefined;
+
+  const mentioned = isGroup ? matchesMentionPatterns(messageText, mentionRegexes) : true;
+  const requireMention = resolveChannelGroupRequireMention({
+    cfg: params.cfg,
+    channel: "imessage",
+    accountId: params.accountId,
+    groupId,
+    requireMentionOverride: params.opts?.requireMention,
+    overrideOrder: "before-config",
+  });
+  const canDetectMention = mentionRegexes.length > 0;
+
+  const useAccessGroups = params.cfg.commands?.useAccessGroups !== false;
+  const ownerAllowedForCommands =
+    effectiveDmAllowFrom.length > 0
+      ? isAllowedIMessageSender({
+          allowFrom: effectiveDmAllowFrom,
+          sender,
+          chatId,
+          chatGuid,
+          chatIdentifier,
+        })
+      : false;
+  const groupAllowedForCommands =
+    effectiveGroupAllowFrom.length > 0
+      ? isAllowedIMessageSender({
+          allowFrom: effectiveGroupAllowFrom,
+          sender,
+          chatId,
+          chatGuid,
+          chatIdentifier,
+        })
+      : false;
+  const hasControlCommandInMessage = hasControlCommand(messageText, params.cfg);
+  const commandGate = resolveControlCommandGate({
+    useAccessGroups,
+    authorizers: [
+      { configured: effectiveDmAllowFrom.length > 0, allowed: ownerAllowedForCommands },
+      { configured: effectiveGroupAllowFrom.length > 0, allowed: groupAllowedForCommands },
+    ],
+    allowTextCommands: true,
+    hasControlCommand: hasControlCommandInMessage,
+  });
+  const commandAuthorized = isGroup ? commandGate.commandAuthorized : dmAuthorized;
+  if (isGroup && commandGate.shouldBlock) {
+    if (params.logVerbose) {
+      logInboundDrop({
+        log: params.logVerbose,
+        channel: "imessage",
+        reason: "control command (unauthorized)",
+        target: sender,
+      });
+    }
+    return { kind: "drop", reason: "control command (unauthorized)" };
+  }
+
+  const shouldBypassMention =
+    isGroup && requireMention && !mentioned && commandAuthorized && hasControlCommandInMessage;
+  const effectiveWasMentioned = mentioned || shouldBypassMention;
+  if (isGroup && requireMention && canDetectMention && !mentioned && !shouldBypassMention) {
+    params.logVerbose?.(`imessage: skipping group message (no mention)`);
+    recordPendingHistoryEntryIfEnabled({
+      historyMap: params.groupHistories,
+      historyKey: historyKey ?? "",
+      limit: params.historyLimit,
+      entry: historyKey
+        ? {
+            sender: senderNormalized,
+            body: bodyText,
+            timestamp: createdAt,
+            messageId: params.message.id ? String(params.message.id) : undefined,
+          }
+        : null,
+    });
+    return { kind: "drop", reason: "no mention" };
+  }
+
+  return {
+    kind: "dispatch",
+    isGroup,
+    chatId,
+    chatGuid,
+    chatIdentifier,
+    groupId,
+    historyKey,
+    sender,
+    senderNormalized,
+    route,
+    bodyText,
+    createdAt,
+    replyContext,
+    effectiveWasMentioned,
+    commandAuthorized,
+    effectiveDmAllowFrom,
+    effectiveGroupAllowFrom,
+  };
+}
+
+export function buildIMessageInboundContext(params: {
+  cfg: OpenClawConfig;
+  decision: IMessageInboundDispatchDecision;
+  message: IMessagePayload;
+  envelopeOptions?: EnvelopeFormatOptions;
+  previousTimestamp?: number;
+  remoteHost?: string;
+  media?: {
+    path?: string;
+    type?: string;
+    paths?: string[];
+    types?: Array<string | undefined>;
+  };
+  historyLimit: number;
+  groupHistories: Map<string, HistoryEntry[]>;
+}): {
+  ctxPayload: ReturnType<typeof finalizeInboundContext>;
+  fromLabel: string;
+  chatTarget?: string;
+  imessageTo: string;
+  inboundHistory?: Array<{ sender: string; body: string; timestamp?: number }>;
+} {
+  const envelopeOptions = params.envelopeOptions ?? resolveEnvelopeFormatOptions(params.cfg);
+  const { decision } = params;
+  const chatId = decision.chatId;
+  const chatTarget =
+    decision.isGroup && chatId != null ? formatIMessageChatTarget(chatId) : undefined;
+
+  const replySuffix = decision.replyContext
+    ? `\n\n[Replying to ${decision.replyContext.sender ?? "unknown sender"}${
+        decision.replyContext.id ? ` id:${decision.replyContext.id}` : ""
+      }]\n${decision.replyContext.body}\n[/Replying]`
+    : "";
+
+  const fromLabel = formatInboundFromLabel({
+    isGroup: decision.isGroup,
+    groupLabel: params.message.chat_name ?? undefined,
+    groupId: chatId !== undefined ? String(chatId) : "unknown",
+    groupFallback: "Group",
+    directLabel: decision.senderNormalized,
+    directId: decision.sender,
+  });
+
+  const body = formatInboundEnvelope({
+    channel: "iMessage",
+    from: fromLabel,
+    timestamp: decision.createdAt,
+    body: `${decision.bodyText}${replySuffix}`,
+    chatType: decision.isGroup ? "group" : "direct",
+    sender: { name: decision.senderNormalized, id: decision.sender },
+    previousTimestamp: params.previousTimestamp,
+    envelope: envelopeOptions,
+  });
+
+  let combinedBody = body;
+  if (decision.isGroup && decision.historyKey) {
+    combinedBody = buildPendingHistoryContextFromMap({
+      historyMap: params.groupHistories,
+      historyKey: decision.historyKey,
+      limit: params.historyLimit,
+      currentMessage: combinedBody,
+      formatEntry: (entry) =>
+        formatInboundEnvelope({
+          channel: "iMessage",
+          from: fromLabel,
+          timestamp: entry.timestamp,
+          body: `${entry.body}${entry.messageId ? ` [id:${entry.messageId}]` : ""}`,
+          chatType: "group",
+          senderLabel: entry.sender,
+          envelope: envelopeOptions,
+        }),
+    });
+  }
+
+  const imessageTo = (decision.isGroup ? chatTarget : undefined) || `imessage:${decision.sender}`;
+  const inboundHistory =
+    decision.isGroup && decision.historyKey && params.historyLimit > 0
+      ? (params.groupHistories.get(decision.historyKey) ?? []).map((entry) => ({
+          sender: entry.sender,
+          body: entry.body,
+          timestamp: entry.timestamp,
+        }))
+      : undefined;
+
+  const ctxPayload = finalizeInboundContext({
+    Body: combinedBody,
+    BodyForAgent: decision.bodyText,
+    InboundHistory: inboundHistory,
+    RawBody: decision.bodyText,
+    CommandBody: decision.bodyText,
+    From: decision.isGroup
+      ? `imessage:group:${chatId ?? "unknown"}`
+      : `imessage:${decision.sender}`,
+    To: imessageTo,
+    SessionKey: decision.route.sessionKey,
+    AccountId: decision.route.accountId,
+    ChatType: decision.isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    GroupSubject: decision.isGroup ? (params.message.chat_name ?? undefined) : undefined,
+    GroupMembers: decision.isGroup
+      ? (params.message.participants ?? []).filter(Boolean).join(", ")
+      : undefined,
+    SenderName: decision.senderNormalized,
+    SenderId: decision.sender,
+    Provider: "imessage",
+    Surface: "imessage",
+    MessageSid: params.message.id ? String(params.message.id) : undefined,
+    ReplyToId: decision.replyContext?.id,
+    ReplyToBody: decision.replyContext?.body,
+    ReplyToSender: decision.replyContext?.sender,
+    Timestamp: decision.createdAt,
+    MediaPath: params.media?.path,
+    MediaType: params.media?.type,
+    MediaUrl: params.media?.path,
+    MediaPaths:
+      params.media?.paths && params.media.paths.length > 0 ? params.media.paths : undefined,
+    MediaTypes:
+      params.media?.types && params.media.types.length > 0 ? params.media.types : undefined,
+    MediaUrls:
+      params.media?.paths && params.media.paths.length > 0 ? params.media.paths : undefined,
+    MediaRemoteHost: params.remoteHost,
+    WasMentioned: decision.effectiveWasMentioned,
+    CommandAuthorized: decision.commandAuthorized,
+    OriginatingChannel: "imessage" as const,
+    OriginatingTo: imessageTo,
+  });
+
+  return { ctxPayload, fromLabel, chatTarget, imessageTo, inboundHistory };
+}
+
+export function buildIMessageEchoScope(params: {
+  accountId: string;
+  isGroup: boolean;
+  chatId?: number;
+  sender: string;
+}): string {
+  return `${params.accountId}:${params.isGroup ? formatIMessageChatTarget(params.chatId) : `imessage:${params.sender}`}`;
+}
+
+export function describeIMessageEchoDropLog(params: { messageText: string }): string {
+  return `imessage: skipping echo message (matches recently sent text within 5s): "${truncateUtf16Safe(params.messageText, 50)}"`;
+}
diff --git a/src/imessage/monitor/monitor-provider.ts b/src/imessage/monitor/monitor-provider.ts
index f918bf6a170..bf7dc90681f 100644
--- a/src/imessage/monitor/monitor-provider.ts
+++ b/src/imessage/monitor/monitor-provider.ts
@@ -4,34 +4,19 @@ import { resolveHumanDelayConfig } from "../../agents/identity.js";
 import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
 import { dispatchInboundMessage } from "../../auto-reply/dispatch.js";
-import {
-  formatInboundEnvelope,
-  formatInboundFromLabel,
-  resolveEnvelopeFormatOptions,
-} from "../../auto-reply/envelope.js";
 import {
   createInboundDebouncer,
   resolveInboundDebounceMs,
 } from "../../auto-reply/inbound-debounce.js";
 import {
-  buildPendingHistoryContextFromMap,
   clearHistoryEntriesIfEnabled,
   DEFAULT_GROUP_HISTORY_LIMIT,
-  recordPendingHistoryEntryIfEnabled,
   type HistoryEntry,
 } from "../../auto-reply/reply/history.js";
-import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
-import { buildMentionRegexes, matchesMentionPatterns } from "../../auto-reply/reply/mentions.js";
 import { createReplyDispatcher } from "../../auto-reply/reply/reply-dispatcher.js";
-import { resolveControlCommandGate } from "../../channels/command-gating.js";
-import { logInboundDrop } from "../../channels/logging.js";
 import { createReplyPrefixOptions } from "../../channels/reply-prefix.js";
 import { recordInboundSession } from "../../channels/session.js";
 import { loadConfig } from "../../config/config.js";
-import {
-  resolveChannelGroupPolicy,
-  resolveChannelGroupRequireMention,
-} from "../../config/group-policy.js";
 import { readSessionUpdatedAt, resolveStorePath } from "../../config/sessions.js";
 import { danger, logVerbose, shouldLogVerbose } from "../../globals.js";
 import { waitForTransportReady } from "../../infra/transport-ready.js";
@@ -41,19 +26,18 @@ import {
   readChannelAllowFromStore,
   upsertChannelPairingRequest,
 } from "../../pairing/pairing-store.js";
-import { resolveAgentRoute } from "../../routing/resolve-route.js";
 import { truncateUtf16Safe } from "../../utils.js";
 import { resolveIMessageAccount } from "../accounts.js";
 import { createIMessageRpcClient } from "../client.js";
 import { DEFAULT_IMESSAGE_PROBE_TIMEOUT_MS } from "../constants.js";
 import { probeIMessage } from "../probe.js";
 import { sendMessageIMessage } from "../send.js";
-import {
-  formatIMessageChatTarget,
-  isAllowedIMessageSender,
-  normalizeIMessageHandle,
-} from "../targets.js";
+import { attachIMessageMonitorAbortHandler } from "./abort-handler.js";
 import { deliverReplies } from "./deliver.js";
+import {
+  buildIMessageInboundContext,
+  resolveIMessageInboundDecision,
+} from "./inbound-processing.js";
 import { parseIMessageNotification } from "./parse-notification.js";
 import { normalizeAllowList, resolveRuntime } from "./runtime.js";
 
@@ -85,33 +69,6 @@ async function detectRemoteHostFromCliPath(cliPath: string): Promise<string | un
   }
 }
 
-type IMessageReplyContext = {
-  id?: string;
-  body: string;
-  sender?: string;
-};
-
-function normalizeReplyField(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    return trimmed ? trimmed : undefined;
-  }
-  if (typeof value === "number") {
-    return String(value);
-  }
-  return undefined;
-}
-
-function describeReplyContext(message: IMessagePayload): IMessageReplyContext | null {
-  const body = normalizeReplyField(message.reply_to_text);
-  if (!body) {
-    return null;
-  }
-  const id = normalizeReplyField(message.reply_to_id);
-  const sender = normalizeReplyField(message.reply_to_sender);
-  return { body, id, sender };
-}
-
 /**
  * Cache for recently sent messages, used for echo detection.
  * Keys are scoped by conversation (accountId:target) so the same text in different chats is not conflated.
@@ -248,165 +205,8 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
   });
 
   async function handleMessageNow(message: IMessagePayload) {
-    const senderRaw = message.sender ?? "";
-    const sender = senderRaw.trim();
-    if (!sender) {
-      return;
-    }
-    const senderNormalized = normalizeIMessageHandle(sender);
-    if (message.is_from_me) {
-      return;
-    }
-
-    const chatId = message.chat_id ?? undefined;
-    const chatGuid = message.chat_guid ?? undefined;
-    const chatIdentifier = message.chat_identifier ?? undefined;
-
-    const groupIdCandidate = chatId !== undefined ? String(chatId) : undefined;
-    const groupListPolicy = groupIdCandidate
-      ? resolveChannelGroupPolicy({
-          cfg,
-          channel: "imessage",
-          accountId: accountInfo.accountId,
-          groupId: groupIdCandidate,
-        })
-      : {
-          allowlistEnabled: false,
-          allowed: true,
-          groupConfig: undefined,
-          defaultConfig: undefined,
-        };
-
-    // Some iMessage threads can have multiple participants but still report
-    // is_group=false depending on how Messages stores the identifier.
-    // If the owner explicitly configures a chat_id under imessage.groups, treat
-    // that thread as a "group" for permission gating and session isolation.
-    const treatAsGroupByConfig = Boolean(
-      groupIdCandidate && groupListPolicy.allowlistEnabled && groupListPolicy.groupConfig,
-    );
-
-    const isGroup = Boolean(message.is_group) || treatAsGroupByConfig;
-    if (isGroup && !chatId) {
-      return;
-    }
-
-    const groupId = isGroup ? groupIdCandidate : undefined;
-    const storeAllowFrom = await readChannelAllowFromStore("imessage").catch(() => []);
-    const effectiveDmAllowFrom = Array.from(new Set([...allowFrom, ...storeAllowFrom]))
-      .map((v) => String(v).trim())
-      .filter(Boolean);
-    // Keep DM pairing-store authorization scoped to DMs; group access must come
-    // from explicit group allowlist config.
-    const effectiveGroupAllowFrom = Array.from(new Set(groupAllowFrom))
-      .map((v) => String(v).trim())
-      .filter(Boolean);
-
-    if (isGroup) {
-      if (groupPolicy === "disabled") {
-        logVerbose("Blocked iMessage group message (groupPolicy: disabled)");
-        return;
-      }
-      if (groupPolicy === "allowlist") {
-        if (effectiveGroupAllowFrom.length === 0) {
-          logVerbose("Blocked iMessage group message (groupPolicy: allowlist, no groupAllowFrom)");
-          return;
-        }
-        const allowed = isAllowedIMessageSender({
-          allowFrom: effectiveGroupAllowFrom,
-          sender,
-          chatId: chatId ?? undefined,
-          chatGuid,
-          chatIdentifier,
-        });
-        if (!allowed) {
-          logVerbose(`Blocked iMessage sender ${sender} (not in groupAllowFrom)`);
-          return;
-        }
-      }
-      if (groupListPolicy.allowlistEnabled && !groupListPolicy.allowed) {
-        logVerbose(`imessage: skipping group message (${groupId ?? "unknown"}) not in allowlist`);
-        return;
-      }
-    }
-
-    const dmHasWildcard = effectiveDmAllowFrom.includes("*");
-    const dmAuthorized =
-      dmPolicy === "open"
-        ? true
-        : dmHasWildcard ||
-          (effectiveDmAllowFrom.length > 0 &&
-            isAllowedIMessageSender({
-              allowFrom: effectiveDmAllowFrom,
-              sender,
-              chatId: chatId ?? undefined,
-              chatGuid,
-              chatIdentifier,
-            }));
-    if (!isGroup) {
-      if (dmPolicy === "disabled") {
-        return;
-      }
-      if (!dmAuthorized) {
-        if (dmPolicy === "pairing") {
-          const senderId = normalizeIMessageHandle(sender);
-          const { code, created } = await upsertChannelPairingRequest({
-            channel: "imessage",
-            id: senderId,
-            meta: {
-              sender: senderId,
-              chatId: chatId ? String(chatId) : undefined,
-            },
-          });
-          if (created) {
-            logVerbose(`imessage pairing request sender=${senderId}`);
-            try {
-              await sendMessageIMessage(
-                sender,
-                buildPairingReply({
-                  channel: "imessage",
-                  idLine: `Your iMessage sender id: ${senderId}`,
-                  code,
-                }),
-                {
-                  client,
-                  maxBytes: mediaMaxBytes,
-                  accountId: accountInfo.accountId,
-                  ...(chatId ? { chatId } : {}),
-                },
-              );
-            } catch (err) {
-              logVerbose(`imessage pairing reply failed for ${senderId}: ${String(err)}`);
-            }
-          }
-        } else {
-          logVerbose(`Blocked iMessage sender ${sender} (dmPolicy=${dmPolicy})`);
-        }
-        return;
-      }
-    }
-
-    const route = resolveAgentRoute({
-      cfg,
-      channel: "imessage",
-      accountId: accountInfo.accountId,
-      peer: {
-        kind: isGroup ? "group" : "direct",
-        id: isGroup ? String(chatId ?? "unknown") : normalizeIMessageHandle(sender),
-      },
-    });
-    const mentionRegexes = buildMentionRegexes(cfg, route.agentId);
     const messageText = (message.text ?? "").trim();
 
-    // Echo detection: check if the received message matches a recently sent message (within 5 seconds).
-    // Scope by conversation so same text in different chats is not conflated.
-    const echoScope = `${accountInfo.accountId}:${isGroup ? formatIMessageChatTarget(chatId) : `imessage:${sender}`}`;
-    if (messageText && sentMessageCache.has(echoScope, messageText)) {
-      logVerbose(
-        `imessage: skipping echo message (matches recently sent text within 5s): "${truncateUtf16Safe(messageText, 50)}"`,
-      );
-      return;
-    }
-
     const attachments = includeAttachments ? (message.attachments ?? []) : [];
     // Filter to valid attachments with paths
     const validAttachments = attachments.filter((entry) => entry?.original_path && !entry?.missing);
@@ -419,196 +219,103 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     const kind = mediaKindFromMime(mediaType ?? undefined);
     const placeholder = kind ? `<media:${kind}>` : attachments?.length ? "<media:attachment>" : "";
     const bodyText = messageText || placeholder;
-    if (!bodyText) {
-      return;
-    }
-    const replyContext = describeReplyContext(message);
-    const createdAt = message.created_at ? Date.parse(message.created_at) : undefined;
-    const historyKey = isGroup
-      ? String(chatId ?? chatGuid ?? chatIdentifier ?? "unknown")
-      : undefined;
-    const mentioned = isGroup ? matchesMentionPatterns(messageText, mentionRegexes) : true;
-    const requireMention = resolveChannelGroupRequireMention({
+
+    const storeAllowFrom = await readChannelAllowFromStore("imessage").catch(() => []);
+    const decision = resolveIMessageInboundDecision({
       cfg,
-      channel: "imessage",
       accountId: accountInfo.accountId,
-      groupId,
-      requireMentionOverride: opts.requireMention,
-      overrideOrder: "before-config",
+      message,
+      opts,
+      messageText,
+      bodyText,
+      allowFrom,
+      groupAllowFrom,
+      groupPolicy,
+      dmPolicy,
+      storeAllowFrom,
+      historyLimit,
+      groupHistories,
+      echoCache: sentMessageCache,
+      logVerbose,
     });
-    const canDetectMention = mentionRegexes.length > 0;
-    const useAccessGroups = cfg.commands?.useAccessGroups !== false;
-    const ownerAllowedForCommands =
-      effectiveDmAllowFrom.length > 0
-        ? isAllowedIMessageSender({
-            allowFrom: effectiveDmAllowFrom,
-            sender,
-            chatId: chatId ?? undefined,
-            chatGuid,
-            chatIdentifier,
-          })
-        : false;
-    const groupAllowedForCommands =
-      effectiveGroupAllowFrom.length > 0
-        ? isAllowedIMessageSender({
-            allowFrom: effectiveGroupAllowFrom,
-            sender,
-            chatId: chatId ?? undefined,
-            chatGuid,
-            chatIdentifier,
-          })
-        : false;
-    const hasControlCommandInMessage = hasControlCommand(messageText, cfg);
-    const commandGate = resolveControlCommandGate({
-      useAccessGroups,
-      authorizers: [
-        { configured: effectiveDmAllowFrom.length > 0, allowed: ownerAllowedForCommands },
-        { configured: effectiveGroupAllowFrom.length > 0, allowed: groupAllowedForCommands },
-      ],
-      allowTextCommands: true,
-      hasControlCommand: hasControlCommandInMessage,
-    });
-    const commandAuthorized = isGroup ? commandGate.commandAuthorized : dmAuthorized;
-    if (isGroup && commandGate.shouldBlock) {
-      logInboundDrop({
-        log: logVerbose,
-        channel: "imessage",
-        reason: "control command (unauthorized)",
-        target: sender,
-      });
-      return;
-    }
-    const shouldBypassMention =
-      isGroup && requireMention && !mentioned && commandAuthorized && hasControlCommandInMessage;
-    const effectiveWasMentioned = mentioned || shouldBypassMention;
-    if (isGroup && requireMention && canDetectMention && !mentioned && !shouldBypassMention) {
-      logVerbose(`imessage: skipping group message (no mention)`);
-      recordPendingHistoryEntryIfEnabled({
-        historyMap: groupHistories,
-        historyKey: historyKey ?? "",
-        limit: historyLimit,
-        entry: historyKey
-          ? {
-              sender: senderNormalized,
-              body: bodyText,
-              timestamp: createdAt,
-              messageId: message.id ? String(message.id) : undefined,
-            }
-          : null,
-      });
+
+    if (decision.kind === "drop") {
+      return;
+    }
+
+    const chatId = message.chat_id ?? undefined;
+    if (decision.kind === "pairing") {
+      const sender = (message.sender ?? "").trim();
+      if (!sender) {
+        return;
+      }
+      const { code, created } = await upsertChannelPairingRequest({
+        channel: "imessage",
+        id: decision.senderId,
+        meta: {
+          sender: decision.senderId,
+          chatId: chatId ? String(chatId) : undefined,
+        },
+      });
+      if (created) {
+        logVerbose(`imessage pairing request sender=${decision.senderId}`);
+        try {
+          await sendMessageIMessage(
+            sender,
+            buildPairingReply({
+              channel: "imessage",
+              idLine: `Your iMessage sender id: ${decision.senderId}`,
+              code,
+            }),
+            {
+              client,
+              maxBytes: mediaMaxBytes,
+              accountId: accountInfo.accountId,
+              ...(chatId ? { chatId } : {}),
+            },
+          );
+        } catch (err) {
+          logVerbose(`imessage pairing reply failed for ${decision.senderId}: ${String(err)}`);
+        }
+      }
       return;
     }
 
-    const chatTarget = formatIMessageChatTarget(chatId);
-    const fromLabel = formatInboundFromLabel({
-      isGroup,
-      groupLabel: message.chat_name ?? undefined,
-      groupId: chatId !== undefined ? String(chatId) : "unknown",
-      groupFallback: "Group",
-      directLabel: senderNormalized,
-      directId: sender,
-    });
     const storePath = resolveStorePath(cfg.session?.store, {
-      agentId: route.agentId,
+      agentId: decision.route.agentId,
     });
-    const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
     const previousTimestamp = readSessionUpdatedAt({
       storePath,
-      sessionKey: route.sessionKey,
+      sessionKey: decision.route.sessionKey,
     });
-    const replySuffix = replyContext
-      ? `\n\n[Replying to ${replyContext.sender ?? "unknown sender"}${
-          replyContext.id ? ` id:${replyContext.id}` : ""
-        }]\n${replyContext.body}\n[/Replying]`
-      : "";
-    const body = formatInboundEnvelope({
-      channel: "iMessage",
-      from: fromLabel,
-      timestamp: createdAt,
-      body: `${bodyText}${replySuffix}`,
-      chatType: isGroup ? "group" : "direct",
-      sender: { name: senderNormalized, id: sender },
+    const { ctxPayload, chatTarget } = buildIMessageInboundContext({
+      cfg,
+      decision,
+      message,
       previousTimestamp,
-      envelope: envelopeOptions,
-    });
-    let combinedBody = body;
-    if (isGroup && historyKey) {
-      combinedBody = buildPendingHistoryContextFromMap({
-        historyMap: groupHistories,
-        historyKey,
-        limit: historyLimit,
-        currentMessage: combinedBody,
-        formatEntry: (entry) =>
-          formatInboundEnvelope({
-            channel: "iMessage",
-            from: fromLabel,
-            timestamp: entry.timestamp,
-            body: `${entry.body}${entry.messageId ? ` [id:${entry.messageId}]` : ""}`,
-            chatType: "group",
-            senderLabel: entry.sender,
-            envelope: envelopeOptions,
-          }),
-      });
-    }
-
-    const imessageTo = (isGroup ? chatTarget : undefined) || `imessage:${sender}`;
-    const inboundHistory =
-      isGroup && historyKey && historyLimit > 0
-        ? (groupHistories.get(historyKey) ?? []).map((entry) => ({
-            sender: entry.sender,
-            body: entry.body,
-            timestamp: entry.timestamp,
-          }))
-        : undefined;
-    const ctxPayload = finalizeInboundContext({
-      Body: combinedBody,
-      BodyForAgent: bodyText,
-      InboundHistory: inboundHistory,
-      RawBody: bodyText,
-      CommandBody: bodyText,
-      From: isGroup ? `imessage:group:${chatId ?? "unknown"}` : `imessage:${sender}`,
-      To: imessageTo,
-      SessionKey: route.sessionKey,
-      AccountId: route.accountId,
-      ChatType: isGroup ? "group" : "direct",
-      ConversationLabel: fromLabel,
-      GroupSubject: isGroup ? (message.chat_name ?? undefined) : undefined,
-      GroupMembers: isGroup ? (message.participants ?? []).filter(Boolean).join(", ") : undefined,
-      SenderName: senderNormalized,
-      SenderId: sender,
-      Provider: "imessage",
-      Surface: "imessage",
-      MessageSid: message.id ? String(message.id) : undefined,
-      ReplyToId: replyContext?.id,
-      ReplyToBody: replyContext?.body,
-      ReplyToSender: replyContext?.sender,
-      Timestamp: createdAt,
-      MediaPath: mediaPath,
-      MediaType: mediaType,
-      MediaUrl: mediaPath,
-      MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
-      MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
-      MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
-      MediaRemoteHost: remoteHost,
-      WasMentioned: effectiveWasMentioned,
-      CommandAuthorized: commandAuthorized,
-      // Originating channel for reply routing.
-      OriginatingChannel: "imessage" as const,
-      OriginatingTo: imessageTo,
+      remoteHost,
+      historyLimit,
+      groupHistories,
+      media: {
+        path: mediaPath,
+        type: mediaType,
+        paths: mediaPaths,
+        types: mediaTypes,
+      },
     });
 
-    const updateTarget = (isGroup ? chatTarget : undefined) || sender;
+    const updateTarget = chatTarget || decision.sender;
     await recordInboundSession({
       storePath,
-      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      sessionKey: ctxPayload.SessionKey ?? decision.route.sessionKey,
       ctx: ctxPayload,
       updateLastRoute:
-        !isGroup && updateTarget
+        !decision.isGroup && updateTarget
           ? {
-              sessionKey: route.mainSessionKey,
+              sessionKey: decision.route.mainSessionKey,
               channel: "imessage",
               to: updateTarget,
-              accountId: route.accountId,
+              accountId: decision.route.accountId,
             }
           : undefined,
       onRecordError: (err) => {
@@ -617,26 +324,33 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     });
 
     if (shouldLogVerbose()) {
-      const preview = truncateUtf16Safe(body, 200).replace(/\n/g, "\\n");
+      const preview = truncateUtf16Safe(String(ctxPayload.Body ?? ""), 200).replace(/\n/g, "\\n");
       logVerbose(
-        `imessage inbound: chatId=${chatId ?? "unknown"} from=${ctxPayload.From} len=${body.length} preview="${preview}"`,
+        `imessage inbound: chatId=${chatId ?? "unknown"} from=${ctxPayload.From} len=${
+          String(ctxPayload.Body ?? "").length
+        } preview="${preview}"`,
       );
     }
 
     const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
       cfg,
-      agentId: route.agentId,
+      agentId: decision.route.agentId,
       channel: "imessage",
-      accountId: route.accountId,
+      accountId: decision.route.accountId,
     });
 
     const dispatcher = createReplyDispatcher({
       ...prefixOptions,
-      humanDelay: resolveHumanDelayConfig(cfg, route.agentId),
+      humanDelay: resolveHumanDelayConfig(cfg, decision.route.agentId),
       deliver: async (payload) => {
+        const target = ctxPayload.To;
+        if (!target) {
+          runtime.error?.(danger("imessage: missing delivery target"));
+          return;
+        }
         await deliverReplies({
           replies: [payload],
-          target: ctxPayload.To,
+          target,
           client,
           accountId: accountInfo.accountId,
           runtime,
@@ -664,17 +378,21 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     });
 
     if (!queuedFinal) {
-      if (isGroup && historyKey) {
+      if (decision.isGroup && decision.historyKey) {
         clearHistoryEntriesIfEnabled({
           historyMap: groupHistories,
-          historyKey,
+          historyKey: decision.historyKey,
           limit: historyLimit,
         });
       }
       return;
     }
-    if (isGroup && historyKey) {
-      clearHistoryEntriesIfEnabled({ historyMap: groupHistories, historyKey, limit: historyLimit });
+    if (decision.isGroup && decision.historyKey) {
+      clearHistoryEntriesIfEnabled({
+        historyMap: groupHistories,
+        historyKey: decision.historyKey,
+        limit: historyLimit,
+      });
     }
   }
 
@@ -728,21 +446,11 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
 
   let subscriptionId: number | null = null;
   const abort = opts.abortSignal;
-  const onAbort = () => {
-    if (subscriptionId) {
-      void client
-        .request("watch.unsubscribe", {
-          subscription: subscriptionId,
-        })
-        .catch(() => {
-          // Ignore disconnect errors during shutdown.
-        });
-    }
-    void client.stop().catch(() => {
-      // Ignore disconnect errors during shutdown.
-    });
-  };
-  abort?.addEventListener("abort", onAbort, { once: true });
+  const detachAbortHandler = attachIMessageMonitorAbortHandler({
+    abortSignal: abort,
+    client,
+    getSubscriptionId: () => subscriptionId,
+  });
 
   try {
     const result = await client.request<{ subscription?: number }>("watch.subscribe", {
@@ -757,7 +465,7 @@ export async function monitorIMessageProvider(opts: MonitorIMessageOpts = {}): P
     runtime.error?.(danger(`imessage: monitor failed: ${String(err)}`));
     throw err;
   } finally {
-    abort?.removeEventListener("abort", onAbort);
+    detachAbortHandler();
     await client.stop();
   }
 }
diff --git a/src/imessage/probe.ts b/src/imessage/probe.ts
index 9226d48b1e2..27b228e8d58 100644
--- a/src/imessage/probe.ts
+++ b/src/imessage/probe.ts
@@ -1,3 +1,4 @@
+import type { BaseProbeResult } from "../channels/plugins/types.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { detectBinary } from "../commands/onboard-helpers.js";
 import { loadConfig } from "../config/config.js";
@@ -8,9 +9,7 @@ import { DEFAULT_IMESSAGE_PROBE_TIMEOUT_MS } from "./constants.js";
 // Re-export for backwards compatibility
 export { DEFAULT_IMESSAGE_PROBE_TIMEOUT_MS } from "./constants.js";
 
-export type IMessageProbe = {
-  ok: boolean;
-  error?: string | null;
+export type IMessageProbe = BaseProbeResult & {
   fatal?: boolean;
 };
 
diff --git a/src/imessage/targets.test.ts b/src/imessage/targets.test.ts
index 3a011821526..217b0ea6732 100644
--- a/src/imessage/targets.test.ts
+++ b/src/imessage/targets.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   formatIMessageChatTarget,
   isAllowedIMessageSender,
@@ -6,6 +6,12 @@ import {
   parseIMessageTarget,
 } from "./targets.js";
 
+const spawnMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:child_process", () => ({
+  spawn: (...args: unknown[]) => spawnMock(...args),
+}));
+
 describe("imessage targets", () => {
   it("parses chat_id targets", () => {
     const target = parseIMessageTarget("chat_id:123");
@@ -70,3 +76,18 @@ describe("imessage targets", () => {
     expect(formatIMessageChatTarget(undefined)).toBe("");
   });
 });
+
+describe("createIMessageRpcClient", () => {
+  beforeEach(() => {
+    spawnMock.mockReset();
+    vi.stubEnv("VITEST", "true");
+  });
+
+  it("refuses to spawn imsg rpc in test environments", async () => {
+    const { createIMessageRpcClient } = await import("./client.js");
+    await expect(createIMessageRpcClient()).rejects.toThrow(
+      /Refusing to start imsg rpc in test environment/i,
+    );
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/index.test.ts b/src/index.test.ts
deleted file mode 100644
index efaf3f00231..00000000000
--- a/src/index.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { assertWebChannel, normalizeE164, toWhatsappJid } from "./index.js";
-
-describe("normalizeE164", () => {
-  it("strips whatsapp prefix and whitespace", () => {
-    expect(normalizeE164("whatsapp:+1 555 555 0123")).toBe("+15555550123");
-  });
-
-  it("adds plus when missing", () => {
-    expect(normalizeE164("1555123")).toBe("+1555123");
-  });
-});
-
-describe("toWhatsappJid", () => {
-  it("converts E164 to jid", () => {
-    expect(toWhatsappJid("+1 555 555 0123")).toBe("15555550123@s.whatsapp.net");
-  });
-
-  it("keeps group JIDs intact", () => {
-    expect(toWhatsappJid("123456789-987654321@g.us")).toBe("123456789-987654321@g.us");
-  });
-});
-
-describe("assertWebChannel", () => {
-  it("accepts valid channels", () => {
-    expect(() => assertWebChannel("web")).not.toThrow();
-  });
-
-  it("throws on invalid channel", () => {
-    expect(() => assertWebChannel("invalid" as string)).toThrow();
-  });
-});
diff --git a/src/infra/archive.ts b/src/infra/archive.ts
index 1dc8953fda6..260c202e571 100644
--- a/src/infra/archive.ts
+++ b/src/infra/archive.ts
@@ -5,6 +5,7 @@ import path from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import * as tar from "tar";
+import { resolveSafeBaseDir } from "./path-safety.js";
 
 export type ArchiveKind = "tar" | "zip";
 
@@ -101,11 +102,6 @@ export async function withTimeout<T>(
   }
 }
 
-function resolveSafeBaseDir(destDir: string): string {
-  const resolved = path.resolve(destDir);
-  return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
-}
-
 // Path hygiene.
 function normalizeArchivePath(raw: string): string {
   // Archives may contain Windows separators; treat them as separators.
diff --git a/src/infra/bonjour-discovery.ts b/src/infra/bonjour-discovery.ts
index f0ee296156b..426d4eb5141 100644
--- a/src/infra/bonjour-discovery.ts
+++ b/src/infra/bonjour-discovery.ts
@@ -1,4 +1,5 @@
 import { runCommandWithTimeout } from "../process/exec.js";
+import { isTailnetIPv4 } from "./tailnet.js";
 import { resolveWideAreaDiscoveryDomain } from "./widearea-dns.js";
 
 export type GatewayBonjourBeacon = {
@@ -70,20 +71,6 @@ function decodeDnsSdEscapes(value: string): string {
   return Buffer.from(bytes).toString("utf8");
 }
 
-function isTailnetIPv4(address: string): boolean {
-  const parts = address.split(".");
-  if (parts.length !== 4) {
-    return false;
-  }
-  const octets = parts.map((p) => Number.parseInt(p, 10));
-  if (octets.some((n) => !Number.isFinite(n) || n < 0 || n > 255)) {
-    return false;
-  }
-  // Tailscale IPv4 range: 100.64.0.0/10
-  const [a, b] = octets;
-  return a === 100 && b >= 64 && b <= 127;
-}
-
 function parseDigShortLines(stdout: string): string[] {
   return stdout
     .split("\n")
diff --git a/src/infra/control-ui-assets.test.ts b/src/infra/control-ui-assets.test.ts
index 5673cb2e027..9421cdfb0b7 100644
--- a/src/infra/control-ui-assets.test.ts
+++ b/src/infra/control-ui-assets.test.ts
@@ -1,299 +1,203 @@
-import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  resolveControlUiDistIndexHealth,
-  resolveControlUiDistIndexPath,
-  resolveControlUiDistIndexPathForRoot,
-  resolveControlUiRepoRoot,
-  resolveControlUiRootOverrideSync,
-  resolveControlUiRootSync,
-} from "./control-ui-assets.js";
-import { resolveOpenClawPackageRoot } from "./openclaw-root.js";
+import { pathToFileURL } from "node:url";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
-/** Try to create a symlink; returns false if the OS denies it (Windows CI without Developer Mode). */
-async function trySymlink(target: string, linkPath: string): Promise<boolean> {
-  try {
-    await fs.symlink(target, linkPath);
-    return true;
-  } catch {
-    return false;
-  }
+type FakeFsEntry = { kind: "file"; content: string } | { kind: "dir" };
+
+const state = vi.hoisted(() => ({
+  entries: new Map<string, FakeFsEntry>(),
+  realpaths: new Map<string, string>(),
+}));
+
+const abs = (p: string) => path.resolve(p);
+
+function setFile(p: string, content = "") {
+  state.entries.set(abs(p), { kind: "file", content });
 }
 
-async function canonicalPath(p: string): Promise<string> {
-  try {
-    return await fs.realpath(p);
-  } catch {
-    return path.resolve(p);
-  }
+function setDir(p: string) {
+  state.entries.set(abs(p), { kind: "dir" });
 }
 
-describe("control UI assets helpers", () => {
-  let fixtureRoot = "";
-  let caseId = 0;
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+  const fixturesRoot = `${absInMock("fixtures")}${pathMod.sep}`;
+  const isFixturePath = (p: string) => {
+    const resolved = absInMock(p);
+    return resolved === fixturesRoot.slice(0, -1) || resolved.startsWith(fixturesRoot);
+  };
 
-  async function withTempDir<T>(fn: (tmp: string) => Promise<T>): Promise<T> {
-    const tmp = path.join(fixtureRoot, `case-${caseId++}`);
-    await fs.mkdir(tmp, { recursive: true });
-    return await fn(tmp);
-  }
+  const wrapped = {
+    ...actual,
+    existsSync: (p: string) =>
+      isFixturePath(p) ? state.entries.has(absInMock(p)) : actual.existsSync(p),
+    readFileSync: (p: string, encoding?: unknown) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return actual.readFileSync(p as any, encoding as any) as unknown;
+      }
+      const entry = state.entries.get(absInMock(p));
+      if (!entry || entry.kind !== "file") {
+        throw new Error(`ENOENT: no such file, open '${p}'`);
+      }
+      return entry.content;
+    },
+    statSync: (p: string) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return actual.statSync(p as any) as unknown;
+      }
+      const entry = state.entries.get(absInMock(p));
+      if (!entry) {
+        throw new Error(`ENOENT: no such file or directory, stat '${p}'`);
+      }
+      return {
+        isFile: () => entry.kind === "file",
+        isDirectory: () => entry.kind === "dir",
+      };
+    },
+    realpathSync: (p: string) =>
+      isFixturePath(p)
+        ? (state.realpaths.get(absInMock(p)) ?? absInMock(p))
+        : actual.realpathSync(p),
+  };
 
-  beforeAll(async () => {
-    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-ui-"));
-  });
+  return { ...wrapped, default: wrapped };
+});
 
-  afterAll(async () => {
-    if (fixtureRoot) {
-      await fs.rm(fixtureRoot, { recursive: true, force: true });
-    }
+vi.mock("./openclaw-root.js", () => ({
+  resolveOpenClawPackageRoot: vi.fn(async () => null),
+  resolveOpenClawPackageRootSync: vi.fn(() => null),
+}));
+
+describe("control UI assets helpers (fs-mocked)", () => {
+  beforeEach(() => {
+    state.entries.clear();
+    state.realpaths.clear();
+    vi.clearAllMocks();
   });
 
   it("resolves repo root from src argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.mkdir(path.join(tmp, "ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "ui", "vite.config.ts"), "export {};\n");
-      await fs.writeFile(path.join(tmp, "package.json"), "{}\n");
-      await fs.mkdir(path.join(tmp, "src"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "src", "index.ts"), "export {};\n");
+    const { resolveControlUiRepoRoot } = await import("./control-ui-assets.js");
 
-      expect(resolveControlUiRepoRoot(path.join(tmp, "src", "index.ts"))).toBe(tmp);
-    });
+    const root = abs("fixtures/ui-src");
+    setFile(path.join(root, "ui", "vite.config.ts"), "export {};\n");
+
+    const argv1 = path.join(root, "src", "index.ts");
+    expect(resolveControlUiRepoRoot(argv1)).toBe(root);
   });
 
-  it("resolves repo root from dist argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.mkdir(path.join(tmp, "ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "ui", "vite.config.ts"), "export {};\n");
-      await fs.writeFile(path.join(tmp, "package.json"), "{}\n");
-      await fs.mkdir(path.join(tmp, "dist"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "index.js"), "export {};\n");
+  it("resolves repo root by traversing up (dist argv1)", async () => {
+    const { resolveControlUiRepoRoot } = await import("./control-ui-assets.js");
 
-      expect(resolveControlUiRepoRoot(path.join(tmp, "dist", "index.js"))).toBe(tmp);
-    });
+    const root = abs("fixtures/ui-dist");
+    setFile(path.join(root, "package.json"), "{}\n");
+    setFile(path.join(root, "ui", "vite.config.ts"), "export {};\n");
+
+    const argv1 = path.join(root, "dist", "index.js");
+    expect(resolveControlUiRepoRoot(argv1)).toBe(root);
   });
 
   it("resolves dist control-ui index path for dist argv1", async () => {
-    const argv1 = path.resolve("/tmp", "pkg", "dist", "index.js");
+    const { resolveControlUiDistIndexPath } = await import("./control-ui-assets.js");
+
+    const argv1 = abs(path.join("fixtures", "pkg", "dist", "index.js"));
     const distDir = path.dirname(argv1);
-    expect(await resolveControlUiDistIndexPath(argv1)).toBe(
+    await expect(resolveControlUiDistIndexPath(argv1)).resolves.toBe(
       path.join(distDir, "control-ui", "index.html"),
     );
   });
 
-  it("resolves control-ui root for dist bundle argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "bundle.js"), "export {};\n");
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
+  it("uses resolveOpenClawPackageRoot when available", async () => {
+    const openclawRoot = await import("./openclaw-root.js");
+    const { resolveControlUiDistIndexPath } = await import("./control-ui-assets.js");
 
-      expect(resolveControlUiRootSync({ argv1: path.join(tmp, "dist", "bundle.js") })).toBe(
-        path.join(tmp, "dist", "control-ui"),
-      );
+    const pkgRoot = abs("fixtures/openclaw");
+    (
+      openclawRoot.resolveOpenClawPackageRoot as unknown as ReturnType<typeof vi.fn>
+    ).mockResolvedValueOnce(pkgRoot);
+
+    await expect(resolveControlUiDistIndexPath(abs("fixtures/bin/openclaw"))).resolves.toBe(
+      path.join(pkgRoot, "dist", "control-ui", "index.html"),
+    );
+  });
+
+  it("falls back to package.json name matching when root resolution fails", async () => {
+    const { resolveControlUiDistIndexPath } = await import("./control-ui-assets.js");
+
+    const root = abs("fixtures/fallback");
+    setFile(path.join(root, "package.json"), JSON.stringify({ name: "openclaw" }));
+    setFile(path.join(root, "dist", "control-ui", "index.html"), "<html></html>\n");
+
+    await expect(resolveControlUiDistIndexPath(path.join(root, "openclaw.mjs"))).resolves.toBe(
+      path.join(root, "dist", "control-ui", "index.html"),
+    );
+  });
+
+  it("returns null when fallback package name does not match", async () => {
+    const { resolveControlUiDistIndexPath } = await import("./control-ui-assets.js");
+
+    const root = abs("fixtures/not-openclaw");
+    setFile(path.join(root, "package.json"), JSON.stringify({ name: "malicious-pkg" }));
+    setFile(path.join(root, "dist", "control-ui", "index.html"), "<html></html>\n");
+
+    await expect(resolveControlUiDistIndexPath(path.join(root, "index.mjs"))).resolves.toBeNull();
+  });
+
+  it("reports health for missing + existing dist assets", async () => {
+    const { resolveControlUiDistIndexHealth } = await import("./control-ui-assets.js");
+
+    const root = abs("fixtures/health");
+    const indexPath = path.join(root, "dist", "control-ui", "index.html");
+
+    await expect(resolveControlUiDistIndexHealth({ root })).resolves.toEqual({
+      indexPath,
+      exists: false,
+    });
+
+    setFile(indexPath, "<html></html>\n");
+    await expect(resolveControlUiDistIndexHealth({ root })).resolves.toEqual({
+      indexPath,
+      exists: true,
     });
   });
 
-  it("resolves control-ui root for dist/gateway bundle argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.mkdir(path.join(tmp, "dist", "gateway"), { recursive: true });
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "gateway", "control-ui.js"), "export {};\n");
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
+  it("resolves control-ui root from override file or directory", async () => {
+    const { resolveControlUiRootOverrideSync } = await import("./control-ui-assets.js");
 
-      expect(
-        resolveControlUiRootSync({ argv1: path.join(tmp, "dist", "gateway", "control-ui.js") }),
-      ).toBe(path.join(tmp, "dist", "control-ui"));
-    });
+    const root = abs("fixtures/override");
+    const uiDir = path.join(root, "dist", "control-ui");
+    const indexPath = path.join(uiDir, "index.html");
+
+    setDir(uiDir);
+    setFile(indexPath, "<html></html>\n");
+
+    expect(resolveControlUiRootOverrideSync(uiDir)).toBe(uiDir);
+    expect(resolveControlUiRootOverrideSync(indexPath)).toBe(uiDir);
+    expect(resolveControlUiRootOverrideSync(path.join(uiDir, "missing.html"))).toBeNull();
   });
 
-  it("resolves control-ui root from override directory or index.html", async () => {
-    await withTempDir(async (tmp) => {
-      const uiDir = path.join(tmp, "dist", "control-ui");
-      await fs.mkdir(uiDir, { recursive: true });
-      await fs.writeFile(path.join(uiDir, "index.html"), "<html></html>\n");
+  it("resolves control-ui root for dist bundle argv1 and moduleUrl candidates", async () => {
+    const openclawRoot = await import("./openclaw-root.js");
+    const { resolveControlUiRootSync } = await import("./control-ui-assets.js");
 
-      expect(resolveControlUiRootOverrideSync(uiDir)).toBe(uiDir);
-      expect(resolveControlUiRootOverrideSync(path.join(uiDir, "index.html"))).toBe(uiDir);
-      expect(resolveControlUiRootOverrideSync(path.join(uiDir, "missing.html"))).toBeNull();
-    });
-  });
+    const pkgRoot = abs("fixtures/openclaw-bundle");
+    (
+      openclawRoot.resolveOpenClawPackageRootSync as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValueOnce(pkgRoot);
 
-  it("resolves dist control-ui index path from package root argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(tmp, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
+    const uiDir = path.join(pkgRoot, "dist", "control-ui");
+    setFile(path.join(uiDir, "index.html"), "<html></html>\n");
 
-      expect(await resolveControlUiDistIndexPath(path.join(tmp, "openclaw.mjs"))).toBe(
-        path.join(tmp, "dist", "control-ui", "index.html"),
-      );
-    });
-  });
+    // argv1Dir candidate: <argv1Dir>/control-ui
+    expect(resolveControlUiRootSync({ argv1: path.join(pkgRoot, "dist", "bundle.js") })).toBe(
+      uiDir,
+    );
 
-  it("resolves control-ui root for package entrypoint argv1", async () => {
-    await withTempDir(async (tmp) => {
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(tmp, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
-
-      expect(resolveControlUiRootSync({ argv1: path.join(tmp, "openclaw.mjs") })).toBe(
-        path.join(tmp, "dist", "control-ui"),
-      );
-    });
-  });
-
-  it("resolves dist control-ui index path from .bin argv1", async () => {
-    await withTempDir(async (tmp) => {
-      const binDir = path.join(tmp, "node_modules", ".bin");
-      const pkgRoot = path.join(tmp, "node_modules", "openclaw");
-      await fs.mkdir(binDir, { recursive: true });
-      await fs.mkdir(path.join(pkgRoot, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(binDir, "openclaw"), "#!/usr/bin/env node\n");
-      await fs.writeFile(path.join(pkgRoot, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(pkgRoot, "dist", "control-ui", "index.html"), "<html></html>\n");
-
-      expect(await resolveControlUiDistIndexPath(path.join(binDir, "openclaw"))).toBe(
-        path.join(pkgRoot, "dist", "control-ui", "index.html"),
-      );
-    });
-  });
-
-  it("resolves via fallback when package root resolution fails but package name matches", async () => {
-    await withTempDir(async (tmp) => {
-      // Package named "openclaw" but resolveOpenClawPackageRoot failed for other reasons
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(tmp, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
-
-      expect(await resolveControlUiDistIndexPath(path.join(tmp, "openclaw.mjs"))).toBe(
-        path.join(tmp, "dist", "control-ui", "index.html"),
-      );
-    });
-  });
-
-  it("returns null when package name does not match openclaw", async () => {
-    await withTempDir(async (tmp) => {
-      // Package with different name should not be resolved
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "malicious-pkg" }));
-      await fs.writeFile(path.join(tmp, "index.mjs"), "export {};\n");
-      await fs.mkdir(path.join(tmp, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(tmp, "dist", "control-ui", "index.html"), "<html></html>\n");
-
-      expect(await resolveControlUiDistIndexPath(path.join(tmp, "index.mjs"))).toBeNull();
-    });
-  });
-
-  it("returns null when no control-ui assets exist", async () => {
-    await withTempDir(async (tmp) => {
-      // Just a package.json, no dist/control-ui
-      await fs.writeFile(path.join(tmp, "package.json"), JSON.stringify({ name: "some-pkg" }));
-      await fs.writeFile(path.join(tmp, "index.mjs"), "export {};\n");
-
-      expect(await resolveControlUiDistIndexPath(path.join(tmp, "index.mjs"))).toBeNull();
-    });
-  });
-
-  it("reports health for existing control-ui assets at a known root", async () => {
-    await withTempDir(async (tmp) => {
-      const indexPath = resolveControlUiDistIndexPathForRoot(tmp);
-      await fs.mkdir(path.dirname(indexPath), { recursive: true });
-      await fs.writeFile(indexPath, "<html></html>\n");
-
-      await expect(resolveControlUiDistIndexHealth({ root: tmp })).resolves.toEqual({
-        indexPath,
-        exists: true,
-      });
-    });
-  });
-
-  it("reports health for missing control-ui assets at a known root", async () => {
-    await withTempDir(async (tmp) => {
-      const indexPath = resolveControlUiDistIndexPathForRoot(tmp);
-      await expect(resolveControlUiDistIndexHealth({ root: tmp })).resolves.toEqual({
-        indexPath,
-        exists: false,
-      });
-    });
-  });
-
-  it("resolves control-ui root when argv1 is a symlink (nvm scenario)", async () => {
-    await withTempDir(async (tmp) => {
-      const realPkg = path.join(tmp, "real-pkg");
-      const bin = path.join(tmp, "bin");
-      await fs.mkdir(realPkg, { recursive: true });
-      await fs.mkdir(bin, { recursive: true });
-      await fs.writeFile(path.join(realPkg, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(realPkg, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(realPkg, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(realPkg, "dist", "control-ui", "index.html"), "<html></html>\n");
-      const ok = await trySymlink(
-        path.join("..", "real-pkg", "openclaw.mjs"),
-        path.join(bin, "openclaw"),
-      );
-      if (!ok) {
-        return; // symlinks not supported (Windows CI)
-      }
-
-      const resolvedRoot = resolveControlUiRootSync({ argv1: path.join(bin, "openclaw") });
-      expect(resolvedRoot).not.toBeNull();
-      expect(await canonicalPath(resolvedRoot ?? "")).toBe(
-        await canonicalPath(path.join(realPkg, "dist", "control-ui")),
-      );
-    });
-  });
-
-  it("resolves package root via symlinked argv1", async () => {
-    await withTempDir(async (tmp) => {
-      const realPkg = path.join(tmp, "real-pkg");
-      const bin = path.join(tmp, "bin");
-      await fs.mkdir(realPkg, { recursive: true });
-      await fs.mkdir(bin, { recursive: true });
-      await fs.writeFile(path.join(realPkg, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(realPkg, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(realPkg, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(realPkg, "dist", "control-ui", "index.html"), "<html></html>\n");
-      const ok = await trySymlink(
-        path.join("..", "real-pkg", "openclaw.mjs"),
-        path.join(bin, "openclaw"),
-      );
-      if (!ok) {
-        return; // symlinks not supported (Windows CI)
-      }
-
-      const packageRoot = await resolveOpenClawPackageRoot({ argv1: path.join(bin, "openclaw") });
-      expect(packageRoot).not.toBeNull();
-      expect(await canonicalPath(packageRoot ?? "")).toBe(await canonicalPath(realPkg));
-    });
-  });
-
-  it("resolves dist index path via symlinked argv1 (async)", async () => {
-    await withTempDir(async (tmp) => {
-      const realPkg = path.join(tmp, "real-pkg");
-      const bin = path.join(tmp, "bin");
-      await fs.mkdir(realPkg, { recursive: true });
-      await fs.mkdir(bin, { recursive: true });
-      await fs.writeFile(path.join(realPkg, "package.json"), JSON.stringify({ name: "openclaw" }));
-      await fs.writeFile(path.join(realPkg, "openclaw.mjs"), "export {};\n");
-      await fs.mkdir(path.join(realPkg, "dist", "control-ui"), { recursive: true });
-      await fs.writeFile(path.join(realPkg, "dist", "control-ui", "index.html"), "<html></html>\n");
-      const ok = await trySymlink(
-        path.join("..", "real-pkg", "openclaw.mjs"),
-        path.join(bin, "openclaw"),
-      );
-      if (!ok) {
-        return; // symlinks not supported (Windows CI)
-      }
-
-      const indexPath = await resolveControlUiDistIndexPath(path.join(bin, "openclaw"));
-      expect(indexPath).not.toBeNull();
-      expect(await canonicalPath(indexPath ?? "")).toBe(
-        await canonicalPath(path.join(realPkg, "dist", "control-ui", "index.html")),
-      );
-    });
+    // moduleUrl candidate: <moduleDir>/control-ui
+    const moduleUrl = pathToFileURL(path.join(pkgRoot, "dist", "bundle.js")).toString();
+    expect(resolveControlUiRootSync({ moduleUrl })).toBe(uiDir);
   });
 });
diff --git a/src/infra/control-ui-assets.ts b/src/infra/control-ui-assets.ts
index 953fb30941b..4091f8b7afb 100644
--- a/src/infra/control-ui-assets.ts
+++ b/src/infra/control-ui-assets.ts
@@ -97,15 +97,18 @@ export async function resolveControlUiDistIndexPath(
   for (let i = 0; i < 8; i++) {
     const pkgJsonPath = path.join(dir, "package.json");
     const indexPath = path.join(dir, "dist", "control-ui", "index.html");
-    if (fs.existsSync(pkgJsonPath) && fs.existsSync(indexPath)) {
+    if (fs.existsSync(pkgJsonPath)) {
       try {
         const raw = fs.readFileSync(pkgJsonPath, "utf-8");
         const parsed = JSON.parse(raw) as { name?: unknown };
         if (parsed.name === "openclaw") {
-          return indexPath;
+          return fs.existsSync(indexPath) ? indexPath : null;
         }
+        // Stop at the first package boundary to avoid resolving through unrelated ancestors.
+        return null;
       } catch {
-        // Invalid package.json, continue searching
+        // Invalid package.json at package boundary; abort fallback resolution.
+        return null;
       }
     }
     const parent = path.dirname(dir);
diff --git a/src/infra/device-pairing.ts b/src/infra/device-pairing.ts
index 41d786238db..a6a9c7fcdfb 100644
--- a/src/infra/device-pairing.ts
+++ b/src/infra/device-pairing.ts
@@ -179,6 +179,35 @@ function newToken() {
   return generatePairingToken();
 }
 
+function getPairedDeviceFromState(
+  state: DevicePairingStateFile,
+  deviceId: string,
+): PairedDevice | null {
+  return state.pairedByDeviceId[normalizeDeviceId(deviceId)] ?? null;
+}
+
+function cloneDeviceTokens(device: PairedDevice): Record<string, DeviceAuthToken> {
+  return device.tokens ? { ...device.tokens } : {};
+}
+
+function buildDeviceAuthToken(params: {
+  role: string;
+  scopes: string[];
+  existing?: DeviceAuthToken;
+  now: number;
+  rotatedAtMs?: number;
+}): DeviceAuthToken {
+  return {
+    token: newToken(),
+    role: params.role,
+    scopes: params.scopes,
+    createdAtMs: params.existing?.createdAtMs ?? params.now,
+    rotatedAtMs: params.rotatedAtMs,
+    revokedAtMs: undefined,
+    lastUsedAtMs: params.existing?.lastUsedAtMs,
+  };
+}
+
 export async function listDevicePairing(baseDir?: string): Promise<DevicePairingList> {
   const state = await loadState(baseDir);
   const pending = Object.values(state.pendingById).toSorted((a, b) => b.ts - a.ts);
@@ -360,7 +389,7 @@ export async function verifyDeviceToken(params: {
 }): Promise<{ ok: boolean; reason?: string }> {
   return await withLock(async () => {
     const state = await loadState(params.baseDir);
-    const device = state.pairedByDeviceId[normalizeDeviceId(params.deviceId)];
+    const device = getPairedDeviceFromState(state, params.deviceId);
     if (!device) {
       return { ok: false, reason: "device-not-paired" };
     }
@@ -399,32 +428,29 @@ export async function ensureDeviceToken(params: {
 }): Promise<DeviceAuthToken | null> {
   return await withLock(async () => {
     const state = await loadState(params.baseDir);
-    const device = state.pairedByDeviceId[normalizeDeviceId(params.deviceId)];
-    if (!device) {
-      return null;
-    }
-    const role = normalizeRole(params.role);
-    if (!role) {
-      return null;
-    }
     const requestedScopes = normalizeScopes(params.scopes);
-    const tokens = device.tokens ? { ...device.tokens } : {};
-    const existing = tokens[role];
+    const context = resolveDeviceTokenUpdateContext({
+      state,
+      deviceId: params.deviceId,
+      role: params.role,
+    });
+    if (!context) {
+      return null;
+    }
+    const { device, role, tokens, existing } = context;
     if (existing && !existing.revokedAtMs) {
       if (scopesAllow(requestedScopes, existing.scopes)) {
         return existing;
       }
     }
     const now = Date.now();
-    const next: DeviceAuthToken = {
-      token: newToken(),
+    const next = buildDeviceAuthToken({
       role,
       scopes: requestedScopes,
-      createdAtMs: existing?.createdAtMs ?? now,
+      existing,
+      now,
       rotatedAtMs: existing ? now : undefined,
-      revokedAtMs: undefined,
-      lastUsedAtMs: existing?.lastUsedAtMs,
-    };
+    });
     tokens[role] = next;
     device.tokens = tokens;
     state.pairedByDeviceId[device.deviceId] = device;
@@ -433,6 +459,29 @@ export async function ensureDeviceToken(params: {
   });
 }
 
+function resolveDeviceTokenUpdateContext(params: {
+  state: DevicePairingStateFile;
+  deviceId: string;
+  role: string;
+}): {
+  device: PairedDevice;
+  role: string;
+  tokens: Record<string, DeviceAuthToken>;
+  existing: DeviceAuthToken | undefined;
+} | null {
+  const device = getPairedDeviceFromState(params.state, params.deviceId);
+  if (!device) {
+    return null;
+  }
+  const role = normalizeRole(params.role);
+  if (!role) {
+    return null;
+  }
+  const tokens = cloneDeviceTokens(device);
+  const existing = tokens[role];
+  return { device, role, tokens, existing };
+}
+
 export async function rotateDeviceToken(params: {
   deviceId: string;
   role: string;
@@ -441,27 +490,24 @@ export async function rotateDeviceToken(params: {
 }): Promise<DeviceAuthToken | null> {
   return await withLock(async () => {
     const state = await loadState(params.baseDir);
-    const device = state.pairedByDeviceId[normalizeDeviceId(params.deviceId)];
-    if (!device) {
+    const context = resolveDeviceTokenUpdateContext({
+      state,
+      deviceId: params.deviceId,
+      role: params.role,
+    });
+    if (!context) {
       return null;
     }
-    const role = normalizeRole(params.role);
-    if (!role) {
-      return null;
-    }
-    const tokens = device.tokens ? { ...device.tokens } : {};
-    const existing = tokens[role];
+    const { device, role, tokens, existing } = context;
     const requestedScopes = normalizeScopes(params.scopes ?? existing?.scopes ?? device.scopes);
     const now = Date.now();
-    const next: DeviceAuthToken = {
-      token: newToken(),
+    const next = buildDeviceAuthToken({
       role,
       scopes: requestedScopes,
-      createdAtMs: existing?.createdAtMs ?? now,
+      existing,
+      now,
       rotatedAtMs: now,
-      revokedAtMs: undefined,
-      lastUsedAtMs: existing?.lastUsedAtMs,
-    };
+    });
     tokens[role] = next;
     device.tokens = tokens;
     if (params.scopes !== undefined) {
diff --git a/src/infra/diagnostic-events.ts b/src/infra/diagnostic-events.ts
index b0de66614d0..6b9f9f2d1bd 100644
--- a/src/infra/diagnostic-events.ts
+++ b/src/infra/diagnostic-events.ts
@@ -22,6 +22,13 @@ export type DiagnosticUsageEvent = DiagnosticBaseEvent & {
     promptTokens?: number;
     total?: number;
   };
+  lastCallUsage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+  };
   context?: {
     limit?: number;
     used?: number;
diff --git a/src/infra/errors.ts b/src/infra/errors.ts
index 1ea7950c2b6..e64881d1d65 100644
--- a/src/infra/errors.ts
+++ b/src/infra/errors.ts
@@ -1,3 +1,5 @@
+import { redactSensitiveText } from "../logging/redact.js";
+
 export function extractErrorCode(err: unknown): string | undefined {
   if (!err || typeof err !== "object") {
     return undefined;
@@ -27,20 +29,22 @@ export function hasErrnoCode(err: unknown, code: string): boolean {
 }
 
 export function formatErrorMessage(err: unknown): string {
+  let formatted: string;
   if (err instanceof Error) {
-    return err.message || err.name || "Error";
-  }
-  if (typeof err === "string") {
-    return err;
-  }
-  if (typeof err === "number" || typeof err === "boolean" || typeof err === "bigint") {
-    return String(err);
-  }
-  try {
-    return JSON.stringify(err);
-  } catch {
-    return Object.prototype.toString.call(err);
+    formatted = err.message || err.name || "Error";
+  } else if (typeof err === "string") {
+    formatted = err;
+  } else if (typeof err === "number" || typeof err === "boolean" || typeof err === "bigint") {
+    formatted = String(err);
+  } else {
+    try {
+      formatted = JSON.stringify(err);
+    } catch {
+      formatted = Object.prototype.toString.call(err);
+    }
   }
+  // Security: best-effort token redaction before returning/logging.
+  return redactSensitiveText(formatted);
 }
 
 export function formatUncaughtError(err: unknown): string {
@@ -48,7 +52,8 @@ export function formatUncaughtError(err: unknown): string {
     return formatErrorMessage(err);
   }
   if (err instanceof Error) {
-    return err.stack ?? err.message ?? err.name;
+    const stack = err.stack ?? err.message ?? err.name;
+    return redactSensitiveText(stack);
   }
   return formatErrorMessage(err);
 }
diff --git a/src/infra/exec-approval-forwarder.test.ts b/src/infra/exec-approval-forwarder.test.ts
index fa0c6c536fa..fc9afb1e537 100644
--- a/src/infra/exec-approval-forwarder.test.ts
+++ b/src/infra/exec-approval-forwarder.test.ts
@@ -137,6 +137,34 @@ describe("exec approval forwarder", () => {
     expect(getFirstDeliveryText(deliver)).toContain("Command:\n```\necho `uname`\necho done\n```");
   });
 
+  it("skips discord forwarding when discord exec approvals target channel", async () => {
+    vi.useFakeTimers();
+    const deliver = vi.fn().mockResolvedValue([]);
+    const cfg = {
+      approvals: { exec: { enabled: true, mode: "session" } },
+      channels: {
+        discord: {
+          execApprovals: {
+            enabled: true,
+            target: "channel",
+            approvers: ["123"],
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const forwarder = createExecApprovalForwarder({
+      getConfig: () => cfg,
+      deliver,
+      nowMs: () => 1000,
+      resolveSessionTarget: () => ({ channel: "discord", to: "channel:123" }),
+    });
+
+    await forwarder.handleRequested(baseRequest);
+
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
   it("uses a longer fence when command already contains triple backticks", async () => {
     vi.useFakeTimers();
     const deliver = vi.fn().mockResolvedValue([]);
diff --git a/src/infra/exec-approval-forwarder.ts b/src/infra/exec-approval-forwarder.ts
index 51e785b60aa..a72938132aa 100644
--- a/src/infra/exec-approval-forwarder.ts
+++ b/src/infra/exec-approval-forwarder.ts
@@ -98,6 +98,15 @@ function buildTargetKey(target: ExecApprovalForwardTarget): string {
   return [channel, target.to, accountId, threadId].join(":");
 }
 
+function shouldSkipDiscordForwarding(cfg: OpenClawConfig): boolean {
+  const discordConfig = cfg.channels?.discord?.execApprovals;
+  if (!discordConfig?.enabled) {
+    return false;
+  }
+  const target = discordConfig.target ?? "dm";
+  return target === "channel" || target === "both";
+}
+
 function formatApprovalCommand(command: string): { inline: boolean; text: string } {
   if (!command.includes("\n") && !command.includes("`")) {
     return { inline: true, text: `\`${command}\`` };
@@ -265,7 +274,11 @@ export function createExecApprovalForwarder(
       }
     }
 
-    if (targets.length === 0) {
+    const filteredTargets = shouldSkipDiscordForwarding(cfg)
+      ? targets.filter((target) => normalizeMessageChannel(target.channel) !== "discord")
+      : targets;
+
+    if (filteredTargets.length === 0) {
       return;
     }
 
@@ -283,7 +296,7 @@ export function createExecApprovalForwarder(
     }, expiresInMs);
     timeoutId.unref?.();
 
-    const pendingEntry: PendingApproval = { request, targets, timeoutId };
+    const pendingEntry: PendingApproval = { request, targets: filteredTargets, timeoutId };
     pending.set(request.id, pendingEntry);
 
     if (pending.get(request.id) !== pendingEntry) {
@@ -293,7 +306,7 @@ export function createExecApprovalForwarder(
     const text = buildRequestMessage(request, nowMs());
     await deliverToTargets({
       cfg,
-      targets,
+      targets: filteredTargets,
       text,
       deliver,
       shouldSend: () => pending.get(request.id) === pendingEntry,
diff --git a/src/infra/exec-approvals.test.ts b/src/infra/exec-approvals.test.ts
index 8251b6ca99f..ee3a4f822f6 100644
--- a/src/infra/exec-approvals.test.ts
+++ b/src/infra/exec-approvals.test.ts
@@ -11,6 +11,7 @@ import {
   isSafeBinUsage,
   matchAllowlist,
   maxAsk,
+  mergeExecApprovalsSocketDefaults,
   minSecurity,
   normalizeExecApprovals,
   normalizeSafeBins,
@@ -79,6 +80,36 @@ describe("exec approvals allowlist matching", () => {
   });
 });
 
+describe("mergeExecApprovalsSocketDefaults", () => {
+  it("prefers normalized socket, then current, then default path", () => {
+    const normalized = normalizeExecApprovals({
+      version: 1,
+      agents: {},
+      socket: { path: "/tmp/a.sock", token: "a" },
+    });
+    const current = normalizeExecApprovals({
+      version: 1,
+      agents: {},
+      socket: { path: "/tmp/b.sock", token: "b" },
+    });
+    const merged = mergeExecApprovalsSocketDefaults({ normalized, current });
+    expect(merged.socket?.path).toBe("/tmp/a.sock");
+    expect(merged.socket?.token).toBe("a");
+  });
+
+  it("falls back to current token when missing in normalized", () => {
+    const normalized = normalizeExecApprovals({ version: 1, agents: {} });
+    const current = normalizeExecApprovals({
+      version: 1,
+      agents: {},
+      socket: { path: "/tmp/b.sock", token: "b" },
+    });
+    const merged = mergeExecApprovalsSocketDefaults({ normalized, current });
+    expect(merged.socket?.path).toBeTruthy();
+    expect(merged.socket?.token).toBe("b");
+  });
+});
+
 describe("exec approvals safe shell command builder", () => {
   it("quotes only safeBins segments (leaves other segments untouched)", () => {
     if (process.platform === "win32") {
diff --git a/src/infra/exec-approvals.ts b/src/infra/exec-approvals.ts
index 6423d935990..56daa99e582 100644
--- a/src/infra/exec-approvals.ts
+++ b/src/infra/exec-approvals.ts
@@ -241,6 +241,24 @@ export function normalizeExecApprovals(file: ExecApprovalsFile): ExecApprovalsFi
   return normalized;
 }
 
+export function mergeExecApprovalsSocketDefaults(params: {
+  normalized: ExecApprovalsFile;
+  current?: ExecApprovalsFile;
+}): ExecApprovalsFile {
+  const currentSocketPath = params.current?.socket?.path?.trim();
+  const currentToken = params.current?.socket?.token?.trim();
+  const socketPath =
+    params.normalized.socket?.path?.trim() ?? currentSocketPath ?? resolveExecApprovalsSocketPath();
+  const token = params.normalized.socket?.token?.trim() ?? currentToken ?? "";
+  return {
+    ...params.normalized,
+    socket: {
+      path: socketPath,
+      token,
+    },
+  };
+}
+
 function generateToken(): string {
   return crypto.randomBytes(24).toString("base64url");
 }
diff --git a/src/infra/gateway-lock.test.ts b/src/infra/gateway-lock.test.ts
index a24e7e35ab8..fd83ef5eab3 100644
--- a/src/infra/gateway-lock.test.ts
+++ b/src/infra/gateway-lock.test.ts
@@ -3,7 +3,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveConfigPath, resolveGatewayLockDir, resolveStateDir } from "../config/paths.js";
 import { acquireGatewayLock, GatewayLockError } from "./gateway-lock.js";
 
@@ -67,6 +67,13 @@ describe("gateway lock", () => {
     fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-gateway-lock-"));
   });
 
+  beforeEach(() => {
+    // Other suites occasionally leave global spies behind (Date.now, setTimeout, etc.).
+    // This test relies on fake timers advancing Date.now and setTimeout deterministically.
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
   afterAll(async () => {
     await fs.rm(fixtureRoot, { recursive: true, force: true });
   });
@@ -76,21 +83,23 @@ describe("gateway lock", () => {
   });
 
   it("blocks concurrent acquisition until release", async () => {
+    // Fake timers can hang on Windows CI when combined with fs open loops.
+    // Keep this test on real timers and use small timeouts.
     vi.useRealTimers();
     const { env, cleanup } = await makeEnv();
     const lock = await acquireGatewayLock({
       env,
       allowInTests: true,
-      timeoutMs: 80,
-      pollIntervalMs: 5,
+      timeoutMs: 50,
+      pollIntervalMs: 2,
     });
     expect(lock).not.toBeNull();
 
     const pending = acquireGatewayLock({
       env,
       allowInTests: true,
-      timeoutMs: 80,
-      pollIntervalMs: 5,
+      timeoutMs: 15,
+      pollIntervalMs: 2,
     });
     await expect(pending).rejects.toBeInstanceOf(GatewayLockError);
 
@@ -98,8 +107,8 @@ describe("gateway lock", () => {
     const lock2 = await acquireGatewayLock({
       env,
       allowInTests: true,
-      timeoutMs: 80,
-      pollIntervalMs: 5,
+      timeoutMs: 30,
+      pollIntervalMs: 2,
     });
     await lock2?.release();
     await cleanup();
@@ -107,6 +116,7 @@ describe("gateway lock", () => {
 
   it("treats recycled linux pid as stale when start time mismatches", async () => {
     vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-02-06T10:05:00.000Z"));
     const { env, cleanup } = await makeEnv();
     const { lockPath, configPath } = resolveLockPath(env);
     const payload = {
@@ -163,8 +173,8 @@ describe("gateway lock", () => {
     const pending = acquireGatewayLock({
       env,
       allowInTests: true,
-      timeoutMs: 50,
-      pollIntervalMs: 5,
+      timeoutMs: 15,
+      pollIntervalMs: 2,
       staleMs: 10_000,
       platform: "linux",
     });
@@ -188,8 +198,8 @@ describe("gateway lock", () => {
     const lock = await acquireGatewayLock({
       env,
       allowInTests: true,
-      timeoutMs: 80,
-      pollIntervalMs: 5,
+      timeoutMs: 30,
+      pollIntervalMs: 2,
       staleMs: 1,
       platform: "linux",
     });
diff --git a/src/infra/gateway-lock.ts b/src/infra/gateway-lock.ts
index ef89f42a101..d6dbf2266a4 100644
--- a/src/infra/gateway-lock.ts
+++ b/src/infra/gateway-lock.ts
@@ -3,6 +3,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveConfigPath, resolveGatewayLockDir, resolveStateDir } from "../config/paths.js";
+import { isPidAlive } from "../shared/pid-alive.js";
 
 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_POLL_INTERVAL_MS = 100;
@@ -42,18 +43,6 @@ export class GatewayLockError extends Error {
 
 type LockOwnerStatus = "alive" | "dead" | "unknown";
 
-function isAlive(pid: number): boolean {
-  if (!Number.isFinite(pid) || pid <= 0) {
-    return false;
-  }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function normalizeProcArg(arg: string): string {
   return arg.replaceAll("\\", "/").toLowerCase();
 }
@@ -116,7 +105,7 @@ function resolveGatewayOwnerStatus(
   payload: LockPayload | null,
   platform: NodeJS.Platform,
 ): LockOwnerStatus {
-  if (!isAlive(pid)) {
+  if (!isPidAlive(pid)) {
     return "dead";
   }
   if (platform !== "linux") {
diff --git a/src/infra/heartbeat-runner.cron-system-event-filter.test.ts b/src/infra/heartbeat-runner.cron-system-event-filter.test.ts
deleted file mode 100644
index dfe4c2c18e8..00000000000
--- a/src/infra/heartbeat-runner.cron-system-event-filter.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isCronSystemEvent } from "./heartbeat-runner.js";
-
-describe("isCronSystemEvent", () => {
-  it("returns false for empty entries", () => {
-    expect(isCronSystemEvent("")).toBe(false);
-    expect(isCronSystemEvent("   ")).toBe(false);
-  });
-
-  it("returns false for heartbeat ack markers", () => {
-    expect(isCronSystemEvent("HEARTBEAT_OK")).toBe(false);
-    expect(isCronSystemEvent("HEARTBEAT_OK 🦞")).toBe(false);
-    expect(isCronSystemEvent("heartbeat_ok")).toBe(false);
-    expect(isCronSystemEvent("HEARTBEAT_OK:")).toBe(false);
-    expect(isCronSystemEvent("HEARTBEAT_OK, continue")).toBe(false);
-  });
-
-  it("returns false for heartbeat poll and wake noise", () => {
-    expect(isCronSystemEvent("heartbeat poll: pending")).toBe(false);
-    expect(isCronSystemEvent("heartbeat wake complete")).toBe(false);
-  });
-
-  it("returns false for exec completion events", () => {
-    expect(isCronSystemEvent("Exec finished (gateway id=abc, code 0)")).toBe(false);
-  });
-
-  it("returns true for real cron reminder content", () => {
-    expect(isCronSystemEvent("Reminder: Check Base Scout results")).toBe(true);
-    expect(isCronSystemEvent("Send weekly status update to the team")).toBe(true);
-  });
-});
diff --git a/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts b/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
index be0e37a4223..83868eec59b 100644
--- a/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
+++ b/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
@@ -190,6 +190,54 @@ describe("resolveHeartbeatIntervalMs", () => {
     });
   });
 
+  it("does not deliver HEARTBEAT_OK to telegram when showOk is false", async () => {
+    await withTempTelegramHeartbeatSandbox(async ({ tmpDir, storePath, replySpy }) => {
+      const cfg: OpenClawConfig = {
+        agents: {
+          defaults: {
+            workspace: tmpDir,
+            heartbeat: {
+              every: "5m",
+              target: "telegram",
+            },
+          },
+        },
+        channels: {
+          telegram: {
+            token: "test-token",
+            allowFrom: ["*"],
+            heartbeat: { showOk: false },
+          },
+        },
+        session: { store: storePath },
+      };
+      const sessionKey = resolveMainSessionKey(cfg);
+
+      await seedSessionStore(storePath, sessionKey, {
+        lastChannel: "telegram",
+        lastProvider: "telegram",
+        lastTo: "12345",
+      });
+
+      replySpy.mockResolvedValue({ text: "HEARTBEAT_OK" });
+      const sendTelegram = vi.fn().mockResolvedValue({
+        messageId: "m1",
+        toJid: "jid",
+      });
+
+      await runHeartbeatOnce({
+        cfg,
+        deps: {
+          sendTelegram,
+          getQueueSize: () => 0,
+          nowMs: () => 0,
+        },
+      });
+
+      expect(sendTelegram).not.toHaveBeenCalled();
+    });
+  });
+
   it("skips heartbeat LLM calls when visibility disables all output", async () => {
     await withTempHeartbeatSandbox(async ({ tmpDir, storePath, replySpy }) => {
       const cfg: OpenClawConfig = {
diff --git a/src/infra/heartbeat-runner.returns-default-unset.test.ts b/src/infra/heartbeat-runner.returns-default-unset.test.ts
index 90359fadacb..f8a76d952c0 100644
--- a/src/infra/heartbeat-runner.returns-default-unset.test.ts
+++ b/src/infra/heartbeat-runner.returns-default-unset.test.ts
@@ -1,24 +1,20 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
-import { telegramPlugin } from "../../extensions/telegram/src/channel.js";
-import { setTelegramRuntime } from "../../extensions/telegram/src/runtime.js";
-import { whatsappPlugin } from "../../extensions/whatsapp/src/channel.js";
-import { setWhatsAppRuntime } from "../../extensions/whatsapp/src/runtime.js";
 import { HEARTBEAT_PROMPT } from "../auto-reply/heartbeat.js";
 import * as replyModule from "../auto-reply/reply.js";
+import { whatsappOutbound } from "../channels/plugins/outbound/whatsapp.js";
 import {
   resolveAgentIdFromSessionKey,
   resolveAgentMainSessionKey,
   resolveMainSessionKey,
   resolveStorePath,
 } from "../config/sessions.js";
-import { setActivePluginRegistry } from "../plugins/runtime.js";
-import { createPluginRuntime } from "../plugins/runtime/index.js";
+import { getActivePluginRegistry, setActivePluginRegistry } from "../plugins/runtime.js";
 import { buildAgentPeerSessionKey } from "../routing/session-key.js";
-import { createTestRegistry } from "../test-utils/channel-plugins.js";
+import { createOutboundTestPlugin, createTestRegistry } from "../test-utils/channel-plugins.js";
 import {
   isHeartbeatEnabledForAgent,
   resolveHeartbeatIntervalMs,
@@ -33,16 +29,90 @@ import {
 // Avoid pulling optional runtime deps during isolated runs.
 vi.mock("jiti", () => ({ createJiti: () => () => ({}) }));
 
+let previousRegistry: ReturnType<typeof getActivePluginRegistry> | null = null;
+let testRegistry: ReturnType<typeof getActivePluginRegistry> | null = null;
+
+let fixtureRoot = "";
+let fixtureCount = 0;
+
+const createCaseDir = async (prefix: string) => {
+  const dir = path.join(fixtureRoot, `${prefix}-${fixtureCount++}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+};
+
+beforeAll(async () => {
+  previousRegistry = getActivePluginRegistry();
+
+  const whatsappPlugin = createOutboundTestPlugin({ id: "whatsapp", outbound: whatsappOutbound });
+  whatsappPlugin.config = {
+    ...whatsappPlugin.config,
+    resolveAllowFrom: ({ cfg }) =>
+      cfg.channels?.whatsapp?.allowFrom?.map((entry) => String(entry)) ?? [],
+  };
+
+  const telegramPlugin = createOutboundTestPlugin({
+    id: "telegram",
+    outbound: {
+      deliveryMode: "direct",
+      sendText: async ({ to, text, deps, accountId }) => {
+        if (!deps?.sendTelegram) {
+          throw new Error("sendTelegram missing");
+        }
+        const res = await deps.sendTelegram(to, text, {
+          verbose: false,
+          accountId: accountId ?? undefined,
+        });
+        return { channel: "telegram", messageId: res.messageId, chatId: res.chatId };
+      },
+      sendMedia: async ({ to, text, mediaUrl, deps, accountId }) => {
+        if (!deps?.sendTelegram) {
+          throw new Error("sendTelegram missing");
+        }
+        const res = await deps.sendTelegram(to, text, {
+          verbose: false,
+          accountId: accountId ?? undefined,
+          mediaUrl,
+        });
+        return { channel: "telegram", messageId: res.messageId, chatId: res.chatId };
+      },
+    },
+  });
+  telegramPlugin.config = {
+    ...telegramPlugin.config,
+    listAccountIds: (cfg) => Object.keys(cfg.channels?.telegram?.accounts ?? {}),
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      const channel = cfg.channels?.telegram;
+      const normalized = accountId?.trim();
+      if (normalized && channel?.accounts?.[normalized]?.allowFrom) {
+        return channel.accounts[normalized].allowFrom?.map((entry) => String(entry)) ?? [];
+      }
+      return channel?.allowFrom?.map((entry) => String(entry)) ?? [];
+    },
+  };
+
+  testRegistry = createTestRegistry([
+    { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+    { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+  ]);
+  setActivePluginRegistry(testRegistry);
+
+  fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-heartbeat-suite-"));
+});
+
 beforeEach(() => {
-  const runtime = createPluginRuntime();
-  setTelegramRuntime(runtime);
-  setWhatsAppRuntime(runtime);
-  setActivePluginRegistry(
-    createTestRegistry([
-      { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
-      { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
-    ]),
-  );
+  if (testRegistry) {
+    setActivePluginRegistry(testRegistry);
+  }
+});
+
+afterAll(async () => {
+  if (fixtureRoot) {
+    await fs.rm(fixtureRoot, { recursive: true, force: true });
+  }
+  if (previousRegistry) {
+    setActivePluginRegistry(previousRegistry);
+  }
 });
 
 describe("resolveHeartbeatIntervalMs", () => {
@@ -217,24 +287,6 @@ describe("resolveHeartbeatDeliveryTarget", () => {
     });
   });
 
-  it("keeps WhatsApp group targets even with allowFrom set", () => {
-    const cfg: OpenClawConfig = {
-      channels: { whatsapp: { allowFrom: ["+1555"] } },
-    };
-    const entry = {
-      ...baseEntry,
-      lastChannel: "whatsapp" as const,
-      lastTo: "120363401234567890@g.us",
-    };
-    expect(resolveHeartbeatDeliveryTarget({ cfg, entry })).toEqual({
-      channel: "whatsapp",
-      to: "120363401234567890@g.us",
-      accountId: undefined,
-      lastChannel: "whatsapp",
-      lastAccountId: undefined,
-    });
-  });
-
   it("normalizes prefixed WhatsApp group targets for heartbeat delivery", () => {
     const cfg: OpenClawConfig = {
       channels: { whatsapp: { allowFrom: ["+1555"] } },
@@ -253,19 +305,6 @@ describe("resolveHeartbeatDeliveryTarget", () => {
     });
   });
 
-  it("keeps explicit telegram targets", () => {
-    const cfg: OpenClawConfig = {
-      agents: { defaults: { heartbeat: { target: "telegram", to: "123" } } },
-    };
-    expect(resolveHeartbeatDeliveryTarget({ cfg, entry: baseEntry })).toEqual({
-      channel: "telegram",
-      to: "123",
-      accountId: undefined,
-      lastChannel: undefined,
-      lastAccountId: undefined,
-    });
-  });
-
   it("uses explicit heartbeat accountId when provided", () => {
     const cfg: OpenClawConfig = {
       agents: {
@@ -397,7 +436,7 @@ describe("runHeartbeatOnce", () => {
   });
 
   it("uses the last non-empty payload for delivery", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-last-payload");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -415,18 +454,14 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastTo: "+1555",
-            },
+        JSON.stringify({
+          [sessionKey]: {
+            sessionId: "sid",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastTo: "+1555",
           },
-          null,
-          2,
-        ),
+        }),
       );
 
       replySpy.mockResolvedValue([{ text: "Let me check..." }, { text: "Final alert" }]);
@@ -450,12 +485,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).toHaveBeenCalledWith("+1555", "Final alert", expect.any(Object));
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("uses per-agent heartbeat overrides and session keys", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-agent-overrides");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -479,18 +513,14 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastTo: "+1555",
-            },
+        JSON.stringify({
+          [sessionKey]: {
+            sessionId: "sid",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastTo: "+1555",
           },
-          null,
-          2,
-        ),
+        }),
       );
       replySpy.mockResolvedValue([{ text: "Final alert" }]);
       const sendWhatsApp = vi.fn().mockResolvedValue({
@@ -520,12 +550,11 @@ describe("runHeartbeatOnce", () => {
       );
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("reuses non-default agent sessionFile from templated stores", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-templated-store");
     const storeTemplate = path.join(tmpDir, "agents", "{agentId}", "sessions", "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     const agentId = "ops";
@@ -598,12 +627,11 @@ describe("runHeartbeatOnce", () => {
       );
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("runs heartbeats in the explicit session key when configured", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-explicit-session");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -635,24 +663,20 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [mainSessionKey]: {
-              sessionId: "sid-main",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastTo: "+1555",
-            },
-            [groupSessionKey]: {
-              sessionId: "sid-group",
-              updatedAt: Date.now() + 10_000,
-              lastChannel: "whatsapp",
-              lastTo: groupId,
-            },
+        JSON.stringify({
+          [mainSessionKey]: {
+            sessionId: "sid-main",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastTo: "+1555",
           },
-          null,
-          2,
-        ),
+          [groupSessionKey]: {
+            sessionId: "sid-group",
+            updatedAt: Date.now() + 10_000,
+            lastChannel: "whatsapp",
+            lastTo: groupId,
+          },
+        }),
       );
 
       replySpy.mockResolvedValue([{ text: "Group alert" }]);
@@ -681,12 +705,11 @@ describe("runHeartbeatOnce", () => {
       );
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("suppresses duplicate heartbeat payloads within 24h", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-dup-suppress");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -704,20 +727,16 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastTo: "+1555",
-              lastHeartbeatText: "Final alert",
-              lastHeartbeatSentAt: 0,
-            },
+        JSON.stringify({
+          [sessionKey]: {
+            sessionId: "sid",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastTo: "+1555",
+            lastHeartbeatText: "Final alert",
+            lastHeartbeatSentAt: 0,
           },
-          null,
-          2,
-        ),
+        }),
       );
 
       replySpy.mockResolvedValue([{ text: "Final alert" }]);
@@ -737,12 +756,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).toHaveBeenCalledTimes(0);
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("can include reasoning payloads when enabled", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-reasoning");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -764,19 +782,15 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastProvider: "whatsapp",
-              lastTo: "+1555",
-            },
+        JSON.stringify({
+          [sessionKey]: {
+            sessionId: "sid",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastProvider: "whatsapp",
+            lastTo: "+1555",
           },
-          null,
-          2,
-        ),
+        }),
       );
 
       replySpy.mockResolvedValue([
@@ -809,12 +823,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).toHaveBeenNthCalledWith(2, "+1555", "Final alert", expect.any(Object));
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("delivers reasoning even when the main heartbeat reply is HEARTBEAT_OK", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("hb-reasoning-heartbeat-ok");
     const storePath = path.join(tmpDir, "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -836,19 +849,15 @@ describe("runHeartbeatOnce", () => {
 
       await fs.writeFile(
         storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastProvider: "whatsapp",
-              lastTo: "+1555",
-            },
+        JSON.stringify({
+          [sessionKey]: {
+            sessionId: "sid",
+            updatedAt: Date.now(),
+            lastChannel: "whatsapp",
+            lastProvider: "whatsapp",
+            lastTo: "+1555",
           },
-          null,
-          2,
-        ),
+        }),
       );
 
       replySpy.mockResolvedValue([
@@ -880,12 +889,11 @@ describe("runHeartbeatOnce", () => {
       );
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("loads the default agent session from templated stores", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("openclaw-hb");
     const storeTemplate = path.join(tmpDir, "agents", "{agentId}", "sessions.json");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
     try {
@@ -944,12 +952,11 @@ describe("runHeartbeatOnce", () => {
       );
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("skips heartbeat when HEARTBEAT.md is effectively empty (saves API calls)", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("openclaw-hb");
     const storePath = path.join(tmpDir, "sessions.json");
     const workspaceDir = path.join(tmpDir, "workspace");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
@@ -1016,12 +1023,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).not.toHaveBeenCalled();
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("does not skip wake-triggered heartbeat when HEARTBEAT.md is effectively empty", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("openclaw-hb");
     const storePath = path.join(tmpDir, "sessions.json");
     const workspaceDir = path.join(tmpDir, "workspace");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
@@ -1084,80 +1090,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).toHaveBeenCalledTimes(1);
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  it("does not skip hook-triggered heartbeat when HEARTBEAT.md is effectively empty", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
-    const storePath = path.join(tmpDir, "sessions.json");
-    const workspaceDir = path.join(tmpDir, "workspace");
-    const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
-    try {
-      await fs.mkdir(workspaceDir, { recursive: true });
-      await fs.writeFile(
-        path.join(workspaceDir, "HEARTBEAT.md"),
-        "# HEARTBEAT.md\n\n## Tasks\n\n",
-        "utf-8",
-      );
-
-      const cfg: OpenClawConfig = {
-        agents: {
-          defaults: {
-            workspace: workspaceDir,
-            heartbeat: { every: "5m", target: "whatsapp" },
-          },
-        },
-        channels: { whatsapp: { allowFrom: ["*"] } },
-        session: { store: storePath },
-      };
-      const sessionKey = resolveMainSessionKey(cfg);
-
-      await fs.writeFile(
-        storePath,
-        JSON.stringify(
-          {
-            [sessionKey]: {
-              sessionId: "sid",
-              updatedAt: Date.now(),
-              lastChannel: "whatsapp",
-              lastTo: "+1555",
-            },
-          },
-          null,
-          2,
-        ),
-      );
-
-      replySpy.mockResolvedValue({ text: "hook event processed" });
-      const sendWhatsApp = vi.fn().mockResolvedValue({
-        messageId: "m1",
-        toJid: "jid",
-      });
-
-      const res = await runHeartbeatOnce({
-        cfg,
-        reason: "hook:wake",
-        deps: {
-          sendWhatsApp,
-          getQueueSize: () => 0,
-          nowMs: () => 0,
-          webAuthExists: async () => true,
-          hasActiveWebListener: () => true,
-        },
-      });
-
-      expect(res.status).toBe("ran");
-      expect(replySpy).toHaveBeenCalled();
-      expect(sendWhatsApp).toHaveBeenCalledTimes(1);
-    } finally {
-      replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("runs heartbeat when HEARTBEAT.md has actionable content", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("openclaw-hb");
     const storePath = path.join(tmpDir, "sessions.json");
     const workspaceDir = path.join(tmpDir, "workspace");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
@@ -1222,12 +1159,11 @@ describe("runHeartbeatOnce", () => {
       expect(sendWhatsApp).toHaveBeenCalledTimes(1);
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
   it("runs heartbeat when HEARTBEAT.md does not exist (lets LLM decide)", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-hb-"));
+    const tmpDir = await createCaseDir("openclaw-hb");
     const storePath = path.join(tmpDir, "sessions.json");
     const workspaceDir = path.join(tmpDir, "workspace");
     const replySpy = vi.spyOn(replyModule, "getReplyFromConfig");
@@ -1285,7 +1221,6 @@ describe("runHeartbeatOnce", () => {
       expect(replySpy).toHaveBeenCalled();
     } finally {
       replySpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 });
diff --git a/src/infra/install-safe-path.test.ts b/src/infra/install-safe-path.test.ts
new file mode 100644
index 00000000000..1d6b9b6e4e5
--- /dev/null
+++ b/src/infra/install-safe-path.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { safePathSegmentHashed } from "./install-safe-path.js";
+
+describe("safePathSegmentHashed", () => {
+  it("keeps safe names unchanged", () => {
+    expect(safePathSegmentHashed("demo-skill")).toBe("demo-skill");
+  });
+
+  it("normalizes separators and adds hash suffix", () => {
+    const result = safePathSegmentHashed("../../demo/skill");
+    expect(result.includes("/")).toBe(false);
+    expect(result.includes("\\")).toBe(false);
+    expect(result).toMatch(/-[a-f0-9]{10}$/);
+  });
+
+  it("hashes long names while staying bounded", () => {
+    const long = "a".repeat(100);
+    const result = safePathSegmentHashed(long);
+    expect(result.length).toBeLessThanOrEqual(61);
+    expect(result).toMatch(/-[a-f0-9]{10}$/);
+  });
+});
diff --git a/src/infra/install-safe-path.ts b/src/infra/install-safe-path.ts
index 012f633a88e..98da6bba6ec 100644
--- a/src/infra/install-safe-path.ts
+++ b/src/infra/install-safe-path.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
 
 export function unscopedPackageName(name: string): string {
@@ -16,6 +17,30 @@ export function safeDirName(input: string): string {
   return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
 }
 
+export function safePathSegmentHashed(input: string): string {
+  const trimmed = input.trim();
+  const base = trimmed
+    .replaceAll(/[\\/]/g, "-")
+    .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-+/g, "")
+    .replaceAll(/-+$/g, "");
+
+  const normalized = base.length > 0 ? base : "skill";
+  const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
+
+  const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
+
+  if (safe !== trimmed) {
+    const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
+    return `${prefix}-${hash}`;
+  }
+  if (safe.length > 60) {
+    return `${safe.slice(0, 50)}-${hash}`;
+  }
+  return safe;
+}
+
 export function resolveSafeInstallDir(params: {
   baseDir: string;
   id: string;
diff --git a/src/infra/json-files.ts b/src/infra/json-files.ts
new file mode 100644
index 00000000000..d71cbf7639b
--- /dev/null
+++ b/src/infra/json-files.ts
@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeJsonAtomic(
+  filePath: string,
+  value: unknown,
+  options?: { mode?: number },
+) {
+  const mode = options?.mode ?? 0o600;
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmp = `${filePath}.${randomUUID()}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(value, null, 2), "utf8");
+  try {
+    await fs.chmod(tmp, mode);
+  } catch {
+    // best-effort; ignore on platforms without chmod
+  }
+  await fs.rename(tmp, filePath);
+  try {
+    await fs.chmod(filePath, mode);
+  } catch {
+    // best-effort; ignore on platforms without chmod
+  }
+}
+
+export function createAsyncLock() {
+  let lock: Promise<void> = Promise.resolve();
+  return async function withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const prev = lock;
+    let release: (() => void) | undefined;
+    lock = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release?.();
+    }
+  };
+}
diff --git a/src/infra/net/hostname.ts b/src/infra/net/hostname.ts
new file mode 100644
index 00000000000..dd048575a08
--- /dev/null
+++ b/src/infra/net/hostname.ts
@@ -0,0 +1,7 @@
+export function normalizeHostname(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    return normalized.slice(1, -1);
+  }
+  return normalized;
+}
diff --git a/src/infra/net/ssrf.test.ts b/src/infra/net/ssrf.test.ts
index b058e5e3410..a093f4155ba 100644
--- a/src/infra/net/ssrf.test.ts
+++ b/src/infra/net/ssrf.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { normalizeFingerprint } from "../tls/fingerprint.js";
 import { isPrivateIpAddress } from "./ssrf.js";
 
 describe("ssrf ip classification", () => {
@@ -30,3 +31,11 @@ describe("ssrf ip classification", () => {
     expect(isPrivateIpAddress("2001:db8::1")).toBe(false);
   });
 });
+
+describe("normalizeFingerprint", () => {
+  it("strips sha256 prefixes and separators", () => {
+    expect(normalizeFingerprint("sha256:AA:BB:cc")).toBe("aabbcc");
+    expect(normalizeFingerprint("SHA-256 11-22-33")).toBe("112233");
+    expect(normalizeFingerprint("aa:bb:cc")).toBe("aabbcc");
+  });
+});
diff --git a/src/infra/net/ssrf.ts b/src/infra/net/ssrf.ts
index e8c524db988..fce4204f4ff 100644
--- a/src/infra/net/ssrf.ts
+++ b/src/infra/net/ssrf.ts
@@ -1,6 +1,7 @@
 import { lookup as dnsLookupCb, type LookupAddress } from "node:dns";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { Agent, type Dispatcher } from "undici";
+import { normalizeHostname } from "./hostname.js";
 
 type LookupCallback = (
   err: NodeJS.ErrnoException | null,
@@ -25,14 +26,6 @@ export type SsrFPolicy = {
 
 const BLOCKED_HOSTNAMES = new Set(["localhost", "metadata.google.internal"]);
 
-function normalizeHostname(hostname: string): string {
-  const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
-  if (normalized.startsWith("[") && normalized.endsWith("]")) {
-    return normalized.slice(1, -1);
-  }
-  return normalized;
-}
-
 function normalizeHostnameSet(values?: string[]): Set<string> {
   if (!values || values.length === 0) {
     return new Set<string>();
diff --git a/src/infra/openclaw-root.test.ts b/src/infra/openclaw-root.test.ts
new file mode 100644
index 00000000000..5f2a4e94d65
--- /dev/null
+++ b/src/infra/openclaw-root.test.ts
@@ -0,0 +1,150 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type FakeFsEntry = { kind: "file"; content: string } | { kind: "dir" };
+
+const VITEST_FS_BASE = path.join(path.parse(process.cwd()).root, "__openclaw_vitest__");
+const FIXTURE_BASE = path.join(VITEST_FS_BASE, "openclaw-root");
+
+const state = vi.hoisted(() => ({
+  entries: new Map<string, FakeFsEntry>(),
+  realpaths: new Map<string, string>(),
+}));
+
+const abs = (p: string) => path.resolve(p);
+const fx = (...parts: string[]) => path.join(FIXTURE_BASE, ...parts);
+
+function setFile(p: string, content = "") {
+  state.entries.set(abs(p), { kind: "file", content });
+}
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+  const vitestRoot = `${absInMock(VITEST_FS_BASE)}${pathMod.sep}`;
+  const isFixturePath = (p: string) => {
+    const resolved = absInMock(p);
+    return resolved === vitestRoot.slice(0, -1) || resolved.startsWith(vitestRoot);
+  };
+  const wrapped = {
+    ...actual,
+    existsSync: (p: string) =>
+      isFixturePath(p) ? state.entries.has(absInMock(p)) : actual.existsSync(p),
+    readFileSync: (p: string, encoding?: unknown) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return actual.readFileSync(p as any, encoding as any) as unknown;
+      }
+      const entry = state.entries.get(absInMock(p));
+      if (!entry || entry.kind !== "file") {
+        throw new Error(`ENOENT: no such file, open '${p}'`);
+      }
+      return encoding ? entry.content : Buffer.from(entry.content, "utf-8");
+    },
+    statSync: (p: string) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return actual.statSync(p as any) as unknown;
+      }
+      const entry = state.entries.get(absInMock(p));
+      if (!entry) {
+        throw new Error(`ENOENT: no such file or directory, stat '${p}'`);
+      }
+      return {
+        isFile: () => entry.kind === "file",
+        isDirectory: () => entry.kind === "dir",
+      };
+    },
+    realpathSync: (p: string) =>
+      isFixturePath(p)
+        ? (state.realpaths.get(absInMock(p)) ?? absInMock(p))
+        : actual.realpathSync(p),
+  };
+  return { ...wrapped, default: wrapped };
+});
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+  const vitestRoot = `${absInMock(VITEST_FS_BASE)}${pathMod.sep}`;
+  const isFixturePath = (p: string) => {
+    const resolved = absInMock(p);
+    return resolved === vitestRoot.slice(0, -1) || resolved.startsWith(vitestRoot);
+  };
+  const wrapped = {
+    ...actual,
+    readFile: async (p: string, encoding?: unknown) => {
+      if (!isFixturePath(p)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (await actual.readFile(p as any, encoding as any)) as unknown;
+      }
+      const entry = state.entries.get(absInMock(p));
+      if (!entry || entry.kind !== "file") {
+        throw new Error(`ENOENT: no such file, open '${p}'`);
+      }
+      return entry.content;
+    },
+  };
+  return { ...wrapped, default: wrapped };
+});
+
+describe("resolveOpenClawPackageRoot", () => {
+  beforeEach(() => {
+    state.entries.clear();
+    state.realpaths.clear();
+  });
+
+  it("resolves package root from .bin argv1", async () => {
+    const { resolveOpenClawPackageRootSync } = await import("./openclaw-root.js");
+
+    const project = fx("bin-scenario");
+    const argv1 = path.join(project, "node_modules", ".bin", "openclaw");
+    const pkgRoot = path.join(project, "node_modules", "openclaw");
+    setFile(path.join(pkgRoot, "package.json"), JSON.stringify({ name: "openclaw" }));
+
+    expect(resolveOpenClawPackageRootSync({ argv1 })).toBe(pkgRoot);
+  });
+
+  it("resolves package root via symlinked argv1", async () => {
+    const { resolveOpenClawPackageRootSync } = await import("./openclaw-root.js");
+
+    const project = fx("symlink-scenario");
+    const bin = path.join(project, "bin", "openclaw");
+    const realPkg = path.join(project, "real-pkg");
+    state.realpaths.set(abs(bin), abs(path.join(realPkg, "openclaw.mjs")));
+    setFile(path.join(realPkg, "package.json"), JSON.stringify({ name: "openclaw" }));
+
+    expect(resolveOpenClawPackageRootSync({ argv1: bin })).toBe(realPkg);
+  });
+
+  it("prefers moduleUrl candidates", async () => {
+    const { resolveOpenClawPackageRootSync } = await import("./openclaw-root.js");
+
+    const pkgRoot = fx("moduleurl");
+    setFile(path.join(pkgRoot, "package.json"), JSON.stringify({ name: "openclaw" }));
+    const moduleUrl = pathToFileURL(path.join(pkgRoot, "dist", "index.js")).toString();
+
+    expect(resolveOpenClawPackageRootSync({ moduleUrl })).toBe(pkgRoot);
+  });
+
+  it("returns null for non-openclaw package roots", async () => {
+    const { resolveOpenClawPackageRootSync } = await import("./openclaw-root.js");
+
+    const pkgRoot = fx("not-openclaw");
+    setFile(path.join(pkgRoot, "package.json"), JSON.stringify({ name: "not-openclaw" }));
+
+    expect(resolveOpenClawPackageRootSync({ cwd: pkgRoot })).toBeNull();
+  });
+
+  it("async resolver matches sync behavior", async () => {
+    const { resolveOpenClawPackageRoot } = await import("./openclaw-root.js");
+
+    const pkgRoot = fx("async");
+    setFile(path.join(pkgRoot, "package.json"), JSON.stringify({ name: "openclaw" }));
+
+    await expect(resolveOpenClawPackageRoot({ cwd: pkgRoot })).resolves.toBe(pkgRoot);
+  });
+});
diff --git a/src/infra/openclaw-root.ts b/src/infra/openclaw-root.ts
index 2beb3e8f0c4..257b547f1ff 100644
--- a/src/infra/openclaw-root.ts
+++ b/src/infra/openclaw-root.ts
@@ -87,19 +87,7 @@ export async function resolveOpenClawPackageRoot(opts: {
   argv1?: string;
   moduleUrl?: string;
 }): Promise<string | null> {
-  const candidates: string[] = [];
-
-  if (opts.moduleUrl) {
-    candidates.push(path.dirname(fileURLToPath(opts.moduleUrl)));
-  }
-  if (opts.argv1) {
-    candidates.push(...candidateDirsFromArgv1(opts.argv1));
-  }
-  if (opts.cwd) {
-    candidates.push(opts.cwd);
-  }
-
-  for (const candidate of candidates) {
+  for (const candidate of buildCandidates(opts)) {
     const found = await findPackageRoot(candidate);
     if (found) {
       return found;
@@ -114,6 +102,17 @@ export function resolveOpenClawPackageRootSync(opts: {
   argv1?: string;
   moduleUrl?: string;
 }): string | null {
+  for (const candidate of buildCandidates(opts)) {
+    const found = findPackageRootSync(candidate);
+    if (found) {
+      return found;
+    }
+  }
+
+  return null;
+}
+
+function buildCandidates(opts: { cwd?: string; argv1?: string; moduleUrl?: string }): string[] {
   const candidates: string[] = [];
 
   if (opts.moduleUrl) {
@@ -126,12 +125,5 @@ export function resolveOpenClawPackageRootSync(opts: {
     candidates.push(opts.cwd);
   }
 
-  for (const candidate of candidates) {
-    const found = findPackageRootSync(candidate);
-    if (found) {
-      return found;
-    }
-  }
-
-  return null;
+  return candidates;
 }
diff --git a/src/infra/outbound/channel-adapters.ts b/src/infra/outbound/channel-adapters.ts
index c48fbb3959e..ba6a1b59444 100644
--- a/src/infra/outbound/channel-adapters.ts
+++ b/src/infra/outbound/channel-adapters.ts
@@ -1,20 +1,50 @@
+import { Separator, TextDisplay, type TopLevelComponents } from "@buape/carbon";
 import type { ChannelId } from "../../channels/plugins/types.js";
+import type { OpenClawConfig } from "../../config/config.js";
+import { DiscordUiContainer } from "../../discord/ui.js";
+
+export type CrossContextComponentsBuilder = (message: string) => TopLevelComponents[];
+
+export type CrossContextComponentsFactory = (params: {
+  originLabel: string;
+  message: string;
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}) => TopLevelComponents[];
 
 export type ChannelMessageAdapter = {
-  supportsEmbeds: boolean;
-  buildCrossContextEmbeds?: (originLabel: string) => unknown[];
+  supportsComponentsV2: boolean;
+  buildCrossContextComponents?: CrossContextComponentsFactory;
 };
 
+type CrossContextContainerParams = {
+  originLabel: string;
+  message: string;
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+};
+
+class CrossContextContainer extends DiscordUiContainer {
+  constructor({ originLabel, message, cfg, accountId }: CrossContextContainerParams) {
+    const trimmed = message.trim();
+    const components = [] as Array<TextDisplay | Separator>;
+    if (trimmed) {
+      components.push(new TextDisplay(message));
+      components.push(new Separator({ divider: true, spacing: "small" }));
+    }
+    components.push(new TextDisplay(`*From ${originLabel}*`));
+    super({ cfg, accountId, components });
+  }
+}
+
 const DEFAULT_ADAPTER: ChannelMessageAdapter = {
-  supportsEmbeds: false,
+  supportsComponentsV2: false,
 };
 
 const DISCORD_ADAPTER: ChannelMessageAdapter = {
-  supportsEmbeds: true,
-  buildCrossContextEmbeds: (originLabel: string) => [
-    {
-      description: `From ${originLabel}`,
-    },
+  supportsComponentsV2: true,
+  buildCrossContextComponents: ({ originLabel, message, cfg, accountId }) => [
+    new CrossContextContainer({ originLabel, message, cfg, accountId }),
   ],
 };
 
diff --git a/src/infra/outbound/deliver.ts b/src/infra/outbound/deliver.ts
index 9d2e2107d62..23c576cd98d 100644
--- a/src/infra/outbound/deliver.ts
+++ b/src/infra/outbound/deliver.ts
@@ -1,5 +1,8 @@
 import type { ReplyPayload } from "../../auto-reply/types.js";
-import type { ChannelOutboundAdapter } from "../../channels/plugins/types.js";
+import type {
+  ChannelOutboundAdapter,
+  ChannelOutboundContext,
+} from "../../channels/plugins/types.js";
 import type { OpenClawConfig } from "../../config/config.js";
 import type { sendMessageDiscord } from "../../discord/send.js";
 import type { sendMessageIMessage } from "../../imessage/send.js";
@@ -79,8 +82,7 @@ type ChannelHandler = {
   sendMedia: (caption: string, mediaUrl: string) => Promise<OutboundDeliveryResult>;
 };
 
-// Channel docking: outbound delivery delegates to plugin.outbound adapters.
-async function createChannelHandler(params: {
+type ChannelHandlerParams = {
   cfg: OpenClawConfig;
   channel: Exclude<OutboundChannel, "none">;
   to: string;
@@ -92,49 +94,26 @@ async function createChannelHandler(params: {
   gifPlayback?: boolean;
   silent?: boolean;
   mediaLocalRoots?: readonly string[];
-}): Promise<ChannelHandler> {
+};
+
+// Channel docking: outbound delivery delegates to plugin.outbound adapters.
+async function createChannelHandler(params: ChannelHandlerParams): Promise<ChannelHandler> {
   const outbound = await loadChannelOutboundAdapter(params.channel);
-  if (!outbound?.sendText || !outbound?.sendMedia) {
-    throw new Error(`Outbound not configured for channel: ${params.channel}`);
-  }
-  const handler = createPluginHandler({
-    outbound,
-    cfg: params.cfg,
-    channel: params.channel,
-    to: params.to,
-    accountId: params.accountId,
-    replyToId: params.replyToId,
-    threadId: params.threadId,
-    identity: params.identity,
-    deps: params.deps,
-    gifPlayback: params.gifPlayback,
-    silent: params.silent,
-    mediaLocalRoots: params.mediaLocalRoots,
-  });
+  const handler = createPluginHandler({ ...params, outbound });
   if (!handler) {
     throw new Error(`Outbound not configured for channel: ${params.channel}`);
   }
   return handler;
 }
 
-function createPluginHandler(params: {
-  outbound?: ChannelOutboundAdapter;
-  cfg: OpenClawConfig;
-  channel: Exclude<OutboundChannel, "none">;
-  to: string;
-  accountId?: string;
-  replyToId?: string | null;
-  threadId?: string | number | null;
-  identity?: OutboundIdentity;
-  deps?: OutboundSendDeps;
-  gifPlayback?: boolean;
-  silent?: boolean;
-  mediaLocalRoots?: readonly string[];
-}): ChannelHandler | null {
+function createPluginHandler(
+  params: ChannelHandlerParams & { outbound?: ChannelOutboundAdapter },
+): ChannelHandler | null {
   const outbound = params.outbound;
   if (!outbound?.sendText || !outbound?.sendMedia) {
     return null;
   }
+  const baseCtx = createChannelOutboundContextBase(params);
   const sendText = outbound.sendText;
   const sendMedia = outbound.sendMedia;
   const chunker = outbound.chunker ?? null;
@@ -146,53 +125,43 @@ function createPluginHandler(params: {
     sendPayload: outbound.sendPayload
       ? async (payload) =>
           outbound.sendPayload!({
-            cfg: params.cfg,
-            to: params.to,
+            ...baseCtx,
             text: payload.text ?? "",
             mediaUrl: payload.mediaUrl,
-            accountId: params.accountId,
-            replyToId: params.replyToId,
-            threadId: params.threadId,
-            identity: params.identity,
-            gifPlayback: params.gifPlayback,
-            deps: params.deps,
-            silent: params.silent,
-            mediaLocalRoots: params.mediaLocalRoots,
             payload,
           })
       : undefined,
     sendText: async (text) =>
       sendText({
-        cfg: params.cfg,
-        to: params.to,
+        ...baseCtx,
         text,
-        accountId: params.accountId,
-        replyToId: params.replyToId,
-        threadId: params.threadId,
-        identity: params.identity,
-        gifPlayback: params.gifPlayback,
-        deps: params.deps,
-        silent: params.silent,
-        mediaLocalRoots: params.mediaLocalRoots,
       }),
     sendMedia: async (caption, mediaUrl) =>
       sendMedia({
-        cfg: params.cfg,
-        to: params.to,
+        ...baseCtx,
         text: caption,
         mediaUrl,
-        accountId: params.accountId,
-        replyToId: params.replyToId,
-        threadId: params.threadId,
-        identity: params.identity,
-        gifPlayback: params.gifPlayback,
-        deps: params.deps,
-        silent: params.silent,
-        mediaLocalRoots: params.mediaLocalRoots,
       }),
   };
 }
 
+function createChannelOutboundContextBase(
+  params: ChannelHandlerParams,
+): Omit<ChannelOutboundContext, "text" | "mediaUrl"> {
+  return {
+    cfg: params.cfg,
+    to: params.to,
+    accountId: params.accountId,
+    replyToId: params.replyToId,
+    threadId: params.threadId,
+    identity: params.identity,
+    gifPlayback: params.gifPlayback,
+    deps: params.deps,
+    silent: params.silent,
+    mediaLocalRoots: params.mediaLocalRoots,
+  };
+}
+
 const isAbortError = (err: unknown): boolean => err instanceof Error && err.name === "AbortError";
 
 type DeliverOutboundPayloadsCoreParams = {
diff --git a/src/infra/outbound/delivery-queue.test.ts b/src/infra/outbound/delivery-queue.test.ts
deleted file mode 100644
index ee94d13b62b..00000000000
--- a/src/infra/outbound/delivery-queue.test.ts
+++ /dev/null
@@ -1,373 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  ackDelivery,
-  computeBackoffMs,
-  enqueueDelivery,
-  failDelivery,
-  loadPendingDeliveries,
-  MAX_RETRIES,
-  moveToFailed,
-  recoverPendingDeliveries,
-} from "./delivery-queue.js";
-
-let tmpDir: string;
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-dq-test-"));
-});
-
-afterEach(() => {
-  fs.rmSync(tmpDir, { recursive: true, force: true });
-});
-
-describe("enqueue + ack lifecycle", () => {
-  it("creates and removes a queue entry", async () => {
-    const id = await enqueueDelivery(
-      {
-        channel: "whatsapp",
-        to: "+1555",
-        payloads: [{ text: "hello" }],
-        bestEffort: true,
-        gifPlayback: true,
-        silent: true,
-        mirror: {
-          sessionKey: "agent:main:main",
-          text: "hello",
-          mediaUrls: ["https://example.com/file.png"],
-        },
-      },
-      tmpDir,
-    );
-
-    // Entry file exists after enqueue.
-    const queueDir = path.join(tmpDir, "delivery-queue");
-    const files = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json"));
-    expect(files).toHaveLength(1);
-    expect(files[0]).toBe(`${id}.json`);
-
-    // Entry contents are correct.
-    const entry = JSON.parse(fs.readFileSync(path.join(queueDir, files[0]), "utf-8"));
-    expect(entry).toMatchObject({
-      id,
-      channel: "whatsapp",
-      to: "+1555",
-      bestEffort: true,
-      gifPlayback: true,
-      silent: true,
-      mirror: {
-        sessionKey: "agent:main:main",
-        text: "hello",
-        mediaUrls: ["https://example.com/file.png"],
-      },
-      retryCount: 0,
-    });
-    expect(entry.payloads).toEqual([{ text: "hello" }]);
-
-    // Ack removes the file.
-    await ackDelivery(id, tmpDir);
-    const remaining = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json"));
-    expect(remaining).toHaveLength(0);
-  });
-
-  it("ack is idempotent (no error on missing file)", async () => {
-    await expect(ackDelivery("nonexistent-id", tmpDir)).resolves.toBeUndefined();
-  });
-});
-
-describe("failDelivery", () => {
-  it("increments retryCount and sets lastError", async () => {
-    const id = await enqueueDelivery(
-      {
-        channel: "telegram",
-        to: "123",
-        payloads: [{ text: "test" }],
-      },
-      tmpDir,
-    );
-
-    await failDelivery(id, "connection refused", tmpDir);
-
-    const queueDir = path.join(tmpDir, "delivery-queue");
-    const entry = JSON.parse(fs.readFileSync(path.join(queueDir, `${id}.json`), "utf-8"));
-    expect(entry.retryCount).toBe(1);
-    expect(entry.lastError).toBe("connection refused");
-  });
-});
-
-describe("moveToFailed", () => {
-  it("moves entry to failed/ subdirectory", async () => {
-    const id = await enqueueDelivery(
-      {
-        channel: "slack",
-        to: "#general",
-        payloads: [{ text: "hi" }],
-      },
-      tmpDir,
-    );
-
-    await moveToFailed(id, tmpDir);
-
-    const queueDir = path.join(tmpDir, "delivery-queue");
-    const failedDir = path.join(queueDir, "failed");
-    expect(fs.existsSync(path.join(queueDir, `${id}.json`))).toBe(false);
-    expect(fs.existsSync(path.join(failedDir, `${id}.json`))).toBe(true);
-  });
-});
-
-describe("loadPendingDeliveries", () => {
-  it("returns empty array when queue directory does not exist", async () => {
-    const nonexistent = path.join(tmpDir, "no-such-dir");
-    const entries = await loadPendingDeliveries(nonexistent);
-    expect(entries).toEqual([]);
-  });
-
-  it("loads multiple entries", async () => {
-    await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
-    await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
-
-    const entries = await loadPendingDeliveries(tmpDir);
-    expect(entries).toHaveLength(2);
-  });
-});
-
-describe("computeBackoffMs", () => {
-  it("returns 0 for retryCount 0", () => {
-    expect(computeBackoffMs(0)).toBe(0);
-  });
-
-  it("returns correct backoff for each retry", () => {
-    expect(computeBackoffMs(1)).toBe(5_000);
-    expect(computeBackoffMs(2)).toBe(25_000);
-    expect(computeBackoffMs(3)).toBe(120_000);
-    expect(computeBackoffMs(4)).toBe(600_000);
-    // Beyond defined schedule — clamps to last value.
-    expect(computeBackoffMs(5)).toBe(600_000);
-  });
-});
-
-describe("recoverPendingDeliveries", () => {
-  const noopDelay = async () => {};
-  const baseCfg = {};
-
-  it("recovers entries from a simulated crash", async () => {
-    // Manually create two queue entries as if gateway crashed before delivery.
-    await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
-    await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
-
-    const deliver = vi.fn().mockResolvedValue([]);
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(deliver).toHaveBeenCalledTimes(2);
-    expect(result.recovered).toBe(2);
-    expect(result.failed).toBe(0);
-    expect(result.skipped).toBe(0);
-
-    // Queue should be empty after recovery.
-    const remaining = await loadPendingDeliveries(tmpDir);
-    expect(remaining).toHaveLength(0);
-  });
-
-  it("moves entries that exceeded max retries to failed/", async () => {
-    // Create an entry and manually set retryCount to MAX_RETRIES.
-    const id = await enqueueDelivery(
-      { channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] },
-      tmpDir,
-    );
-    const filePath = path.join(tmpDir, "delivery-queue", `${id}.json`);
-    const entry = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    entry.retryCount = MAX_RETRIES;
-    fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
-
-    const deliver = vi.fn();
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(deliver).not.toHaveBeenCalled();
-    expect(result.skipped).toBe(1);
-
-    // Entry should be in failed/ directory.
-    const failedDir = path.join(tmpDir, "delivery-queue", "failed");
-    expect(fs.existsSync(path.join(failedDir, `${id}.json`))).toBe(true);
-  });
-
-  it("increments retryCount on failed recovery attempt", async () => {
-    await enqueueDelivery({ channel: "slack", to: "#ch", payloads: [{ text: "x" }] }, tmpDir);
-
-    const deliver = vi.fn().mockRejectedValue(new Error("network down"));
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(result.failed).toBe(1);
-    expect(result.recovered).toBe(0);
-
-    // Entry should still be in queue with incremented retryCount.
-    const entries = await loadPendingDeliveries(tmpDir);
-    expect(entries).toHaveLength(1);
-    expect(entries[0].retryCount).toBe(1);
-    expect(entries[0].lastError).toBe("network down");
-  });
-
-  it("passes skipQueue: true to prevent re-enqueueing during recovery", async () => {
-    await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
-
-    const deliver = vi.fn().mockResolvedValue([]);
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(deliver).toHaveBeenCalledWith(expect.objectContaining({ skipQueue: true }));
-  });
-
-  it("replays stored delivery options during recovery", async () => {
-    await enqueueDelivery(
-      {
-        channel: "whatsapp",
-        to: "+1",
-        payloads: [{ text: "a" }],
-        bestEffort: true,
-        gifPlayback: true,
-        silent: true,
-        mirror: {
-          sessionKey: "agent:main:main",
-          text: "a",
-          mediaUrls: ["https://example.com/a.png"],
-        },
-      },
-      tmpDir,
-    );
-
-    const deliver = vi.fn().mockResolvedValue([]);
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(deliver).toHaveBeenCalledWith(
-      expect.objectContaining({
-        bestEffort: true,
-        gifPlayback: true,
-        silent: true,
-        mirror: {
-          sessionKey: "agent:main:main",
-          text: "a",
-          mediaUrls: ["https://example.com/a.png"],
-        },
-      }),
-    );
-  });
-
-  it("respects maxRecoveryMs time budget", async () => {
-    await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
-    await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
-    await enqueueDelivery({ channel: "slack", to: "#c", payloads: [{ text: "c" }] }, tmpDir);
-
-    const deliver = vi.fn().mockResolvedValue([]);
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-      maxRecoveryMs: 0, // Immediate timeout — no entries should be processed.
-    });
-
-    expect(deliver).not.toHaveBeenCalled();
-    expect(result.recovered).toBe(0);
-    expect(result.failed).toBe(0);
-    expect(result.skipped).toBe(0);
-
-    // All entries should still be in the queue.
-    const remaining = await loadPendingDeliveries(tmpDir);
-    expect(remaining).toHaveLength(3);
-
-    // Should have logged a warning about deferred entries.
-    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("deferred to next restart"));
-  });
-
-  it("defers entries when backoff exceeds the recovery budget", async () => {
-    const id = await enqueueDelivery(
-      { channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] },
-      tmpDir,
-    );
-    const filePath = path.join(tmpDir, "delivery-queue", `${id}.json`);
-    const entry = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-    entry.retryCount = 3;
-    fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
-
-    const deliver = vi.fn().mockResolvedValue([]);
-    const delay = vi.fn(async () => {});
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay,
-      maxRecoveryMs: 1000,
-    });
-
-    expect(deliver).not.toHaveBeenCalled();
-    expect(delay).not.toHaveBeenCalled();
-    expect(result).toEqual({ recovered: 0, failed: 0, skipped: 0 });
-
-    const remaining = await loadPendingDeliveries(tmpDir);
-    expect(remaining).toHaveLength(1);
-
-    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("deferred to next restart"));
-  });
-
-  it("returns zeros when queue is empty", async () => {
-    const deliver = vi.fn();
-    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
-
-    const result = await recoverPendingDeliveries({
-      deliver,
-      log,
-      cfg: baseCfg,
-      stateDir: tmpDir,
-      delay: noopDelay,
-    });
-
-    expect(result).toEqual({ recovered: 0, failed: 0, skipped: 0 });
-    expect(deliver).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/infra/outbound/delivery-queue.ts b/src/infra/outbound/delivery-queue.ts
index 57565e338c0..ade2c67e47a 100644
--- a/src/infra/outbound/delivery-queue.ts
+++ b/src/infra/outbound/delivery-queue.ts
@@ -65,19 +65,21 @@ export async function ensureQueueDir(stateDir?: string): Promise<string> {
 }
 
 /** Persist a delivery entry to disk before attempting send. Returns the entry ID. */
+type QueuedDeliveryParams = {
+  channel: Exclude<OutboundChannel, "none">;
+  to: string;
+  accountId?: string;
+  payloads: ReplyPayload[];
+  threadId?: string | number | null;
+  replyToId?: string | null;
+  bestEffort?: boolean;
+  gifPlayback?: boolean;
+  silent?: boolean;
+  mirror?: DeliveryMirrorPayload;
+};
+
 export async function enqueueDelivery(
-  params: {
-    channel: Exclude<OutboundChannel, "none">;
-    to: string;
-    accountId?: string;
-    payloads: ReplyPayload[];
-    threadId?: string | number | null;
-    replyToId?: string | null;
-    bestEffort?: boolean;
-    gifPlayback?: boolean;
-    silent?: boolean;
-    mirror?: DeliveryMirrorPayload;
-  },
+  params: QueuedDeliveryParams,
   stateDir?: string,
 ): Promise<string> {
   const queueDir = await ensureQueueDir(stateDir);
@@ -191,20 +193,13 @@ export function computeBackoffMs(retryCount: number): number {
   return BACKOFF_MS[Math.min(retryCount - 1, BACKOFF_MS.length - 1)] ?? BACKOFF_MS.at(-1) ?? 0;
 }
 
-export type DeliverFn = (params: {
-  cfg: OpenClawConfig;
-  channel: Exclude<OutboundChannel, "none">;
-  to: string;
-  accountId?: string;
-  payloads: ReplyPayload[];
-  threadId?: string | number | null;
-  replyToId?: string | null;
-  bestEffort?: boolean;
-  gifPlayback?: boolean;
-  silent?: boolean;
-  mirror?: DeliveryMirrorPayload;
-  skipQueue?: boolean;
-}) => Promise<unknown>;
+export type DeliverFn = (
+  params: {
+    cfg: OpenClawConfig;
+  } & QueuedDeliveryParams & {
+      skipQueue?: boolean;
+    },
+) => Promise<unknown>;
 
 export interface RecoveryLogger {
   info(msg: string): void;
diff --git a/src/infra/outbound/directory-cache.test.ts b/src/infra/outbound/directory-cache.test.ts
deleted file mode 100644
index ce7d041951e..00000000000
--- a/src/infra/outbound/directory-cache.test.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { DirectoryCache } from "./directory-cache.js";
-
-describe("DirectoryCache", () => {
-  const cfg = {} as OpenClawConfig;
-
-  it("expires entries after ttl", () => {
-    vi.useFakeTimers();
-    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
-    const cache = new DirectoryCache<string>(1000, 10);
-
-    cache.set("a", "value-a", cfg);
-    expect(cache.get("a", cfg)).toBe("value-a");
-
-    vi.setSystemTime(new Date("2026-01-01T00:00:02.000Z"));
-    expect(cache.get("a", cfg)).toBeUndefined();
-
-    vi.useRealTimers();
-  });
-
-  it("evicts oldest keys when max size is exceeded", () => {
-    const cache = new DirectoryCache<string>(60_000, 2);
-    cache.set("a", "value-a", cfg);
-    cache.set("b", "value-b", cfg);
-    cache.set("c", "value-c", cfg);
-
-    expect(cache.get("a", cfg)).toBeUndefined();
-    expect(cache.get("b", cfg)).toBe("value-b");
-    expect(cache.get("c", cfg)).toBe("value-c");
-  });
-
-  it("refreshes insertion order on key updates", () => {
-    const cache = new DirectoryCache<string>(60_000, 2);
-    cache.set("a", "value-a", cfg);
-    cache.set("b", "value-b", cfg);
-    cache.set("a", "value-a2", cfg);
-    cache.set("c", "value-c", cfg);
-
-    // Updating "a" should keep it and evict older "b".
-    expect(cache.get("a", cfg)).toBe("value-a2");
-    expect(cache.get("b", cfg)).toBeUndefined();
-    expect(cache.get("c", cfg)).toBe("value-c");
-  });
-});
diff --git a/src/infra/outbound/envelope.test.ts b/src/infra/outbound/envelope.test.ts
deleted file mode 100644
index 71effdee808..00000000000
--- a/src/infra/outbound/envelope.test.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OutboundDeliveryJson } from "./format.js";
-import { buildOutboundResultEnvelope } from "./envelope.js";
-
-describe("buildOutboundResultEnvelope", () => {
-  it("flattens delivery-only payloads by default", () => {
-    const delivery: OutboundDeliveryJson = {
-      provider: "whatsapp",
-      via: "gateway",
-      to: "+1",
-      messageId: "m1",
-      mediaUrl: null,
-    };
-    expect(buildOutboundResultEnvelope({ delivery })).toEqual(delivery);
-  });
-
-  it("keeps payloads and meta in the envelope", () => {
-    const envelope = buildOutboundResultEnvelope({
-      payloads: [{ text: "hi", mediaUrl: null, mediaUrls: undefined }],
-      meta: { foo: "bar" },
-    });
-    expect(envelope).toEqual({
-      payloads: [{ text: "hi", mediaUrl: null, mediaUrls: undefined }],
-      meta: { foo: "bar" },
-    });
-  });
-
-  it("includes delivery when payloads are present", () => {
-    const delivery: OutboundDeliveryJson = {
-      provider: "telegram",
-      via: "direct",
-      to: "123",
-      messageId: "m2",
-      mediaUrl: null,
-      chatId: "c1",
-    };
-    const envelope = buildOutboundResultEnvelope({
-      payloads: [],
-      delivery,
-      meta: { ok: true },
-    });
-    expect(envelope).toEqual({
-      payloads: [],
-      meta: { ok: true },
-      delivery,
-    });
-  });
-
-  it("can keep delivery wrapped when requested", () => {
-    const delivery: OutboundDeliveryJson = {
-      provider: "discord",
-      via: "gateway",
-      to: "channel:C1",
-      messageId: "m3",
-      mediaUrl: null,
-      channelId: "C1",
-    };
-    const envelope = buildOutboundResultEnvelope({
-      delivery,
-      flattenDelivery: false,
-    });
-    expect(envelope).toEqual({ delivery });
-  });
-});
diff --git a/src/infra/outbound/format.test.ts b/src/infra/outbound/format.test.ts
deleted file mode 100644
index 950bb3e5fd1..00000000000
--- a/src/infra/outbound/format.test.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildOutboundDeliveryJson,
-  formatGatewaySummary,
-  formatOutboundDeliverySummary,
-} from "./format.js";
-
-describe("formatOutboundDeliverySummary", () => {
-  it("falls back when result is missing", () => {
-    expect(formatOutboundDeliverySummary("telegram")).toBe(
-      "✅ Sent via Telegram. Message ID: unknown",
-    );
-    expect(formatOutboundDeliverySummary("imessage")).toBe(
-      "✅ Sent via iMessage. Message ID: unknown",
-    );
-  });
-
-  it("adds chat or channel details", () => {
-    expect(
-      formatOutboundDeliverySummary("telegram", {
-        channel: "telegram",
-        messageId: "m1",
-        chatId: "c1",
-      }),
-    ).toBe("✅ Sent via Telegram. Message ID: m1 (chat c1)");
-
-    expect(
-      formatOutboundDeliverySummary("discord", {
-        channel: "discord",
-        messageId: "d1",
-        channelId: "chan",
-      }),
-    ).toBe("✅ Sent via Discord. Message ID: d1 (channel chan)");
-  });
-});
-
-describe("buildOutboundDeliveryJson", () => {
-  it("builds direct delivery payloads", () => {
-    expect(
-      buildOutboundDeliveryJson({
-        channel: "telegram",
-        to: "123",
-        result: { channel: "telegram", messageId: "m1", chatId: "c1" },
-        mediaUrl: "https://example.com/a.png",
-      }),
-    ).toEqual({
-      channel: "telegram",
-      via: "direct",
-      to: "123",
-      messageId: "m1",
-      mediaUrl: "https://example.com/a.png",
-      chatId: "c1",
-    });
-  });
-
-  it("supports whatsapp metadata when present", () => {
-    expect(
-      buildOutboundDeliveryJson({
-        channel: "whatsapp",
-        to: "+1",
-        result: { channel: "whatsapp", messageId: "w1", toJid: "jid" },
-      }),
-    ).toEqual({
-      channel: "whatsapp",
-      via: "direct",
-      to: "+1",
-      messageId: "w1",
-      mediaUrl: null,
-      toJid: "jid",
-    });
-  });
-
-  it("keeps timestamp for signal", () => {
-    expect(
-      buildOutboundDeliveryJson({
-        channel: "signal",
-        to: "+1",
-        result: { channel: "signal", messageId: "s1", timestamp: 123 },
-      }),
-    ).toEqual({
-      channel: "signal",
-      via: "direct",
-      to: "+1",
-      messageId: "s1",
-      mediaUrl: null,
-      timestamp: 123,
-    });
-  });
-});
-
-describe("formatGatewaySummary", () => {
-  it("formats gateway summaries with channel", () => {
-    expect(formatGatewaySummary({ channel: "whatsapp", messageId: "m1" })).toBe(
-      "✅ Sent via gateway (whatsapp). Message ID: m1",
-    );
-  });
-
-  it("supports custom actions", () => {
-    expect(
-      formatGatewaySummary({
-        action: "Poll sent",
-        channel: "discord",
-        messageId: "p1",
-      }),
-    ).toBe("✅ Poll sent via gateway (discord). Message ID: p1");
-  });
-});
diff --git a/src/infra/outbound/message-action-params.ts b/src/infra/outbound/message-action-params.ts
index a0c2c835052..20376b2ed6a 100644
--- a/src/infra/outbound/message-action-params.ts
+++ b/src/infra/outbound/message-action-params.ts
@@ -272,6 +272,42 @@ export async function normalizeSandboxMediaList(params: {
   return normalized;
 }
 
+async function hydrateAttachmentActionPayload(params: {
+  cfg: OpenClawConfig;
+  channel: ChannelId;
+  accountId?: string | null;
+  args: Record<string, unknown>;
+  dryRun?: boolean;
+  /** If caption is missing, copy message -> caption. */
+  allowMessageCaptionFallback?: boolean;
+}): Promise<void> {
+  const mediaHint = readStringParam(params.args, "media", { trim: false });
+  const fileHint =
+    readStringParam(params.args, "path", { trim: false }) ??
+    readStringParam(params.args, "filePath", { trim: false });
+  const contentTypeParam =
+    readStringParam(params.args, "contentType") ?? readStringParam(params.args, "mimeType");
+
+  if (params.allowMessageCaptionFallback) {
+    const caption = readStringParam(params.args, "caption", { allowEmpty: true })?.trim();
+    const message = readStringParam(params.args, "message", { allowEmpty: true })?.trim();
+    if (!caption && message) {
+      params.args.caption = message;
+    }
+  }
+
+  await hydrateAttachmentPayload({
+    cfg: params.cfg,
+    channel: params.channel,
+    accountId: params.accountId,
+    args: params.args,
+    dryRun: params.dryRun,
+    contentTypeParam,
+    mediaHint,
+    fileHint,
+  });
+}
+
 export async function hydrateSetGroupIconParams(params: {
   cfg: OpenClawConfig;
   channel: ChannelId;
@@ -283,23 +319,7 @@ export async function hydrateSetGroupIconParams(params: {
   if (params.action !== "setGroupIcon") {
     return;
   }
-
-  const mediaHint = readStringParam(params.args, "media", { trim: false });
-  const fileHint =
-    readStringParam(params.args, "path", { trim: false }) ??
-    readStringParam(params.args, "filePath", { trim: false });
-  const contentTypeParam =
-    readStringParam(params.args, "contentType") ?? readStringParam(params.args, "mimeType");
-  await hydrateAttachmentPayload({
-    cfg: params.cfg,
-    channel: params.channel,
-    accountId: params.accountId,
-    args: params.args,
-    dryRun: params.dryRun,
-    contentTypeParam,
-    mediaHint,
-    fileHint,
-  });
+  await hydrateAttachmentActionPayload(params);
 }
 
 export async function hydrateSendAttachmentParams(params: {
@@ -313,28 +333,7 @@ export async function hydrateSendAttachmentParams(params: {
   if (params.action !== "sendAttachment") {
     return;
   }
-
-  const mediaHint = readStringParam(params.args, "media", { trim: false });
-  const fileHint =
-    readStringParam(params.args, "path", { trim: false }) ??
-    readStringParam(params.args, "filePath", { trim: false });
-  const contentTypeParam =
-    readStringParam(params.args, "contentType") ?? readStringParam(params.args, "mimeType");
-  const caption = readStringParam(params.args, "caption", { allowEmpty: true })?.trim();
-  const message = readStringParam(params.args, "message", { allowEmpty: true })?.trim();
-  if (!caption && message) {
-    params.args.caption = message;
-  }
-  await hydrateAttachmentPayload({
-    cfg: params.cfg,
-    channel: params.channel,
-    accountId: params.accountId,
-    args: params.args,
-    dryRun: params.dryRun,
-    contentTypeParam,
-    mediaHint,
-    fileHint,
-  });
+  await hydrateAttachmentActionPayload({ ...params, allowMessageCaptionFallback: true });
 }
 
 export function parseButtonsParam(params: Record<string, unknown>): void {
diff --git a/src/infra/outbound/message-action-runner.threading.test.ts b/src/infra/outbound/message-action-runner.threading.test.ts
index c1b0122ec81..bc4d68c2d9b 100644
--- a/src/infra/outbound/message-action-runner.threading.test.ts
+++ b/src/infra/outbound/message-action-runner.threading.test.ts
@@ -102,6 +102,7 @@ describe("runMessageAction threading auto-injection", () => {
     });
 
     const call = mocks.executeSendAction.mock.calls[0]?.[0];
+    expect(call?.ctx?.agentId).toBe("main");
     expect(call?.ctx?.mirror?.sessionKey).toBe("agent:main:slack:channel:c123:thread:111.222");
   });
 
diff --git a/src/infra/outbound/message-action-runner.ts b/src/infra/outbound/message-action-runner.ts
index f9abe97fedc..412ba5c37ba 100644
--- a/src/infra/outbound/message-action-runner.ts
+++ b/src/infra/outbound/message-action-runner.ts
@@ -161,21 +161,21 @@ function applyCrossContextMessageDecoration({
   params,
   message,
   decoration,
-  preferEmbeds,
+  preferComponents,
 }: {
   params: Record<string, unknown>;
   message: string;
   decoration: CrossContextDecoration;
-  preferEmbeds: boolean;
+  preferComponents: boolean;
 }): string {
   const applied = applyCrossContextDecoration({
     message,
     decoration,
-    preferEmbeds,
+    preferComponents,
   });
   params.message = applied.message;
-  if (applied.embeds?.length) {
-    params.embeds = applied.embeds;
+  if (applied.componentsBuilder) {
+    params.components = applied.componentsBuilder;
   }
   return applied.message;
 }
@@ -189,7 +189,7 @@ async function maybeApplyCrossContextMarker(params: {
   accountId?: string | null;
   args: Record<string, unknown>;
   message: string;
-  preferEmbeds: boolean;
+  preferComponents: boolean;
 }): Promise<string> {
   if (!shouldApplyCrossContextMarker(params.action) || !params.toolContext) {
     return params.message;
@@ -208,7 +208,7 @@ async function maybeApplyCrossContextMarker(params: {
     params: params.args,
     message: params.message,
     decoration,
-    preferEmbeds: params.preferEmbeds,
+    preferComponents: params.preferComponents,
   });
 }
 
@@ -395,10 +395,11 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
     readStringParam(params, "path", { trim: false }) ??
     readStringParam(params, "filePath", { trim: false });
   const hasCard = params.card != null && typeof params.card === "object";
+  const hasComponents = params.components != null && typeof params.components === "object";
   const caption = readStringParam(params, "caption", { allowEmpty: true }) ?? "";
   let message =
     readStringParam(params, "message", {
-      required: !mediaHint && !hasCard,
+      required: !mediaHint && !hasCard && !hasComponents,
       allowEmpty: true,
     }) ?? "";
   if (message.includes("\\n")) {
@@ -454,7 +455,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
     accountId,
     args: params,
     message,
-    preferEmbeds: true,
+    preferComponents: true,
   });
 
   const mediaUrl = readStringParam(params, "media", { trim: false });
@@ -464,7 +465,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
       message = "";
     }
   }
-  if (!message.trim() && !mediaUrl && mergedMediaUrls.length === 0 && !hasCard) {
+  if (!message.trim() && !mediaUrl && mergedMediaUrls.length === 0 && !hasCard && !hasComponents) {
     throw new Error("send requires text or media");
   }
   params.message = message;
@@ -501,6 +502,12 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
       route: outboundRoute,
     });
   }
+  if (outboundRoute && !dryRun) {
+    params.__sessionKey = outboundRoute.sessionKey;
+  }
+  if (agentId) {
+    params.__agentId = agentId;
+  }
   const mirrorMediaUrls =
     mergedMediaUrls.length > 0 ? mergedMediaUrls : mediaUrl ? [mediaUrl] : undefined;
   throwIfAborted(abortSignal);
@@ -509,6 +516,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
       cfg,
       channel,
       params,
+      agentId,
       accountId: accountId ?? undefined,
       gateway,
       toolContext: input.toolContext,
@@ -601,7 +609,7 @@ async function handlePollAction(ctx: ResolvedActionContext): Promise<MessageActi
     accountId,
     args: params,
     message: base,
-    preferEmbeds: true,
+    preferComponents: false,
   });
 
   const poll = await executePollAction({
diff --git a/src/infra/outbound/message.test.ts b/src/infra/outbound/message.test.ts
new file mode 100644
index 00000000000..44be8770ca5
--- /dev/null
+++ b/src/infra/outbound/message.test.ts
@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getChannelPlugin: vi.fn(),
+  resolveOutboundTarget: vi.fn(),
+  deliverOutboundPayloads: vi.fn(),
+}));
+
+vi.mock("../../channels/plugins/index.js", () => ({
+  normalizeChannelId: (channel?: string) => channel?.trim().toLowerCase() ?? undefined,
+  getChannelPlugin: mocks.getChannelPlugin,
+}));
+
+vi.mock("./targets.js", () => ({
+  resolveOutboundTarget: mocks.resolveOutboundTarget,
+}));
+
+vi.mock("./deliver.js", () => ({
+  deliverOutboundPayloads: mocks.deliverOutboundPayloads,
+}));
+
+import { sendMessage } from "./message.js";
+
+describe("sendMessage", () => {
+  beforeEach(() => {
+    mocks.getChannelPlugin.mockReset();
+    mocks.resolveOutboundTarget.mockReset();
+    mocks.deliverOutboundPayloads.mockReset();
+
+    mocks.getChannelPlugin.mockReturnValue({
+      outbound: { deliveryMode: "direct" },
+    });
+    mocks.resolveOutboundTarget.mockImplementation(({ to }: { to: string }) => ({ ok: true, to }));
+    mocks.deliverOutboundPayloads.mockResolvedValue([{ channel: "mattermost", messageId: "m1" }]);
+  });
+
+  it("passes explicit agentId to outbound delivery for scoped media roots", async () => {
+    await sendMessage({
+      cfg: {},
+      channel: "mattermost",
+      to: "channel:town-square",
+      content: "hi",
+      agentId: "work",
+    });
+
+    expect(mocks.deliverOutboundPayloads).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentId: "work",
+        channel: "mattermost",
+        to: "channel:town-square",
+      }),
+    );
+  });
+});
diff --git a/src/infra/outbound/message.ts b/src/infra/outbound/message.ts
index 93d105a331f..bf013f7a15b 100644
--- a/src/infra/outbound/message.ts
+++ b/src/infra/outbound/message.ts
@@ -31,6 +31,8 @@ export type MessageGatewayOptions = {
 type MessageSendParams = {
   to: string;
   content: string;
+  /** Active agent id for per-agent outbound media root scoping. */
+  agentId?: string;
   channel?: string;
   mediaUrl?: string;
   mediaUrls?: string[];
@@ -122,6 +124,24 @@ function resolveGatewayOptions(opts?: MessageGatewayOptions) {
   };
 }
 
+async function callMessageGateway<T>(params: {
+  gateway?: MessageGatewayOptions;
+  method: string;
+  params: Record<string, unknown>;
+}): Promise<T> {
+  const gateway = resolveGatewayOptions(params.gateway);
+  return await callGateway<T>({
+    url: gateway.url,
+    token: gateway.token,
+    method: params.method,
+    params: params.params,
+    timeoutMs: gateway.timeoutMs,
+    clientName: gateway.clientName,
+    clientDisplayName: gateway.clientDisplayName,
+    mode: gateway.mode,
+  });
+}
+
 export async function sendMessage(params: MessageSendParams): Promise<MessageSendResult> {
   const cfg = params.cfg ?? loadConfig();
   const channel = params.channel?.trim()
@@ -179,6 +199,7 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
       cfg,
       channel: outboundChannel,
       to: resolvedTarget.to,
+      agentId: params.agentId,
       accountId: params.accountId,
       payloads: normalizedPayloads,
       replyToId: params.replyToId,
@@ -207,10 +228,8 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
     };
   }
 
-  const gateway = resolveGatewayOptions(params.gateway);
-  const result = await callGateway<{ messageId: string }>({
-    url: gateway.url,
-    token: gateway.token,
+  const result = await callMessageGateway<{ messageId: string }>({
+    gateway: params.gateway,
     method: "send",
     params: {
       to: params.to,
@@ -223,10 +242,6 @@ export async function sendMessage(params: MessageSendParams): Promise<MessageSen
       sessionKey: params.mirror?.sessionKey,
       idempotencyKey: params.idempotencyKey ?? randomIdempotencyKey(),
     },
-    timeoutMs: gateway.timeoutMs,
-    clientName: gateway.clientName,
-    clientDisplayName: gateway.clientDisplayName,
-    mode: gateway.mode,
   });
 
   return {
@@ -278,16 +293,14 @@ export async function sendPoll(params: MessagePollParams): Promise<MessagePollRe
     };
   }
 
-  const gateway = resolveGatewayOptions(params.gateway);
-  const result = await callGateway<{
+  const result = await callMessageGateway<{
     messageId: string;
     toJid?: string;
     channelId?: string;
     conversationId?: string;
     pollId?: string;
   }>({
-    url: gateway.url,
-    token: gateway.token,
+    gateway: params.gateway,
     method: "poll",
     params: {
       to: params.to,
@@ -303,10 +316,6 @@ export async function sendPoll(params: MessagePollParams): Promise<MessagePollRe
       accountId: params.accountId,
       idempotencyKey: params.idempotencyKey ?? randomIdempotencyKey(),
     },
-    timeoutMs: gateway.timeoutMs,
-    clientName: gateway.clientName,
-    clientDisplayName: gateway.clientDisplayName,
-    mode: gateway.mode,
   });
 
   return {
diff --git a/src/infra/outbound/outbound-policy.test.ts b/src/infra/outbound/outbound-policy.test.ts
deleted file mode 100644
index 8cac1f8c391..00000000000
--- a/src/infra/outbound/outbound-policy.test.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import {
-  applyCrossContextDecoration,
-  buildCrossContextDecoration,
-  enforceCrossContextPolicy,
-} from "./outbound-policy.js";
-
-const slackConfig = {
-  channels: {
-    slack: {
-      botToken: "xoxb-test",
-      appToken: "xapp-test",
-    },
-  },
-} as OpenClawConfig;
-
-const discordConfig = {
-  channels: {
-    discord: {},
-  },
-} as OpenClawConfig;
-
-describe("outbound policy", () => {
-  it("blocks cross-provider sends by default", () => {
-    expect(() =>
-      enforceCrossContextPolicy({
-        cfg: slackConfig,
-        channel: "telegram",
-        action: "send",
-        args: { to: "telegram:@ops" },
-        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
-      }),
-    ).toThrow(/Cross-context messaging denied/);
-  });
-
-  it("allows cross-provider sends when enabled", () => {
-    const cfg = {
-      ...slackConfig,
-      tools: {
-        message: { crossContext: { allowAcrossProviders: true } },
-      },
-    } as OpenClawConfig;
-
-    expect(() =>
-      enforceCrossContextPolicy({
-        cfg,
-        channel: "telegram",
-        action: "send",
-        args: { to: "telegram:@ops" },
-        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
-      }),
-    ).not.toThrow();
-  });
-
-  it("blocks same-provider cross-context when disabled", () => {
-    const cfg = {
-      ...slackConfig,
-      tools: { message: { crossContext: { allowWithinProvider: false } } },
-    } as OpenClawConfig;
-
-    expect(() =>
-      enforceCrossContextPolicy({
-        cfg,
-        channel: "slack",
-        action: "send",
-        args: { to: "C99999999" },
-        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
-      }),
-    ).toThrow(/Cross-context messaging denied/);
-  });
-
-  it("uses embeds when available and preferred", async () => {
-    const decoration = await buildCrossContextDecoration({
-      cfg: discordConfig,
-      channel: "discord",
-      target: "123",
-      toolContext: { currentChannelId: "C12345678", currentChannelProvider: "discord" },
-    });
-
-    expect(decoration).not.toBeNull();
-    const applied = applyCrossContextDecoration({
-      message: "hello",
-      decoration: decoration!,
-      preferEmbeds: true,
-    });
-
-    expect(applied.usedEmbeds).toBe(true);
-    expect(applied.embeds?.length).toBeGreaterThan(0);
-    expect(applied.message).toBe("hello");
-  });
-});
diff --git a/src/infra/outbound/outbound-policy.ts b/src/infra/outbound/outbound-policy.ts
index 809c523dcf5..c24ae135b24 100644
--- a/src/infra/outbound/outbound-policy.ts
+++ b/src/infra/outbound/outbound-policy.ts
@@ -4,14 +4,17 @@ import type {
   ChannelThreadingToolContext,
 } from "../../channels/plugins/types.js";
 import type { OpenClawConfig } from "../../config/config.js";
-import { getChannelMessageAdapter } from "./channel-adapters.js";
+import {
+  getChannelMessageAdapter,
+  type CrossContextComponentsBuilder,
+} from "./channel-adapters.js";
 import { normalizeTargetForProvider } from "./target-normalization.js";
 import { formatTargetDisplay, lookupDirectoryDisplay } from "./target-resolver.js";
 
 export type CrossContextDecoration = {
   prefix: string;
   suffix: string;
-  embeds?: unknown[];
+  componentsBuilder?: CrossContextComponentsBuilder;
 };
 
 const CONTEXT_GUARDED_ACTIONS = new Set<ChannelMessageActionName>([
@@ -177,11 +180,19 @@ export async function buildCrossContextDecoration(params: {
   const suffix = suffixTemplate.replaceAll("{channel}", originLabel);
 
   const adapter = getChannelMessageAdapter(params.channel);
-  const embeds = adapter.supportsEmbeds
-    ? (adapter.buildCrossContextEmbeds?.(originLabel) ?? undefined)
+  const componentsBuilder = adapter.supportsComponentsV2
+    ? adapter.buildCrossContextComponents
+      ? (message: string) =>
+          adapter.buildCrossContextComponents!({
+            originLabel,
+            message,
+            cfg: params.cfg,
+            accountId: params.accountId ?? undefined,
+          })
+      : undefined
     : undefined;
 
-  return { prefix, suffix, embeds };
+  return { prefix, suffix, componentsBuilder };
 }
 
 export function shouldApplyCrossContextMarker(action: ChannelMessageActionName): boolean {
@@ -191,12 +202,20 @@ export function shouldApplyCrossContextMarker(action: ChannelMessageActionName):
 export function applyCrossContextDecoration(params: {
   message: string;
   decoration: CrossContextDecoration;
-  preferEmbeds: boolean;
-}): { message: string; embeds?: unknown[]; usedEmbeds: boolean } {
-  const useEmbeds = params.preferEmbeds && params.decoration.embeds?.length;
-  if (useEmbeds) {
-    return { message: params.message, embeds: params.decoration.embeds, usedEmbeds: true };
+  preferComponents: boolean;
+}): {
+  message: string;
+  componentsBuilder?: CrossContextComponentsBuilder;
+  usedComponents: boolean;
+} {
+  const useComponents = params.preferComponents && params.decoration.componentsBuilder;
+  if (useComponents) {
+    return {
+      message: params.message,
+      componentsBuilder: params.decoration.componentsBuilder,
+      usedComponents: true,
+    };
   }
   const message = `${params.decoration.prefix}${params.message}${params.decoration.suffix}`;
-  return { message, usedEmbeds: false };
+  return { message, usedComponents: false };
 }
diff --git a/src/infra/outbound/outbound-send-service.test.ts b/src/infra/outbound/outbound-send-service.test.ts
new file mode 100644
index 00000000000..b8b44410c4d
--- /dev/null
+++ b/src/infra/outbound/outbound-send-service.test.ts
@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  dispatchChannelMessageAction: vi.fn(),
+  sendMessage: vi.fn(),
+}));
+
+vi.mock("../../channels/plugins/message-actions.js", () => ({
+  dispatchChannelMessageAction: (...args: unknown[]) => mocks.dispatchChannelMessageAction(...args),
+}));
+
+vi.mock("./message.js", () => ({
+  sendMessage: (...args: unknown[]) => mocks.sendMessage(...args),
+  sendPoll: vi.fn(),
+}));
+
+import { executeSendAction } from "./outbound-send-service.js";
+
+describe("executeSendAction", () => {
+  beforeEach(() => {
+    mocks.dispatchChannelMessageAction.mockReset();
+    mocks.sendMessage.mockReset();
+  });
+
+  it("forwards ctx.agentId to sendMessage on core outbound path", async () => {
+    mocks.dispatchChannelMessageAction.mockResolvedValue(null);
+    mocks.sendMessage.mockResolvedValue({
+      channel: "discord",
+      to: "channel:123",
+      via: "direct",
+      mediaUrl: null,
+    });
+
+    await executeSendAction({
+      ctx: {
+        cfg: {},
+        channel: "discord",
+        params: {},
+        agentId: "work",
+        dryRun: false,
+      },
+      to: "channel:123",
+      message: "hello",
+    });
+
+    expect(mocks.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentId: "work",
+        channel: "discord",
+        to: "channel:123",
+        content: "hello",
+      }),
+    );
+  });
+});
diff --git a/src/infra/outbound/outbound-send-service.ts b/src/infra/outbound/outbound-send-service.ts
index e2e96986a44..88eda04d87e 100644
--- a/src/infra/outbound/outbound-send-service.ts
+++ b/src/infra/outbound/outbound-send-service.ts
@@ -23,6 +23,8 @@ export type OutboundSendContext = {
   cfg: OpenClawConfig;
   channel: ChannelId;
   params: Record<string, unknown>;
+  /** Active agent id for per-agent outbound media root scoping. */
+  agentId?: string;
   accountId?: string | null;
   gateway?: OutboundGatewayContext;
   toolContext?: ChannelThreadingToolContext;
@@ -93,6 +95,7 @@ export async function executeSendAction(params: {
     cfg: params.ctx.cfg,
     to: params.to,
     content: params.message,
+    agentId: params.ctx.agentId,
     mediaUrl: params.mediaUrl || undefined,
     mediaUrls: params.mediaUrls,
     channel: params.ctx.channel || undefined,
diff --git a/src/infra/outbound/outbound-session.test.ts b/src/infra/outbound/outbound-session.test.ts
deleted file mode 100644
index 48da825a5f3..00000000000
--- a/src/infra/outbound/outbound-session.test.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { resolveOutboundSessionRoute } from "./outbound-session.js";
-
-const baseConfig = {} as OpenClawConfig;
-
-describe("resolveOutboundSessionRoute", () => {
-  it("builds Slack thread session keys", async () => {
-    const route = await resolveOutboundSessionRoute({
-      cfg: baseConfig,
-      channel: "slack",
-      agentId: "main",
-      target: "channel:C123",
-      replyToId: "456",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:slack:channel:c123:thread:456");
-    expect(route?.from).toBe("slack:channel:C123");
-    expect(route?.to).toBe("channel:C123");
-    expect(route?.threadId).toBe("456");
-  });
-
-  it("uses Telegram topic ids in group session keys", async () => {
-    const route = await resolveOutboundSessionRoute({
-      cfg: baseConfig,
-      channel: "telegram",
-      agentId: "main",
-      target: "-100123456:topic:42",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:telegram:group:-100123456:topic:42");
-    expect(route?.from).toBe("telegram:group:-100123456:topic:42");
-    expect(route?.to).toBe("telegram:-100123456");
-    expect(route?.threadId).toBe(42);
-  });
-
-  it("treats Telegram usernames as DMs when unresolved", async () => {
-    const cfg = { session: { dmScope: "per-channel-peer" } } as OpenClawConfig;
-    const route = await resolveOutboundSessionRoute({
-      cfg,
-      channel: "telegram",
-      agentId: "main",
-      target: "@alice",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:telegram:direct:@alice");
-    expect(route?.chatType).toBe("direct");
-  });
-
-  it("honors dmScope identity links", async () => {
-    const cfg = {
-      session: {
-        dmScope: "per-peer",
-        identityLinks: {
-          alice: ["discord:123"],
-        },
-      },
-    } as OpenClawConfig;
-
-    const route = await resolveOutboundSessionRoute({
-      cfg,
-      channel: "discord",
-      agentId: "main",
-      target: "user:123",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:direct:alice");
-  });
-
-  it("strips chat_* prefixes for BlueBubbles group session keys", async () => {
-    const route = await resolveOutboundSessionRoute({
-      cfg: baseConfig,
-      channel: "bluebubbles",
-      agentId: "main",
-      target: "chat_guid:ABC123",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:bluebubbles:group:abc123");
-    expect(route?.from).toBe("group:ABC123");
-  });
-
-  it("treats Zalo Personal DM targets as direct sessions", async () => {
-    const cfg = { session: { dmScope: "per-channel-peer" } } as OpenClawConfig;
-    const route = await resolveOutboundSessionRoute({
-      cfg,
-      channel: "zalouser",
-      agentId: "main",
-      target: "123456",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:zalouser:direct:123456");
-    expect(route?.chatType).toBe("direct");
-  });
-
-  it("uses group session keys for Slack mpim allowlist entries", async () => {
-    const cfg = {
-      channels: {
-        slack: {
-          dm: {
-            groupChannels: ["G123"],
-          },
-        },
-      },
-    } as OpenClawConfig;
-
-    const route = await resolveOutboundSessionRoute({
-      cfg,
-      channel: "slack",
-      agentId: "main",
-      target: "channel:G123",
-    });
-
-    expect(route?.sessionKey).toBe("agent:main:slack:group:g123");
-    expect(route?.from).toBe("slack:group:G123");
-  });
-});
diff --git a/src/infra/outbound/outbound.test.ts b/src/infra/outbound/outbound.test.ts
new file mode 100644
index 00000000000..797d2486ba5
--- /dev/null
+++ b/src/infra/outbound/outbound.test.ts
@@ -0,0 +1,1084 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { OutboundDeliveryJson } from "./format.js";
+import { telegramPlugin } from "../../../extensions/telegram/src/channel.js";
+import { whatsappPlugin } from "../../../extensions/whatsapp/src/channel.js";
+import { setActivePluginRegistry } from "../../plugins/runtime.js";
+import { createTestRegistry } from "../../test-utils/channel-plugins.js";
+import {
+  ackDelivery,
+  computeBackoffMs,
+  enqueueDelivery,
+  failDelivery,
+  loadPendingDeliveries,
+  MAX_RETRIES,
+  moveToFailed,
+  recoverPendingDeliveries,
+} from "./delivery-queue.js";
+import { DirectoryCache } from "./directory-cache.js";
+import { buildOutboundResultEnvelope } from "./envelope.js";
+import {
+  buildOutboundDeliveryJson,
+  formatGatewaySummary,
+  formatOutboundDeliverySummary,
+} from "./format.js";
+import {
+  applyCrossContextDecoration,
+  buildCrossContextDecoration,
+  enforceCrossContextPolicy,
+} from "./outbound-policy.js";
+import { resolveOutboundSessionRoute } from "./outbound-session.js";
+import {
+  formatOutboundPayloadLog,
+  normalizeOutboundPayloads,
+  normalizeOutboundPayloadsForJson,
+} from "./payloads.js";
+import { resolveOutboundTarget, resolveSessionDeliveryTarget } from "./targets.js";
+
+describe("delivery-queue", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-dq-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("enqueue + ack lifecycle", () => {
+    it("creates and removes a queue entry", async () => {
+      const id = await enqueueDelivery(
+        {
+          channel: "whatsapp",
+          to: "+1555",
+          payloads: [{ text: "hello" }],
+          bestEffort: true,
+          gifPlayback: true,
+          silent: true,
+          mirror: {
+            sessionKey: "agent:main:main",
+            text: "hello",
+            mediaUrls: ["https://example.com/file.png"],
+          },
+        },
+        tmpDir,
+      );
+
+      // Entry file exists after enqueue.
+      const queueDir = path.join(tmpDir, "delivery-queue");
+      const files = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json"));
+      expect(files).toHaveLength(1);
+      expect(files[0]).toBe(`${id}.json`);
+
+      // Entry contents are correct.
+      const entry = JSON.parse(fs.readFileSync(path.join(queueDir, files[0]), "utf-8"));
+      expect(entry).toMatchObject({
+        id,
+        channel: "whatsapp",
+        to: "+1555",
+        bestEffort: true,
+        gifPlayback: true,
+        silent: true,
+        mirror: {
+          sessionKey: "agent:main:main",
+          text: "hello",
+          mediaUrls: ["https://example.com/file.png"],
+        },
+        retryCount: 0,
+      });
+      expect(entry.payloads).toEqual([{ text: "hello" }]);
+
+      // Ack removes the file.
+      await ackDelivery(id, tmpDir);
+      const remaining = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json"));
+      expect(remaining).toHaveLength(0);
+    });
+
+    it("ack is idempotent (no error on missing file)", async () => {
+      await expect(ackDelivery("nonexistent-id", tmpDir)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("failDelivery", () => {
+    it("increments retryCount and sets lastError", async () => {
+      const id = await enqueueDelivery(
+        {
+          channel: "telegram",
+          to: "123",
+          payloads: [{ text: "test" }],
+        },
+        tmpDir,
+      );
+
+      await failDelivery(id, "connection refused", tmpDir);
+
+      const queueDir = path.join(tmpDir, "delivery-queue");
+      const entry = JSON.parse(fs.readFileSync(path.join(queueDir, `${id}.json`), "utf-8"));
+      expect(entry.retryCount).toBe(1);
+      expect(entry.lastError).toBe("connection refused");
+    });
+  });
+
+  describe("moveToFailed", () => {
+    it("moves entry to failed/ subdirectory", async () => {
+      const id = await enqueueDelivery(
+        {
+          channel: "slack",
+          to: "#general",
+          payloads: [{ text: "hi" }],
+        },
+        tmpDir,
+      );
+
+      await moveToFailed(id, tmpDir);
+
+      const queueDir = path.join(tmpDir, "delivery-queue");
+      const failedDir = path.join(queueDir, "failed");
+      expect(fs.existsSync(path.join(queueDir, `${id}.json`))).toBe(false);
+      expect(fs.existsSync(path.join(failedDir, `${id}.json`))).toBe(true);
+    });
+  });
+
+  describe("loadPendingDeliveries", () => {
+    it("returns empty array when queue directory does not exist", async () => {
+      const nonexistent = path.join(tmpDir, "no-such-dir");
+      const entries = await loadPendingDeliveries(nonexistent);
+      expect(entries).toEqual([]);
+    });
+
+    it("loads multiple entries", async () => {
+      await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
+      await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
+
+      const entries = await loadPendingDeliveries(tmpDir);
+      expect(entries).toHaveLength(2);
+    });
+  });
+
+  describe("computeBackoffMs", () => {
+    it("returns 0 for retryCount 0", () => {
+      expect(computeBackoffMs(0)).toBe(0);
+    });
+
+    it("returns correct backoff for each retry", () => {
+      expect(computeBackoffMs(1)).toBe(5_000);
+      expect(computeBackoffMs(2)).toBe(25_000);
+      expect(computeBackoffMs(3)).toBe(120_000);
+      expect(computeBackoffMs(4)).toBe(600_000);
+      // Beyond defined schedule -- clamps to last value.
+      expect(computeBackoffMs(5)).toBe(600_000);
+    });
+  });
+
+  describe("recoverPendingDeliveries", () => {
+    const noopDelay = async () => {};
+    const baseCfg = {};
+
+    it("recovers entries from a simulated crash", async () => {
+      // Manually create two queue entries as if gateway crashed before delivery.
+      await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
+      await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
+
+      const deliver = vi.fn().mockResolvedValue([]);
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(deliver).toHaveBeenCalledTimes(2);
+      expect(result.recovered).toBe(2);
+      expect(result.failed).toBe(0);
+      expect(result.skipped).toBe(0);
+
+      // Queue should be empty after recovery.
+      const remaining = await loadPendingDeliveries(tmpDir);
+      expect(remaining).toHaveLength(0);
+    });
+
+    it("moves entries that exceeded max retries to failed/", async () => {
+      // Create an entry and manually set retryCount to MAX_RETRIES.
+      const id = await enqueueDelivery(
+        { channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] },
+        tmpDir,
+      );
+      const filePath = path.join(tmpDir, "delivery-queue", `${id}.json`);
+      const entry = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      entry.retryCount = MAX_RETRIES;
+      fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
+
+      const deliver = vi.fn();
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(deliver).not.toHaveBeenCalled();
+      expect(result.skipped).toBe(1);
+
+      // Entry should be in failed/ directory.
+      const failedDir = path.join(tmpDir, "delivery-queue", "failed");
+      expect(fs.existsSync(path.join(failedDir, `${id}.json`))).toBe(true);
+    });
+
+    it("increments retryCount on failed recovery attempt", async () => {
+      await enqueueDelivery({ channel: "slack", to: "#ch", payloads: [{ text: "x" }] }, tmpDir);
+
+      const deliver = vi.fn().mockRejectedValue(new Error("network down"));
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(result.failed).toBe(1);
+      expect(result.recovered).toBe(0);
+
+      // Entry should still be in queue with incremented retryCount.
+      const entries = await loadPendingDeliveries(tmpDir);
+      expect(entries).toHaveLength(1);
+      expect(entries[0].retryCount).toBe(1);
+      expect(entries[0].lastError).toBe("network down");
+    });
+
+    it("passes skipQueue: true to prevent re-enqueueing during recovery", async () => {
+      await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
+
+      const deliver = vi.fn().mockResolvedValue([]);
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(deliver).toHaveBeenCalledWith(expect.objectContaining({ skipQueue: true }));
+    });
+
+    it("replays stored delivery options during recovery", async () => {
+      await enqueueDelivery(
+        {
+          channel: "whatsapp",
+          to: "+1",
+          payloads: [{ text: "a" }],
+          bestEffort: true,
+          gifPlayback: true,
+          silent: true,
+          mirror: {
+            sessionKey: "agent:main:main",
+            text: "a",
+            mediaUrls: ["https://example.com/a.png"],
+          },
+        },
+        tmpDir,
+      );
+
+      const deliver = vi.fn().mockResolvedValue([]);
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(deliver).toHaveBeenCalledWith(
+        expect.objectContaining({
+          bestEffort: true,
+          gifPlayback: true,
+          silent: true,
+          mirror: {
+            sessionKey: "agent:main:main",
+            text: "a",
+            mediaUrls: ["https://example.com/a.png"],
+          },
+        }),
+      );
+    });
+
+    it("respects maxRecoveryMs time budget", async () => {
+      await enqueueDelivery({ channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] }, tmpDir);
+      await enqueueDelivery({ channel: "telegram", to: "2", payloads: [{ text: "b" }] }, tmpDir);
+      await enqueueDelivery({ channel: "slack", to: "#c", payloads: [{ text: "c" }] }, tmpDir);
+
+      const deliver = vi.fn().mockResolvedValue([]);
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+        maxRecoveryMs: 0, // Immediate timeout -- no entries should be processed.
+      });
+
+      expect(deliver).not.toHaveBeenCalled();
+      expect(result.recovered).toBe(0);
+      expect(result.failed).toBe(0);
+      expect(result.skipped).toBe(0);
+
+      // All entries should still be in the queue.
+      const remaining = await loadPendingDeliveries(tmpDir);
+      expect(remaining).toHaveLength(3);
+
+      // Should have logged a warning about deferred entries.
+      expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("deferred to next restart"));
+    });
+
+    it("defers entries when backoff exceeds the recovery budget", async () => {
+      const id = await enqueueDelivery(
+        { channel: "whatsapp", to: "+1", payloads: [{ text: "a" }] },
+        tmpDir,
+      );
+      const filePath = path.join(tmpDir, "delivery-queue", `${id}.json`);
+      const entry = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      entry.retryCount = 3;
+      fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
+
+      const deliver = vi.fn().mockResolvedValue([]);
+      const delay = vi.fn(async () => {});
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay,
+        maxRecoveryMs: 1000,
+      });
+
+      expect(deliver).not.toHaveBeenCalled();
+      expect(delay).not.toHaveBeenCalled();
+      expect(result).toEqual({ recovered: 0, failed: 0, skipped: 0 });
+
+      const remaining = await loadPendingDeliveries(tmpDir);
+      expect(remaining).toHaveLength(1);
+
+      expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("deferred to next restart"));
+    });
+
+    it("returns zeros when queue is empty", async () => {
+      const deliver = vi.fn();
+      const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+      const result = await recoverPendingDeliveries({
+        deliver,
+        log,
+        cfg: baseCfg,
+        stateDir: tmpDir,
+        delay: noopDelay,
+      });
+
+      expect(result).toEqual({ recovered: 0, failed: 0, skipped: 0 });
+      expect(deliver).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("DirectoryCache", () => {
+  const cfg = {} as OpenClawConfig;
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("expires entries after ttl", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+    const cache = new DirectoryCache<string>(1000, 10);
+
+    cache.set("a", "value-a", cfg);
+    expect(cache.get("a", cfg)).toBe("value-a");
+
+    vi.setSystemTime(new Date("2026-01-01T00:00:02.000Z"));
+    expect(cache.get("a", cfg)).toBeUndefined();
+  });
+
+  it("evicts oldest keys when max size is exceeded", () => {
+    const cache = new DirectoryCache<string>(60_000, 2);
+    cache.set("a", "value-a", cfg);
+    cache.set("b", "value-b", cfg);
+    cache.set("c", "value-c", cfg);
+
+    expect(cache.get("a", cfg)).toBeUndefined();
+    expect(cache.get("b", cfg)).toBe("value-b");
+    expect(cache.get("c", cfg)).toBe("value-c");
+  });
+
+  it("refreshes insertion order on key updates", () => {
+    const cache = new DirectoryCache<string>(60_000, 2);
+    cache.set("a", "value-a", cfg);
+    cache.set("b", "value-b", cfg);
+    cache.set("a", "value-a2", cfg);
+    cache.set("c", "value-c", cfg);
+
+    // Updating "a" should keep it and evict older "b".
+    expect(cache.get("a", cfg)).toBe("value-a2");
+    expect(cache.get("b", cfg)).toBeUndefined();
+    expect(cache.get("c", cfg)).toBe("value-c");
+  });
+});
+
+describe("buildOutboundResultEnvelope", () => {
+  it("flattens delivery-only payloads by default", () => {
+    const delivery: OutboundDeliveryJson = {
+      provider: "whatsapp",
+      via: "gateway",
+      to: "+1",
+      messageId: "m1",
+      mediaUrl: null,
+    };
+    expect(buildOutboundResultEnvelope({ delivery })).toEqual(delivery);
+  });
+
+  it("keeps payloads and meta in the envelope", () => {
+    const envelope = buildOutboundResultEnvelope({
+      payloads: [{ text: "hi", mediaUrl: null, mediaUrls: undefined }],
+      meta: { foo: "bar" },
+    });
+    expect(envelope).toEqual({
+      payloads: [{ text: "hi", mediaUrl: null, mediaUrls: undefined }],
+      meta: { foo: "bar" },
+    });
+  });
+
+  it("includes delivery when payloads are present", () => {
+    const delivery: OutboundDeliveryJson = {
+      provider: "telegram",
+      via: "direct",
+      to: "123",
+      messageId: "m2",
+      mediaUrl: null,
+      chatId: "c1",
+    };
+    const envelope = buildOutboundResultEnvelope({
+      payloads: [],
+      delivery,
+      meta: { ok: true },
+    });
+    expect(envelope).toEqual({
+      payloads: [],
+      meta: { ok: true },
+      delivery,
+    });
+  });
+
+  it("can keep delivery wrapped when requested", () => {
+    const delivery: OutboundDeliveryJson = {
+      provider: "discord",
+      via: "gateway",
+      to: "channel:C1",
+      messageId: "m3",
+      mediaUrl: null,
+      channelId: "C1",
+    };
+    const envelope = buildOutboundResultEnvelope({
+      delivery,
+      flattenDelivery: false,
+    });
+    expect(envelope).toEqual({ delivery });
+  });
+});
+
+describe("formatOutboundDeliverySummary", () => {
+  it("falls back when result is missing", () => {
+    expect(formatOutboundDeliverySummary("telegram")).toBe(
+      "✅ Sent via Telegram. Message ID: unknown",
+    );
+    expect(formatOutboundDeliverySummary("imessage")).toBe(
+      "✅ Sent via iMessage. Message ID: unknown",
+    );
+  });
+
+  it("adds chat or channel details", () => {
+    expect(
+      formatOutboundDeliverySummary("telegram", {
+        channel: "telegram",
+        messageId: "m1",
+        chatId: "c1",
+      }),
+    ).toBe("✅ Sent via Telegram. Message ID: m1 (chat c1)");
+
+    expect(
+      formatOutboundDeliverySummary("discord", {
+        channel: "discord",
+        messageId: "d1",
+        channelId: "chan",
+      }),
+    ).toBe("✅ Sent via Discord. Message ID: d1 (channel chan)");
+  });
+});
+
+describe("buildOutboundDeliveryJson", () => {
+  it("builds direct delivery payloads", () => {
+    expect(
+      buildOutboundDeliveryJson({
+        channel: "telegram",
+        to: "123",
+        result: { channel: "telegram", messageId: "m1", chatId: "c1" },
+        mediaUrl: "https://example.com/a.png",
+      }),
+    ).toEqual({
+      channel: "telegram",
+      via: "direct",
+      to: "123",
+      messageId: "m1",
+      mediaUrl: "https://example.com/a.png",
+      chatId: "c1",
+    });
+  });
+
+  it("supports whatsapp metadata when present", () => {
+    expect(
+      buildOutboundDeliveryJson({
+        channel: "whatsapp",
+        to: "+1",
+        result: { channel: "whatsapp", messageId: "w1", toJid: "jid" },
+      }),
+    ).toEqual({
+      channel: "whatsapp",
+      via: "direct",
+      to: "+1",
+      messageId: "w1",
+      mediaUrl: null,
+      toJid: "jid",
+    });
+  });
+
+  it("keeps timestamp for signal", () => {
+    expect(
+      buildOutboundDeliveryJson({
+        channel: "signal",
+        to: "+1",
+        result: { channel: "signal", messageId: "s1", timestamp: 123 },
+      }),
+    ).toEqual({
+      channel: "signal",
+      via: "direct",
+      to: "+1",
+      messageId: "s1",
+      mediaUrl: null,
+      timestamp: 123,
+    });
+  });
+});
+
+describe("formatGatewaySummary", () => {
+  it("formats gateway summaries with channel", () => {
+    expect(formatGatewaySummary({ channel: "whatsapp", messageId: "m1" })).toBe(
+      "✅ Sent via gateway (whatsapp). Message ID: m1",
+    );
+  });
+
+  it("supports custom actions", () => {
+    expect(
+      formatGatewaySummary({
+        action: "Poll sent",
+        channel: "discord",
+        messageId: "p1",
+      }),
+    ).toBe("✅ Poll sent via gateway (discord). Message ID: p1");
+  });
+});
+
+const slackConfig = {
+  channels: {
+    slack: {
+      botToken: "xoxb-test",
+      appToken: "xapp-test",
+    },
+  },
+} as OpenClawConfig;
+
+const discordConfig = {
+  channels: {
+    discord: {},
+  },
+} as OpenClawConfig;
+
+describe("outbound policy", () => {
+  it("blocks cross-provider sends by default", () => {
+    expect(() =>
+      enforceCrossContextPolicy({
+        cfg: slackConfig,
+        channel: "telegram",
+        action: "send",
+        args: { to: "telegram:@ops" },
+        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
+      }),
+    ).toThrow(/Cross-context messaging denied/);
+  });
+
+  it("allows cross-provider sends when enabled", () => {
+    const cfg = {
+      ...slackConfig,
+      tools: {
+        message: { crossContext: { allowAcrossProviders: true } },
+      },
+    } as OpenClawConfig;
+
+    expect(() =>
+      enforceCrossContextPolicy({
+        cfg,
+        channel: "telegram",
+        action: "send",
+        args: { to: "telegram:@ops" },
+        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
+      }),
+    ).not.toThrow();
+  });
+
+  it("blocks same-provider cross-context when disabled", () => {
+    const cfg = {
+      ...slackConfig,
+      tools: { message: { crossContext: { allowWithinProvider: false } } },
+    } as OpenClawConfig;
+
+    expect(() =>
+      enforceCrossContextPolicy({
+        cfg,
+        channel: "slack",
+        action: "send",
+        args: { to: "C99999999" },
+        toolContext: { currentChannelId: "C12345678", currentChannelProvider: "slack" },
+      }),
+    ).toThrow(/Cross-context messaging denied/);
+  });
+
+  it("uses components when available and preferred", async () => {
+    const decoration = await buildCrossContextDecoration({
+      cfg: discordConfig,
+      channel: "discord",
+      target: "123",
+      toolContext: { currentChannelId: "C12345678", currentChannelProvider: "discord" },
+    });
+
+    expect(decoration).not.toBeNull();
+    const applied = applyCrossContextDecoration({
+      message: "hello",
+      decoration: decoration!,
+      preferComponents: true,
+    });
+
+    expect(applied.usedComponents).toBe(true);
+    expect(applied.componentsBuilder).toBeDefined();
+    expect(applied.componentsBuilder?.("hello").length).toBeGreaterThan(0);
+    expect(applied.message).toBe("hello");
+  });
+});
+
+describe("resolveOutboundSessionRoute", () => {
+  const baseConfig = {} as OpenClawConfig;
+
+  it("builds Slack thread session keys", async () => {
+    const route = await resolveOutboundSessionRoute({
+      cfg: baseConfig,
+      channel: "slack",
+      agentId: "main",
+      target: "channel:C123",
+      replyToId: "456",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:slack:channel:c123:thread:456");
+    expect(route?.from).toBe("slack:channel:C123");
+    expect(route?.to).toBe("channel:C123");
+    expect(route?.threadId).toBe("456");
+  });
+
+  it("uses Telegram topic ids in group session keys", async () => {
+    const route = await resolveOutboundSessionRoute({
+      cfg: baseConfig,
+      channel: "telegram",
+      agentId: "main",
+      target: "-100123456:topic:42",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:telegram:group:-100123456:topic:42");
+    expect(route?.from).toBe("telegram:group:-100123456:topic:42");
+    expect(route?.to).toBe("telegram:-100123456");
+    expect(route?.threadId).toBe(42);
+  });
+
+  it("treats Telegram usernames as DMs when unresolved", async () => {
+    const cfg = { session: { dmScope: "per-channel-peer" } } as OpenClawConfig;
+    const route = await resolveOutboundSessionRoute({
+      cfg,
+      channel: "telegram",
+      agentId: "main",
+      target: "@alice",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:telegram:direct:@alice");
+    expect(route?.chatType).toBe("direct");
+  });
+
+  it("honors dmScope identity links", async () => {
+    const cfg = {
+      session: {
+        dmScope: "per-peer",
+        identityLinks: {
+          alice: ["discord:123"],
+        },
+      },
+    } as OpenClawConfig;
+
+    const route = await resolveOutboundSessionRoute({
+      cfg,
+      channel: "discord",
+      agentId: "main",
+      target: "user:123",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:direct:alice");
+  });
+
+  it("strips chat_* prefixes for BlueBubbles group session keys", async () => {
+    const route = await resolveOutboundSessionRoute({
+      cfg: baseConfig,
+      channel: "bluebubbles",
+      agentId: "main",
+      target: "chat_guid:ABC123",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:bluebubbles:group:abc123");
+    expect(route?.from).toBe("group:ABC123");
+  });
+
+  it("treats Zalo Personal DM targets as direct sessions", async () => {
+    const cfg = { session: { dmScope: "per-channel-peer" } } as OpenClawConfig;
+    const route = await resolveOutboundSessionRoute({
+      cfg,
+      channel: "zalouser",
+      agentId: "main",
+      target: "123456",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:zalouser:direct:123456");
+    expect(route?.chatType).toBe("direct");
+  });
+
+  it("uses group session keys for Slack mpim allowlist entries", async () => {
+    const cfg = {
+      channels: {
+        slack: {
+          dm: {
+            groupChannels: ["G123"],
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const route = await resolveOutboundSessionRoute({
+      cfg,
+      channel: "slack",
+      agentId: "main",
+      target: "channel:G123",
+    });
+
+    expect(route?.sessionKey).toBe("agent:main:slack:group:g123");
+    expect(route?.from).toBe("slack:group:G123");
+  });
+});
+
+describe("normalizeOutboundPayloadsForJson", () => {
+  it("normalizes payloads with mediaUrl and mediaUrls", () => {
+    expect(
+      normalizeOutboundPayloadsForJson([
+        { text: "hi" },
+        { text: "photo", mediaUrl: "https://x.test/a.jpg" },
+        { text: "multi", mediaUrls: ["https://x.test/1.png"] },
+      ]),
+    ).toEqual([
+      { text: "hi", mediaUrl: null, mediaUrls: undefined, channelData: undefined },
+      {
+        text: "photo",
+        mediaUrl: "https://x.test/a.jpg",
+        mediaUrls: ["https://x.test/a.jpg"],
+        channelData: undefined,
+      },
+      {
+        text: "multi",
+        mediaUrl: null,
+        mediaUrls: ["https://x.test/1.png"],
+        channelData: undefined,
+      },
+    ]);
+  });
+
+  it("keeps mediaUrl null for multi MEDIA tags", () => {
+    expect(
+      normalizeOutboundPayloadsForJson([
+        {
+          text: "MEDIA:https://x.test/a.png\nMEDIA:https://x.test/b.png",
+        },
+      ]),
+    ).toEqual([
+      {
+        text: "",
+        mediaUrl: null,
+        mediaUrls: ["https://x.test/a.png", "https://x.test/b.png"],
+        channelData: undefined,
+      },
+    ]);
+  });
+});
+
+describe("normalizeOutboundPayloads", () => {
+  it("keeps channelData-only payloads", () => {
+    const channelData = { line: { flexMessage: { altText: "Card", contents: {} } } };
+    const normalized = normalizeOutboundPayloads([{ channelData }]);
+    expect(normalized).toEqual([{ text: "", mediaUrls: [], channelData }]);
+  });
+});
+
+describe("formatOutboundPayloadLog", () => {
+  it("trims trailing text and appends media lines", () => {
+    expect(
+      formatOutboundPayloadLog({
+        text: "hello  ",
+        mediaUrls: ["https://x.test/a.png", "https://x.test/b.png"],
+      }),
+    ).toBe("hello\nMEDIA:https://x.test/a.png\nMEDIA:https://x.test/b.png");
+  });
+
+  it("logs media-only payloads", () => {
+    expect(
+      formatOutboundPayloadLog({
+        text: "",
+        mediaUrls: ["https://x.test/a.png"],
+      }),
+    ).toBe("MEDIA:https://x.test/a.png");
+  });
+});
+
+describe("resolveOutboundTarget", () => {
+  beforeEach(() => {
+    setActivePluginRegistry(
+      createTestRegistry([
+        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
+        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
+      ]),
+    );
+  });
+
+  afterEach(() => {
+    setActivePluginRegistry(createTestRegistry());
+  });
+
+  it("rejects whatsapp with empty target even when allowFrom configured", () => {
+    const cfg: OpenClawConfig = {
+      channels: { whatsapp: { allowFrom: ["+1555"] } },
+    };
+    const res = resolveOutboundTarget({
+      channel: "whatsapp",
+      to: "",
+      cfg,
+      mode: "explicit",
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.message).toContain("WhatsApp");
+    }
+  });
+
+  it.each([
+    {
+      name: "normalizes whatsapp target when provided",
+      input: { channel: "whatsapp" as const, to: " (555) 123-4567 " },
+      expected: { ok: true as const, to: "+5551234567" },
+    },
+    {
+      name: "keeps whatsapp group targets",
+      input: { channel: "whatsapp" as const, to: "120363401234567890@g.us" },
+      expected: { ok: true as const, to: "120363401234567890@g.us" },
+    },
+    {
+      name: "normalizes prefixed/uppercase whatsapp group targets",
+      input: {
+        channel: "whatsapp" as const,
+        to: " WhatsApp:120363401234567890@G.US ",
+      },
+      expected: { ok: true as const, to: "120363401234567890@g.us" },
+    },
+    {
+      name: "rejects whatsapp with empty target and allowFrom (no silent fallback)",
+      input: { channel: "whatsapp" as const, to: "", allowFrom: ["+1555"] },
+      expectedErrorIncludes: "WhatsApp",
+    },
+    {
+      name: "rejects whatsapp with empty target and prefixed allowFrom (no silent fallback)",
+      input: {
+        channel: "whatsapp" as const,
+        to: "",
+        allowFrom: ["whatsapp:(555) 123-4567"],
+      },
+      expectedErrorIncludes: "WhatsApp",
+    },
+    {
+      name: "rejects invalid whatsapp target",
+      input: { channel: "whatsapp" as const, to: "wat" },
+      expectedErrorIncludes: "WhatsApp",
+    },
+    {
+      name: "rejects whatsapp without to when allowFrom missing",
+      input: { channel: "whatsapp" as const, to: " " },
+      expectedErrorIncludes: "WhatsApp",
+    },
+    {
+      name: "rejects whatsapp allowFrom fallback when invalid",
+      input: { channel: "whatsapp" as const, to: "", allowFrom: ["wat"] },
+      expectedErrorIncludes: "WhatsApp",
+    },
+  ])("$name", ({ input, expected, expectedErrorIncludes }) => {
+    const res = resolveOutboundTarget(input);
+    if (expected) {
+      expect(res).toEqual(expected);
+      return;
+    }
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.message).toContain(expectedErrorIncludes);
+    }
+  });
+
+  it("rejects telegram with missing target", () => {
+    const res = resolveOutboundTarget({ channel: "telegram", to: " " });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.message).toContain("Telegram");
+    }
+  });
+
+  it("rejects webchat delivery", () => {
+    const res = resolveOutboundTarget({ channel: "webchat", to: "x" });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.message).toContain("WebChat");
+    }
+  });
+});
+
+describe("resolveSessionDeliveryTarget", () => {
+  it("derives implicit delivery from the last route", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-1",
+        updatedAt: 1,
+        lastChannel: " whatsapp ",
+        lastTo: " +1555 ",
+        lastAccountId: " acct-1 ",
+      },
+      requestedChannel: "last",
+    });
+
+    expect(resolved).toEqual({
+      channel: "whatsapp",
+      to: "+1555",
+      accountId: "acct-1",
+      threadId: undefined,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: "acct-1",
+      lastThreadId: undefined,
+    });
+  });
+
+  it("prefers explicit targets without reusing lastTo", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-2",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "telegram",
+    });
+
+    expect(resolved).toEqual({
+      channel: "telegram",
+      to: undefined,
+      accountId: undefined,
+      threadId: undefined,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+
+  it("allows mismatched lastTo when configured", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-3",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "telegram",
+      allowMismatchedLastTo: true,
+    });
+
+    expect(resolved).toEqual({
+      channel: "telegram",
+      to: "+1555",
+      accountId: undefined,
+      threadId: undefined,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+
+  it("falls back to a provided channel when requested is unsupported", () => {
+    const resolved = resolveSessionDeliveryTarget({
+      entry: {
+        sessionId: "sess-4",
+        updatedAt: 1,
+        lastChannel: "whatsapp",
+        lastTo: "+1555",
+      },
+      requestedChannel: "webchat",
+      fallbackChannel: "slack",
+    });
+
+    expect(resolved).toEqual({
+      channel: "slack",
+      to: undefined,
+      accountId: undefined,
+      threadId: undefined,
+      mode: "implicit",
+      lastChannel: "whatsapp",
+      lastTo: "+1555",
+      lastAccountId: undefined,
+      lastThreadId: undefined,
+    });
+  });
+});
diff --git a/src/infra/outbound/payloads.test.ts b/src/infra/outbound/payloads.test.ts
deleted file mode 100644
index be3f66daf38..00000000000
--- a/src/infra/outbound/payloads.test.ts
+++ /dev/null
@@ -1,77 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  formatOutboundPayloadLog,
-  normalizeOutboundPayloads,
-  normalizeOutboundPayloadsForJson,
-} from "./payloads.js";
-
-describe("normalizeOutboundPayloadsForJson", () => {
-  it("normalizes payloads with mediaUrl and mediaUrls", () => {
-    expect(
-      normalizeOutboundPayloadsForJson([
-        { text: "hi" },
-        { text: "photo", mediaUrl: "https://x.test/a.jpg" },
-        { text: "multi", mediaUrls: ["https://x.test/1.png"] },
-      ]),
-    ).toEqual([
-      { text: "hi", mediaUrl: null, mediaUrls: undefined, channelData: undefined },
-      {
-        text: "photo",
-        mediaUrl: "https://x.test/a.jpg",
-        mediaUrls: ["https://x.test/a.jpg"],
-        channelData: undefined,
-      },
-      {
-        text: "multi",
-        mediaUrl: null,
-        mediaUrls: ["https://x.test/1.png"],
-        channelData: undefined,
-      },
-    ]);
-  });
-
-  it("keeps mediaUrl null for multi MEDIA tags", () => {
-    expect(
-      normalizeOutboundPayloadsForJson([
-        {
-          text: "MEDIA:https://x.test/a.png\nMEDIA:https://x.test/b.png",
-        },
-      ]),
-    ).toEqual([
-      {
-        text: "",
-        mediaUrl: null,
-        mediaUrls: ["https://x.test/a.png", "https://x.test/b.png"],
-        channelData: undefined,
-      },
-    ]);
-  });
-});
-
-describe("normalizeOutboundPayloads", () => {
-  it("keeps channelData-only payloads", () => {
-    const channelData = { line: { flexMessage: { altText: "Card", contents: {} } } };
-    const normalized = normalizeOutboundPayloads([{ channelData }]);
-    expect(normalized).toEqual([{ text: "", mediaUrls: [], channelData }]);
-  });
-});
-
-describe("formatOutboundPayloadLog", () => {
-  it("trims trailing text and appends media lines", () => {
-    expect(
-      formatOutboundPayloadLog({
-        text: "hello  ",
-        mediaUrls: ["https://x.test/a.png", "https://x.test/b.png"],
-      }),
-    ).toBe("hello\nMEDIA:https://x.test/a.png\nMEDIA:https://x.test/b.png");
-  });
-
-  it("logs media-only payloads", () => {
-    expect(
-      formatOutboundPayloadLog({
-        text: "",
-        mediaUrls: ["https://x.test/a.png"],
-      }),
-    ).toBe("MEDIA:https://x.test/a.png");
-  });
-});
diff --git a/src/infra/outbound/target-resolver.ts b/src/infra/outbound/target-resolver.ts
index d2bac1e9dd5..def41c70cf5 100644
--- a/src/infra/outbound/target-resolver.ts
+++ b/src/infra/outbound/target-resolver.ts
@@ -228,20 +228,14 @@ async function listDirectoryEntries(params: {
   }
   const runtime = params.runtime ?? defaultRuntime;
   const useLive = params.source === "live";
-  if (params.kind === "user") {
-    const fn = useLive ? (directory.listPeersLive ?? directory.listPeers) : directory.listPeers;
-    if (!fn) {
-      return [];
-    }
-    return await fn({
-      cfg: params.cfg,
-      accountId: params.accountId ?? undefined,
-      query: params.query ?? undefined,
-      limit: undefined,
-      runtime,
-    });
-  }
-  const fn = useLive ? (directory.listGroupsLive ?? directory.listGroups) : directory.listGroups;
+  const fn =
+    params.kind === "user"
+      ? useLive
+        ? (directory.listPeersLive ?? directory.listPeers)
+        : directory.listPeers
+      : useLive
+        ? (directory.listGroupsLive ?? directory.listGroups)
+        : directory.listGroups;
   if (!fn) {
     return [];
   }
diff --git a/src/infra/outbound/targets.test.ts b/src/infra/outbound/targets.test.ts
deleted file mode 100644
index ff9dee1613a..00000000000
--- a/src/infra/outbound/targets.test.ts
+++ /dev/null
@@ -1,211 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import { telegramPlugin } from "../../../extensions/telegram/src/channel.js";
-import { whatsappPlugin } from "../../../extensions/whatsapp/src/channel.js";
-import { setActivePluginRegistry } from "../../plugins/runtime.js";
-import { createTestRegistry } from "../../test-utils/channel-plugins.js";
-import { resolveOutboundTarget, resolveSessionDeliveryTarget } from "./targets.js";
-
-describe("resolveOutboundTarget", () => {
-  beforeEach(() => {
-    setActivePluginRegistry(
-      createTestRegistry([
-        { pluginId: "whatsapp", plugin: whatsappPlugin, source: "test" },
-        { pluginId: "telegram", plugin: telegramPlugin, source: "test" },
-      ]),
-    );
-  });
-
-  it("rejects whatsapp with empty target even when allowFrom configured", () => {
-    const cfg: OpenClawConfig = {
-      channels: { whatsapp: { allowFrom: ["+1555"] } },
-    };
-    const res = resolveOutboundTarget({
-      channel: "whatsapp",
-      to: "",
-      cfg,
-      mode: "explicit",
-    });
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.error.message).toContain("WhatsApp");
-    }
-  });
-
-  it.each([
-    {
-      name: "normalizes whatsapp target when provided",
-      input: { channel: "whatsapp" as const, to: " (555) 123-4567 " },
-      expected: { ok: true as const, to: "+5551234567" },
-    },
-    {
-      name: "keeps whatsapp group targets",
-      input: { channel: "whatsapp" as const, to: "120363401234567890@g.us" },
-      expected: { ok: true as const, to: "120363401234567890@g.us" },
-    },
-    {
-      name: "normalizes prefixed/uppercase whatsapp group targets",
-      input: {
-        channel: "whatsapp" as const,
-        to: " WhatsApp:120363401234567890@G.US ",
-      },
-      expected: { ok: true as const, to: "120363401234567890@g.us" },
-    },
-    {
-      name: "rejects whatsapp with empty target and allowFrom (no silent fallback)",
-      input: { channel: "whatsapp" as const, to: "", allowFrom: ["+1555"] },
-      expectedErrorIncludes: "WhatsApp",
-    },
-    {
-      name: "rejects whatsapp with empty target and prefixed allowFrom (no silent fallback)",
-      input: {
-        channel: "whatsapp" as const,
-        to: "",
-        allowFrom: ["whatsapp:(555) 123-4567"],
-      },
-      expectedErrorIncludes: "WhatsApp",
-    },
-    {
-      name: "rejects invalid whatsapp target",
-      input: { channel: "whatsapp" as const, to: "wat" },
-      expectedErrorIncludes: "WhatsApp",
-    },
-    {
-      name: "rejects whatsapp without to when allowFrom missing",
-      input: { channel: "whatsapp" as const, to: " " },
-      expectedErrorIncludes: "WhatsApp",
-    },
-    {
-      name: "rejects whatsapp allowFrom fallback when invalid",
-      input: { channel: "whatsapp" as const, to: "", allowFrom: ["wat"] },
-      expectedErrorIncludes: "WhatsApp",
-    },
-  ])("$name", ({ input, expected, expectedErrorIncludes }) => {
-    const res = resolveOutboundTarget(input);
-    if (expected) {
-      expect(res).toEqual(expected);
-      return;
-    }
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.error.message).toContain(expectedErrorIncludes);
-    }
-  });
-
-  it("rejects telegram with missing target", () => {
-    const res = resolveOutboundTarget({ channel: "telegram", to: " " });
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.error.message).toContain("Telegram");
-    }
-  });
-
-  it("rejects webchat delivery", () => {
-    const res = resolveOutboundTarget({ channel: "webchat", to: "x" });
-    expect(res.ok).toBe(false);
-    if (!res.ok) {
-      expect(res.error.message).toContain("WebChat");
-    }
-  });
-});
-
-describe("resolveSessionDeliveryTarget", () => {
-  it("derives implicit delivery from the last route", () => {
-    const resolved = resolveSessionDeliveryTarget({
-      entry: {
-        sessionId: "sess-1",
-        updatedAt: 1,
-        lastChannel: " whatsapp ",
-        lastTo: " +1555 ",
-        lastAccountId: " acct-1 ",
-      },
-      requestedChannel: "last",
-    });
-
-    expect(resolved).toEqual({
-      channel: "whatsapp",
-      to: "+1555",
-      accountId: "acct-1",
-      threadId: undefined,
-      mode: "implicit",
-      lastChannel: "whatsapp",
-      lastTo: "+1555",
-      lastAccountId: "acct-1",
-      lastThreadId: undefined,
-    });
-  });
-
-  it("prefers explicit targets without reusing lastTo", () => {
-    const resolved = resolveSessionDeliveryTarget({
-      entry: {
-        sessionId: "sess-2",
-        updatedAt: 1,
-        lastChannel: "whatsapp",
-        lastTo: "+1555",
-      },
-      requestedChannel: "telegram",
-    });
-
-    expect(resolved).toEqual({
-      channel: "telegram",
-      to: undefined,
-      accountId: undefined,
-      threadId: undefined,
-      mode: "implicit",
-      lastChannel: "whatsapp",
-      lastTo: "+1555",
-      lastAccountId: undefined,
-      lastThreadId: undefined,
-    });
-  });
-
-  it("allows mismatched lastTo when configured", () => {
-    const resolved = resolveSessionDeliveryTarget({
-      entry: {
-        sessionId: "sess-3",
-        updatedAt: 1,
-        lastChannel: "whatsapp",
-        lastTo: "+1555",
-      },
-      requestedChannel: "telegram",
-      allowMismatchedLastTo: true,
-    });
-
-    expect(resolved).toEqual({
-      channel: "telegram",
-      to: "+1555",
-      accountId: undefined,
-      threadId: undefined,
-      mode: "implicit",
-      lastChannel: "whatsapp",
-      lastTo: "+1555",
-      lastAccountId: undefined,
-      lastThreadId: undefined,
-    });
-  });
-
-  it("falls back to a provided channel when requested is unsupported", () => {
-    const resolved = resolveSessionDeliveryTarget({
-      entry: {
-        sessionId: "sess-4",
-        updatedAt: 1,
-        lastChannel: "whatsapp",
-        lastTo: "+1555",
-      },
-      requestedChannel: "webchat",
-      fallbackChannel: "slack",
-    });
-
-    expect(resolved).toEqual({
-      channel: "slack",
-      to: undefined,
-      accountId: undefined,
-      threadId: undefined,
-      mode: "implicit",
-      lastChannel: "whatsapp",
-      lastTo: "+1555",
-      lastAccountId: undefined,
-      lastThreadId: undefined,
-    });
-  });
-});
diff --git a/src/infra/package-json.ts b/src/infra/package-json.ts
new file mode 100644
index 00000000000..f0007a3c04d
--- /dev/null
+++ b/src/infra/package-json.ts
@@ -0,0 +1,23 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function readPackageVersion(root: string): Promise<string | null> {
+  try {
+    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    return typeof parsed?.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readPackageName(root: string): Promise<string | null> {
+  try {
+    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
+    const parsed = JSON.parse(raw) as { name?: string };
+    const name = parsed?.name?.trim();
+    return name ? name : null;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/infra/pairing-files.ts b/src/infra/pairing-files.ts
index fb6c3ee5ebb..f2578facdfb 100644
--- a/src/infra/pairing-files.ts
+++ b/src/infra/pairing-files.ts
@@ -1,8 +1,8 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
 
+export { createAsyncLock, readJsonFile, writeJsonAtomic } from "./json-files.js";
+
 export function resolvePairingPaths(baseDir: string | undefined, subdir: string) {
   const root = baseDir ?? resolveStateDir();
   const dir = path.join(root, subdir);
@@ -13,33 +13,6 @@ export function resolvePairingPaths(baseDir: string | undefined, subdir: string)
   };
 }
 
-export async function readJsonFile<T>(filePath: string): Promise<T | null> {
-  try {
-    const raw = await fs.readFile(filePath, "utf8");
-    return JSON.parse(raw) as T;
-  } catch {
-    return null;
-  }
-}
-
-export async function writeJsonAtomic(filePath: string, value: unknown) {
-  const dir = path.dirname(filePath);
-  await fs.mkdir(dir, { recursive: true });
-  const tmp = `${filePath}.${randomUUID()}.tmp`;
-  await fs.writeFile(tmp, JSON.stringify(value, null, 2), "utf8");
-  try {
-    await fs.chmod(tmp, 0o600);
-  } catch {
-    // best-effort; ignore on platforms without chmod
-  }
-  await fs.rename(tmp, filePath);
-  try {
-    await fs.chmod(filePath, 0o600);
-  } catch {
-    // best-effort; ignore on platforms without chmod
-  }
-}
-
 export function pruneExpiredPending<T extends { ts: number }>(
   pendingById: Record<string, T>,
   nowMs: number,
@@ -51,20 +24,3 @@ export function pruneExpiredPending<T extends { ts: number }>(
     }
   }
 }
-
-export function createAsyncLock() {
-  let lock: Promise<void> = Promise.resolve();
-  return async function withLock<T>(fn: () => Promise<T>): Promise<T> {
-    const prev = lock;
-    let release: (() => void) | undefined;
-    lock = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    await prev;
-    try {
-      return await fn();
-    } finally {
-      release?.();
-    }
-  };
-}
diff --git a/src/infra/path-env.test.ts b/src/infra/path-env.test.ts
index 924406cca40..a439602d653 100644
--- a/src/infra/path-env.test.ts
+++ b/src/infra/path-env.test.ts
@@ -1,237 +1,215 @@
-import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { ensureOpenClawCliOnPath } from "./path-env.js";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+  dirs: new Set<string>(),
+  executables: new Set<string>(),
+}));
+
+const abs = (p: string) => path.resolve(p);
+const setDir = (p: string) => state.dirs.add(abs(p));
+const setExe = (p: string) => state.executables.add(abs(p));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const pathMod = await import("node:path");
+  const absInMock = (p: string) => pathMod.resolve(p);
+
+  const wrapped = {
+    ...actual,
+    constants: { ...actual.constants, X_OK: actual.constants.X_OK ?? 1 },
+    accessSync: (p: string, mode?: number) => {
+      // `mode` is ignored in tests; we only model "is executable" or "not".
+      if (!state.executables.has(absInMock(p))) {
+        throw new Error(`EACCES: permission denied, access '${p}' (mode=${mode ?? 0})`);
+      }
+    },
+    statSync: (p: string) => ({
+      // Avoid throws for non-existent paths; the code under test only cares about isDirectory().
+      isDirectory: () => state.dirs.has(absInMock(p)),
+    }),
+  };
+
+  return { ...wrapped, default: wrapped };
+});
+
+let ensureOpenClawCliOnPath: typeof import("./path-env.js").ensureOpenClawCliOnPath;
 
 describe("ensureOpenClawCliOnPath", () => {
-  let fixtureRoot = "";
-  let fixtureCount = 0;
-
-  async function makeTmpDir(): Promise<string> {
-    const tmp = path.join(fixtureRoot, `case-${fixtureCount++}`);
-    await fs.mkdir(tmp);
-    return tmp;
-  }
+  const envKeys = [
+    "PATH",
+    "OPENCLAW_PATH_BOOTSTRAPPED",
+    "OPENCLAW_ALLOW_PROJECT_LOCAL_BIN",
+    "MISE_DATA_DIR",
+    "HOMEBREW_PREFIX",
+    "HOMEBREW_BREW_FILE",
+    "XDG_BIN_HOME",
+  ] as const;
+  let envSnapshot: Record<(typeof envKeys)[number], string | undefined>;
 
   beforeAll(async () => {
-    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-path-"));
+    ({ ensureOpenClawCliOnPath } = await import("./path-env.js"));
   });
 
-  afterAll(async () => {
-    await fs.rm(fixtureRoot, { recursive: true, force: true });
+  beforeEach(() => {
+    envSnapshot = Object.fromEntries(envKeys.map((k) => [k, process.env[k]])) as typeof envSnapshot;
+    state.dirs.clear();
+    state.executables.clear();
+
+    setDir("/usr/bin");
+    setDir("/bin");
+    vi.clearAllMocks();
   });
 
-  it("prepends the bundled app bin dir when a sibling openclaw exists", async () => {
-    const tmp = await makeTmpDir();
-    const appBinDir = path.join(tmp, "AppBin");
-    await fs.mkdir(appBinDir);
-    const cliPath = path.join(appBinDir, "openclaw");
-    await fs.writeFile(cliPath, "#!/bin/sh\necho ok\n", "utf-8");
-    await fs.chmod(cliPath, 0o755);
-
-    const originalPath = process.env.PATH;
-    const originalFlag = process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-    process.env.PATH = "/usr/bin";
-    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-    try {
-      ensureOpenClawCliOnPath({
-        execPath: cliPath,
-        cwd: tmp,
-        homeDir: tmp,
-        platform: "darwin",
-      });
-      const updated = process.env.PATH ?? "";
-      expect(updated.split(path.delimiter)[0]).toBe(appBinDir);
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalFlag === undefined) {
-        delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+  afterEach(() => {
+    for (const k of envKeys) {
+      const value = envSnapshot[k];
+      if (value === undefined) {
+        delete process.env[k];
       } else {
-        process.env.OPENCLAW_PATH_BOOTSTRAPPED = originalFlag;
+        process.env[k] = value;
       }
     }
   });
 
+  it("prepends the bundled app bin dir when a sibling openclaw exists", () => {
+    const tmp = abs("/tmp/openclaw-path/case-bundled");
+    const appBinDir = path.join(tmp, "AppBin");
+    const cliPath = path.join(appBinDir, "openclaw");
+    setDir(tmp);
+    setDir(appBinDir);
+    setExe(cliPath);
+
+    process.env.PATH = "/usr/bin";
+    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+
+    ensureOpenClawCliOnPath({
+      execPath: cliPath,
+      cwd: tmp,
+      homeDir: tmp,
+      platform: "darwin",
+    });
+
+    const updated = process.env.PATH ?? "";
+    expect(updated.split(path.delimiter)[0]).toBe(appBinDir);
+  });
+
   it("is idempotent", () => {
-    const originalPath = process.env.PATH;
-    const originalFlag = process.env.OPENCLAW_PATH_BOOTSTRAPPED;
     process.env.PATH = "/bin";
     process.env.OPENCLAW_PATH_BOOTSTRAPPED = "1";
-    try {
-      ensureOpenClawCliOnPath({
-        execPath: "/tmp/does-not-matter",
-        cwd: "/tmp",
-        homeDir: "/tmp",
-        platform: "darwin",
-      });
-      expect(process.env.PATH).toBe("/bin");
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalFlag === undefined) {
-        delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-      } else {
-        process.env.OPENCLAW_PATH_BOOTSTRAPPED = originalFlag;
-      }
-    }
+    ensureOpenClawCliOnPath({
+      execPath: "/tmp/does-not-matter",
+      cwd: "/tmp",
+      homeDir: "/tmp",
+      platform: "darwin",
+    });
+    expect(process.env.PATH).toBe("/bin");
   });
 
-  it("prepends mise shims when available", async () => {
-    const tmp = await makeTmpDir();
-    const originalPath = process.env.PATH;
-    const originalFlag = process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-    const originalMiseDataDir = process.env.MISE_DATA_DIR;
-    try {
-      const appBinDir = path.join(tmp, "AppBin");
-      await fs.mkdir(appBinDir);
-      const appCli = path.join(appBinDir, "openclaw");
-      await fs.writeFile(appCli, "#!/bin/sh\necho ok\n", "utf-8");
-      await fs.chmod(appCli, 0o755);
+  it("prepends mise shims when available", () => {
+    const tmp = abs("/tmp/openclaw-path/case-mise");
+    const appBinDir = path.join(tmp, "AppBin");
+    const appCli = path.join(appBinDir, "openclaw");
+    setDir(tmp);
+    setDir(appBinDir);
+    setExe(appCli);
 
-      const miseDataDir = path.join(tmp, "mise");
-      const shimsDir = path.join(miseDataDir, "shims");
-      await fs.mkdir(shimsDir, { recursive: true });
-      process.env.MISE_DATA_DIR = miseDataDir;
-      process.env.PATH = "/usr/bin";
-      delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+    const miseDataDir = path.join(tmp, "mise");
+    const shimsDir = path.join(miseDataDir, "shims");
+    setDir(miseDataDir);
+    setDir(shimsDir);
 
-      ensureOpenClawCliOnPath({
-        execPath: appCli,
-        cwd: tmp,
-        homeDir: tmp,
-        platform: "darwin",
-      });
+    process.env.MISE_DATA_DIR = miseDataDir;
+    process.env.PATH = "/usr/bin";
+    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
 
-      const updated = process.env.PATH ?? "";
-      const parts = updated.split(path.delimiter);
-      const appBinIndex = parts.indexOf(appBinDir);
-      const shimsIndex = parts.indexOf(shimsDir);
-      expect(appBinIndex).toBeGreaterThanOrEqual(0);
-      expect(shimsIndex).toBeGreaterThan(appBinIndex);
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalFlag === undefined) {
-        delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-      } else {
-        process.env.OPENCLAW_PATH_BOOTSTRAPPED = originalFlag;
-      }
-      if (originalMiseDataDir === undefined) {
-        delete process.env.MISE_DATA_DIR;
-      } else {
-        process.env.MISE_DATA_DIR = originalMiseDataDir;
-      }
-    }
+    ensureOpenClawCliOnPath({
+      execPath: appCli,
+      cwd: tmp,
+      homeDir: tmp,
+      platform: "darwin",
+    });
+
+    const updated = process.env.PATH ?? "";
+    const parts = updated.split(path.delimiter);
+    const appBinIndex = parts.indexOf(appBinDir);
+    const shimsIndex = parts.indexOf(shimsDir);
+    expect(appBinIndex).toBeGreaterThanOrEqual(0);
+    expect(shimsIndex).toBeGreaterThan(appBinIndex);
   });
 
-  it("only appends project-local node_modules/.bin when explicitly enabled", async () => {
-    const tmp = await makeTmpDir();
-    const originalPath = process.env.PATH;
-    const originalFlag = process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-    try {
-      const appBinDir = path.join(tmp, "AppBin");
-      await fs.mkdir(appBinDir);
-      const appCli = path.join(appBinDir, "openclaw");
-      await fs.writeFile(appCli, "#!/bin/sh\necho ok\n", "utf-8");
-      await fs.chmod(appCli, 0o755);
+  it("only appends project-local node_modules/.bin when explicitly enabled", () => {
+    const tmp = abs("/tmp/openclaw-path/case-project-local");
+    const appBinDir = path.join(tmp, "AppBin");
+    const appCli = path.join(appBinDir, "openclaw");
+    setDir(tmp);
+    setDir(appBinDir);
+    setExe(appCli);
 
-      const localBinDir = path.join(tmp, "node_modules", ".bin");
-      await fs.mkdir(localBinDir, { recursive: true });
-      const localCli = path.join(localBinDir, "openclaw");
-      await fs.writeFile(localCli, "#!/bin/sh\necho ok\n", "utf-8");
-      await fs.chmod(localCli, 0o755);
+    const localBinDir = path.join(tmp, "node_modules", ".bin");
+    const localCli = path.join(localBinDir, "openclaw");
+    setDir(path.join(tmp, "node_modules"));
+    setDir(localBinDir);
+    setExe(localCli);
 
-      process.env.PATH = "/usr/bin";
-      delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+    process.env.PATH = "/usr/bin";
+    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
 
-      ensureOpenClawCliOnPath({
-        execPath: appCli,
-        cwd: tmp,
-        homeDir: tmp,
-        platform: "darwin",
-      });
-      const withoutOptIn = (process.env.PATH ?? "").split(path.delimiter);
-      expect(withoutOptIn.includes(localBinDir)).toBe(false);
+    ensureOpenClawCliOnPath({
+      execPath: appCli,
+      cwd: tmp,
+      homeDir: tmp,
+      platform: "darwin",
+    });
+    const withoutOptIn = (process.env.PATH ?? "").split(path.delimiter);
+    expect(withoutOptIn.includes(localBinDir)).toBe(false);
 
-      process.env.PATH = "/usr/bin";
-      delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+    process.env.PATH = "/usr/bin";
+    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
 
-      ensureOpenClawCliOnPath({
-        execPath: appCli,
-        cwd: tmp,
-        homeDir: tmp,
-        platform: "darwin",
-        allowProjectLocalBin: true,
-      });
-      const withOptIn = (process.env.PATH ?? "").split(path.delimiter);
-      const usrBinIndex = withOptIn.indexOf("/usr/bin");
-      const localIndex = withOptIn.indexOf(localBinDir);
-      expect(usrBinIndex).toBeGreaterThanOrEqual(0);
-      expect(localIndex).toBeGreaterThan(usrBinIndex);
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalFlag === undefined) {
-        delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-      } else {
-        process.env.OPENCLAW_PATH_BOOTSTRAPPED = originalFlag;
-      }
-    }
+    ensureOpenClawCliOnPath({
+      execPath: appCli,
+      cwd: tmp,
+      homeDir: tmp,
+      platform: "darwin",
+      allowProjectLocalBin: true,
+    });
+    const withOptIn = (process.env.PATH ?? "").split(path.delimiter);
+    const usrBinIndex = withOptIn.indexOf("/usr/bin");
+    const localIndex = withOptIn.indexOf(localBinDir);
+    expect(usrBinIndex).toBeGreaterThanOrEqual(0);
+    expect(localIndex).toBeGreaterThan(usrBinIndex);
   });
 
-  it("prepends Linuxbrew dirs when present", async () => {
-    const tmp = await makeTmpDir();
-    const originalPath = process.env.PATH;
-    const originalFlag = process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-    const originalHomebrewPrefix = process.env.HOMEBREW_PREFIX;
-    const originalHomebrewBrewFile = process.env.HOMEBREW_BREW_FILE;
-    const originalXdgBinHome = process.env.XDG_BIN_HOME;
-    try {
-      const execDir = path.join(tmp, "exec");
-      await fs.mkdir(execDir);
+  it("prepends Linuxbrew dirs when present", () => {
+    const tmp = abs("/tmp/openclaw-path/case-linuxbrew");
+    const execDir = path.join(tmp, "exec");
+    setDir(tmp);
+    setDir(execDir);
 
-      const linuxbrewBin = path.join(tmp, ".linuxbrew", "bin");
-      const linuxbrewSbin = path.join(tmp, ".linuxbrew", "sbin");
-      await fs.mkdir(linuxbrewBin, { recursive: true });
-      await fs.mkdir(linuxbrewSbin, { recursive: true });
+    const linuxbrewDir = path.join(tmp, ".linuxbrew");
+    const linuxbrewBin = path.join(linuxbrewDir, "bin");
+    const linuxbrewSbin = path.join(linuxbrewDir, "sbin");
+    setDir(linuxbrewDir);
+    setDir(linuxbrewBin);
+    setDir(linuxbrewSbin);
 
-      process.env.PATH = "/usr/bin";
-      delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-      delete process.env.HOMEBREW_PREFIX;
-      delete process.env.HOMEBREW_BREW_FILE;
-      delete process.env.XDG_BIN_HOME;
+    process.env.PATH = "/usr/bin";
+    delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
+    delete process.env.HOMEBREW_PREFIX;
+    delete process.env.HOMEBREW_BREW_FILE;
+    delete process.env.XDG_BIN_HOME;
 
-      ensureOpenClawCliOnPath({
-        execPath: path.join(execDir, "node"),
-        cwd: tmp,
-        homeDir: tmp,
-        platform: "linux",
-      });
+    ensureOpenClawCliOnPath({
+      execPath: path.join(execDir, "node"),
+      cwd: tmp,
+      homeDir: tmp,
+      platform: "linux",
+    });
 
-      const updated = process.env.PATH ?? "";
-      const parts = updated.split(path.delimiter);
-      expect(parts[0]).toBe(linuxbrewBin);
-      expect(parts[1]).toBe(linuxbrewSbin);
-    } finally {
-      process.env.PATH = originalPath;
-      if (originalFlag === undefined) {
-        delete process.env.OPENCLAW_PATH_BOOTSTRAPPED;
-      } else {
-        process.env.OPENCLAW_PATH_BOOTSTRAPPED = originalFlag;
-      }
-      if (originalHomebrewPrefix === undefined) {
-        delete process.env.HOMEBREW_PREFIX;
-      } else {
-        process.env.HOMEBREW_PREFIX = originalHomebrewPrefix;
-      }
-      if (originalHomebrewBrewFile === undefined) {
-        delete process.env.HOMEBREW_BREW_FILE;
-      } else {
-        process.env.HOMEBREW_BREW_FILE = originalHomebrewBrewFile;
-      }
-      if (originalXdgBinHome === undefined) {
-        delete process.env.XDG_BIN_HOME;
-      } else {
-        process.env.XDG_BIN_HOME = originalXdgBinHome;
-      }
-    }
+    const updated = process.env.PATH ?? "";
+    const parts = updated.split(path.delimiter);
+    expect(parts[0]).toBe(linuxbrewBin);
+    expect(parts[1]).toBe(linuxbrewSbin);
   });
 });
diff --git a/src/infra/path-safety.test.ts b/src/infra/path-safety.test.ts
new file mode 100644
index 00000000000..b05eeced172
--- /dev/null
+++ b/src/infra/path-safety.test.ts
@@ -0,0 +1,16 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { isWithinDir, resolveSafeBaseDir } from "./path-safety.js";
+
+describe("path-safety", () => {
+  it("resolves safe base dir with trailing separator", () => {
+    const base = resolveSafeBaseDir("/tmp/demo");
+    expect(base.endsWith(path.sep)).toBe(true);
+  });
+
+  it("checks directory containment", () => {
+    expect(isWithinDir("/tmp/demo", "/tmp/demo")).toBe(true);
+    expect(isWithinDir("/tmp/demo", "/tmp/demo/sub/file.txt")).toBe(true);
+    expect(isWithinDir("/tmp/demo", "/tmp/demo/../escape.txt")).toBe(false);
+  });
+});
diff --git a/src/infra/path-safety.ts b/src/infra/path-safety.ts
new file mode 100644
index 00000000000..df05097b312
--- /dev/null
+++ b/src/infra/path-safety.ts
@@ -0,0 +1,20 @@
+import path from "node:path";
+
+export function resolveSafeBaseDir(rootDir: string): string {
+  const resolved = path.resolve(rootDir);
+  return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
+}
+
+export function isWithinDir(rootDir: string, targetPath: string): boolean {
+  const resolvedRoot = path.resolve(rootDir);
+  const resolvedTarget = path.resolve(targetPath);
+
+  // Windows paths are effectively case-insensitive; normalize to avoid false negatives.
+  if (process.platform === "win32") {
+    const relative = path.win32.relative(resolvedRoot.toLowerCase(), resolvedTarget.toLowerCase());
+    return relative === "" || (!relative.startsWith("..") && !path.win32.isAbsolute(relative));
+  }
+
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
diff --git a/src/infra/ports-inspect.test.ts b/src/infra/ports-inspect.test.ts
deleted file mode 100644
index 8aaeff42437..00000000000
--- a/src/infra/ports-inspect.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import net from "node:net";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const runCommandWithTimeoutMock = vi.fn();
-
-vi.mock("../process/exec.js", () => ({
-  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
-}));
-
-const describeUnix = process.platform === "win32" ? describe.skip : describe;
-
-describeUnix("inspectPortUsage", () => {
-  beforeEach(() => {
-    runCommandWithTimeoutMock.mockReset();
-  });
-
-  it("reports busy when lsof is missing but loopback listener exists", async () => {
-    const server = net.createServer();
-    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
-    const port = (server.address() as net.AddressInfo).port;
-
-    runCommandWithTimeoutMock.mockRejectedValueOnce(
-      Object.assign(new Error("spawn lsof ENOENT"), { code: "ENOENT" }),
-    );
-
-    try {
-      const { inspectPortUsage } = await import("./ports-inspect.js");
-      const result = await inspectPortUsage(port);
-      expect(result.status).toBe("busy");
-      expect(result.errors?.some((err) => err.includes("ENOENT"))).toBe(true);
-    } finally {
-      server.close();
-    }
-  });
-});
diff --git a/src/infra/ports.test.ts b/src/infra/ports.test.ts
index 399ccd39816..a58ca4e4318 100644
--- a/src/infra/ports.test.ts
+++ b/src/infra/ports.test.ts
@@ -1,5 +1,13 @@
 import net from "node:net";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { stripAnsi } from "../terminal/ansi.js";
+
+const runCommandWithTimeoutMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../process/exec.js", () => ({
+  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
+}));
+import { inspectPortUsage } from "./ports-inspect.js";
 import {
   buildPortHints,
   classifyPortListener,
@@ -9,13 +17,15 @@ import {
   PortInUseError,
 } from "./ports.js";
 
+const describeUnix = process.platform === "win32" ? describe.skip : describe;
+
 describe("ports helpers", () => {
   it("ensurePortAvailable rejects when port busy", async () => {
     const server = net.createServer();
     await new Promise((resolve) => server.listen(0, resolve));
     const port = (server.address() as net.AddressInfo).port;
     await expect(ensurePortAvailable(port)).rejects.toBeInstanceOf(PortInUseError);
-    server.close();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
   });
 
   it("handlePortError exits nicely on EADDRINUSE", async () => {
@@ -28,10 +38,30 @@ describe("ports helpers", () => {
     await handlePortError(new PortInUseError(1234, "details"), 1234, "context", runtime).catch(
       () => {},
     );
-    expect(runtime.error).toHaveBeenCalled();
+    const messages = runtime.error.mock.calls.map((call) => stripAnsi(String(call[0] ?? "")));
+    expect(messages.join("\n")).toContain("context failed: port 1234 is already in use.");
+    expect(messages.join("\n")).toContain("Resolve by stopping the process");
     expect(runtime.exit).toHaveBeenCalledWith(1);
   });
 
+  it("prints an OpenClaw-specific hint when port details look like another OpenClaw instance", async () => {
+    const runtime = {
+      error: vi.fn(),
+      log: vi.fn(),
+      exit: vi.fn() as unknown as (code: number) => never,
+    };
+
+    await handlePortError(
+      new PortInUseError(18789, "node dist/index.js openclaw gateway"),
+      18789,
+      "gateway start",
+      runtime,
+    ).catch(() => {});
+
+    const messages = runtime.error.mock.calls.map((call) => stripAnsi(String(call[0] ?? "")));
+    expect(messages.join("\n")).toContain("another OpenClaw instance is already running");
+  });
+
   it("classifies ssh and gateway listeners", () => {
     expect(
       classifyPortListener({ commandLine: "ssh -N -L 18789:127.0.0.1:18789 user@host" }, 18789),
@@ -58,3 +88,27 @@ describe("ports helpers", () => {
     expect(lines.some((line) => line.includes("SSH tunnel"))).toBe(true);
   });
 });
+
+describeUnix("inspectPortUsage", () => {
+  beforeEach(() => {
+    runCommandWithTimeoutMock.mockReset();
+  });
+
+  it("reports busy when lsof is missing but loopback listener exists", async () => {
+    const server = net.createServer();
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = (server.address() as net.AddressInfo).port;
+
+    runCommandWithTimeoutMock.mockRejectedValueOnce(
+      Object.assign(new Error("spawn lsof ENOENT"), { code: "ENOENT" }),
+    );
+
+    try {
+      const result = await inspectPortUsage(port);
+      expect(result.status).toBe("busy");
+      expect(result.errors?.some((err) => err.includes("ENOENT"))).toBe(true);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});
diff --git a/src/infra/process-respawn.test.ts b/src/infra/process-respawn.test.ts
index d7ea3649af3..324282ec990 100644
--- a/src/infra/process-respawn.test.ts
+++ b/src/infra/process-respawn.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { captureFullEnv } from "../test-utils/env.js";
 
 const spawnMock = vi.hoisted(() => vi.fn());
 
@@ -8,27 +9,12 @@ vi.mock("node:child_process", () => ({
 
 import { restartGatewayProcessWithFreshPid } from "./process-respawn.js";
 
-const originalEnv = { ...process.env };
 const originalArgv = [...process.argv];
 const originalExecArgv = [...process.execArgv];
-
-function restoreEnv() {
-  for (const key of Object.keys(process.env)) {
-    if (!(key in originalEnv)) {
-      delete process.env[key];
-    }
-  }
-  for (const [key, value] of Object.entries(originalEnv)) {
-    if (value === undefined) {
-      delete process.env[key];
-    } else {
-      process.env[key] = value;
-    }
-  }
-}
+const envSnapshot = captureFullEnv();
 
 afterEach(() => {
-  restoreEnv();
+  envSnapshot.restore();
   process.argv = [...originalArgv];
   process.execArgv = [...originalExecArgv];
   spawnMock.mockReset();
diff --git a/src/infra/provider-usage.auth.normalizes-keys.test.ts b/src/infra/provider-usage.auth.normalizes-keys.test.ts
index 5b193061ecd..2adacf98686 100644
--- a/src/infra/provider-usage.auth.normalizes-keys.test.ts
+++ b/src/infra/provider-usage.auth.normalizes-keys.test.ts
@@ -1,12 +1,71 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { withTempHome } from "../../test/helpers/temp-home.js";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { resolveProviderAuths } from "./provider-usage.auth.js";
 
 describe("resolveProviderAuths key normalization", () => {
+  let suiteRoot = "";
+  let suiteCase = 0;
+
+  beforeAll(async () => {
+    suiteRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-provider-auth-suite-"));
+  });
+
+  afterAll(async () => {
+    await fs.rm(suiteRoot, { recursive: true, force: true });
+    suiteRoot = "";
+    suiteCase = 0;
+  });
+
+  async function withSuiteHome<T>(
+    fn: (home: string) => Promise<T>,
+    env: Record<string, string | undefined>,
+  ): Promise<T> {
+    const base = path.join(suiteRoot, `case-${++suiteCase}`);
+    await fs.mkdir(base, { recursive: true });
+    await fs.mkdir(path.join(base, ".openclaw", "agents", "main", "sessions"), { recursive: true });
+
+    const keysToRestore = new Set<string>([
+      "HOME",
+      "USERPROFILE",
+      "HOMEDRIVE",
+      "HOMEPATH",
+      "OPENCLAW_HOME",
+      "OPENCLAW_STATE_DIR",
+      ...Object.keys(env),
+    ]);
+    const snapshot: Record<string, string | undefined> = {};
+    for (const key of keysToRestore) {
+      snapshot[key] = process.env[key];
+    }
+
+    process.env.HOME = base;
+    process.env.USERPROFILE = base;
+    delete process.env.OPENCLAW_HOME;
+    process.env.OPENCLAW_STATE_DIR = path.join(base, ".openclaw");
+    for (const [key, value] of Object.entries(env)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    try {
+      return await fn(base);
+    } finally {
+      for (const [key, value] of Object.entries(snapshot)) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    }
+  }
+
   it("strips embedded CR/LF from env keys", async () => {
-    await withTempHome(
+    await withSuiteHome(
       async () => {
         const auths = await resolveProviderAuths({
           providers: ["zai", "minimax", "xiaomi"],
@@ -18,17 +77,15 @@ describe("resolveProviderAuths key normalization", () => {
         ]);
       },
       {
-        env: {
-          ZAI_API_KEY: "zai-\r\nkey",
-          MINIMAX_API_KEY: "minimax-\r\nkey",
-          XIAOMI_API_KEY: "xiaomi-\r\nkey",
-        },
+        ZAI_API_KEY: "zai-\r\nkey",
+        MINIMAX_API_KEY: "minimax-\r\nkey",
+        XIAOMI_API_KEY: "xiaomi-\r\nkey",
       },
     );
   });
 
   it("strips embedded CR/LF from stored auth profiles (token + api_key)", async () => {
-    await withTempHome(
+    await withSuiteHome(
       async (home) => {
         const agentDir = path.join(home, ".openclaw", "agents", "main", "agent");
         await fs.mkdir(agentDir, { recursive: true });
@@ -57,11 +114,9 @@ describe("resolveProviderAuths key normalization", () => {
         ]);
       },
       {
-        env: {
-          MINIMAX_API_KEY: undefined,
-          MINIMAX_CODE_PLAN_KEY: undefined,
-          XIAOMI_API_KEY: undefined,
-        },
+        MINIMAX_API_KEY: undefined,
+        MINIMAX_CODE_PLAN_KEY: undefined,
+        XIAOMI_API_KEY: undefined,
       },
     );
   });
diff --git a/src/infra/session-cost-usage.ts b/src/infra/session-cost-usage.ts
index 4dd1203f91e..e4e64a4c6e2 100644
--- a/src/infra/session-cost-usage.ts
+++ b/src/infra/session-cost-usage.ts
@@ -212,39 +212,52 @@ const applyCostTotal = (totals: CostUsageTotals, costTotal: number | undefined)
   totals.totalCost += costTotal;
 };
 
+async function* readJsonlRecords(filePath: string): AsyncGenerator<Record<string, unknown>> {
+  const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
+  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(trimmed) as unknown;
+        if (!parsed || typeof parsed !== "object") {
+          continue;
+        }
+        yield parsed as Record<string, unknown>;
+      } catch {
+        // Ignore malformed lines
+      }
+    }
+  } finally {
+    rl.close();
+    fileStream.destroy();
+  }
+}
+
 async function scanTranscriptFile(params: {
   filePath: string;
   config?: OpenClawConfig;
   onEntry: (entry: ParsedTranscriptEntry) => void;
 }): Promise<void> {
-  const fileStream = fs.createReadStream(params.filePath, { encoding: "utf-8" });
-  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-
-  for await (const line of rl) {
-    const trimmed = line.trim();
-    if (!trimmed) {
+  for await (const parsed of readJsonlRecords(params.filePath)) {
+    const entry = parseTranscriptEntry(parsed);
+    if (!entry) {
       continue;
     }
-    try {
-      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
-      const entry = parseTranscriptEntry(parsed);
-      if (!entry) {
-        continue;
-      }
 
-      if (entry.usage && entry.costTotal === undefined) {
-        const cost = resolveModelCostConfig({
-          provider: entry.provider,
-          model: entry.model,
-          config: params.config,
-        });
-        entry.costTotal = estimateUsageCost({ usage: entry.usage, cost });
-      }
-
-      params.onEntry(entry);
-    } catch {
-      // Ignore malformed lines
+    if (entry.usage && entry.costTotal === undefined) {
+      const cost = resolveModelCostConfig({
+        provider: entry.provider,
+        model: entry.model,
+        config: params.config,
+      });
+      entry.costTotal = estimateUsageCost({ usage: entry.usage, cost });
     }
+
+    params.onEntry(entry);
   }
 }
 
@@ -400,16 +413,8 @@ export async function discoverAllSessions(params?: {
     // Try to read first user message for label extraction
     let firstUserMessage: string | undefined;
     try {
-      const fileStream = fs.createReadStream(filePath, { encoding: "utf-8" });
-      const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-
-      for await (const line of rl) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-          continue;
-        }
+      for await (const parsed of readJsonlRecords(filePath)) {
         try {
-          const parsed = JSON.parse(trimmed) as Record<string, unknown>;
           const message = parsed.message as Record<string, unknown> | undefined;
           if (message?.role === "user") {
             const content = message.content;
@@ -436,8 +441,6 @@ export async function discoverAllSessions(params?: {
           // Skip malformed lines
         }
       }
-      rl.close();
-      fileStream.destroy();
     } catch {
       // Ignore read errors
     }
@@ -831,16 +834,8 @@ export async function loadSessionLogs(params: {
   const logs: SessionLogEntry[] = [];
   const limit = params.limit ?? 50;
 
-  const fileStream = fs.createReadStream(sessionFile, { encoding: "utf-8" });
-  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-
-  for await (const line of rl) {
-    const trimmed = line.trim();
-    if (!trimmed) {
-      continue;
-    }
+  for await (const parsed of readJsonlRecords(sessionFile)) {
     try {
-      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
       const message = parsed.message as Record<string, unknown> | undefined;
       if (!message) {
         continue;
diff --git a/src/infra/state-migrations.ts b/src/infra/state-migrations.ts
index 9bec6f57892..7b570935a1d 100644
--- a/src/infra/state-migrations.ts
+++ b/src/infra/state-migrations.ts
@@ -20,6 +20,7 @@ import {
   DEFAULT_MAIN_KEY,
   normalizeAgentId,
 } from "../routing/session-key.js";
+import { isWithinDir } from "./path-safety.js";
 import {
   ensureDir,
   existsDir,
@@ -54,6 +55,11 @@ export type LegacyStateDetection = {
     targetDir: string;
     hasLegacy: boolean;
   };
+  pairingAllowFrom: {
+    legacyTelegramPath: string;
+    targetTelegramPath: string;
+    hasLegacyTelegram: boolean;
+  };
   preview: string[];
 };
 
@@ -360,11 +366,6 @@ function isDirPath(filePath: string): boolean {
   }
 }
 
-function isWithinDir(targetPath: string, rootDir: string): boolean {
-  const relative = path.relative(path.resolve(rootDir), path.resolve(targetPath));
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function isLegacyTreeSymlinkMirror(currentDir: string, realTargetDir: string): boolean {
   let entries: fs.Dirent[];
   try {
@@ -395,7 +396,7 @@ function isLegacyTreeSymlinkMirror(currentDir: string, realTargetDir: string): b
       } catch {
         return false;
       }
-      if (!isWithinDir(resolvedRealTarget, realTargetDir)) {
+      if (!isWithinDir(realTargetDir, resolvedRealTarget)) {
         return false;
       }
       continue;
@@ -616,6 +617,13 @@ export async function detectLegacyStateMigrations(params: {
   const hasLegacyWhatsAppAuth =
     fileExists(path.join(oauthDir, "creds.json")) &&
     !fileExists(path.join(targetWhatsAppAuthDir, "creds.json"));
+  const legacyTelegramAllowFromPath = path.join(oauthDir, "telegram-allowFrom.json");
+  const targetTelegramAllowFromPath = path.join(
+    oauthDir,
+    `telegram-${DEFAULT_ACCOUNT_ID}-allowFrom.json`,
+  );
+  const hasLegacyTelegramAllowFrom =
+    fileExists(legacyTelegramAllowFromPath) && !fileExists(targetTelegramAllowFromPath);
 
   const preview: string[] = [];
   if (hasLegacySessions) {
@@ -630,6 +638,11 @@ export async function detectLegacyStateMigrations(params: {
   if (hasLegacyWhatsAppAuth) {
     preview.push(`- WhatsApp auth: ${oauthDir} → ${targetWhatsAppAuthDir} (keep oauth.json)`);
   }
+  if (hasLegacyTelegramAllowFrom) {
+    preview.push(
+      `- Telegram pairing allowFrom: ${legacyTelegramAllowFromPath} → ${targetTelegramAllowFromPath}`,
+    );
+  }
 
   return {
     targetAgentId,
@@ -655,6 +668,11 @@ export async function detectLegacyStateMigrations(params: {
       targetDir: targetWhatsAppAuthDir,
       hasLegacy: hasLegacyWhatsAppAuth,
     },
+    pairingAllowFrom: {
+      legacyTelegramPath: legacyTelegramAllowFromPath,
+      targetTelegramPath: targetTelegramAllowFromPath,
+      hasLegacyTelegram: hasLegacyTelegramAllowFrom,
+    },
     preview,
   };
 }
@@ -871,6 +889,28 @@ async function migrateLegacyWhatsAppAuth(
   return { changes, warnings };
 }
 
+async function migrateLegacyTelegramPairingAllowFrom(
+  detected: LegacyStateDetection,
+): Promise<{ changes: string[]; warnings: string[] }> {
+  const changes: string[] = [];
+  const warnings: string[] = [];
+  if (!detected.pairingAllowFrom.hasLegacyTelegram) {
+    return { changes, warnings };
+  }
+
+  const legacyPath = detected.pairingAllowFrom.legacyTelegramPath;
+  const targetPath = detected.pairingAllowFrom.targetTelegramPath;
+  try {
+    ensureDir(path.dirname(targetPath));
+    fs.copyFileSync(legacyPath, targetPath);
+    changes.push(`Copied Telegram pairing allowFrom → ${targetPath}`);
+  } catch (err) {
+    warnings.push(`Failed migrating Telegram pairing allowFrom (${legacyPath}): ${String(err)}`);
+  }
+
+  return { changes, warnings };
+}
+
 export async function runLegacyStateMigrations(params: {
   detected: LegacyStateDetection;
   now?: () => number;
@@ -880,9 +920,20 @@ export async function runLegacyStateMigrations(params: {
   const sessions = await migrateLegacySessions(detected, now);
   const agentDir = await migrateLegacyAgentDir(detected, now);
   const whatsappAuth = await migrateLegacyWhatsAppAuth(detected);
+  const telegramPairingAllowFrom = await migrateLegacyTelegramPairingAllowFrom(detected);
   return {
-    changes: [...sessions.changes, ...agentDir.changes, ...whatsappAuth.changes],
-    warnings: [...sessions.warnings, ...agentDir.warnings, ...whatsappAuth.warnings],
+    changes: [
+      ...sessions.changes,
+      ...agentDir.changes,
+      ...whatsappAuth.changes,
+      ...telegramPairingAllowFrom.changes,
+    ],
+    warnings: [
+      ...sessions.warnings,
+      ...agentDir.warnings,
+      ...whatsappAuth.warnings,
+      ...telegramPairingAllowFrom.warnings,
+    ],
   };
 }
 
diff --git a/src/infra/system-events.test.ts b/src/infra/system-events.test.ts
index 03a39cd9e73..9175d45c700 100644
--- a/src/infra/system-events.test.ts
+++ b/src/infra/system-events.test.ts
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { prependSystemEvents } from "../auto-reply/reply/session-updates.js";
 import { resolveMainSessionKey } from "../config/sessions.js";
+import { isCronSystemEvent } from "./heartbeat-runner.js";
 import { enqueueSystemEvent, peekSystemEvents, resetSystemEventsForTest } from "./system-events.js";
 
 const cfg = {} as unknown as OpenClawConfig;
@@ -46,3 +47,32 @@ describe("system events (session routing)", () => {
     expect(() => enqueueSystemEvent("Node: Mac Studio", { sessionKey: " " })).toThrow("sessionKey");
   });
 });
+
+describe("isCronSystemEvent", () => {
+  it("returns false for empty entries", () => {
+    expect(isCronSystemEvent("")).toBe(false);
+    expect(isCronSystemEvent("   ")).toBe(false);
+  });
+
+  it("returns false for heartbeat ack markers", () => {
+    expect(isCronSystemEvent("HEARTBEAT_OK")).toBe(false);
+    expect(isCronSystemEvent("HEARTBEAT_OK 🦞")).toBe(false);
+    expect(isCronSystemEvent("heartbeat_ok")).toBe(false);
+    expect(isCronSystemEvent("HEARTBEAT_OK:")).toBe(false);
+    expect(isCronSystemEvent("HEARTBEAT_OK, continue")).toBe(false);
+  });
+
+  it("returns false for heartbeat poll and wake noise", () => {
+    expect(isCronSystemEvent("heartbeat poll: pending")).toBe(false);
+    expect(isCronSystemEvent("heartbeat wake complete")).toBe(false);
+  });
+
+  it("returns false for exec completion events", () => {
+    expect(isCronSystemEvent("Exec finished (gateway id=abc, code 0)")).toBe(false);
+  });
+
+  it("returns true for real cron reminder content", () => {
+    expect(isCronSystemEvent("Reminder: Check Base Scout results")).toBe(true);
+    expect(isCronSystemEvent("Send weekly status update to the team")).toBe(true);
+  });
+});
diff --git a/src/infra/tailnet.ts b/src/infra/tailnet.ts
index ed666b86848..ed2384cfeb0 100644
--- a/src/infra/tailnet.ts
+++ b/src/infra/tailnet.ts
@@ -5,7 +5,7 @@ export type TailnetAddresses = {
   ipv6: string[];
 };
 
-function isTailnetIPv4(address: string): boolean {
+export function isTailnetIPv4(address: string): boolean {
   const parts = address.split(".");
   if (parts.length !== 4) {
     return false;
diff --git a/src/infra/tls/fingerprint.test.ts b/src/infra/tls/fingerprint.test.ts
deleted file mode 100644
index 7e0f99ec6da..00000000000
--- a/src/infra/tls/fingerprint.test.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeFingerprint } from "./fingerprint.js";
-
-describe("normalizeFingerprint", () => {
-  it("strips sha256 prefixes and separators", () => {
-    expect(normalizeFingerprint("sha256:AA:BB:cc")).toBe("aabbcc");
-    expect(normalizeFingerprint("SHA-256 11-22-33")).toBe("112233");
-    expect(normalizeFingerprint("aa:bb:cc")).toBe("aabbcc");
-  });
-});
diff --git a/src/infra/transport-ready.test.ts b/src/infra/transport-ready.test.ts
index 2df90a6420e..f2b8d770aa0 100644
--- a/src/infra/transport-ready.test.ts
+++ b/src/infra/transport-ready.test.ts
@@ -1,6 +1,17 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { waitForTransportReady } from "./transport-ready.js";
 
+// Perf: `sleepWithAbort` uses `node:timers/promises` which isn't controlled by fake timers.
+// Route sleeps through global `setTimeout` so tests can advance time deterministically.
+vi.mock("./backoff.js", () => ({
+  sleepWithAbort: async (ms: number) => {
+    if (ms <= 0) {
+      return;
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, ms));
+  },
+}));
+
 describe("waitForTransportReady", () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -16,7 +27,8 @@ describe("waitForTransportReady", () => {
     const readyPromise = waitForTransportReady({
       label: "test transport",
       timeoutMs: 220,
-      logAfterMs: 60,
+      // Deterministic: first attempt at t=0 won't log; second attempt at t=50 will.
+      logAfterMs: 1,
       logIntervalMs: 1_000,
       pollIntervalMs: 50,
       runtime,
@@ -29,9 +41,7 @@ describe("waitForTransportReady", () => {
       },
     });
 
-    for (let i = 0; i < 3; i += 1) {
-      await vi.advanceTimersByTimeAsync(50);
-    }
+    await vi.advanceTimersByTimeAsync(200);
 
     await readyPromise;
     expect(runtime.error).toHaveBeenCalled();
@@ -48,8 +58,9 @@ describe("waitForTransportReady", () => {
       runtime,
       check: async () => ({ ok: false, error: "still down" }),
     });
+    const asserted = expect(waitPromise).rejects.toThrow("test transport not ready");
     await vi.advanceTimersByTimeAsync(200);
-    await expect(waitPromise).rejects.toThrow("test transport not ready");
+    await asserted;
     expect(runtime.error).toHaveBeenCalled();
   });
 
diff --git a/src/infra/update-runner.ts b/src/infra/update-runner.ts
index 46bbf8a19fd..4e84cea4073 100644
--- a/src/infra/update-runner.ts
+++ b/src/infra/update-runner.ts
@@ -7,6 +7,7 @@ import {
   resolveControlUiDistIndexPathForRoot,
 } from "./control-ui-assets.js";
 import { detectPackageManager as detectPackageManagerImpl } from "./detect-package-manager.js";
+import { readPackageName, readPackageVersion } from "./package-json.js";
 import { trimLogTail } from "./restart-sentinel.js";
 import {
   channelToNpmTag,
@@ -131,27 +132,6 @@ function buildStartDirs(opts: UpdateRunnerOptions): string[] {
   return Array.from(new Set(dirs));
 }
 
-async function readPackageVersion(root: string) {
-  try {
-    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { version?: string };
-    return typeof parsed?.version === "string" ? parsed.version : null;
-  } catch {
-    return null;
-  }
-}
-
-async function readPackageName(root: string) {
-  try {
-    const raw = await fs.readFile(path.join(root, "package.json"), "utf-8");
-    const parsed = JSON.parse(raw) as { name?: string };
-    const name = parsed?.name?.trim();
-    return name ? name : null;
-  } catch {
-    return null;
-  }
-}
-
 async function readBranchName(
   runCommand: CommandRunner,
   root: string,
@@ -411,6 +391,23 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
     const branch = channel === "dev" ? await readBranchName(runCommand, gitRoot, timeoutMs) : null;
     const needsCheckoutMain = channel === "dev" && branch !== DEV_BRANCH;
     gitTotalSteps = channel === "dev" ? (needsCheckoutMain ? 11 : 10) : 9;
+    const buildGitErrorResult = (reason: string): UpdateRunResult => ({
+      status: "error",
+      mode: "git",
+      root: gitRoot,
+      reason,
+      before: { sha: beforeSha, version: beforeVersion },
+      steps,
+      durationMs: Date.now() - startedAt,
+    });
+    const runGitCheckoutOrFail = async (name: string, argv: string[]) => {
+      const checkoutStep = await runStep(step(name, argv, gitRoot));
+      steps.push(checkoutStep);
+      if (checkoutStep.exitCode !== 0) {
+        return buildGitErrorResult("checkout-failed");
+      }
+      return null;
+    };
 
     const statusCheck = await runStep(
       step(
@@ -436,24 +433,15 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
 
     if (channel === "dev") {
       if (needsCheckoutMain) {
-        const checkoutStep = await runStep(
-          step(
-            `git checkout ${DEV_BRANCH}`,
-            ["git", "-C", gitRoot, "checkout", DEV_BRANCH],
-            gitRoot,
-          ),
-        );
-        steps.push(checkoutStep);
-        if (checkoutStep.exitCode !== 0) {
-          return {
-            status: "error",
-            mode: "git",
-            root: gitRoot,
-            reason: "checkout-failed",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
+        const failure = await runGitCheckoutOrFail(`git checkout ${DEV_BRANCH}`, [
+          "git",
+          "-C",
+          gitRoot,
+          "checkout",
+          DEV_BRANCH,
+        ]);
+        if (failure) {
+          return failure;
         }
       }
 
@@ -700,20 +688,16 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
         };
       }
 
-      const checkoutStep = await runStep(
-        step(`git checkout ${tag}`, ["git", "-C", gitRoot, "checkout", "--detach", tag], gitRoot),
-      );
-      steps.push(checkoutStep);
-      if (checkoutStep.exitCode !== 0) {
-        return {
-          status: "error",
-          mode: "git",
-          root: gitRoot,
-          reason: "checkout-failed",
-          before: { sha: beforeSha, version: beforeVersion },
-          steps,
-          durationMs: Date.now() - startedAt,
-        };
+      const failure = await runGitCheckoutOrFail(`git checkout ${tag}`, [
+        "git",
+        "-C",
+        gitRoot,
+        "checkout",
+        "--detach",
+        tag,
+      ]);
+      if (failure) {
+        return failure;
       }
     }
 
diff --git a/src/infra/voicewake.ts b/src/infra/voicewake.ts
index 9d0867a0a00..ee73c8e40a4 100644
--- a/src/infra/voicewake.ts
+++ b/src/infra/voicewake.ts
@@ -1,7 +1,6 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
+import { createAsyncLock, readJsonFile, writeJsonAtomic } from "./json-files.js";
 
 export type VoiceWakeConfig = {
   triggers: string[];
@@ -22,37 +21,7 @@ function sanitizeTriggers(triggers: string[] | undefined | null): string[] {
   return cleaned.length > 0 ? cleaned : DEFAULT_TRIGGERS;
 }
 
-async function readJSON<T>(filePath: string): Promise<T | null> {
-  try {
-    const raw = await fs.readFile(filePath, "utf8");
-    return JSON.parse(raw) as T;
-  } catch {
-    return null;
-  }
-}
-
-async function writeJSONAtomic(filePath: string, value: unknown) {
-  const dir = path.dirname(filePath);
-  await fs.mkdir(dir, { recursive: true });
-  const tmp = `${filePath}.${randomUUID()}.tmp`;
-  await fs.writeFile(tmp, JSON.stringify(value, null, 2), "utf8");
-  await fs.rename(tmp, filePath);
-}
-
-let lock: Promise<void> = Promise.resolve();
-async function withLock<T>(fn: () => Promise<T>): Promise<T> {
-  const prev = lock;
-  let release: (() => void) | undefined;
-  lock = new Promise<void>((resolve) => {
-    release = resolve;
-  });
-  await prev;
-  try {
-    return await fn();
-  } finally {
-    release?.();
-  }
-}
+const withLock = createAsyncLock();
 
 export function defaultVoiceWakeTriggers() {
   return [...DEFAULT_TRIGGERS];
@@ -60,7 +29,7 @@ export function defaultVoiceWakeTriggers() {
 
 export async function loadVoiceWakeConfig(baseDir?: string): Promise<VoiceWakeConfig> {
   const filePath = resolvePath(baseDir);
-  const existing = await readJSON<VoiceWakeConfig>(filePath);
+  const existing = await readJsonFile<VoiceWakeConfig>(filePath);
   if (!existing) {
     return { triggers: defaultVoiceWakeTriggers(), updatedAtMs: 0 };
   }
@@ -84,7 +53,7 @@ export async function setVoiceWakeTriggers(
       triggers: sanitized,
       updatedAtMs: Date.now(),
     };
-    await writeJSONAtomic(filePath, next);
+    await writeJsonAtomic(filePath, next);
     return next;
   });
 }
diff --git a/src/line/accounts.test.ts b/src/line/accounts.test.ts
index 3330d052391..c74841b219f 100644
--- a/src/line/accounts.test.ts
+++ b/src/line/accounts.test.ts
@@ -2,7 +2,6 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
   resolveLineAccount,
-  listLineAccountIds,
   resolveDefaultLineAccountId,
   normalizeAccountId,
   DEFAULT_ACCOUNT_ID,
@@ -100,64 +99,7 @@ describe("LINE accounts", () => {
     });
   });
 
-  describe("listLineAccountIds", () => {
-    it("returns default account when configured at base level", () => {
-      const cfg: OpenClawConfig = {
-        channels: {
-          line: {
-            channelAccessToken: "test-token",
-          },
-        },
-      };
-
-      const ids = listLineAccountIds(cfg);
-
-      expect(ids).toContain(DEFAULT_ACCOUNT_ID);
-    });
-
-    it("returns named accounts", () => {
-      const cfg: OpenClawConfig = {
-        channels: {
-          line: {
-            accounts: {
-              business: { enabled: true },
-              personal: { enabled: true },
-            },
-          },
-        },
-      };
-
-      const ids = listLineAccountIds(cfg);
-
-      expect(ids).toContain("business");
-      expect(ids).toContain("personal");
-    });
-
-    it("returns default from env", () => {
-      process.env.LINE_CHANNEL_ACCESS_TOKEN = "env-token";
-      const cfg: OpenClawConfig = {};
-
-      const ids = listLineAccountIds(cfg);
-
-      expect(ids).toContain(DEFAULT_ACCOUNT_ID);
-    });
-  });
-
   describe("resolveDefaultLineAccountId", () => {
-    it("returns default when configured", () => {
-      const cfg: OpenClawConfig = {
-        channels: {
-          line: {
-            channelAccessToken: "test-token",
-          },
-        },
-      };
-
-      const id = resolveDefaultLineAccountId(cfg);
-
-      expect(id).toBe(DEFAULT_ACCOUNT_ID);
-    });
-
     it("returns first named account when default not configured", () => {
       const cfg: OpenClawConfig = {
         channels: {
@@ -176,24 +118,8 @@ describe("LINE accounts", () => {
   });
 
   describe("normalizeAccountId", () => {
-    it("normalizes undefined to default", () => {
-      expect(normalizeAccountId(undefined)).toBe(DEFAULT_ACCOUNT_ID);
-    });
-
-    it("normalizes 'default' to DEFAULT_ACCOUNT_ID", () => {
-      expect(normalizeAccountId("default")).toBe(DEFAULT_ACCOUNT_ID);
-    });
-
-    it("preserves other account ids", () => {
-      expect(normalizeAccountId("business")).toBe("business");
-    });
-
-    it("lowercases account ids", () => {
-      expect(normalizeAccountId("Business")).toBe("business");
-    });
-
-    it("trims whitespace", () => {
-      expect(normalizeAccountId("  business  ")).toBe("business");
+    it("trims and lowercases account ids", () => {
+      expect(normalizeAccountId("  Business  ")).toBe("business");
     });
   });
 });
diff --git a/src/line/auto-reply-delivery.ts b/src/line/auto-reply-delivery.ts
index c303382f9b2..aa5443a536e 100644
--- a/src/line/auto-reply-delivery.ts
+++ b/src/line/auto-reply-delivery.ts
@@ -2,7 +2,7 @@ import type { messagingApi } from "@line/bot-sdk";
 import type { ReplyPayload } from "../auto-reply/types.js";
 import type { FlexContainer } from "./flex-templates.js";
 import type { ProcessedLineMessage } from "./markdown-to-line.js";
-import type { LineReplyMessage, SendLineReplyChunksParams } from "./reply-chunks.js";
+import type { SendLineReplyChunksParams } from "./reply-chunks.js";
 import type { LineChannelData, LineTemplateMessagePayload } from "./types.js";
 
 export type LineAutoReplyDeps = {
@@ -12,19 +12,6 @@ export type LineAutoReplyDeps = {
   processLineMessage: (text: string) => ProcessedLineMessage;
   chunkMarkdownText: (text: string, limit: number) => string[];
   sendLineReplyChunks: (params: SendLineReplyChunksParams) => Promise<{ replyTokenUsed: boolean }>;
-  replyMessageLine: (
-    replyToken: string,
-    messages: messagingApi.Message[],
-    opts?: { accountId?: string },
-  ) => Promise<unknown>;
-  pushMessageLine: (to: string, text: string, opts?: { accountId?: string }) => Promise<unknown>;
-  pushTextMessageWithQuickReplies: (
-    to: string,
-    text: string,
-    quickReplies: string[],
-    opts?: { accountId?: string },
-  ) => Promise<unknown>;
-  createTextMessageWithQuickReplies: (text: string, quickReplies: string[]) => LineReplyMessage;
   createQuickReplyItems: (labels: string[]) => messagingApi.QuickReply;
   pushMessagesLine: (
     to: string,
@@ -42,8 +29,14 @@ export type LineAutoReplyDeps = {
     latitude: number;
     longitude: number;
   }) => messagingApi.LocationMessage;
-  onReplyError?: (err: unknown) => void;
-};
+} & Pick<
+  SendLineReplyChunksParams,
+  | "replyMessageLine"
+  | "pushMessageLine"
+  | "pushTextMessageWithQuickReplies"
+  | "createTextMessageWithQuickReplies"
+  | "onReplyError"
+>;
 
 export async function deliverLineAutoReply(params: {
   payload: ReplyPayload;
diff --git a/src/line/bot-handlers.test.ts b/src/line/bot-handlers.test.ts
index dda3201d9fe..bf4c108a5d5 100644
--- a/src/line/bot-handlers.test.ts
+++ b/src/line/bot-handlers.test.ts
@@ -45,6 +45,17 @@ const { buildLineMessageContextMock, buildLinePostbackContextMock } = vi.hoisted
 vi.mock("./bot-message-context.js", () => ({
   buildLineMessageContext: (...args: unknown[]) => buildLineMessageContextMock(...args),
   buildLinePostbackContext: (...args: unknown[]) => buildLinePostbackContextMock(...args),
+  getLineSourceInfo: (source: {
+    type?: string;
+    userId?: string;
+    groupId?: string;
+    roomId?: string;
+  }) => ({
+    userId: source.userId,
+    groupId: source.type === "group" ? source.groupId : undefined,
+    roomId: source.type === "room" ? source.roomId : undefined,
+    isGroup: source.type === "group" || source.type === "room",
+  }),
 }));
 
 const { readAllowFromStoreMock, upsertPairingRequestMock } = vi.hoisted(() => ({
diff --git a/src/line/bot-handlers.ts b/src/line/bot-handlers.ts
index 757c8c180e5..d56e62549bb 100644
--- a/src/line/bot-handlers.ts
+++ b/src/line/bot-handlers.ts
@@ -6,7 +6,6 @@ import type {
   JoinEvent,
   LeaveEvent,
   PostbackEvent,
-  EventSource,
 } from "@line/bot-sdk";
 import type { OpenClawConfig } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
@@ -20,6 +19,7 @@ import {
 } from "../pairing/pairing-store.js";
 import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore } from "./bot-access.js";
 import {
+  getLineSourceInfo,
   buildLineMessageContext,
   buildLinePostbackContext,
   type LineInboundContext,
@@ -40,28 +40,6 @@ export interface LineHandlerContext {
   processMessage: (ctx: LineInboundContext) => Promise<void>;
 }
 
-type LineSourceInfo = {
-  userId?: string;
-  groupId?: string;
-  roomId?: string;
-  isGroup: boolean;
-};
-
-function getSourceInfo(source: EventSource): LineSourceInfo {
-  const userId =
-    source.type === "user"
-      ? source.userId
-      : source.type === "group"
-        ? source.userId
-        : source.type === "room"
-          ? source.userId
-          : undefined;
-  const groupId = source.type === "group" ? source.groupId : undefined;
-  const roomId = source.type === "room" ? source.roomId : undefined;
-  const isGroup = source.type === "group" || source.type === "room";
-  return { userId, groupId, roomId, isGroup };
-}
-
 function resolveLineGroupConfig(params: {
   config: ResolvedLineAccount["config"];
   groupId?: string;
@@ -129,7 +107,7 @@ async function shouldProcessLineEvent(
   context: LineHandlerContext,
 ): Promise<boolean> {
   const { cfg, account } = context;
-  const { userId, groupId, roomId, isGroup } = getSourceInfo(event.source);
+  const { userId, groupId, roomId, isGroup } = getLineSourceInfo(event.source);
   const senderId = userId ?? "";
 
   const storeAllowFrom = await readChannelAllowFromStore("line").catch(() => []);
diff --git a/src/line/bot-message-context.ts b/src/line/bot-message-context.ts
index 51b1a5704d4..7381a9f5076 100644
--- a/src/line/bot-message-context.ts
+++ b/src/line/bot-message-context.ts
@@ -26,12 +26,14 @@ interface BuildLineMessageContextParams {
   account: ResolvedLineAccount;
 }
 
-function getSourceInfo(source: EventSource): {
+export type LineSourceInfo = {
   userId?: string;
   groupId?: string;
   roomId?: string;
   isGroup: boolean;
-} {
+};
+
+export function getLineSourceInfo(source: EventSource): LineSourceInfo {
   const userId =
     source.type === "user"
       ? source.userId
@@ -78,7 +80,7 @@ function resolveLineInboundRoute(params: {
     direction: "inbound",
   });
 
-  const { userId, groupId, roomId, isGroup } = getSourceInfo(params.source);
+  const { userId, groupId, roomId, isGroup } = getLineSourceInfo(params.source);
   const peerId = buildPeerId(params.source);
   const route = resolveAgentRoute({
     cfg: params.cfg,
@@ -170,7 +172,7 @@ function extractMediaPlaceholder(message: MessageEvent["message"]): string {
 }
 
 type LineRouteInfo = ReturnType<typeof resolveAgentRoute>;
-type LineSourceInfo = ReturnType<typeof getSourceInfo> & { peerId: string };
+type LineSourceInfoWithPeerId = LineSourceInfo & { peerId: string };
 
 function resolveLineConversationLabel(params: {
   isGroup: boolean;
@@ -211,7 +213,7 @@ async function finalizeLineInboundContext(params: {
   account: ResolvedLineAccount;
   event: MessageEvent | PostbackEvent;
   route: LineRouteInfo;
-  source: LineSourceInfo;
+  source: LineSourceInfoWithPeerId;
   rawBody: string;
   timestamp: number;
   messageSid: string;
diff --git a/src/line/config-schema.ts b/src/line/config-schema.ts
index 55804f81e5c..7e1af506ae0 100644
--- a/src/line/config-schema.ts
+++ b/src/line/config-schema.ts
@@ -3,6 +3,22 @@ import { z } from "zod";
 const DmPolicySchema = z.enum(["open", "allowlist", "pairing", "disabled"]);
 const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
 
+const LineCommonConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  channelAccessToken: z.string().optional(),
+  channelSecret: z.string().optional(),
+  tokenFile: z.string().optional(),
+  secretFile: z.string().optional(),
+  name: z.string().optional(),
+  allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  dmPolicy: DmPolicySchema.optional().default("pairing"),
+  groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+  responsePrefix: z.string().optional(),
+  mediaMaxMb: z.number().optional(),
+  webhookPath: z.string().optional(),
+});
+
 const LineGroupConfigSchema = z
   .object({
     enabled: z.boolean().optional(),
@@ -13,43 +29,13 @@ const LineGroupConfigSchema = z
   })
   .strict();
 
-const LineAccountConfigSchema = z
-  .object({
-    enabled: z.boolean().optional(),
-    channelAccessToken: z.string().optional(),
-    channelSecret: z.string().optional(),
-    tokenFile: z.string().optional(),
-    secretFile: z.string().optional(),
-    name: z.string().optional(),
-    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
-    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
-    dmPolicy: DmPolicySchema.optional().default("pairing"),
-    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
-    responsePrefix: z.string().optional(),
-    mediaMaxMb: z.number().optional(),
-    webhookPath: z.string().optional(),
-    groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
-  })
-  .strict();
+const LineAccountConfigSchema = LineCommonConfigSchema.extend({
+  groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
+}).strict();
 
-export const LineConfigSchema = z
-  .object({
-    enabled: z.boolean().optional(),
-    channelAccessToken: z.string().optional(),
-    channelSecret: z.string().optional(),
-    tokenFile: z.string().optional(),
-    secretFile: z.string().optional(),
-    name: z.string().optional(),
-    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
-    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
-    dmPolicy: DmPolicySchema.optional().default("pairing"),
-    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
-    responsePrefix: z.string().optional(),
-    mediaMaxMb: z.number().optional(),
-    webhookPath: z.string().optional(),
-    accounts: z.record(z.string(), LineAccountConfigSchema.optional()).optional(),
-    groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
-  })
-  .strict();
+export const LineConfigSchema = LineCommonConfigSchema.extend({
+  accounts: z.record(z.string(), LineAccountConfigSchema.optional()).optional(),
+  groups: z.record(z.string(), LineGroupConfigSchema.optional()).optional(),
+}).strict();
 
 export type LineConfigSchemaType = z.infer<typeof LineConfigSchema>;
diff --git a/src/line/flex-templates.test.ts b/src/line/flex-templates.test.ts
index cfaa2297e22..fe5e168e34c 100644
--- a/src/line/flex-templates.test.ts
+++ b/src/line/flex-templates.test.ts
@@ -5,49 +5,20 @@ import {
   createImageCard,
   createActionCard,
   createCarousel,
-  createNotificationBubble,
-  createReceiptCard,
   createEventCard,
-  createAgendaCard,
-  createMediaPlayerCard,
-  createAppleTvRemoteCard,
   createDeviceControlCard,
-  toFlexMessage,
 } from "./flex-templates.js";
 
 describe("createInfoCard", () => {
-  it("creates a bubble with title and body", () => {
-    const card = createInfoCard("Test Title", "Test body content");
-
-    expect(card.type).toBe("bubble");
-    expect(card.size).toBe("mega");
-    expect(card.body).toBeDefined();
-    expect(card.body?.type).toBe("box");
-  });
-
   it("includes footer when provided", () => {
     const card = createInfoCard("Title", "Body", "Footer text");
 
-    expect(card.footer).toBeDefined();
     const footer = card.footer as { contents: Array<{ text: string }> };
     expect(footer.contents[0].text).toBe("Footer text");
   });
-
-  it("omits footer when not provided", () => {
-    const card = createInfoCard("Title", "Body");
-    expect(card.footer).toBeUndefined();
-  });
 });
 
 describe("createListCard", () => {
-  it("creates a list with title and items", () => {
-    const items = [{ title: "Item 1", subtitle: "Description 1" }, { title: "Item 2" }];
-    const card = createListCard("My List", items);
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-
   it("limits items to 8", () => {
     const items = Array.from({ length: 15 }, (_, i) => ({ title: `Item ${i}` }));
     const card = createListCard("List", items);
@@ -57,28 +28,9 @@ describe("createListCard", () => {
     const listBox = body.contents[2] as { contents: unknown[] };
     expect(listBox.contents.length).toBe(8);
   });
-
-  it("includes actions on items when provided", () => {
-    const items = [
-      {
-        title: "Clickable",
-        action: { type: "message" as const, label: "Click", text: "clicked" },
-      },
-    ];
-    const card = createListCard("List", items);
-    expect(card.body).toBeDefined();
-  });
 });
 
 describe("createImageCard", () => {
-  it("creates a card with hero image", () => {
-    const card = createImageCard("https://example.com/image.jpg", "Image Title");
-
-    expect(card.type).toBe("bubble");
-    expect(card.hero).toBeDefined();
-    expect((card.hero as { url: string }).url).toBe("https://example.com/image.jpg");
-  });
-
   it("includes body text when provided", () => {
     const card = createImageCard("https://example.com/img.jpg", "Title", "Body text");
 
@@ -86,34 +38,9 @@ describe("createImageCard", () => {
     expect(body.contents.length).toBe(2);
     expect(body.contents[1].text).toBe("Body text");
   });
-
-  it("applies custom aspect ratio", () => {
-    const card = createImageCard("https://example.com/img.jpg", "Title", undefined, {
-      aspectRatio: "16:9",
-    });
-
-    expect((card.hero as { aspectRatio: string }).aspectRatio).toBe("16:9");
-  });
 });
 
 describe("createActionCard", () => {
-  it("creates a card with action buttons", () => {
-    const actions = [
-      { label: "Action 1", action: { type: "message" as const, label: "Act1", text: "action1" } },
-      {
-        label: "Action 2",
-        action: { type: "uri" as const, label: "Act2", uri: "https://example.com" },
-      },
-    ];
-    const card = createActionCard("Title", "Description", actions);
-
-    expect(card.type).toBe("bubble");
-    expect(card.footer).toBeDefined();
-
-    const footer = card.footer as { contents: Array<{ type: string }> };
-    expect(footer.contents.length).toBe(2);
-  });
-
   it("limits actions to 4", () => {
     const actions = Array.from({ length: 6 }, (_, i) => ({
       label: `Action ${i}`,
@@ -124,26 +51,9 @@ describe("createActionCard", () => {
     const footer = card.footer as { contents: unknown[] };
     expect(footer.contents.length).toBe(4);
   });
-
-  it("includes hero image when provided", () => {
-    const card = createActionCard("Title", "Body", [], {
-      imageUrl: "https://example.com/hero.jpg",
-    });
-
-    expect(card.hero).toBeDefined();
-    expect((card.hero as { url: string }).url).toBe("https://example.com/hero.jpg");
-  });
 });
 
 describe("createCarousel", () => {
-  it("creates a carousel from bubbles", () => {
-    const bubbles = [createInfoCard("Card 1", "Body 1"), createInfoCard("Card 2", "Body 2")];
-    const carousel = createCarousel(bubbles);
-
-    expect(carousel.type).toBe("carousel");
-    expect(carousel.contents.length).toBe(2);
-  });
-
   it("limits to 12 bubbles", () => {
     const bubbles = Array.from({ length: 15 }, (_, i) => createInfoCard(`Card ${i}`, `Body ${i}`));
     const carousel = createCarousel(bubbles);
@@ -152,159 +62,7 @@ describe("createCarousel", () => {
   });
 });
 
-describe("createNotificationBubble", () => {
-  it("creates a simple notification", () => {
-    const bubble = createNotificationBubble("Hello world");
-
-    expect(bubble.type).toBe("bubble");
-    expect(bubble.body).toBeDefined();
-  });
-
-  it("applies notification type styling", () => {
-    const successBubble = createNotificationBubble("Success!", { type: "success" });
-    const errorBubble = createNotificationBubble("Error!", { type: "error" });
-
-    expect(successBubble.body).toBeDefined();
-    expect(errorBubble.body).toBeDefined();
-  });
-
-  it("includes title when provided", () => {
-    const bubble = createNotificationBubble("Details here", {
-      title: "Alert Title",
-    });
-
-    expect(bubble.body).toBeDefined();
-  });
-});
-
-describe("createReceiptCard", () => {
-  it("creates a receipt with items", () => {
-    const card = createReceiptCard({
-      title: "Order Receipt",
-      items: [
-        { name: "Item A", value: "$10" },
-        { name: "Item B", value: "$20" },
-      ],
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes total when provided", () => {
-    const card = createReceiptCard({
-      title: "Receipt",
-      items: [{ name: "Item", value: "$10" }],
-      total: { label: "Total", value: "$10" },
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes footer when provided", () => {
-    const card = createReceiptCard({
-      title: "Receipt",
-      items: [{ name: "Item", value: "$10" }],
-      footer: "Thank you!",
-    });
-
-    expect(card.footer).toBeDefined();
-  });
-});
-
-describe("createMediaPlayerCard", () => {
-  it("creates a basic player card", () => {
-    const card = createMediaPlayerCard({
-      title: "Bohemian Rhapsody",
-      subtitle: "Queen",
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes album art when provided", () => {
-    const card = createMediaPlayerCard({
-      title: "Track Name",
-      imageUrl: "https://example.com/album.jpg",
-    });
-
-    expect(card.hero).toBeDefined();
-    expect((card.hero as { url: string }).url).toBe("https://example.com/album.jpg");
-  });
-
-  it("shows playing status", () => {
-    const card = createMediaPlayerCard({
-      title: "Track",
-      isPlaying: true,
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes playback controls", () => {
-    const card = createMediaPlayerCard({
-      title: "Track",
-      controls: {
-        previous: { data: "action=prev" },
-        play: { data: "action=play" },
-        pause: { data: "action=pause" },
-        next: { data: "action=next" },
-      },
-    });
-
-    expect(card.footer).toBeDefined();
-  });
-
-  it("includes extra actions", () => {
-    const card = createMediaPlayerCard({
-      title: "Track",
-      extraActions: [
-        { label: "Add to Playlist", data: "action=add_playlist" },
-        { label: "Share", data: "action=share" },
-      ],
-    });
-
-    expect(card.footer).toBeDefined();
-  });
-});
-
 describe("createDeviceControlCard", () => {
-  it("creates a device card with controls", () => {
-    const card = createDeviceControlCard({
-      deviceName: "Apple TV",
-      deviceType: "Streaming Box",
-      controls: [
-        { label: "Play/Pause", data: "action=playpause" },
-        { label: "Menu", data: "action=menu" },
-      ],
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-    expect(card.footer).toBeDefined();
-  });
-
-  it("shows device status", () => {
-    const card = createDeviceControlCard({
-      deviceName: "Apple TV",
-      status: "Playing",
-      controls: [{ label: "Pause", data: "action=pause" }],
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes device image", () => {
-    const card = createDeviceControlCard({
-      deviceName: "Device",
-      imageUrl: "https://example.com/device.jpg",
-      controls: [],
-    });
-
-    expect(card.hero).toBeDefined();
-  });
-
   it("limits controls to 6", () => {
     const card = createDeviceControlCard({
       deviceName: "Device",
@@ -314,80 +72,13 @@ describe("createDeviceControlCard", () => {
       })),
     });
 
-    expect(card.footer).toBeDefined();
     // Should have max 3 rows of 2 buttons
     const footer = card.footer as { contents: unknown[] };
     expect(footer.contents.length).toBeLessThanOrEqual(3);
   });
 });
 
-describe("createAppleTvRemoteCard", () => {
-  it("creates an Apple TV remote card with controls", () => {
-    const card = createAppleTvRemoteCard({
-      deviceName: "Apple TV",
-      status: "Playing",
-      actionData: {
-        up: "action=up",
-        down: "action=down",
-        left: "action=left",
-        right: "action=right",
-        select: "action=select",
-        menu: "action=menu",
-        home: "action=home",
-        play: "action=play",
-        pause: "action=pause",
-        volumeUp: "action=volume_up",
-        volumeDown: "action=volume_down",
-        mute: "action=mute",
-      },
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-});
-
 describe("createEventCard", () => {
-  it("creates an event card with required fields", () => {
-    const card = createEventCard({
-      title: "Team Meeting",
-      date: "January 24, 2026",
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes time when provided", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-      time: "2:00 PM - 3:00 PM",
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes location when provided", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-      location: "Conference Room A",
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes description when provided", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-      description: "Discuss Q1 roadmap",
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
   it("includes all optional fields together", () => {
     const card = createEventCard({
       title: "Team Offsite",
@@ -397,103 +88,8 @@ describe("createEventCard", () => {
       description: "Annual team building event",
     });
 
-    expect(card.type).toBe("bubble");
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes action when provided", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-      action: { type: "uri", label: "Join", uri: "https://meet.google.com/abc" },
-    });
-
-    expect(card.body).toBeDefined();
-    expect((card.body as { action?: unknown }).action).toBeDefined();
-  });
-
-  it("includes calendar name when provided", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-      calendar: "Work Calendar",
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("uses mega size for better readability", () => {
-    const card = createEventCard({
-      title: "Meeting",
-      date: "Jan 24",
-    });
-
     expect(card.size).toBe("mega");
-  });
-});
-
-describe("createAgendaCard", () => {
-  it("creates an agenda card with title and events", () => {
-    const card = createAgendaCard({
-      title: "Today's Schedule",
-      events: [
-        { title: "Team Meeting", time: "9:00 AM" },
-        { title: "Lunch", time: "12:00 PM" },
-      ],
-    });
-
-    expect(card.type).toBe("bubble");
-    expect(card.size).toBe("mega");
-    expect(card.body).toBeDefined();
-  });
-
-  it("limits events to 8", () => {
-    const manyEvents = Array.from({ length: 15 }, (_, i) => ({
-      title: `Event ${i + 1}`,
-    }));
-
-    const card = createAgendaCard({
-      title: "Many Events",
-      events: manyEvents,
-    });
-
-    expect(card.body).toBeDefined();
-  });
-
-  it("includes footer when provided", () => {
-    const card = createAgendaCard({
-      title: "Today",
-      events: [{ title: "Event" }],
-      footer: "Synced from Google Calendar",
-    });
-
-    expect(card.footer).toBeDefined();
-  });
-
-  it("shows event metadata (time, location, calendar)", () => {
-    const card = createAgendaCard({
-      title: "Schedule",
-      events: [
-        {
-          title: "Meeting",
-          time: "10:00 AM",
-          location: "Room A",
-          calendar: "Work",
-        },
-      ],
-    });
-
-    expect(card.body).toBeDefined();
-  });
-});
-
-describe("toFlexMessage", () => {
-  it("wraps a container in a FlexMessage", () => {
-    const bubble = createInfoCard("Title", "Body");
-    const message = toFlexMessage("Alt text", bubble);
-
-    expect(message.type).toBe("flex");
-    expect(message.altText).toBe("Alt text");
-    expect(message.contents).toBe(bubble);
+    const body = card.body as { contents: Array<{ type: string }> };
+    expect(body.contents).toHaveLength(3);
   });
 });
diff --git a/src/line/flex-templates/schedule-cards.ts b/src/line/flex-templates/schedule-cards.ts
index 28010d0f160..5de8d24405a 100644
--- a/src/line/flex-templates/schedule-cards.ts
+++ b/src/line/flex-templates/schedule-cards.ts
@@ -28,6 +28,21 @@ function buildTitleSubtitleHeader(params: { title: string; subtitle?: string }):
   return headerContents;
 }
 
+function buildCardHeaderSections(headerContents: FlexComponent[]): FlexComponent[] {
+  return [
+    {
+      type: "box",
+      layout: "vertical",
+      contents: headerContents,
+      paddingBottom: "lg",
+    } as FlexBox,
+    {
+      type: "separator",
+      color: "#EEEEEE",
+    },
+  ];
+}
+
 function createMegaBubbleWithFooter(params: {
   bodyContents: FlexComponent[];
   footer?: string;
@@ -101,16 +116,7 @@ export function createReceiptCard(params: {
   const headerContents = buildTitleSubtitleHeader({ title, subtitle });
 
   const bodyContents: FlexComponent[] = [
-    {
-      type: "box",
-      layout: "vertical",
-      contents: headerContents,
-      paddingBottom: "lg",
-    } as FlexBox,
-    {
-      type: "separator",
-      color: "#EEEEEE",
-    },
+    ...buildCardHeaderSections(headerContents),
     {
       type: "box",
       layout: "vertical",
@@ -448,16 +454,7 @@ export function createAgendaCard(params: {
   });
 
   const bodyContents: FlexComponent[] = [
-    {
-      type: "box",
-      layout: "vertical",
-      contents: headerContents,
-      paddingBottom: "lg",
-    } as FlexBox,
-    {
-      type: "separator",
-      color: "#EEEEEE",
-    },
+    ...buildCardHeaderSections(headerContents),
     {
       type: "box",
       layout: "vertical",
diff --git a/src/line/markdown-to-line.test.ts b/src/line/markdown-to-line.test.ts
index 99c37a4f499..a8daa0260f0 100644
--- a/src/line/markdown-to-line.test.ts
+++ b/src/line/markdown-to-line.test.ts
@@ -34,19 +34,6 @@ And some more text.`;
     expect(textWithoutTables).not.toContain("|");
   });
 
-  it("extracts a multi-column table", () => {
-    const text = `| Col A | Col B | Col C |
-|-------|-------|-------|
-| 1     | 2     | 3     |
-| a     | b     | c     |`;
-
-    const { tables } = extractMarkdownTables(text);
-
-    expect(tables).toHaveLength(1);
-    expect(tables[0].headers).toEqual(["Col A", "Col B", "Col C"]);
-    expect(tables[0].rows).toHaveLength(2);
-  });
-
   it("extracts multiple tables", () => {
     const text = `Table 1:
 
@@ -139,15 +126,6 @@ echo "world"
     expect(codeBlocks[0].language).toBe("python");
     expect(codeBlocks[1].language).toBe("bash");
   });
-
-  it("returns empty when no code blocks present", () => {
-    const text = "No code here, just text.";
-
-    const { codeBlocks, textWithoutCode } = extractCodeBlocks(text);
-
-    expect(codeBlocks).toHaveLength(0);
-    expect(textWithoutCode).toBe(text);
-  });
 });
 
 describe("extractLinks", () => {
@@ -161,15 +139,6 @@ describe("extractLinks", () => {
     expect(links[1]).toEqual({ text: "GitHub", url: "https://github.com" });
     expect(textWithLinks).toBe("Check out Google and GitHub.");
   });
-
-  it("handles text without links", () => {
-    const text = "No links here.";
-
-    const { links, textWithLinks } = extractLinks(text);
-
-    expect(links).toHaveLength(0);
-    expect(textWithLinks).toBe(text);
-  });
 });
 
 describe("stripMarkdown", () => {
@@ -187,17 +156,6 @@ describe("stripMarkdown", () => {
     expect(stripMarkdown("This is ~~deleted~~ text")).toBe("This is deleted text");
   });
 
-  it("strips headers", () => {
-    expect(stripMarkdown("# Heading 1")).toBe("Heading 1");
-    expect(stripMarkdown("## Heading 2")).toBe("Heading 2");
-    expect(stripMarkdown("### Heading 3")).toBe("Heading 3");
-  });
-
-  it("strips blockquotes", () => {
-    expect(stripMarkdown("> This is a quote")).toBe("This is a quote");
-    expect(stripMarkdown(">This is also a quote")).toBe("This is also a quote");
-  });
-
   it("removes horizontal rules", () => {
     expect(stripMarkdown("Above\n---\nBelow")).toBe("Above\n\nBelow");
     expect(stripMarkdown("Above\n***\nBelow")).toBe("Above\n\nBelow");
@@ -230,33 +188,6 @@ Some ~~deleted~~ content.`;
 });
 
 describe("convertTableToFlexBubble", () => {
-  it("creates a receipt-style card for 2-column tables", () => {
-    const table = {
-      headers: ["Item", "Price"],
-      rows: [
-        ["Apple", "$1"],
-        ["Banana", "$2"],
-      ],
-    };
-
-    const bubble = convertTableToFlexBubble(table);
-
-    expect(bubble.type).toBe("bubble");
-    expect(bubble.body).toBeDefined();
-  });
-
-  it("creates a multi-column layout for 3+ column tables", () => {
-    const table = {
-      headers: ["A", "B", "C"],
-      rows: [["1", "2", "3"]],
-    };
-
-    const bubble = convertTableToFlexBubble(table);
-
-    expect(bubble.type).toBe("bubble");
-    expect(bubble.body).toBeDefined();
-  });
-
   it("replaces empty cells with placeholders", () => {
     const table = {
       headers: ["A", "B"],
@@ -299,9 +230,6 @@ describe("convertCodeBlockToFlexBubble", () => {
 
     const bubble = convertCodeBlockToFlexBubble(block);
 
-    expect(bubble.type).toBe("bubble");
-    expect(bubble.body).toBeDefined();
-
     const body = bubble.body as { contents: Array<{ text: string }> };
     expect(body.contents[0].text).toBe("Code (typescript)");
   });
@@ -329,24 +257,6 @@ describe("convertCodeBlockToFlexBubble", () => {
 });
 
 describe("processLineMessage", () => {
-  it("processes text with tables", () => {
-    const text = `Here's the data:
-
-| Key | Value |
-|-----|-------|
-| a   | 1     |
-
-Done.`;
-
-    const result = processLineMessage(text);
-
-    expect(result.flexMessages).toHaveLength(1);
-    expect(result.flexMessages[0].type).toBe("flex");
-    expect(result.text).toContain("Here's the data:");
-    expect(result.text).toContain("Done.");
-    expect(result.text).not.toContain("|");
-  });
-
   it("processes text with code blocks", () => {
     const text = `Check this code:
 
@@ -364,15 +274,6 @@ That's it.`;
     expect(result.text).not.toContain("```");
   });
 
-  it("processes text with markdown formatting", () => {
-    const text = "This is **bold** and *italic* text.";
-
-    const result = processLineMessage(text);
-
-    expect(result.text).toBe("This is bold and italic text.");
-    expect(result.flexMessages).toHaveLength(0);
-  });
-
   it("handles mixed content", () => {
     const text = `# Summary
 
@@ -415,32 +316,21 @@ print("done")
 });
 
 describe("hasMarkdownToConvert", () => {
-  it("detects tables", () => {
-    const text = `| A | B |
+  it("detects supported markdown patterns", () => {
+    const cases = [
+      `| A | B |
 |---|---|
-| 1 | 2 |`;
-    expect(hasMarkdownToConvert(text)).toBe(true);
-  });
+| 1 | 2 |`,
+      "```js\ncode\n```",
+      "**bold**",
+      "~~deleted~~",
+      "# Title",
+      "> quote",
+    ];
 
-  it("detects code blocks", () => {
-    const text = "```js\ncode\n```";
-    expect(hasMarkdownToConvert(text)).toBe(true);
-  });
-
-  it("detects bold", () => {
-    expect(hasMarkdownToConvert("**bold**")).toBe(true);
-  });
-
-  it("detects strikethrough", () => {
-    expect(hasMarkdownToConvert("~~deleted~~")).toBe(true);
-  });
-
-  it("detects headers", () => {
-    expect(hasMarkdownToConvert("# Title")).toBe(true);
-  });
-
-  it("detects blockquotes", () => {
-    expect(hasMarkdownToConvert("> quote")).toBe(true);
+    for (const text of cases) {
+      expect(hasMarkdownToConvert(text)).toBe(true);
+    }
   });
 
   it("returns false for plain text", () => {
diff --git a/src/line/monitor.fail-closed.test.ts b/src/line/monitor.fail-closed.test.ts
new file mode 100644
index 00000000000..ef3df2757a5
--- /dev/null
+++ b/src/line/monitor.fail-closed.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import type { RuntimeEnv } from "../runtime.js";
+import { monitorLineProvider } from "./monitor.js";
+
+describe("monitorLineProvider fail-closed webhook auth", () => {
+  it("rejects startup when channel secret is missing", async () => {
+    await expect(
+      monitorLineProvider({
+        channelAccessToken: "token",
+        channelSecret: "   ",
+        config: {} as OpenClawConfig,
+        runtime: {} as RuntimeEnv,
+      }),
+    ).rejects.toThrow("LINE webhook mode requires a non-empty channel secret.");
+  });
+
+  it("rejects startup when channel access token is missing", async () => {
+    await expect(
+      monitorLineProvider({
+        channelAccessToken: "   ",
+        channelSecret: "secret",
+        config: {} as OpenClawConfig,
+        runtime: {} as RuntimeEnv,
+      }),
+    ).rejects.toThrow("LINE webhook mode requires a non-empty channel access token.");
+  });
+});
diff --git a/src/line/monitor.ts b/src/line/monitor.ts
index c09b471951c..24572a91287 100644
--- a/src/line/monitor.ts
+++ b/src/line/monitor.ts
@@ -129,6 +129,15 @@ export async function monitorLineProvider(
     webhookPath,
   } = opts;
   const resolvedAccountId = accountId ?? "default";
+  const token = channelAccessToken.trim();
+  const secret = channelSecret.trim();
+
+  if (!token) {
+    throw new Error("LINE webhook mode requires a non-empty channel access token.");
+  }
+  if (!secret) {
+    throw new Error("LINE webhook mode requires a non-empty channel secret.");
+  }
 
   // Record starting state
   recordChannelRuntimeState({
@@ -142,8 +151,8 @@ export async function monitorLineProvider(
 
   // Create the bot
   const bot = createLineBot({
-    channelAccessToken,
-    channelSecret,
+    channelAccessToken: token,
+    channelSecret: secret,
     accountId,
     runtime,
     config,
@@ -281,7 +290,7 @@ export async function monitorLineProvider(
     pluginId: "line",
     accountId: resolvedAccountId,
     log: (msg) => logVerbose(msg),
-    handler: createLineNodeWebhookHandler({ channelSecret, bot, runtime }),
+    handler: createLineNodeWebhookHandler({ channelSecret: secret, bot, runtime }),
   });
 
   logVerbose(`line: registered webhook handler at ${normalizedPath}`);
diff --git a/src/line/probe.ts b/src/line/probe.ts
index d5f7755cd2b..0da983de465 100644
--- a/src/line/probe.ts
+++ b/src/line/probe.ts
@@ -1,5 +1,6 @@
 import { messagingApi } from "@line/bot-sdk";
 import type { LineProbeResult } from "./types.js";
+import { withTimeout } from "../utils/with-timeout.js";
 
 export async function probeLineBot(
   channelAccessToken: string,
@@ -30,18 +31,3 @@ export async function probeLineBot(
     return { ok: false, error: message };
   }
 }
-
-function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  if (!timeoutMs || timeoutMs <= 0) {
-    return promise;
-  }
-  let timer: NodeJS.Timeout | null = null;
-  const timeout = new Promise<T>((_, reject) => {
-    timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
-  });
-  return Promise.race([promise, timeout]).finally(() => {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  });
-}
diff --git a/src/line/rich-menu.test.ts b/src/line/rich-menu.test.ts
index 96b069f345d..c31f3bf7d98 100644
--- a/src/line/rich-menu.test.ts
+++ b/src/line/rich-menu.test.ts
@@ -1,117 +1,5 @@
 import { describe, expect, it } from "vitest";
-import {
-  createGridLayout,
-  messageAction,
-  uriAction,
-  postbackAction,
-  datetimePickerAction,
-  createDefaultMenuConfig,
-} from "./rich-menu.js";
-
-describe("messageAction", () => {
-  it("creates a message action", () => {
-    const action = messageAction("Help", "/help");
-
-    expect(action.type).toBe("message");
-    expect(action.label).toBe("Help");
-    expect((action as { text: string }).text).toBe("/help");
-  });
-
-  it("uses label as text when text not provided", () => {
-    const action = messageAction("Click");
-
-    expect((action as { text: string }).text).toBe("Click");
-  });
-
-  it("truncates label to 20 characters", () => {
-    const action = messageAction("This is a very long label text");
-
-    expect(action.label.length).toBe(20);
-    expect(action.label).toBe("This is a very long ");
-  });
-});
-
-describe("uriAction", () => {
-  it("creates a URI action", () => {
-    const action = uriAction("Open", "https://example.com");
-
-    expect(action.type).toBe("uri");
-    expect(action.label).toBe("Open");
-    expect((action as { uri: string }).uri).toBe("https://example.com");
-  });
-
-  it("truncates label to 20 characters", () => {
-    const action = uriAction("Click here to visit our website", "https://example.com");
-
-    expect(action.label.length).toBe(20);
-  });
-});
-
-describe("postbackAction", () => {
-  it("creates a postback action", () => {
-    const action = postbackAction("Select", "action=select&item=1", "Selected item 1");
-
-    expect(action.type).toBe("postback");
-    expect(action.label).toBe("Select");
-    expect((action as { data: string }).data).toBe("action=select&item=1");
-    expect((action as { displayText: string }).displayText).toBe("Selected item 1");
-  });
-
-  it("truncates data to 300 characters", () => {
-    const longData = "x".repeat(400);
-    const action = postbackAction("Test", longData);
-
-    expect((action as { data: string }).data.length).toBe(300);
-  });
-
-  it("truncates displayText to 300 characters", () => {
-    const longText = "y".repeat(400);
-    const action = postbackAction("Test", "data", longText);
-
-    expect((action as { displayText: string }).displayText?.length).toBe(300);
-  });
-
-  it("omits displayText when not provided", () => {
-    const action = postbackAction("Test", "data");
-
-    expect((action as { displayText?: string }).displayText).toBeUndefined();
-  });
-});
-
-describe("datetimePickerAction", () => {
-  it("creates a date picker action", () => {
-    const action = datetimePickerAction("Pick date", "date_picked", "date");
-
-    expect(action.type).toBe("datetimepicker");
-    expect(action.label).toBe("Pick date");
-    expect((action as { mode: string }).mode).toBe("date");
-    expect((action as { data: string }).data).toBe("date_picked");
-  });
-
-  it("creates a time picker action", () => {
-    const action = datetimePickerAction("Pick time", "time_picked", "time");
-
-    expect((action as { mode: string }).mode).toBe("time");
-  });
-
-  it("creates a datetime picker action", () => {
-    const action = datetimePickerAction("Pick datetime", "datetime_picked", "datetime");
-
-    expect((action as { mode: string }).mode).toBe("datetime");
-  });
-
-  it("includes initial/min/max when provided", () => {
-    const action = datetimePickerAction("Pick", "data", "date", {
-      initial: "2024-06-15",
-      min: "2024-01-01",
-      max: "2024-12-31",
-    });
-
-    expect((action as { initial: string }).initial).toBe("2024-06-15");
-    expect((action as { min: string }).min).toBe("2024-01-01");
-    expect((action as { max: string }).max).toBe("2024-12-31");
-  });
-});
+import { createGridLayout, messageAction } from "./rich-menu.js";
 
 describe("createGridLayout", () => {
   it("creates a 2x3 grid layout for tall menu", () => {
@@ -148,100 +36,4 @@ describe("createGridLayout", () => {
     expect(areas[4].bounds.y).toBe(843);
     expect(areas[5].bounds.y).toBe(843);
   });
-
-  it("creates a 2x3 grid layout for short menu", () => {
-    const actions = [
-      messageAction("A1"),
-      messageAction("A2"),
-      messageAction("A3"),
-      messageAction("A4"),
-      messageAction("A5"),
-      messageAction("A6"),
-    ] as [
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-    ];
-
-    const areas = createGridLayout(843, actions);
-
-    expect(areas.length).toBe(6);
-
-    // Row height should be half of 843
-    expect(areas[0].bounds.height).toBe(421);
-    expect(areas[3].bounds.y).toBe(421);
-  });
-
-  it("assigns correct actions to areas", () => {
-    const actions = [
-      messageAction("Help", "/help"),
-      messageAction("Status", "/status"),
-      messageAction("Settings", "/settings"),
-      messageAction("About", "/about"),
-      messageAction("Feedback", "/feedback"),
-      messageAction("Contact", "/contact"),
-    ] as [
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-      ReturnType<typeof messageAction>,
-    ];
-
-    const areas = createGridLayout(843, actions);
-
-    expect((areas[0].action as { text: string }).text).toBe("/help");
-    expect((areas[1].action as { text: string }).text).toBe("/status");
-    expect((areas[2].action as { text: string }).text).toBe("/settings");
-    expect((areas[3].action as { text: string }).text).toBe("/about");
-    expect((areas[4].action as { text: string }).text).toBe("/feedback");
-    expect((areas[5].action as { text: string }).text).toBe("/contact");
-  });
-});
-
-describe("createDefaultMenuConfig", () => {
-  it("creates a valid default menu configuration", () => {
-    const config = createDefaultMenuConfig();
-
-    expect(config.size.width).toBe(2500);
-    expect(config.size.height).toBe(843);
-    expect(config.selected).toBe(false);
-    expect(config.name).toBe("Default Menu");
-    expect(config.chatBarText).toBe("Menu");
-    expect(config.areas.length).toBe(6);
-  });
-
-  it("has valid area bounds", () => {
-    const config = createDefaultMenuConfig();
-
-    for (const area of config.areas) {
-      expect(area.bounds.x).toBeGreaterThanOrEqual(0);
-      expect(area.bounds.y).toBeGreaterThanOrEqual(0);
-      expect(area.bounds.width).toBeGreaterThan(0);
-      expect(area.bounds.height).toBeGreaterThan(0);
-      expect(area.bounds.x + area.bounds.width).toBeLessThanOrEqual(2500);
-      expect(area.bounds.y + area.bounds.height).toBeLessThanOrEqual(843);
-    }
-  });
-
-  it("has message actions for all areas", () => {
-    const config = createDefaultMenuConfig();
-
-    for (const area of config.areas) {
-      expect(area.action.type).toBe("message");
-    }
-  });
-
-  it("has expected default commands", () => {
-    const config = createDefaultMenuConfig();
-
-    const commands = config.areas.map((a) => (a.action as { text: string }).text);
-    expect(commands).toContain("/help");
-    expect(commands).toContain("/status");
-    expect(commands).toContain("/settings");
-  });
 });
diff --git a/src/line/send.test.ts b/src/line/send.test.ts
index add3669f79f..317ab3084f2 100644
--- a/src/line/send.test.ts
+++ b/src/line/send.test.ts
@@ -1,95 +1,11 @@
 import { describe, expect, it } from "vitest";
-import {
-  createFlexMessage,
-  createQuickReplyItems,
-  createTextMessageWithQuickReplies,
-} from "./send.js";
-
-describe("createFlexMessage", () => {
-  it("creates a flex message with alt text and contents", () => {
-    const contents = {
-      type: "bubble" as const,
-      body: {
-        type: "box" as const,
-        layout: "vertical" as const,
-        contents: [],
-      },
-    };
-
-    const message = createFlexMessage("Alt text for flex", contents);
-
-    expect(message.type).toBe("flex");
-    expect(message.altText).toBe("Alt text for flex");
-    expect(message.contents).toBe(contents);
-  });
-});
+import { createQuickReplyItems } from "./send.js";
 
 describe("createQuickReplyItems", () => {
-  it("creates quick reply items from labels", () => {
-    const quickReply = createQuickReplyItems(["Option 1", "Option 2", "Option 3"]);
-
-    expect(quickReply.items).toHaveLength(3);
-    expect(quickReply.items[0].type).toBe("action");
-    expect((quickReply.items[0].action as { label: string }).label).toBe("Option 1");
-    expect((quickReply.items[0].action as { text: string }).text).toBe("Option 1");
-  });
-
   it("limits items to 13 (LINE maximum)", () => {
     const labels = Array.from({ length: 20 }, (_, i) => `Option ${i + 1}`);
     const quickReply = createQuickReplyItems(labels);
 
     expect(quickReply.items).toHaveLength(13);
   });
-
-  it("truncates labels to 20 characters", () => {
-    const quickReply = createQuickReplyItems([
-      "This is a very long option label that exceeds the limit",
-    ]);
-
-    expect((quickReply.items[0].action as { label: string }).label).toBe("This is a very long ");
-    // Text is not truncated
-    expect((quickReply.items[0].action as { text: string }).text).toBe(
-      "This is a very long option label that exceeds the limit",
-    );
-  });
-
-  it("creates message actions for each item", () => {
-    const quickReply = createQuickReplyItems(["A", "B"]);
-
-    expect((quickReply.items[0].action as { type: string }).type).toBe("message");
-    expect((quickReply.items[1].action as { type: string }).type).toBe("message");
-  });
-});
-
-describe("createTextMessageWithQuickReplies", () => {
-  it("creates a text message with quick replies attached", () => {
-    const message = createTextMessageWithQuickReplies("Choose an option:", ["Yes", "No"]);
-
-    expect(message.type).toBe("text");
-    expect(message.text).toBe("Choose an option:");
-    expect(message.quickReply).toBeDefined();
-    expect(message.quickReply.items).toHaveLength(2);
-  });
-
-  it("preserves text content", () => {
-    const longText =
-      "This is a longer message that asks the user to select from multiple options below.";
-    const message = createTextMessageWithQuickReplies(longText, ["A", "B", "C"]);
-
-    expect(message.text).toBe(longText);
-  });
-
-  it("handles empty quick replies array", () => {
-    const message = createTextMessageWithQuickReplies("No options", []);
-
-    expect(message.quickReply.items).toHaveLength(0);
-  });
-
-  it("quick replies use label as both label and text", () => {
-    const message = createTextMessageWithQuickReplies("Pick one:", ["Apple", "Banana"]);
-
-    const firstAction = message.quickReply.items[0].action as { label: string; text: string };
-    expect(firstAction.label).toBe("Apple");
-    expect(firstAction.text).toBe("Apple");
-  });
 });
diff --git a/src/line/signature.test.ts b/src/line/signature.test.ts
deleted file mode 100644
index 8bd9b1f3f64..00000000000
--- a/src/line/signature.test.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import crypto from "node:crypto";
-import { describe, expect, it } from "vitest";
-import { validateLineSignature } from "./signature.js";
-
-const sign = (body: string, secret: string) =>
-  crypto.createHmac("SHA256", secret).update(body).digest("base64");
-
-describe("validateLineSignature", () => {
-  it("accepts valid signatures", () => {
-    const secret = "secret";
-    const rawBody = JSON.stringify({ events: [{ type: "message" }] });
-
-    expect(validateLineSignature(rawBody, sign(rawBody, secret), secret)).toBe(true);
-  });
-
-  it("rejects signatures computed with the wrong secret", () => {
-    const rawBody = JSON.stringify({ events: [{ type: "message" }] });
-
-    expect(validateLineSignature(rawBody, sign(rawBody, "wrong-secret"), "secret")).toBe(false);
-  });
-
-  it("rejects signatures with a different length", () => {
-    const rawBody = JSON.stringify({ events: [{ type: "message" }] });
-
-    expect(validateLineSignature(rawBody, "short", "secret")).toBe(false);
-  });
-});
diff --git a/src/line/template-messages.test.ts b/src/line/template-messages.test.ts
index dc43b321b8a..4cf296a4b9a 100644
--- a/src/line/template-messages.test.ts
+++ b/src/line/template-messages.test.ts
@@ -6,31 +6,12 @@ import {
   createCarouselColumn,
   createImageCarousel,
   createImageCarouselColumn,
-  createYesNoConfirm,
-  createButtonMenu,
-  createLinkMenu,
   createProductCarousel,
   messageAction,
-  uriAction,
   postbackAction,
-  datetimePickerAction,
 } from "./template-messages.js";
 
 describe("messageAction", () => {
-  it("creates a message action", () => {
-    const action = messageAction("Click me", "clicked");
-
-    expect(action.type).toBe("message");
-    expect(action.label).toBe("Click me");
-    expect((action as { text: string }).text).toBe("clicked");
-  });
-
-  it("uses label as text when text not provided", () => {
-    const action = messageAction("Click");
-
-    expect((action as { text: string }).text).toBe("Click");
-  });
-
   it("truncates label to 20 characters", () => {
     const action = messageAction("This is a very long label that exceeds the limit");
 
@@ -38,31 +19,7 @@ describe("messageAction", () => {
   });
 });
 
-describe("uriAction", () => {
-  it("creates a URI action", () => {
-    const action = uriAction("Visit", "https://example.com");
-
-    expect(action.type).toBe("uri");
-    expect(action.label).toBe("Visit");
-    expect((action as { uri: string }).uri).toBe("https://example.com");
-  });
-});
-
 describe("postbackAction", () => {
-  it("creates a postback action", () => {
-    const action = postbackAction("Select", "action=select&id=1");
-
-    expect(action.type).toBe("postback");
-    expect(action.label).toBe("Select");
-    expect((action as { data: string }).data).toBe("action=select&id=1");
-  });
-
-  it("includes displayText when provided", () => {
-    const action = postbackAction("Select", "data", "Selected!");
-
-    expect((action as { displayText: string }).displayText).toBe("Selected!");
-  });
-
   it("truncates data to 300 characters", () => {
     const longData = "x".repeat(400);
     const action = postbackAction("Test", longData);
@@ -71,69 +28,16 @@ describe("postbackAction", () => {
   });
 });
 
-describe("datetimePickerAction", () => {
-  it("creates a datetime picker action", () => {
-    const action = datetimePickerAction("Pick date", "date_selected", "date");
-
-    expect(action.type).toBe("datetimepicker");
-    expect(action.label).toBe("Pick date");
-    expect((action as { mode: string }).mode).toBe("date");
-  });
-
-  it("includes min/max/initial when provided", () => {
-    const action = datetimePickerAction("Pick", "data", "datetime", {
-      initial: "2024-01-01T12:00",
-      min: "2024-01-01T00:00",
-      max: "2024-12-31T23:59",
-    });
-
-    expect((action as { initial: string }).initial).toBe("2024-01-01T12:00");
-    expect((action as { min: string }).min).toBe("2024-01-01T00:00");
-    expect((action as { max: string }).max).toBe("2024-12-31T23:59");
-  });
-});
-
 describe("createConfirmTemplate", () => {
-  it("creates a confirm template", () => {
-    const confirm = messageAction("Yes");
-    const cancel = messageAction("No");
-    const template = createConfirmTemplate("Are you sure?", confirm, cancel);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("confirm");
-    expect((template.template as { text: string }).text).toBe("Are you sure?");
-  });
-
   it("truncates text to 240 characters", () => {
     const longText = "x".repeat(300);
     const template = createConfirmTemplate(longText, messageAction("Yes"), messageAction("No"));
 
     expect((template.template as { text: string }).text.length).toBe(240);
   });
-
-  it("uses custom altText when provided", () => {
-    const template = createConfirmTemplate(
-      "Question?",
-      messageAction("Yes"),
-      messageAction("No"),
-      "Custom alt",
-    );
-
-    expect(template.altText).toBe("Custom alt");
-  });
 });
 
 describe("createButtonTemplate", () => {
-  it("creates a button template", () => {
-    const actions = [messageAction("Button 1"), messageAction("Button 2")];
-    const template = createButtonTemplate("Title", "Description", actions);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("buttons");
-    expect((template.template as { title: string }).title).toBe("Title");
-    expect((template.template as { text: string }).text).toBe("Description");
-  });
-
   it("limits actions to 4", () => {
     const actions = Array.from({ length: 6 }, (_, i) => messageAction(`Button ${i}`));
     const template = createButtonTemplate("Title", "Text", actions);
@@ -148,16 +52,6 @@ describe("createButtonTemplate", () => {
     expect((template.template as { title: string }).title.length).toBe(40);
   });
 
-  it("includes thumbnail when provided", () => {
-    const template = createButtonTemplate("Title", "Text", [messageAction("OK")], {
-      thumbnailImageUrl: "https://example.com/thumb.jpg",
-    });
-
-    expect((template.template as { thumbnailImageUrl: string }).thumbnailImageUrl).toBe(
-      "https://example.com/thumb.jpg",
-    );
-  });
-
   it("truncates text to 60 chars when no thumbnail is provided", () => {
     const longText = "x".repeat(100);
     const template = createButtonTemplate("Title", longText, [messageAction("OK")]);
@@ -176,18 +70,6 @@ describe("createButtonTemplate", () => {
 });
 
 describe("createTemplateCarousel", () => {
-  it("creates a carousel template", () => {
-    const columns = [
-      createCarouselColumn({ text: "Column 1", actions: [messageAction("Select")] }),
-      createCarouselColumn({ text: "Column 2", actions: [messageAction("Select")] }),
-    ];
-    const template = createTemplateCarousel(columns);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("carousel");
-    expect((template.template as { columns: unknown[] }).columns.length).toBe(2);
-  });
-
   it("limits columns to 10", () => {
     const columns = Array.from({ length: 15 }, () =>
       createCarouselColumn({ text: "Text", actions: [messageAction("OK")] }),
@@ -199,20 +81,6 @@ describe("createTemplateCarousel", () => {
 });
 
 describe("createCarouselColumn", () => {
-  it("creates a carousel column", () => {
-    const column = createCarouselColumn({
-      title: "Item",
-      text: "Description",
-      actions: [messageAction("View")],
-      thumbnailImageUrl: "https://example.com/img.jpg",
-    });
-
-    expect(column.title).toBe("Item");
-    expect(column.text).toBe("Description");
-    expect(column.thumbnailImageUrl).toBe("https://example.com/img.jpg");
-    expect(column.actions.length).toBe(1);
-  });
-
   it("limits actions to 3", () => {
     const column = createCarouselColumn({
       text: "Text",
@@ -237,17 +105,6 @@ describe("createCarouselColumn", () => {
 });
 
 describe("createImageCarousel", () => {
-  it("creates an image carousel", () => {
-    const columns = [
-      createImageCarouselColumn("https://example.com/1.jpg", messageAction("View 1")),
-      createImageCarouselColumn("https://example.com/2.jpg", messageAction("View 2")),
-    ];
-    const template = createImageCarousel(columns);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("image_carousel");
-  });
-
   it("limits columns to 10", () => {
     const columns = Array.from({ length: 15 }, (_, i) =>
       createImageCarouselColumn(`https://example.com/${i}.jpg`, messageAction("View")),
@@ -258,96 +115,7 @@ describe("createImageCarousel", () => {
   });
 });
 
-describe("createImageCarouselColumn", () => {
-  it("creates an image carousel column", () => {
-    const action = uriAction("Visit", "https://example.com");
-    const column = createImageCarouselColumn("https://example.com/img.jpg", action);
-
-    expect(column.imageUrl).toBe("https://example.com/img.jpg");
-    expect(column.action).toBe(action);
-  });
-});
-
-describe("createYesNoConfirm", () => {
-  it("creates a yes/no confirmation with defaults", () => {
-    const template = createYesNoConfirm("Continue?");
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("confirm");
-
-    const actions = (template.template as { actions: Array<{ label: string }> }).actions;
-    expect(actions[0].label).toBe("Yes");
-    expect(actions[1].label).toBe("No");
-  });
-
-  it("allows custom button text", () => {
-    const template = createYesNoConfirm("Delete?", {
-      yesText: "Delete",
-      noText: "Cancel",
-    });
-
-    const actions = (template.template as { actions: Array<{ label: string }> }).actions;
-    expect(actions[0].label).toBe("Delete");
-    expect(actions[1].label).toBe("Cancel");
-  });
-
-  it("uses postback actions when data provided", () => {
-    const template = createYesNoConfirm("Confirm?", {
-      yesData: "action=confirm",
-      noData: "action=cancel",
-    });
-
-    const actions = (template.template as { actions: Array<{ type: string }> }).actions;
-    expect(actions[0].type).toBe("postback");
-    expect(actions[1].type).toBe("postback");
-  });
-});
-
-describe("createButtonMenu", () => {
-  it("creates a button menu with text buttons", () => {
-    const template = createButtonMenu("Menu", "Choose an option", [
-      { label: "Option 1" },
-      { label: "Option 2", text: "selected option 2" },
-    ]);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("buttons");
-
-    const actions = (template.template as { actions: Array<{ type: string }> }).actions;
-    expect(actions.length).toBe(2);
-    expect(actions[0].type).toBe("message");
-  });
-});
-
-describe("createLinkMenu", () => {
-  it("creates a button menu with URL links", () => {
-    const template = createLinkMenu("Links", "Visit our sites", [
-      { label: "Site 1", url: "https://site1.com" },
-      { label: "Site 2", url: "https://site2.com" },
-    ]);
-
-    expect(template.type).toBe("template");
-
-    const actions = (template.template as { actions: Array<{ type: string }> }).actions;
-    expect(actions[0].type).toBe("uri");
-    expect(actions[1].type).toBe("uri");
-  });
-});
-
 describe("createProductCarousel", () => {
-  it("creates a product carousel", () => {
-    const template = createProductCarousel([
-      { title: "Product 1", description: "Desc 1", price: "$10" },
-      { title: "Product 2", description: "Desc 2", imageUrl: "https://example.com/p2.jpg" },
-    ]);
-
-    expect(template.type).toBe("template");
-    expect(template.template.type).toBe("carousel");
-
-    const columns = (template.template as { columns: unknown[] }).columns;
-    expect(columns.length).toBe(2);
-  });
-
   it("uses URI action when actionUrl provided", () => {
     const template = createProductCarousel([
       {
@@ -377,15 +145,4 @@ describe("createProductCarousel", () => {
       .columns;
     expect(columns[0].actions[0].type).toBe("postback");
   });
-
-  it("limits to 10 products", () => {
-    const products = Array.from({ length: 15 }, (_, i) => ({
-      title: `Product ${i}`,
-      description: `Desc ${i}`,
-    }));
-    const template = createProductCarousel(products);
-
-    const columns = (template.template as { columns: unknown[] }).columns;
-    expect(columns.length).toBe(10);
-  });
 });
diff --git a/src/line/types.ts b/src/line/types.ts
index dbd157cad71..8a797016255 100644
--- a/src/line/types.ts
+++ b/src/line/types.ts
@@ -7,6 +7,7 @@ import type {
   StickerMessage,
   LocationMessage,
 } from "@line/bot-sdk";
+import type { BaseProbeResult } from "../channels/plugins/types.js";
 
 export type LineTokenSource = "config" | "env" | "file" | "none";
 
@@ -86,16 +87,14 @@ export interface LineSendResult {
   chatId: string;
 }
 
-export interface LineProbeResult {
-  ok: boolean;
+export type LineProbeResult = BaseProbeResult<string> & {
   bot?: {
     displayName?: string;
     userId?: string;
     basicId?: string;
     pictureUrl?: string;
   };
-  error?: string;
-}
+};
 
 export type LineFlexMessagePayload = {
   altText: string;
diff --git a/src/line/webhook.test.ts b/src/line/webhook.test.ts
index 8707617544d..3c19ee587aa 100644
--- a/src/line/webhook.test.ts
+++ b/src/line/webhook.test.ts
@@ -139,25 +139,4 @@ describe("createLineWebhookMiddleware", () => {
     expect(res.json).toHaveBeenCalledWith({ error: "Missing X-Line-Signature header" });
     expect(onEvents).not.toHaveBeenCalled();
   });
-
-  it("rejects webhooks with signatures computed using wrong secret", async () => {
-    const onEvents = vi.fn(async () => {});
-    const correctSecret = "correct-secret";
-    const wrongSecret = "wrong-secret";
-    const rawBody = JSON.stringify({ events: [{ type: "message" }] });
-    const middleware = createLineWebhookMiddleware({ channelSecret: correctSecret, onEvents });
-
-    const req = {
-      headers: { "x-line-signature": sign(rawBody, wrongSecret) },
-      body: rawBody,
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-    const res = createRes();
-
-    // oxlint-disable-next-line typescript/no-explicit-any
-    await middleware(req, res, {} as any);
-
-    expect(res.status).toHaveBeenCalledWith(401);
-    expect(onEvents).not.toHaveBeenCalled();
-  });
 });
diff --git a/src/logger.test.ts b/src/logger.test.ts
index 93523906e3f..faa5d5d97a5 100644
--- a/src/logger.test.ts
+++ b/src/logger.test.ts
@@ -4,15 +4,21 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "./runtime.js";
-import { setVerbose } from "./globals.js";
+import { isVerbose, isYes, logVerbose, setVerbose, setYes } from "./globals.js";
 import { logDebug, logError, logInfo, logSuccess, logWarn } from "./logger.js";
-import { DEFAULT_LOG_DIR, resetLogger, setLoggerOverride } from "./logging.js";
+import {
+  DEFAULT_LOG_DIR,
+  resetLogger,
+  setLoggerOverride,
+  stripRedundantSubsystemPrefixForConsole,
+} from "./logging.js";
 
 describe("logger helpers", () => {
   afterEach(() => {
     resetLogger();
     setLoggerOverride(null);
     setVerbose(false);
+    setYes(false);
   });
 
   it("formats messages through runtime log/error", () => {
@@ -88,6 +94,61 @@ describe("logger helpers", () => {
   });
 });
 
+describe("globals", () => {
+  afterEach(() => {
+    setVerbose(false);
+    setYes(false);
+    vi.restoreAllMocks();
+  });
+
+  it("toggles verbose flag and logs when enabled", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    setVerbose(false);
+    logVerbose("hidden");
+    expect(logSpy).not.toHaveBeenCalled();
+
+    setVerbose(true);
+    logVerbose("shown");
+    expect(isVerbose()).toBe(true);
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("shown"));
+  });
+
+  it("stores yes flag", () => {
+    setYes(true);
+    expect(isYes()).toBe(true);
+    setYes(false);
+    expect(isYes()).toBe(false);
+  });
+});
+
+describe("stripRedundantSubsystemPrefixForConsole", () => {
+  it("drops '<subsystem>:' prefix", () => {
+    expect(stripRedundantSubsystemPrefixForConsole("discord: hello", "discord")).toBe("hello");
+  });
+
+  it("drops '<Subsystem>:' prefix case-insensitively", () => {
+    expect(stripRedundantSubsystemPrefixForConsole("WhatsApp: hello", "whatsapp")).toBe("hello");
+  });
+
+  it("drops '<subsystem> ' prefix", () => {
+    expect(stripRedundantSubsystemPrefixForConsole("discord gateway: closed", "discord")).toBe(
+      "gateway: closed",
+    );
+  });
+
+  it("drops '[subsystem]' prefix", () => {
+    expect(stripRedundantSubsystemPrefixForConsole("[discord] connection stalled", "discord")).toBe(
+      "connection stalled",
+    );
+  });
+
+  it("keeps messages that do not start with the subsystem", () => {
+    expect(stripRedundantSubsystemPrefixForConsole("discordant: hello", "discord")).toBe(
+      "discordant: hello",
+    );
+  });
+});
+
 function pathForTest() {
   const file = path.join(os.tmpdir(), `openclaw-log-${crypto.randomUUID()}.log`);
   fs.mkdirSync(path.dirname(file), { recursive: true });
diff --git a/src/logging/console-prefix.test.ts b/src/logging/console-prefix.test.ts
deleted file mode 100644
index 3bc3b13df91..00000000000
--- a/src/logging/console-prefix.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { stripRedundantSubsystemPrefixForConsole } from "../logging.js";
-
-describe("stripRedundantSubsystemPrefixForConsole", () => {
-  it("drops '<subsystem>:' prefix", () => {
-    expect(stripRedundantSubsystemPrefixForConsole("discord: hello", "discord")).toBe("hello");
-  });
-
-  it("drops '<Subsystem>:' prefix case-insensitively", () => {
-    expect(stripRedundantSubsystemPrefixForConsole("WhatsApp: hello", "whatsapp")).toBe("hello");
-  });
-
-  it("drops '<subsystem> ' prefix", () => {
-    expect(stripRedundantSubsystemPrefixForConsole("discord gateway: closed", "discord")).toBe(
-      "gateway: closed",
-    );
-  });
-
-  it("drops '[subsystem]' prefix", () => {
-    expect(stripRedundantSubsystemPrefixForConsole("[discord] connection stalled", "discord")).toBe(
-      "connection stalled",
-    );
-  });
-
-  it("keeps messages that do not start with the subsystem", () => {
-    expect(stripRedundantSubsystemPrefixForConsole("discordant: hello", "discord")).toBe(
-      "discordant: hello",
-    );
-  });
-});
diff --git a/src/logging/console.ts b/src/logging/console.ts
index 879a250676c..3454bb604ec 100644
--- a/src/logging/console.ts
+++ b/src/logging/console.ts
@@ -7,6 +7,7 @@ import { readLoggingConfig } from "./config.js";
 import { type LogLevel, normalizeLogLevel } from "./levels.js";
 import { getLogger, type LoggerSettings } from "./logger.js";
 import { loggingState } from "./state.js";
+import { formatLocalIsoWithOffset } from "./timestamps.js";
 
 export type ConsoleStyle = "pretty" | "compact" | "json";
 type ConsoleSettings = {
@@ -157,18 +158,7 @@ export function formatConsoleTimestamp(style: ConsoleStyle): string {
     const s = String(now.getSeconds()).padStart(2, "0");
     return `${h}:${m}:${s}`;
   }
-  const year = now.getFullYear();
-  const month = String(now.getMonth() + 1).padStart(2, "0");
-  const day = String(now.getDate()).padStart(2, "0");
-  const h = String(now.getHours()).padStart(2, "0");
-  const m = String(now.getMinutes()).padStart(2, "0");
-  const s = String(now.getSeconds()).padStart(2, "0");
-  const ms = String(now.getMilliseconds()).padStart(3, "0");
-  const tzOffset = now.getTimezoneOffset();
-  const tzSign = tzOffset <= 0 ? "+" : "-";
-  const tzHours = String(Math.floor(Math.abs(tzOffset) / 60)).padStart(2, "0");
-  const tzMinutes = String(Math.abs(tzOffset) % 60).padStart(2, "0");
-  return `${year}-${month}-${day}T${h}:${m}:${s}.${ms}${tzSign}${tzHours}:${tzMinutes}`;
+  return formatLocalIsoWithOffset(now);
 }
 
 function hasTimestampPrefix(value: string): boolean {
diff --git a/src/logging/diagnostic-session-state.ts b/src/logging/diagnostic-session-state.ts
index c060866ff92..aa5224550b8 100644
--- a/src/logging/diagnostic-session-state.ts
+++ b/src/logging/diagnostic-session-state.ts
@@ -56,10 +56,20 @@ function resolveSessionKey({ sessionKey, sessionId }: SessionRef) {
   return sessionKey ?? sessionId ?? "unknown";
 }
 
+function findStateBySessionId(sessionId: string): SessionState | undefined {
+  for (const state of diagnosticSessionStates.values()) {
+    if (state.sessionId === sessionId) {
+      return state;
+    }
+  }
+  return undefined;
+}
+
 export function getDiagnosticSessionState(ref: SessionRef): SessionState {
   pruneDiagnosticSessionStates();
   const key = resolveSessionKey(ref);
-  const existing = diagnosticSessionStates.get(key);
+  const existing =
+    diagnosticSessionStates.get(key) ?? (ref.sessionId && findStateBySessionId(ref.sessionId));
   if (existing) {
     if (ref.sessionId) {
       existing.sessionId = ref.sessionId;
diff --git a/src/logging/diagnostic.test.ts b/src/logging/diagnostic.test.ts
index c7cd72f5c08..1648b244b64 100644
--- a/src/logging/diagnostic.test.ts
+++ b/src/logging/diagnostic.test.ts
@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   getDiagnosticSessionStateCountForTest,
@@ -33,4 +34,34 @@ describe("diagnostic session state pruning", () => {
 
     expect(getDiagnosticSessionStateCountForTest()).toBe(2000);
   });
+
+  it("reuses keyed session state when later looked up by sessionId", () => {
+    const keyed = getDiagnosticSessionState({
+      sessionId: "s1",
+      sessionKey: "agent:main:discord:channel:c1",
+    });
+    const bySessionId = getDiagnosticSessionState({ sessionId: "s1" });
+
+    expect(bySessionId).toBe(keyed);
+    expect(bySessionId.sessionKey).toBe("agent:main:discord:channel:c1");
+    expect(getDiagnosticSessionStateCountForTest()).toBe(1);
+  });
+});
+
+describe("logger import side effects", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  it("does not mkdir at import time", async () => {
+    vi.useRealTimers();
+    vi.resetModules();
+
+    const mkdirSpy = vi.spyOn(fs, "mkdirSync");
+
+    await import("./logger.js");
+
+    expect(mkdirSpy).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/logging/logger.import-side-effects.test.ts b/src/logging/logger.import-side-effects.test.ts
deleted file mode 100644
index b0e8c2b9729..00000000000
--- a/src/logging/logger.import-side-effects.test.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import fs from "node:fs";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-describe("logger import side effects", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("does not mkdir at import time", async () => {
-    const mkdirSpy = vi.spyOn(fs, "mkdirSync");
-
-    await import("./logger.js");
-
-    expect(mkdirSpy).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/logging/redact.test.ts b/src/logging/redact.test.ts
index 3e8b754dd71..131c41c6b22 100644
--- a/src/logging/redact.test.ts
+++ b/src/logging/redact.test.ts
@@ -49,6 +49,16 @@ describe("redactSensitiveText", () => {
     expect(output).toBe("123456…cdef");
   });
 
+  it("masks Telegram Bot API URL tokens", () => {
+    const input =
+      "GET https://api.telegram.org/bot123456:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef/getMe HTTP/1.1";
+    const output = redactSensitiveText(input, {
+      mode: "tools",
+      patterns: defaults,
+    });
+    expect(output).toBe("GET https://api.telegram.org/bot123456…cdef/getMe HTTP/1.1");
+  });
+
   it("redacts short tokens fully", () => {
     const input = "TOKEN=shortvalue";
     const output = redactSensitiveText(input, {
diff --git a/src/logging/redact.ts b/src/logging/redact.ts
index f79bed7e07f..e60766cba4c 100644
--- a/src/logging/redact.ts
+++ b/src/logging/redact.ts
@@ -32,6 +32,8 @@ const DEFAULT_REDACT_PATTERNS: string[] = [
   String.raw`\b(AIza[0-9A-Za-z\-_]{20,})\b`,
   String.raw`\b(pplx-[A-Za-z0-9_-]{10,})\b`,
   String.raw`\b(npm_[A-Za-z0-9]{10,})\b`,
+  // Telegram Bot API URLs embed the token as `/bot<token>/...` (no word-boundary before digits).
+  String.raw`\bbot(\d{6,}:[A-Za-z0-9_-]{20,})\b`,
   String.raw`\b(\d{6,}:[A-Za-z0-9_-]{20,})\b`,
 ];
 
diff --git a/src/logging/timestamps.test.ts b/src/logging/timestamps.test.ts
new file mode 100644
index 00000000000..f2d72125987
--- /dev/null
+++ b/src/logging/timestamps.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { formatLocalIsoWithOffset } from "./timestamps.js";
+
+function buildFakeDate(parts: {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  millisecond: number;
+  timezoneOffsetMinutes: number;
+}): Date {
+  return {
+    getFullYear: () => parts.year,
+    getMonth: () => parts.month - 1,
+    getDate: () => parts.day,
+    getHours: () => parts.hour,
+    getMinutes: () => parts.minute,
+    getSeconds: () => parts.second,
+    getMilliseconds: () => parts.millisecond,
+    getTimezoneOffset: () => parts.timezoneOffsetMinutes,
+  } as unknown as Date;
+}
+
+describe("formatLocalIsoWithOffset", () => {
+  it("formats positive offset with millisecond padding", () => {
+    const value = formatLocalIsoWithOffset(
+      buildFakeDate({
+        year: 2026,
+        month: 1,
+        day: 2,
+        hour: 3,
+        minute: 4,
+        second: 5,
+        millisecond: 6,
+        timezoneOffsetMinutes: -150, // UTC+02:30
+      }),
+    );
+    expect(value).toBe("2026-01-02T03:04:05.006+02:30");
+  });
+
+  it("formats negative offset", () => {
+    const value = formatLocalIsoWithOffset(
+      buildFakeDate({
+        year: 2026,
+        month: 12,
+        day: 31,
+        hour: 23,
+        minute: 59,
+        second: 58,
+        millisecond: 321,
+        timezoneOffsetMinutes: 300, // UTC-05:00
+      }),
+    );
+    expect(value).toBe("2026-12-31T23:59:58.321-05:00");
+  });
+});
diff --git a/src/logging/timestamps.ts b/src/logging/timestamps.ts
new file mode 100644
index 00000000000..9945630b03b
--- /dev/null
+++ b/src/logging/timestamps.ts
@@ -0,0 +1,14 @@
+export function formatLocalIsoWithOffset(now: Date): string {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const h = String(now.getHours()).padStart(2, "0");
+  const m = String(now.getMinutes()).padStart(2, "0");
+  const s = String(now.getSeconds()).padStart(2, "0");
+  const ms = String(now.getMilliseconds()).padStart(3, "0");
+  const tzOffset = now.getTimezoneOffset();
+  const tzSign = tzOffset <= 0 ? "+" : "-";
+  const tzHours = String(Math.floor(Math.abs(tzOffset) / 60)).padStart(2, "0");
+  const tzMinutes = String(Math.abs(tzOffset) % 60).padStart(2, "0");
+  return `${year}-${month}-${day}T${h}:${m}:${s}.${ms}${tzSign}${tzHours}:${tzMinutes}`;
+}
diff --git a/src/macos/relay-smoke.test.ts b/src/macos/relay-smoke.test.ts
index bbd75c5719d..891efd67676 100644
--- a/src/macos/relay-smoke.test.ts
+++ b/src/macos/relay-smoke.test.ts
@@ -10,6 +10,18 @@ describe("parseRelaySmokeTest", () => {
     expect(parseRelaySmokeTest(["--smoke", "qr"], {})).toBe("qr");
   });
 
+  it("rejects --smoke without a value", () => {
+    expect(() => parseRelaySmokeTest(["--smoke"], {})).toThrow(
+      "Missing value for --smoke (expected: qr)",
+    );
+  });
+
+  it("rejects --smoke when the next arg is another flag", () => {
+    expect(() => parseRelaySmokeTest(["--smoke", "--smoke-qr"], {})).toThrow(
+      "Missing value for --smoke (expected: qr)",
+    );
+  });
+
   it("parses --smoke-qr", () => {
     expect(parseRelaySmokeTest(["--smoke-qr"], {})).toBe("qr");
   });
@@ -19,9 +31,18 @@ describe("parseRelaySmokeTest", () => {
     expect(parseRelaySmokeTest(["send"], { OPENCLAW_SMOKE_QR: "1" })).toBe(null);
   });
 
+  it("supports OPENCLAW_SMOKE=qr only when no args", () => {
+    expect(parseRelaySmokeTest([], { OPENCLAW_SMOKE: "qr" })).toBe("qr");
+    expect(parseRelaySmokeTest(["send"], { OPENCLAW_SMOKE: "qr" })).toBe(null);
+  });
+
   it("rejects unknown smoke values", () => {
     expect(() => parseRelaySmokeTest(["--smoke", "nope"], {})).toThrow("Unknown smoke test");
   });
+
+  it("prefers explicit --smoke over env vars", () => {
+    expect(parseRelaySmokeTest(["--smoke", "qr"], { OPENCLAW_SMOKE: "nope" })).toBe("qr");
+  });
 });
 
 describe("runRelaySmokeTest", () => {
diff --git a/src/markdown/ir.hr-spacing.test.ts b/src/markdown/ir.hr-spacing.test.ts
index c5bb6127bad..5a7a0931cc8 100644
--- a/src/markdown/ir.hr-spacing.test.ts
+++ b/src/markdown/ir.hr-spacing.test.ts
@@ -27,16 +27,6 @@ describe("hr (thematic break) spacing", () => {
       expect(result.text).toBe("───");
     });
 
-    it("hr between paragraphs renders with separator", () => {
-      const input = `Para 1
-
----
-
-Para 2`;
-      const result = markdownToIR(input);
-      expect(result.text).toBe("Para 1\n\n───\n\nPara 2");
-    });
-
     it("hr interrupting paragraph (setext heading case)", () => {
       // Note: "Para\n---" is a setext heading in CommonMark!
       // Using *** to test actual HR behavior
diff --git a/src/markdown/ir.list-spacing.test.ts b/src/markdown/ir.list-spacing.test.ts
deleted file mode 100644
index 56a8b3f174c..00000000000
--- a/src/markdown/ir.list-spacing.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { markdownToIR } from "./ir.js";
-
-describe("list paragraph spacing", () => {
-  it("adds blank line between bullet list and following paragraph", () => {
-    const input = `- item 1
-- item 2
-
-Paragraph after`;
-    const result = markdownToIR(input);
-    // Should have two newlines between "item 2" and "Paragraph"
-    expect(result.text).toContain("item 2\n\nParagraph");
-  });
-
-  it("adds blank line between ordered list and following paragraph", () => {
-    const input = `1. item 1
-2. item 2
-
-Paragraph after`;
-    const result = markdownToIR(input);
-    expect(result.text).toContain("item 2\n\nParagraph");
-  });
-
-  it("does not produce triple newlines", () => {
-    const input = `- item 1
-- item 2
-
-Paragraph after`;
-    const result = markdownToIR(input);
-    // Should NOT have three consecutive newlines
-    expect(result.text).not.toContain("\n\n\n");
-  });
-});
diff --git a/src/markdown/ir.nested-lists.test.ts b/src/markdown/ir.nested-lists.test.ts
index 4ca4e9bd9d7..7de8931eb40 100644
--- a/src/markdown/ir.nested-lists.test.ts
+++ b/src/markdown/ir.nested-lists.test.ts
@@ -299,3 +299,34 @@ describe("Nested Lists - Edge Cases", () => {
     expect(result.text).toBe(expected);
   });
 });
+
+describe("list paragraph spacing", () => {
+  it("adds blank line between bullet list and following paragraph", () => {
+    const input = `- item 1
+- item 2
+
+Paragraph after`;
+    const result = markdownToIR(input);
+    // Should have two newlines between "item 2" and "Paragraph"
+    expect(result.text).toContain("item 2\n\nParagraph");
+  });
+
+  it("adds blank line between ordered list and following paragraph", () => {
+    const input = `1. item 1
+2. item 2
+
+Paragraph after`;
+    const result = markdownToIR(input);
+    expect(result.text).toContain("item 2\n\nParagraph");
+  });
+
+  it("does not produce triple newlines", () => {
+    const input = `- item 1
+- item 2
+
+Paragraph after`;
+    const result = markdownToIR(input);
+    // Should NOT have three consecutive newlines
+    expect(result.text).not.toContain("\n\n\n");
+  });
+});
diff --git a/src/media-understanding/fs.ts b/src/media-understanding/fs.ts
new file mode 100644
index 00000000000..3bea43d0536
--- /dev/null
+++ b/src/media-understanding/fs.ts
@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+
+export async function fileExists(filePath?: string | null): Promise<boolean> {
+  if (!filePath) {
+    return false;
+  }
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/src/media-understanding/attachments.ssrf.test.ts b/src/media-understanding/media-understanding-misc.test.ts
similarity index 53%
rename from src/media-understanding/attachments.ssrf.test.ts
rename to src/media-understanding/media-understanding-misc.test.ts
index 03066fa6371..f33a9ebbeb9 100644
--- a/src/media-understanding/attachments.ssrf.test.ts
+++ b/src/media-understanding/media-understanding-misc.test.ts
@@ -1,5 +1,22 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { MediaAttachmentCache } from "./attachments.js";
+import { normalizeMediaUnderstandingChatType, resolveMediaUnderstandingScope } from "./scope.js";
+
+describe("media understanding scope", () => {
+  it("normalizes chatType", () => {
+    expect(normalizeMediaUnderstandingChatType("channel")).toBe("channel");
+    expect(normalizeMediaUnderstandingChatType("dm")).toBe("direct");
+    expect(normalizeMediaUnderstandingChatType("room")).toBeUndefined();
+  });
+
+  it("matches channel chatType explicitly", () => {
+    const scope = {
+      rules: [{ action: "deny", match: { chatType: "channel" } }],
+    } as const;
+
+    expect(resolveMediaUnderstandingScope({ scope, chatType: "channel" })).toBe("deny");
+  });
+});
 
 const originalFetch = globalThis.fetch;
 
diff --git a/src/media-understanding/providers/deepgram/audio.ts b/src/media-understanding/providers/deepgram/audio.ts
index 35965459fec..b32f18c870a 100644
--- a/src/media-understanding/providers/deepgram/audio.ts
+++ b/src/media-understanding/providers/deepgram/audio.ts
@@ -1,5 +1,5 @@
 import type { AudioTranscriptionRequest, AudioTranscriptionResult } from "../../types.js";
-import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { assertOkOrThrowHttpError, fetchWithTimeoutGuarded, normalizeBaseUrl } from "../shared.js";
 
 export const DEFAULT_DEEPGRAM_AUDIO_BASE_URL = "https://api.deepgram.com/v1";
 export const DEFAULT_DEEPGRAM_AUDIO_MODEL = "nova-3";
@@ -63,11 +63,7 @@ export async function transcribeDeepgramAudio(
   );
 
   try {
-    if (!res.ok) {
-      const detail = await readErrorResponse(res);
-      const suffix = detail ? `: ${detail}` : "";
-      throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
-    }
+    await assertOkOrThrowHttpError(res, "Audio transcription failed");
 
     const payload = (await res.json()) as DeepgramTranscriptResponse;
     const transcript = payload.results?.channels?.[0]?.alternatives?.[0]?.transcript?.trim();
diff --git a/src/media-understanding/providers/google/inline-data.ts b/src/media-understanding/providers/google/inline-data.ts
index 4f5df896a0a..39c1093644a 100644
--- a/src/media-understanding/providers/google/inline-data.ts
+++ b/src/media-understanding/providers/google/inline-data.ts
@@ -1,5 +1,5 @@
 import { normalizeGoogleModelId } from "../../../agents/models-config.providers.js";
-import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { assertOkOrThrowHttpError, fetchWithTimeoutGuarded, normalizeBaseUrl } from "../shared.js";
 
 export async function generateGeminiInlineDataText(params: {
   buffer: Buffer;
@@ -73,11 +73,7 @@ export async function generateGeminiInlineDataText(params: {
   );
 
   try {
-    if (!res.ok) {
-      const detail = await readErrorResponse(res);
-      const suffix = detail ? `: ${detail}` : "";
-      throw new Error(`${params.httpErrorLabel} (HTTP ${res.status})${suffix}`);
-    }
+    await assertOkOrThrowHttpError(res, params.httpErrorLabel);
 
     const payload = (await res.json()) as {
       candidates?: Array<{
diff --git a/src/media-understanding/providers/openai/audio.ts b/src/media-understanding/providers/openai/audio.ts
index bfd87009909..2635ad23d0b 100644
--- a/src/media-understanding/providers/openai/audio.ts
+++ b/src/media-understanding/providers/openai/audio.ts
@@ -1,6 +1,6 @@
 import path from "node:path";
 import type { AudioTranscriptionRequest, AudioTranscriptionResult } from "../../types.js";
-import { fetchWithTimeoutGuarded, normalizeBaseUrl, readErrorResponse } from "../shared.js";
+import { assertOkOrThrowHttpError, fetchWithTimeoutGuarded, normalizeBaseUrl } from "../shared.js";
 
 export const DEFAULT_OPENAI_AUDIO_BASE_URL = "https://api.openai.com/v1";
 const DEFAULT_OPENAI_AUDIO_MODEL = "gpt-4o-mini-transcribe";
@@ -52,11 +52,7 @@ export async function transcribeOpenAiCompatibleAudio(
   );
 
   try {
-    if (!res.ok) {
-      const detail = await readErrorResponse(res);
-      const suffix = detail ? `: ${detail}` : "";
-      throw new Error(`Audio transcription failed (HTTP ${res.status})${suffix}`);
-    }
+    await assertOkOrThrowHttpError(res, "Audio transcription failed");
 
     const payload = (await res.json()) as { text?: string };
     const text = payload.text?.trim();
diff --git a/src/media-understanding/providers/shared.ts b/src/media-understanding/providers/shared.ts
index 3e9a9ee7d93..beaafcf9e51 100644
--- a/src/media-understanding/providers/shared.ts
+++ b/src/media-understanding/providers/shared.ts
@@ -47,3 +47,12 @@ export async function readErrorResponse(res: Response): Promise<string | undefin
     return undefined;
   }
 }
+
+export async function assertOkOrThrowHttpError(res: Response, label: string): Promise<void> {
+  if (res.ok) {
+    return;
+  }
+  const detail = await readErrorResponse(res);
+  const suffix = detail ? `: ${detail}` : "";
+  throw new Error(`${label} (HTTP ${res.status})${suffix}`);
+}
diff --git a/src/media-understanding/runner.entries.ts b/src/media-understanding/runner.entries.ts
index b40e16fa531..e1f74bef8bb 100644
--- a/src/media-understanding/runner.entries.ts
+++ b/src/media-understanding/runner.entries.ts
@@ -25,6 +25,7 @@ import {
   DEFAULT_TIMEOUT_SECONDS,
 } from "./defaults.js";
 import { MediaUnderstandingSkipError } from "./errors.js";
+import { fileExists } from "./fs.js";
 import { extractGeminiResponse } from "./output-extract.js";
 import { describeImageWithModel } from "./providers/image.js";
 import { getMediaUnderstandingProvider, normalizeMediaProviderId } from "./providers/index.js";
@@ -129,18 +130,6 @@ function resolveWhisperCppOutputPath(args: string[]): string | null {
   return `${outputBase}.txt`;
 }
 
-async function fileExists(filePath?: string | null): Promise<boolean> {
-  if (!filePath) {
-    return false;
-  }
-  try {
-    await fs.stat(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function resolveCliOutput(params: {
   command: string;
   args: string[];
diff --git a/src/media-understanding/runner.ts b/src/media-understanding/runner.ts
index 8dd7e2f979a..2ca1ce654fe 100644
--- a/src/media-understanding/runner.ts
+++ b/src/media-understanding/runner.ts
@@ -32,6 +32,7 @@ import {
   DEFAULT_IMAGE_MODELS,
 } from "./defaults.js";
 import { isMediaUnderstandingSkipError } from "./errors.js";
+import { fileExists } from "./fs.js";
 import { extractGeminiResponse } from "./output-extract.js";
 import {
   buildMediaUnderstandingRegistry,
@@ -175,18 +176,6 @@ async function hasBinary(name: string): Promise<boolean> {
   return Boolean(await findBinary(name));
 }
 
-async function fileExists(filePath?: string | null): Promise<boolean> {
-  if (!filePath) {
-    return false;
-  }
-  try {
-    await fs.stat(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function probeGeminiCli(): Promise<boolean> {
   const cached = geminiProbeCache.get("gemini");
   if (cached) {
diff --git a/src/media-understanding/scope.test.ts b/src/media-understanding/scope.test.ts
deleted file mode 100644
index 0607c4bf2cb..00000000000
--- a/src/media-understanding/scope.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { normalizeMediaUnderstandingChatType, resolveMediaUnderstandingScope } from "./scope.js";
-
-describe("media understanding scope", () => {
-  it("normalizes chatType", () => {
-    expect(normalizeMediaUnderstandingChatType("channel")).toBe("channel");
-    expect(normalizeMediaUnderstandingChatType("dm")).toBe("direct");
-    expect(normalizeMediaUnderstandingChatType("room")).toBeUndefined();
-  });
-
-  it("matches channel chatType explicitly", () => {
-    const scope = {
-      rules: [{ action: "deny", match: { chatType: "channel" } }],
-    } as const;
-
-    expect(resolveMediaUnderstandingScope({ scope, chatType: "channel" })).toBe("deny");
-  });
-});
diff --git a/src/media/constants.test.ts b/src/media/constants.test.ts
deleted file mode 100644
index 613f4c4b381..00000000000
--- a/src/media/constants.test.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { mediaKindFromMime } from "./constants.js";
-
-describe("mediaKindFromMime", () => {
-  it("classifies text mimes as document", () => {
-    expect(mediaKindFromMime("text/plain")).toBe("document");
-    expect(mediaKindFromMime("text/csv")).toBe("document");
-    expect(mediaKindFromMime("text/html; charset=utf-8")).toBe("document");
-  });
-
-  it("keeps unknown mimes as unknown", () => {
-    expect(mediaKindFromMime("model/gltf+json")).toBe("unknown");
-  });
-});
diff --git a/src/media/local-roots.ts b/src/media/local-roots.ts
index b43e2d0f53c..ec4943e8780 100644
--- a/src/media/local-roots.ts
+++ b/src/media/local-roots.ts
@@ -2,25 +2,28 @@ import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
-import { STATE_DIR } from "../config/paths.js";
+import { resolveStateDir } from "../config/paths.js";
 
-const STATIC_LOCAL_ROOTS = [
-  os.tmpdir(),
-  path.join(STATE_DIR, "media"),
-  path.join(STATE_DIR, "agents"),
-  path.join(STATE_DIR, "workspace"),
-  path.join(STATE_DIR, "sandboxes"),
-] as const;
+function buildMediaLocalRoots(stateDir: string): string[] {
+  const resolvedStateDir = path.resolve(stateDir);
+  return [
+    os.tmpdir(),
+    path.join(resolvedStateDir, "media"),
+    path.join(resolvedStateDir, "agents"),
+    path.join(resolvedStateDir, "workspace"),
+    path.join(resolvedStateDir, "sandboxes"),
+  ];
+}
 
 export function getDefaultMediaLocalRoots(): readonly string[] {
-  return STATIC_LOCAL_ROOTS;
+  return buildMediaLocalRoots(resolveStateDir());
 }
 
 export function getAgentScopedMediaLocalRoots(
   cfg: OpenClawConfig,
   agentId?: string,
 ): readonly string[] {
-  const roots = [...STATIC_LOCAL_ROOTS];
+  const roots = buildMediaLocalRoots(resolveStateDir());
   if (!agentId?.trim()) {
     return roots;
   }
diff --git a/src/media/mime.test.ts b/src/media/mime.test.ts
index d1544889793..7b9be7a74b7 100644
--- a/src/media/mime.test.ts
+++ b/src/media/mime.test.ts
@@ -1,5 +1,6 @@
 import JSZip from "jszip";
 import { describe, expect, it } from "vitest";
+import { mediaKindFromMime } from "./constants.js";
 import {
   detectMime,
   extensionForMime,
@@ -128,3 +129,15 @@ describe("normalizeMimeType", () => {
     expect(normalizeMimeType(undefined)).toBeUndefined();
   });
 });
+
+describe("mediaKindFromMime", () => {
+  it("classifies text mimes as document", () => {
+    expect(mediaKindFromMime("text/plain")).toBe("document");
+    expect(mediaKindFromMime("text/csv")).toBe("document");
+    expect(mediaKindFromMime("text/html; charset=utf-8")).toBe("document");
+  });
+
+  it("keeps unknown mimes as unknown", () => {
+    expect(mediaKindFromMime("model/gltf+json")).toBe("unknown");
+  });
+});
diff --git a/src/media/store.header-ext.test.ts b/src/media/store.header-ext.test.ts
deleted file mode 100644
index 7cfa99e24e1..00000000000
--- a/src/media/store.header-ext.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
-
-const realOs = await vi.importActual<typeof import("node:os")>("node:os");
-const HOME = path.join(realOs.tmpdir(), "openclaw-home-header-ext-test");
-
-vi.mock("node:os", () => ({
-  default: { homedir: () => HOME, tmpdir: () => realOs.tmpdir() },
-  homedir: () => HOME,
-  tmpdir: () => realOs.tmpdir(),
-}));
-
-vi.mock("./mime.js", async () => {
-  const actual = await vi.importActual<typeof import("./mime.js")>("./mime.js");
-  return {
-    ...actual,
-    detectMime: vi.fn(async () => "audio/opus"),
-  };
-});
-
-const store = await import("./store.js");
-
-describe("media store header extensions", () => {
-  beforeAll(async () => {
-    await fs.rm(HOME, { recursive: true, force: true });
-  });
-
-  afterAll(async () => {
-    await fs.rm(HOME, { recursive: true, force: true });
-  });
-
-  it("prefers header mime extension when sniffed mime lacks mapping", async () => {
-    const buf = Buffer.from("fake-audio");
-    const saved = await store.saveMediaBuffer(buf, "audio/ogg; codecs=opus");
-    expect(path.extname(saved.path)).toBe(".ogg");
-  });
-});
diff --git a/src/media/store.redirect.test.ts b/src/media/store.redirect.test.ts
index 40ba39815da..3d87f5bf9bf 100644
--- a/src/media/store.redirect.test.ts
+++ b/src/media/store.redirect.test.ts
@@ -4,14 +4,17 @@ import os from "node:os";
 import path from "node:path";
 import { PassThrough } from "node:stream";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { saveMediaSource, setMediaStoreNetworkDepsForTest } from "./store.js";
 
 const HOME = path.join(os.tmpdir(), "openclaw-home-redirect");
-const previousStateDir = process.env.OPENCLAW_STATE_DIR;
 const mockRequest = vi.fn();
 
 describe("media store redirects", () => {
+  let envSnapshot: ReturnType<typeof captureEnv>;
+
   beforeAll(async () => {
+    envSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
     await fs.rm(HOME, { recursive: true, force: true });
     process.env.OPENCLAW_STATE_DIR = HOME;
   });
@@ -29,11 +32,7 @@ describe("media store redirects", () => {
 
   afterAll(async () => {
     await fs.rm(HOME, { recursive: true, force: true });
-    if (previousStateDir === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previousStateDir;
-    }
+    envSnapshot.restore();
     setMediaStoreNetworkDepsForTest();
     vi.clearAllMocks();
   });
diff --git a/src/media/store.test.ts b/src/media/store.test.ts
index 5e7f510a829..0b6313c6b85 100644
--- a/src/media/store.test.ts
+++ b/src/media/store.test.ts
@@ -3,32 +3,23 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import sharp from "sharp";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { isPathWithinBase } from "../../test/helpers/paths.js";
+import { captureEnv } from "../test-utils/env.js";
 
 describe("media store", () => {
   let store: typeof import("./store.js");
   let home = "";
-  const envSnapshot: Record<string, string | undefined> = {};
-
-  const snapshotEnv = () => {
-    for (const key of ["HOME", "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "OPENCLAW_STATE_DIR"]) {
-      envSnapshot[key] = process.env[key];
-    }
-  };
-
-  const restoreEnv = () => {
-    for (const [key, value] of Object.entries(envSnapshot)) {
-      if (value === undefined) {
-        delete process.env[key];
-      } else {
-        process.env[key] = value;
-      }
-    }
-  };
+  let envSnapshot: ReturnType<typeof captureEnv>;
 
   beforeAll(async () => {
-    snapshotEnv();
+    envSnapshot = captureEnv([
+      "HOME",
+      "USERPROFILE",
+      "HOMEDRIVE",
+      "HOMEPATH",
+      "OPENCLAW_STATE_DIR",
+    ]);
     home = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-test-home-"));
     process.env.HOME = home;
     process.env.USERPROFILE = home;
@@ -45,7 +36,7 @@ describe("media store", () => {
   });
 
   afterAll(async () => {
-    restoreEnv();
+    envSnapshot.restore();
     try {
       await fs.rm(home, { recursive: true, force: true });
     } catch {
@@ -164,6 +155,29 @@ describe("media store", () => {
     });
   });
 
+  it("prefers header mime extension when sniffed mime lacks mapping", async () => {
+    await withTempStore(async (_store, home) => {
+      vi.resetModules();
+      vi.doMock("./mime.js", async () => {
+        const actual = await vi.importActual<typeof import("./mime.js")>("./mime.js");
+        return {
+          ...actual,
+          detectMime: vi.fn(async () => "audio/opus"),
+        };
+      });
+
+      try {
+        const storeWithMock = await import("./store.js");
+        const buf = Buffer.from("fake-audio");
+        const saved = await storeWithMock.saveMediaBuffer(buf, "audio/ogg; codecs=opus");
+        expect(path.extname(saved.path)).toBe(".ogg");
+        expect(saved.path.startsWith(home)).toBe(true);
+      } finally {
+        vi.doUnmock("./mime.js");
+      }
+    });
+  });
+
   describe("extractOriginalFilename", () => {
     it("extracts original filename from embedded pattern", async () => {
       await withTempStore(async (store) => {
diff --git a/src/memory/backend-config.test.ts b/src/memory/backend-config.test.ts
index 78fd73967e5..42385a1224d 100644
--- a/src/memory/backend-config.test.ts
+++ b/src/memory/backend-config.test.ts
@@ -31,6 +31,10 @@ describe("resolveMemoryBackendConfig", () => {
     expect(resolved.qmd?.update.commandTimeoutMs).toBe(30_000);
     expect(resolved.qmd?.update.updateTimeoutMs).toBe(120_000);
     expect(resolved.qmd?.update.embedTimeoutMs).toBe(120_000);
+    const names = new Set((resolved.qmd?.collections ?? []).map((collection) => collection.name));
+    expect(names.has("memory-root-main")).toBe(true);
+    expect(names.has("memory-alt-main")).toBe(true);
+    expect(names.has("memory-dir-main")).toBe(true);
   });
 
   it("parses quoted qmd command paths", () => {
@@ -73,6 +77,37 @@ describe("resolveMemoryBackendConfig", () => {
     expect(custom?.path).toBe(path.resolve(workspaceRoot, "notes"));
   });
 
+  it("scopes qmd collection names per agent", () => {
+    const cfg = {
+      agents: {
+        defaults: { workspace: "/workspace/root" },
+        list: [
+          { id: "main", default: true, workspace: "/workspace/root" },
+          { id: "dev", workspace: "/workspace/dev" },
+        ],
+      },
+      memory: {
+        backend: "qmd",
+        qmd: {
+          includeDefaultMemory: true,
+          paths: [{ path: "notes", name: "workspace", pattern: "**/*.md" }],
+        },
+      },
+    } as OpenClawConfig;
+    const mainResolved = resolveMemoryBackendConfig({ cfg, agentId: "main" });
+    const devResolved = resolveMemoryBackendConfig({ cfg, agentId: "dev" });
+    const mainNames = new Set(
+      (mainResolved.qmd?.collections ?? []).map((collection) => collection.name),
+    );
+    const devNames = new Set(
+      (devResolved.qmd?.collections ?? []).map((collection) => collection.name),
+    );
+    expect(mainNames.has("memory-dir-main")).toBe(true);
+    expect(devNames.has("memory-dir-dev")).toBe(true);
+    expect(mainNames.has("workspace-main")).toBe(true);
+    expect(devNames.has("workspace-dev")).toBe(true);
+  });
+
   it("resolves qmd update timeout overrides", () => {
     const cfg = {
       agents: { defaults: { workspace: "/tmp/memory-test" } },
diff --git a/src/memory/backend-config.ts b/src/memory/backend-config.ts
index 53f0a55845b..d632f4e8cb3 100644
--- a/src/memory/backend-config.ts
+++ b/src/memory/backend-config.ts
@@ -95,6 +95,10 @@ function sanitizeName(input: string): string {
   return trimmed || "collection";
 }
 
+function scopeCollectionBase(base: string, agentId: string): string {
+  return `${base}-${sanitizeName(agentId)}`;
+}
+
 function ensureUniqueName(base: string, existing: Set<string>): string {
   let name = sanitizeName(base);
   if (!existing.has(name)) {
@@ -203,6 +207,7 @@ function resolveCustomPaths(
   rawPaths: MemoryQmdIndexPath[] | undefined,
   workspaceDir: string,
   existing: Set<string>,
+  agentId: string,
 ): ResolvedQmdCollection[] {
   if (!rawPaths?.length) {
     return [];
@@ -220,7 +225,7 @@ function resolveCustomPaths(
       return;
     }
     const pattern = entry.pattern?.trim() || "**/*.md";
-    const baseName = entry.name?.trim() || `custom-${index + 1}`;
+    const baseName = scopeCollectionBase(entry.name?.trim() || `custom-${index + 1}`, agentId);
     const name = ensureUniqueName(baseName, existing);
     collections.push({
       name,
@@ -236,6 +241,7 @@ function resolveDefaultCollections(
   include: boolean,
   workspaceDir: string,
   existing: Set<string>,
+  agentId: string,
 ): ResolvedQmdCollection[] {
   if (!include) {
     return [];
@@ -246,7 +252,7 @@ function resolveDefaultCollections(
     { path: path.join(workspaceDir, "memory"), pattern: "**/*.md", base: "memory-dir" },
   ];
   return entries.map((entry) => ({
-    name: ensureUniqueName(entry.base, existing),
+    name: ensureUniqueName(scopeCollectionBase(entry.base, agentId), existing),
     path: entry.path,
     pattern: entry.pattern,
     kind: "memory",
@@ -268,8 +274,8 @@ export function resolveMemoryBackendConfig(params: {
   const includeDefaultMemory = qmdCfg?.includeDefaultMemory !== false;
   const nameSet = new Set<string>();
   const collections = [
-    ...resolveDefaultCollections(includeDefaultMemory, workspaceDir, nameSet),
-    ...resolveCustomPaths(qmdCfg?.paths, workspaceDir, nameSet),
+    ...resolveDefaultCollections(includeDefaultMemory, workspaceDir, nameSet, params.agentId),
+    ...resolveCustomPaths(qmdCfg?.paths, workspaceDir, nameSet, params.agentId),
   ];
 
   const rawCommand = qmdCfg?.command?.trim() || "qmd";
diff --git a/src/memory/batch-gemini.ts b/src/memory/batch-gemini.ts
index 83c8e83186f..a0feef2672a 100644
--- a/src/memory/batch-gemini.ts
+++ b/src/memory/batch-gemini.ts
@@ -1,6 +1,7 @@
 import type { GeminiEmbeddingClient } from "./embeddings-gemini.js";
 import { isTruthyEnvValue } from "../infra/env.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
+import { buildBatchHeaders, normalizeBatchBaseUrl, splitBatchRequests } from "./batch-utils.js";
 import { hashText, runWithConcurrency } from "./internal.js";
 
 export type GeminiBatchRequest = {
@@ -45,26 +46,6 @@ const debugLog = (message: string, meta?: Record<string, unknown>) => {
   log.raw(`${message}${suffix}`);
 };
 
-function getGeminiBaseUrl(gemini: GeminiEmbeddingClient): string {
-  return gemini.baseUrl?.replace(/\/$/, "") ?? "";
-}
-
-function getGeminiHeaders(
-  gemini: GeminiEmbeddingClient,
-  params: { json: boolean },
-): Record<string, string> {
-  const headers = gemini.headers ? { ...gemini.headers } : {};
-  if (params.json) {
-    if (!headers["Content-Type"] && !headers["content-type"]) {
-      headers["Content-Type"] = "application/json";
-    }
-  } else {
-    delete headers["Content-Type"];
-    delete headers["content-type"];
-  }
-  return headers;
-}
-
 function getGeminiUploadUrl(baseUrl: string): string {
   if (baseUrl.includes("/v1beta")) {
     return baseUrl.replace(/\/v1beta\/?$/, "/upload/v1beta");
@@ -72,17 +53,6 @@ function getGeminiUploadUrl(baseUrl: string): string {
   return `${baseUrl.replace(/\/$/, "")}/upload`;
 }
 
-function splitGeminiBatchRequests(requests: GeminiBatchRequest[]): GeminiBatchRequest[][] {
-  if (requests.length <= GEMINI_BATCH_MAX_REQUESTS) {
-    return [requests];
-  }
-  const groups: GeminiBatchRequest[][] = [];
-  for (let i = 0; i < requests.length; i += GEMINI_BATCH_MAX_REQUESTS) {
-    groups.push(requests.slice(i, i + GEMINI_BATCH_MAX_REQUESTS));
-  }
-  return groups;
-}
-
 function buildGeminiUploadBody(params: { jsonl: string; displayName: string }): {
   body: Blob;
   contentType: string;
@@ -113,7 +83,7 @@ async function submitGeminiBatch(params: {
   requests: GeminiBatchRequest[];
   agentId: string;
 }): Promise<GeminiBatchStatus> {
-  const baseUrl = getGeminiBaseUrl(params.gemini);
+  const baseUrl = normalizeBatchBaseUrl(params.gemini);
   const jsonl = params.requests
     .map((request) =>
       JSON.stringify({
@@ -137,7 +107,7 @@ async function submitGeminiBatch(params: {
   const fileRes = await fetch(uploadUrl, {
     method: "POST",
     headers: {
-      ...getGeminiHeaders(params.gemini, { json: false }),
+      ...buildBatchHeaders(params.gemini, { json: false }),
       "Content-Type": uploadPayload.contentType,
     },
     body: uploadPayload.body,
@@ -168,7 +138,7 @@ async function submitGeminiBatch(params: {
   });
   const batchRes = await fetch(batchEndpoint, {
     method: "POST",
-    headers: getGeminiHeaders(params.gemini, { json: true }),
+    headers: buildBatchHeaders(params.gemini, { json: true }),
     body: JSON.stringify(batchBody),
   });
   if (batchRes.ok) {
@@ -187,14 +157,14 @@ async function fetchGeminiBatchStatus(params: {
   gemini: GeminiEmbeddingClient;
   batchName: string;
 }): Promise<GeminiBatchStatus> {
-  const baseUrl = getGeminiBaseUrl(params.gemini);
+  const baseUrl = normalizeBatchBaseUrl(params.gemini);
   const name = params.batchName.startsWith("batches/")
     ? params.batchName
     : `batches/${params.batchName}`;
   const statusUrl = `${baseUrl}/${name}`;
   debugLog("memory embeddings: gemini batch status", { statusUrl });
   const res = await fetch(statusUrl, {
-    headers: getGeminiHeaders(params.gemini, { json: true }),
+    headers: buildBatchHeaders(params.gemini, { json: true }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -207,12 +177,12 @@ async function fetchGeminiFileContent(params: {
   gemini: GeminiEmbeddingClient;
   fileId: string;
 }): Promise<string> {
-  const baseUrl = getGeminiBaseUrl(params.gemini);
+  const baseUrl = normalizeBatchBaseUrl(params.gemini);
   const file = params.fileId.startsWith("files/") ? params.fileId : `files/${params.fileId}`;
   const downloadUrl = `${baseUrl}/${file}:download`;
   debugLog("memory embeddings: gemini batch download", { downloadUrl });
   const res = await fetch(downloadUrl, {
-    headers: getGeminiHeaders(params.gemini, { json: true }),
+    headers: buildBatchHeaders(params.gemini, { json: true }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -290,7 +260,7 @@ export async function runGeminiEmbeddingBatches(params: {
   if (params.requests.length === 0) {
     return new Map();
   }
-  const groups = splitGeminiBatchRequests(params.requests);
+  const groups = splitBatchRequests(params.requests, GEMINI_BATCH_MAX_REQUESTS);
   const byCustomId = new Map<string, number[]>();
 
   const tasks = groups.map((group, groupIndex) => async () => {
diff --git a/src/memory/batch-openai.ts b/src/memory/batch-openai.ts
index 6c35a831b36..cdce55b0a98 100644
--- a/src/memory/batch-openai.ts
+++ b/src/memory/batch-openai.ts
@@ -1,6 +1,7 @@
 import type { OpenAiEmbeddingClient } from "./embeddings-openai.js";
 import { postJsonWithRetry } from "./batch-http.js";
 import { applyEmbeddingBatchOutputLine } from "./batch-output.js";
+import { buildBatchHeaders, normalizeBatchBaseUrl, splitBatchRequests } from "./batch-utils.js";
 import { hashText, runWithConcurrency } from "./internal.js";
 
 export type OpenAiBatchRequest = {
@@ -36,43 +37,12 @@ export const OPENAI_BATCH_ENDPOINT = "/v1/embeddings";
 const OPENAI_BATCH_COMPLETION_WINDOW = "24h";
 const OPENAI_BATCH_MAX_REQUESTS = 50000;
 
-function getOpenAiBaseUrl(openAi: OpenAiEmbeddingClient): string {
-  return openAi.baseUrl?.replace(/\/$/, "") ?? "";
-}
-
-function getOpenAiHeaders(
-  openAi: OpenAiEmbeddingClient,
-  params: { json: boolean },
-): Record<string, string> {
-  const headers = openAi.headers ? { ...openAi.headers } : {};
-  if (params.json) {
-    if (!headers["Content-Type"] && !headers["content-type"]) {
-      headers["Content-Type"] = "application/json";
-    }
-  } else {
-    delete headers["Content-Type"];
-    delete headers["content-type"];
-  }
-  return headers;
-}
-
-function splitOpenAiBatchRequests(requests: OpenAiBatchRequest[]): OpenAiBatchRequest[][] {
-  if (requests.length <= OPENAI_BATCH_MAX_REQUESTS) {
-    return [requests];
-  }
-  const groups: OpenAiBatchRequest[][] = [];
-  for (let i = 0; i < requests.length; i += OPENAI_BATCH_MAX_REQUESTS) {
-    groups.push(requests.slice(i, i + OPENAI_BATCH_MAX_REQUESTS));
-  }
-  return groups;
-}
-
 async function submitOpenAiBatch(params: {
   openAi: OpenAiEmbeddingClient;
   requests: OpenAiBatchRequest[];
   agentId: string;
 }): Promise<OpenAiBatchStatus> {
-  const baseUrl = getOpenAiBaseUrl(params.openAi);
+  const baseUrl = normalizeBatchBaseUrl(params.openAi);
   const jsonl = params.requests.map((request) => JSON.stringify(request)).join("\n");
   const form = new FormData();
   form.append("purpose", "batch");
@@ -84,7 +54,7 @@ async function submitOpenAiBatch(params: {
 
   const fileRes = await fetch(`${baseUrl}/files`, {
     method: "POST",
-    headers: getOpenAiHeaders(params.openAi, { json: false }),
+    headers: buildBatchHeaders(params.openAi, { json: false }),
     body: form,
   });
   if (!fileRes.ok) {
@@ -98,7 +68,7 @@ async function submitOpenAiBatch(params: {
 
   return await postJsonWithRetry<OpenAiBatchStatus>({
     url: `${baseUrl}/batches`,
-    headers: getOpenAiHeaders(params.openAi, { json: true }),
+    headers: buildBatchHeaders(params.openAi, { json: true }),
     body: {
       input_file_id: filePayload.id,
       endpoint: OPENAI_BATCH_ENDPOINT,
@@ -116,9 +86,9 @@ async function fetchOpenAiBatchStatus(params: {
   openAi: OpenAiEmbeddingClient;
   batchId: string;
 }): Promise<OpenAiBatchStatus> {
-  const baseUrl = getOpenAiBaseUrl(params.openAi);
+  const baseUrl = normalizeBatchBaseUrl(params.openAi);
   const res = await fetch(`${baseUrl}/batches/${params.batchId}`, {
-    headers: getOpenAiHeaders(params.openAi, { json: true }),
+    headers: buildBatchHeaders(params.openAi, { json: true }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -131,9 +101,9 @@ async function fetchOpenAiFileContent(params: {
   openAi: OpenAiEmbeddingClient;
   fileId: string;
 }): Promise<string> {
-  const baseUrl = getOpenAiBaseUrl(params.openAi);
+  const baseUrl = normalizeBatchBaseUrl(params.openAi);
   const res = await fetch(`${baseUrl}/files/${params.fileId}/content`, {
-    headers: getOpenAiHeaders(params.openAi, { json: true }),
+    headers: buildBatchHeaders(params.openAi, { json: true }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -236,7 +206,7 @@ export async function runOpenAiEmbeddingBatches(params: {
   if (params.requests.length === 0) {
     return new Map();
   }
-  const groups = splitOpenAiBatchRequests(params.requests);
+  const groups = splitBatchRequests(params.requests, OPENAI_BATCH_MAX_REQUESTS);
   const byCustomId = new Map<string, number[]>();
 
   const tasks = groups.map((group, groupIndex) => async () => {
diff --git a/src/memory/batch-utils.ts b/src/memory/batch-utils.ts
new file mode 100644
index 00000000000..95aa773e81e
--- /dev/null
+++ b/src/memory/batch-utils.ts
@@ -0,0 +1,35 @@
+export type BatchHttpClientConfig = {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+};
+
+export function normalizeBatchBaseUrl(client: BatchHttpClientConfig): string {
+  return client.baseUrl?.replace(/\/$/, "") ?? "";
+}
+
+export function buildBatchHeaders(
+  client: Pick<BatchHttpClientConfig, "headers">,
+  params: { json: boolean },
+): Record<string, string> {
+  const headers = client.headers ? { ...client.headers } : {};
+  if (params.json) {
+    if (!headers["Content-Type"] && !headers["content-type"]) {
+      headers["Content-Type"] = "application/json";
+    }
+  } else {
+    delete headers["Content-Type"];
+    delete headers["content-type"];
+  }
+  return headers;
+}
+
+export function splitBatchRequests<T>(requests: T[], maxRequests: number): T[][] {
+  if (requests.length <= maxRequests) {
+    return [requests];
+  }
+  const groups: T[][] = [];
+  for (let i = 0; i < requests.length; i += maxRequests) {
+    groups.push(requests.slice(i, i + maxRequests));
+  }
+  return groups;
+}
diff --git a/src/memory/batch-voyage.ts b/src/memory/batch-voyage.ts
index 72fdf09a2ff..b2c7f9f4d52 100644
--- a/src/memory/batch-voyage.ts
+++ b/src/memory/batch-voyage.ts
@@ -3,6 +3,7 @@ import { Readable } from "node:stream";
 import type { VoyageEmbeddingClient } from "./embeddings-voyage.js";
 import { postJsonWithRetry } from "./batch-http.js";
 import { applyEmbeddingBatchOutputLine } from "./batch-output.js";
+import { buildBatchHeaders, normalizeBatchBaseUrl, splitBatchRequests } from "./batch-utils.js";
 import { hashText, runWithConcurrency } from "./internal.js";
 
 /**
@@ -39,43 +40,12 @@ export const VOYAGE_BATCH_ENDPOINT = "/v1/embeddings";
 const VOYAGE_BATCH_COMPLETION_WINDOW = "12h";
 const VOYAGE_BATCH_MAX_REQUESTS = 50000;
 
-function getVoyageBaseUrl(client: VoyageEmbeddingClient): string {
-  return client.baseUrl?.replace(/\/$/, "") ?? "";
-}
-
-function getVoyageHeaders(
-  client: VoyageEmbeddingClient,
-  params: { json: boolean },
-): Record<string, string> {
-  const headers = client.headers ? { ...client.headers } : {};
-  if (params.json) {
-    if (!headers["Content-Type"] && !headers["content-type"]) {
-      headers["Content-Type"] = "application/json";
-    }
-  } else {
-    delete headers["Content-Type"];
-    delete headers["content-type"];
-  }
-  return headers;
-}
-
-function splitVoyageBatchRequests(requests: VoyageBatchRequest[]): VoyageBatchRequest[][] {
-  if (requests.length <= VOYAGE_BATCH_MAX_REQUESTS) {
-    return [requests];
-  }
-  const groups: VoyageBatchRequest[][] = [];
-  for (let i = 0; i < requests.length; i += VOYAGE_BATCH_MAX_REQUESTS) {
-    groups.push(requests.slice(i, i + VOYAGE_BATCH_MAX_REQUESTS));
-  }
-  return groups;
-}
-
 async function submitVoyageBatch(params: {
   client: VoyageEmbeddingClient;
   requests: VoyageBatchRequest[];
   agentId: string;
 }): Promise<VoyageBatchStatus> {
-  const baseUrl = getVoyageBaseUrl(params.client);
+  const baseUrl = normalizeBatchBaseUrl(params.client);
   const jsonl = params.requests.map((request) => JSON.stringify(request)).join("\n");
   const form = new FormData();
   form.append("purpose", "batch");
@@ -88,7 +58,7 @@ async function submitVoyageBatch(params: {
   // 1. Upload file using Voyage Files API
   const fileRes = await fetch(`${baseUrl}/files`, {
     method: "POST",
-    headers: getVoyageHeaders(params.client, { json: false }),
+    headers: buildBatchHeaders(params.client, { json: false }),
     body: form,
   });
   if (!fileRes.ok) {
@@ -103,7 +73,7 @@ async function submitVoyageBatch(params: {
   // 2. Create batch job using Voyage Batches API
   return await postJsonWithRetry<VoyageBatchStatus>({
     url: `${baseUrl}/batches`,
-    headers: getVoyageHeaders(params.client, { json: true }),
+    headers: buildBatchHeaders(params.client, { json: true }),
     body: {
       input_file_id: filePayload.id,
       endpoint: VOYAGE_BATCH_ENDPOINT,
@@ -125,9 +95,9 @@ async function fetchVoyageBatchStatus(params: {
   client: VoyageEmbeddingClient;
   batchId: string;
 }): Promise<VoyageBatchStatus> {
-  const baseUrl = getVoyageBaseUrl(params.client);
+  const baseUrl = normalizeBatchBaseUrl(params.client);
   const res = await fetch(`${baseUrl}/batches/${params.batchId}`, {
-    headers: getVoyageHeaders(params.client, { json: true }),
+    headers: buildBatchHeaders(params.client, { json: true }),
   });
   if (!res.ok) {
     const text = await res.text();
@@ -141,9 +111,9 @@ async function readVoyageBatchError(params: {
   errorFileId: string;
 }): Promise<string | undefined> {
   try {
-    const baseUrl = getVoyageBaseUrl(params.client);
+    const baseUrl = normalizeBatchBaseUrl(params.client);
     const res = await fetch(`${baseUrl}/files/${params.errorFileId}/content`, {
-      headers: getVoyageHeaders(params.client, { json: true }),
+      headers: buildBatchHeaders(params.client, { json: true }),
     });
     if (!res.ok) {
       const text = await res.text();
@@ -231,7 +201,7 @@ export async function runVoyageEmbeddingBatches(params: {
   if (params.requests.length === 0) {
     return new Map();
   }
-  const groups = splitVoyageBatchRequests(params.requests);
+  const groups = splitBatchRequests(params.requests, VOYAGE_BATCH_MAX_REQUESTS);
   const byCustomId = new Map<string, number[]>();
 
   const tasks = groups.map((group, groupIndex) => async () => {
@@ -277,9 +247,9 @@ export async function runVoyageEmbeddingBatches(params: {
       throw new Error(`voyage batch ${batchInfo.id} completed without output file`);
     }
 
-    const baseUrl = getVoyageBaseUrl(params.client);
+    const baseUrl = normalizeBatchBaseUrl(params.client);
     const contentRes = await fetch(`${baseUrl}/files/${completed.outputFileId}/content`, {
-      headers: getVoyageHeaders(params.client, { json: true }),
+      headers: buildBatchHeaders(params.client, { json: true }),
     });
     if (!contentRes.ok) {
       const text = await contentRes.text();
diff --git a/src/memory/embedding-chunk-limits.test.ts b/src/memory/embedding-chunk-limits.test.ts
new file mode 100644
index 00000000000..9785693ee75
--- /dev/null
+++ b/src/memory/embedding-chunk-limits.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import type { EmbeddingProvider } from "./embeddings.js";
+import { enforceEmbeddingMaxInputTokens } from "./embedding-chunk-limits.js";
+import { estimateUtf8Bytes } from "./embedding-input-limits.js";
+
+function createProvider(maxInputTokens: number): EmbeddingProvider {
+  return {
+    id: "mock",
+    model: "mock-embed",
+    maxInputTokens,
+    embedQuery: async () => [0],
+    embedBatch: async () => [[0]],
+  };
+}
+
+describe("embedding chunk limits", () => {
+  it("splits oversized chunks so each embedding input stays <= maxInputTokens bytes", () => {
+    const provider = createProvider(8192);
+    const input = {
+      startLine: 1,
+      endLine: 1,
+      text: "x".repeat(9000),
+      hash: "ignored",
+    };
+
+    const out = enforceEmbeddingMaxInputTokens(provider, [input]);
+    expect(out.length).toBeGreaterThan(1);
+    expect(out.map((chunk) => chunk.text).join("")).toBe(input.text);
+    expect(out.every((chunk) => estimateUtf8Bytes(chunk.text) <= 8192)).toBe(true);
+    expect(out.every((chunk) => chunk.startLine === 1 && chunk.endLine === 1)).toBe(true);
+    expect(out.every((chunk) => typeof chunk.hash === "string" && chunk.hash.length > 0)).toBe(
+      true,
+    );
+  });
+
+  it("does not split inside surrogate pairs (emoji)", () => {
+    const provider = createProvider(8192);
+    const emoji = "😀";
+    const inputText = `${emoji.repeat(2100)}\n${emoji.repeat(2100)}`;
+
+    const out = enforceEmbeddingMaxInputTokens(provider, [
+      { startLine: 1, endLine: 2, text: inputText, hash: "ignored" },
+    ]);
+
+    expect(out.length).toBeGreaterThan(1);
+    expect(out.map((chunk) => chunk.text).join("")).toBe(inputText);
+    expect(out.every((chunk) => estimateUtf8Bytes(chunk.text) <= 8192)).toBe(true);
+
+    // If we split inside surrogate pairs we'd likely end up with replacement chars.
+    expect(out.map((chunk) => chunk.text).join("")).not.toContain("\uFFFD");
+  });
+});
diff --git a/src/memory/hybrid.test.ts b/src/memory/hybrid.test.ts
index 7105e9ecf27..6e9d8f42646 100644
--- a/src/memory/hybrid.test.ts
+++ b/src/memory/hybrid.test.ts
@@ -5,6 +5,8 @@ describe("memory hybrid helpers", () => {
   it("buildFtsQuery tokenizes and AND-joins", () => {
     expect(buildFtsQuery("hello world")).toBe('"hello" AND "world"');
     expect(buildFtsQuery("FOO_bar baz-1")).toBe('"FOO_bar" AND "baz" AND "1"');
+    expect(buildFtsQuery("金银价格")).toBe('"金银价格"');
+    expect(buildFtsQuery("価格 2026年")).toBe('"価格" AND "2026年"');
     expect(buildFtsQuery("   ")).toBeNull();
   });
 
diff --git a/src/memory/hybrid.ts b/src/memory/hybrid.ts
index 1dd7c9fdab8..cea9f260412 100644
--- a/src/memory/hybrid.ts
+++ b/src/memory/hybrid.ts
@@ -23,7 +23,7 @@ export type HybridKeywordResult = {
 export function buildFtsQuery(raw: string): string | null {
   const tokens =
     raw
-      .match(/[A-Za-z0-9_]+/g)
+      .match(/[\p{L}\p{N}_]+/gu)
       ?.map((t) => t.trim())
       .filter(Boolean) ?? [];
   if (tokens.length === 0) {
diff --git a/src/memory/index.test.ts b/src/memory/index.test.ts
index 4e8d5a84712..4c94ebfc31f 100644
--- a/src/memory/index.test.ts
+++ b/src/memory/index.test.ts
@@ -46,10 +46,8 @@ describe("memory index", () => {
   let workspaceDir = "";
   let memoryDir = "";
   let extraDir = "";
-  let indexBasicPath = "";
-  let indexCachePath = "";
-  let indexHybridPath = "";
   let indexVectorPath = "";
+  let indexMainPath = "";
   let indexExtraPath = "";
 
   // Perf: keep managers open across tests, but only reset the one a test uses.
@@ -61,13 +59,15 @@ describe("memory index", () => {
     workspaceDir = path.join(fixtureRoot, "workspace");
     memoryDir = path.join(workspaceDir, "memory");
     extraDir = path.join(workspaceDir, "extra");
-    indexBasicPath = path.join(workspaceDir, "index-basic.sqlite");
-    indexCachePath = path.join(workspaceDir, "index-cache.sqlite");
-    indexHybridPath = path.join(workspaceDir, "index-hybrid.sqlite");
+    indexMainPath = path.join(workspaceDir, "index-main.sqlite");
     indexVectorPath = path.join(workspaceDir, "index-vector.sqlite");
     indexExtraPath = path.join(workspaceDir, "index-extra.sqlite");
 
     await fs.mkdir(memoryDir, { recursive: true });
+    await fs.writeFile(
+      path.join(memoryDir, "2026-01-12.md"),
+      "# Log\nAlpha memory line.\nZebra memory line.",
+    );
   });
 
   afterAll(async () => {
@@ -83,10 +83,6 @@ describe("memory index", () => {
 
     // Keep the workspace stable to allow manager reuse across tests.
     await fs.mkdir(memoryDir, { recursive: true });
-    await fs.writeFile(
-      path.join(memoryDir, "2026-01-12.md"),
-      "# Log\nAlpha memory line.\nZebra memory line.",
-    );
 
     // Clean additional paths that may have been created by earlier cases.
     await fs.rm(extraDir, { recursive: true, force: true });
@@ -105,6 +101,38 @@ describe("memory index", () => {
 
   type TestCfg = Parameters<typeof getMemorySearchManager>[0]["cfg"];
 
+  function createCfg(params: {
+    storePath: string;
+    extraPaths?: string[];
+    model?: string;
+    vectorEnabled?: boolean;
+    cacheEnabled?: boolean;
+    hybrid?: { enabled: boolean; vectorWeight?: number; textWeight?: number };
+  }): TestCfg {
+    return {
+      agents: {
+        defaults: {
+          workspace: workspaceDir,
+          memorySearch: {
+            provider: "openai",
+            model: params.model ?? "mock-embed",
+            store: { path: params.storePath, vector: { enabled: params.vectorEnabled ?? false } },
+            // Perf: keep test indexes to a single chunk to reduce sqlite work.
+            chunking: { tokens: 4000, overlap: 0 },
+            sync: { watch: false, onSessionStart: false, onSearch: true },
+            query: {
+              minScore: 0,
+              hybrid: params.hybrid ?? { enabled: false },
+            },
+            cache: params.cacheEnabled ? { enabled: true } : undefined,
+            extraPaths: params.extraPaths,
+          },
+        },
+        list: [{ id: "main", default: true }],
+      },
+    };
+  }
+
   async function getPersistentManager(cfg: TestCfg): Promise<MemoryIndexManager> {
     const storePath = cfg.agents?.defaults?.memorySearch?.store?.path;
     if (!storePath) {
@@ -128,24 +156,14 @@ describe("memory index", () => {
     return manager;
   }
 
-  it("indexes memory files and searches by vector", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexBasicPath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: { minScore: 0, hybrid: { enabled: false } },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+  it("indexes memory files and searches", async () => {
+    const cfg = createCfg({
+      storePath: indexMainPath,
+      hybrid: { enabled: true, vectorWeight: 0.5, textWeight: 0.5 },
+    });
     const manager = await getPersistentManager(cfg);
     await manager.sync({ reason: "test" });
+    expect(embedBatchCalls).toBeGreaterThan(0);
     const results = await manager.search("alpha");
     expect(results.length).toBeGreaterThan(0);
     expect(results[0]?.path).toContain("memory/2026-01-12.md");
@@ -162,26 +180,8 @@ describe("memory index", () => {
   });
 
   it("keeps dirty false in status-only manager after prior indexing", async () => {
-    const indexStatusPath = path.join(workspaceDir, "index-status.sqlite");
-    await fs.rm(indexStatusPath, { force: true });
-    await fs.rm(`${indexStatusPath}-shm`, { force: true });
-    await fs.rm(`${indexStatusPath}-wal`, { force: true });
-
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexStatusPath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: { minScore: 0, hybrid: { enabled: false } },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const indexStatusPath = path.join(workspaceDir, `index-status-${Date.now()}.sqlite`);
+    const cfg = createCfg({ storePath: indexStatusPath });
 
     const first = await getMemorySearchManager({ cfg, agentId: "main" });
     expect(first.manager).not.toBeNull();
@@ -207,25 +207,8 @@ describe("memory index", () => {
   });
 
   it("reindexes when the embedding model changes", async () => {
-    const indexModelPath = path.join(workspaceDir, "index-model-change.sqlite");
-    await fs.rm(indexModelPath, { force: true });
-    await fs.rm(`${indexModelPath}-shm`, { force: true });
-    await fs.rm(`${indexModelPath}-wal`, { force: true });
-
-    const base = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            store: { path: indexModelPath },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: { minScore: 0, hybrid: { enabled: false } },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const indexModelPath = path.join(workspaceDir, `index-model-change-${Date.now()}.sqlite`);
+    const base = createCfg({ storePath: indexModelPath });
 
     const first = await getMemorySearchManager({
       cfg: {
@@ -279,24 +262,11 @@ describe("memory index", () => {
   });
 
   it("reuses cached embeddings on forced reindex", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexCachePath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: false },
-            query: { minScore: 0, hybrid: { enabled: false } },
-            cache: { enabled: true },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const cfg = createCfg({ storePath: indexMainPath, cacheEnabled: true });
     const manager = await getPersistentManager(cfg);
-    await manager.sync({ force: true });
+    // Seed the embedding cache once, then ensure a forced reindex doesn't
+    // re-embed when the cache is enabled.
+    await manager.sync({ reason: "test" });
     const afterFirst = embedBatchCalls;
     expect(afterFirst).toBeGreaterThan(0);
 
@@ -305,24 +275,10 @@ describe("memory index", () => {
   });
 
   it("finds keyword matches via hybrid search when query embedding is zero", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexHybridPath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: {
-              minScore: 0,
-              hybrid: { enabled: true, vectorWeight: 0, textWeight: 1 },
-            },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const cfg = createCfg({
+      storePath: indexMainPath,
+      hybrid: { enabled: true, vectorWeight: 0, textWeight: 1 },
+    });
     const manager = await getPersistentManager(cfg);
 
     const status = manager.status();
@@ -337,20 +293,7 @@ describe("memory index", () => {
   });
 
   it("reports vector availability after probe", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexVectorPath, vector: { enabled: true } },
-            sync: { watch: false, onSessionStart: false, onSearch: false },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const cfg = createCfg({ storePath: indexVectorPath, vectorEnabled: true });
     const manager = await getPersistentManager(cfg);
     const available = await manager.probeVectorAvailability();
     const status = manager.status();
@@ -360,21 +303,7 @@ describe("memory index", () => {
   });
 
   it("rejects reading non-memory paths", async () => {
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexBasicPath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: { minScore: 0, hybrid: { enabled: false } },
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const cfg = createCfg({ storePath: indexMainPath });
     const manager = await getPersistentManager(cfg);
     await expect(manager.readFile({ relPath: "NOTES.md" })).rejects.toThrow("path required");
   });
@@ -383,22 +312,7 @@ describe("memory index", () => {
     await fs.mkdir(extraDir, { recursive: true });
     await fs.writeFile(path.join(extraDir, "extra.md"), "Extra content.");
 
-    const cfg = {
-      agents: {
-        defaults: {
-          workspace: workspaceDir,
-          memorySearch: {
-            provider: "openai",
-            model: "mock-embed",
-            store: { path: indexExtraPath, vector: { enabled: false } },
-            sync: { watch: false, onSessionStart: false, onSearch: true },
-            query: { minScore: 0, hybrid: { enabled: false } },
-            extraPaths: [extraDir],
-          },
-        },
-        list: [{ id: "main", default: true }],
-      },
-    };
+    const cfg = createCfg({ storePath: indexExtraPath, extraPaths: [extraDir] });
     const manager = await getPersistentManager(cfg);
     await expect(manager.readFile({ relPath: "extra/extra.md" })).resolves.toEqual({
       path: "extra/extra.md",
diff --git a/src/memory/manager-embedding-ops.ts b/src/memory/manager-embedding-ops.ts
index 973ae3610e4..72b5c25c46b 100644
--- a/src/memory/manager-embedding-ops.ts
+++ b/src/memory/manager-embedding-ops.ts
@@ -175,19 +175,7 @@ class MemoryManagerEmbeddingOps {
     if (chunks.length === 0) {
       return [];
     }
-    const cached = this.loadEmbeddingCache(chunks.map((chunk) => chunk.hash));
-    const embeddings: number[][] = Array.from({ length: chunks.length }, () => []);
-    const missing: Array<{ index: number; chunk: MemoryChunk }> = [];
-
-    for (let i = 0; i < chunks.length; i += 1) {
-      const chunk = chunks[i];
-      const hit = chunk?.hash ? cached.get(chunk.hash) : undefined;
-      if (hit && hit.length > 0) {
-        embeddings[i] = hit;
-      } else if (chunk) {
-        missing.push({ index: i, chunk });
-      }
-    }
+    const { embeddings, missing } = this.collectCachedEmbeddings(chunks);
 
     if (missing.length === 0) {
       return embeddings;
diff --git a/src/memory/manager.async-search.test.ts b/src/memory/manager.async-search.test.ts
index 7f60ef0ea9f..114957bbc4c 100644
--- a/src/memory/manager.async-search.test.ts
+++ b/src/memory/manager.async-search.test.ts
@@ -73,10 +73,19 @@ describe("memory search async sync", () => {
     const pending = new Promise<void>(() => {});
     (manager as unknown as { sync: () => Promise<void> }).sync = vi.fn(async () => pending);
 
-    const resolved = await Promise.race([
-      manager.search("hello").then(() => true),
-      new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 1000)),
-    ]);
+    const resolved = await new Promise<boolean>((resolve, reject) => {
+      const timeout = setTimeout(() => resolve(false), 1000);
+      void manager
+        .search("hello")
+        .then(() => {
+          clearTimeout(timeout);
+          resolve(true);
+        })
+        .catch((err) => {
+          clearTimeout(timeout);
+          reject(err);
+        });
+    });
     expect(resolved).toBe(true);
   });
 });
diff --git a/src/memory/manager.atomic-reindex.test.ts b/src/memory/manager.atomic-reindex.test.ts
index 17434610e11..8979f388b7a 100644
--- a/src/memory/manager.atomic-reindex.test.ts
+++ b/src/memory/manager.atomic-reindex.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { getMemorySearchManager, type MemoryIndexManager } from "./index.js";
 
 let shouldFail = false;
@@ -34,15 +34,26 @@ vi.mock("./embeddings.js", () => {
   };
 });
 
+vi.mock("./sqlite-vec.js", () => ({
+  loadSqliteVecExtension: async () => ({ ok: false, error: "sqlite-vec disabled in tests" }),
+}));
+
 describe("memory manager atomic reindex", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
   let workspaceDir: string;
   let indexPath: string;
   let manager: MemoryIndexManager | null = null;
 
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-mem-atomic-"));
+  });
+
   beforeEach(async () => {
     vi.stubEnv("OPENCLAW_TEST_MEMORY_UNSAFE_REINDEX", "0");
     shouldFail = false;
-    workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-mem-"));
+    workspaceDir = path.join(fixtureRoot, `case-${caseId++}`);
+    await fs.mkdir(workspaceDir, { recursive: true });
     indexPath = path.join(workspaceDir, "index.sqlite");
     await fs.mkdir(path.join(workspaceDir, "memory"));
     await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "Hello memory.");
@@ -53,7 +64,13 @@ describe("memory manager atomic reindex", () => {
       await manager.close();
       manager = null;
     }
-    await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  afterAll(async () => {
+    if (!fixtureRoot) {
+      return;
+    }
+    await fs.rm(fixtureRoot, { recursive: true, force: true });
   });
 
   it("keeps the prior index when a full reindex fails", async () => {
@@ -66,6 +83,8 @@ describe("memory manager atomic reindex", () => {
             model: "mock-embed",
             store: { path: indexPath },
             cache: { enabled: false },
+            // Perf: keep test indexes to a single chunk to reduce sqlite work.
+            chunking: { tokens: 4000, overlap: 0 },
             sync: { watch: false, onSessionStart: false, onSearch: false },
           },
         },
@@ -81,13 +100,13 @@ describe("memory manager atomic reindex", () => {
     manager = result.manager;
 
     await manager.sync({ force: true });
-    const before = await manager.search("Hello");
-    expect(before.length).toBeGreaterThan(0);
+    const beforeStatus = manager.status();
+    expect(beforeStatus.chunks).toBeGreaterThan(0);
 
     shouldFail = true;
     await expect(manager.sync({ force: true })).rejects.toThrow("embedding failure");
 
-    const after = await manager.search("Hello");
-    expect(after.length).toBeGreaterThan(0);
+    const afterStatus = manager.status();
+    expect(afterStatus.chunks).toBeGreaterThan(0);
   });
 });
diff --git a/src/memory/manager.embedding-token-limit.test.ts b/src/memory/manager.embedding-token-limit.test.ts
deleted file mode 100644
index 51b0de421b6..00000000000
--- a/src/memory/manager.embedding-token-limit.test.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { installEmbeddingManagerFixture } from "./embedding-manager.test-harness.js";
-
-const fx = installEmbeddingManagerFixture({
-  fixturePrefix: "openclaw-mem-token-",
-  largeTokens: 10_000,
-  smallTokens: 1000,
-  createCfg: ({ workspaceDir, indexPath, tokens }) => ({
-    agents: {
-      defaults: {
-        workspace: workspaceDir,
-        memorySearch: {
-          provider: "openai",
-          model: "mock-embed",
-          store: { path: indexPath, vector: { enabled: false } },
-          chunking: { tokens, overlap: 0 },
-          sync: { watch: false, onSessionStart: false, onSearch: false },
-          query: { minScore: 0 },
-        },
-      },
-      list: [{ id: "main", default: true }],
-    },
-  }),
-});
-const { embedBatch } = fx;
-
-describe("memory embedding token limits", () => {
-  it("splits oversized chunks so each embedding input stays <= 8192 UTF-8 bytes", async () => {
-    const memoryDir = fx.getMemoryDir();
-    const managerLarge = fx.getManagerLarge();
-    const content = "x".repeat(9500);
-    await fs.writeFile(path.join(memoryDir, "2026-01-09.md"), content);
-    await managerLarge.sync({ reason: "test" });
-
-    const inputs = embedBatch.mock.calls.flatMap((call) => call[0] ?? []);
-    expect(inputs.length).toBeGreaterThan(1);
-    expect(
-      Math.max(...inputs.map((input) => Buffer.byteLength(input, "utf8"))),
-    ).toBeLessThanOrEqual(8192);
-  });
-
-  it("uses UTF-8 byte estimates when batching multibyte chunks", async () => {
-    const memoryDir = fx.getMemoryDir();
-    const managerSmall = fx.getManagerSmall();
-    const line = "😀".repeat(1800);
-    const content = `${line}\n${line}\n${line}`;
-    await fs.writeFile(path.join(memoryDir, "2026-01-10.md"), content);
-    await managerSmall.sync({ reason: "test" });
-
-    const batchSizes = embedBatch.mock.calls.map(
-      (call) => (call[0] as string[] | undefined)?.length ?? 0,
-    );
-    expect(batchSizes.length).toBe(3);
-    expect(batchSizes.every((size) => size === 1)).toBe(true);
-    const inputs = embedBatch.mock.calls.flatMap((call) => call[0] ?? []);
-    expect(inputs.every((input) => Buffer.byteLength(input, "utf8") <= 8192)).toBe(true);
-  });
-});
diff --git a/src/memory/qmd-manager.test.ts b/src/memory/qmd-manager.test.ts
index f9f5b4a5238..af338e25427 100644
--- a/src/memory/qmd-manager.test.ts
+++ b/src/memory/qmd-manager.test.ts
@@ -290,6 +290,122 @@ describe("QmdMemoryManager", () => {
     await manager?.close();
   });
 
+  it("rebinds sessions collection when existing collection path targets another agent", async () => {
+    const devAgentId = "dev";
+    const devWorkspaceDir = path.join(tmpRoot, "workspace-dev");
+    await fs.mkdir(devWorkspaceDir);
+    cfg = {
+      ...cfg,
+      agents: {
+        list: [
+          { id: agentId, default: true, workspace: workspaceDir },
+          { id: devAgentId, workspace: devWorkspaceDir },
+        ],
+      },
+      memory: {
+        backend: "qmd",
+        qmd: {
+          includeDefaultMemory: false,
+          update: { interval: "0s", debounceMs: 60_000, onBoot: false },
+          paths: [{ path: devWorkspaceDir, pattern: "**/*.md", name: "workspace" }],
+          sessions: { enabled: true },
+        },
+      },
+    } as OpenClawConfig;
+
+    const sessionCollectionName = `sessions-${devAgentId}`;
+    const wrongSessionsPath = path.join(stateDir, "agents", agentId, "qmd", "sessions");
+    spawnMock.mockImplementation((_cmd: string, args: string[]) => {
+      if (args[0] === "collection" && args[1] === "list") {
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(
+          child,
+          "stdout",
+          JSON.stringify([
+            { name: sessionCollectionName, path: wrongSessionsPath, mask: "**/*.md" },
+          ]),
+        );
+        return child;
+      }
+      return createMockChild();
+    });
+
+    const resolved = resolveMemoryBackendConfig({ cfg, agentId: devAgentId });
+    const manager = await QmdMemoryManager.create({
+      cfg,
+      agentId: devAgentId,
+      resolved,
+      mode: "full",
+    });
+    expect(manager).toBeTruthy();
+    await manager?.close();
+
+    const commands = spawnMock.mock.calls.map((call) => call[1] as string[]);
+    const removeSessions = commands.find(
+      (args) =>
+        args[0] === "collection" && args[1] === "remove" && args[2] === sessionCollectionName,
+    );
+    expect(removeSessions).toBeDefined();
+
+    const addSessions = commands.find((args) => {
+      if (args[0] !== "collection" || args[1] !== "add") {
+        return false;
+      }
+      const nameIdx = args.indexOf("--name");
+      return nameIdx >= 0 && args[nameIdx + 1] === sessionCollectionName;
+    });
+    expect(addSessions).toBeDefined();
+    expect(addSessions?.[2]).toBe(path.join(stateDir, "agents", devAgentId, "qmd", "sessions"));
+  });
+
+  it("rebinds sessions collection when qmd only reports collection names", async () => {
+    cfg = {
+      ...cfg,
+      memory: {
+        backend: "qmd",
+        qmd: {
+          includeDefaultMemory: false,
+          update: { interval: "0s", debounceMs: 60_000, onBoot: false },
+          paths: [{ path: workspaceDir, pattern: "**/*.md", name: "workspace" }],
+          sessions: { enabled: true },
+        },
+      },
+    } as OpenClawConfig;
+
+    const sessionCollectionName = `sessions-${agentId}`;
+    spawnMock.mockImplementation((_cmd: string, args: string[]) => {
+      if (args[0] === "collection" && args[1] === "list") {
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(
+          child,
+          "stdout",
+          JSON.stringify([`workspace-${agentId}`, sessionCollectionName]),
+        );
+        return child;
+      }
+      return createMockChild();
+    });
+
+    const { manager } = await createManager({ mode: "full" });
+    await manager.close();
+
+    const commands = spawnMock.mock.calls.map((call) => call[1] as string[]);
+    const removeSessions = commands.find(
+      (args) =>
+        args[0] === "collection" && args[1] === "remove" && args[2] === sessionCollectionName,
+    );
+    expect(removeSessions).toBeDefined();
+
+    const addSessions = commands.find((args) => {
+      if (args[0] !== "collection" || args[1] !== "add") {
+        return false;
+      }
+      const nameIdx = args.indexOf("--name");
+      return nameIdx >= 0 && args[nameIdx + 1] === sessionCollectionName;
+    });
+    expect(addSessions).toBeDefined();
+  });
+
   it("times out qmd update during sync when configured", async () => {
     vi.useFakeTimers();
     cfg = {
@@ -378,8 +494,8 @@ describe("QmdMemoryManager", () => {
       .map((args) => args[args.indexOf("--name") + 1]);
 
     expect(updateCalls).toBe(2);
-    expect(removeCalls).toEqual(["memory-root", "memory-alt", "memory-dir"]);
-    expect(addCalls).toEqual(["memory-root", "memory-alt", "memory-dir"]);
+    expect(removeCalls).toEqual(["memory-root-main", "memory-alt-main", "memory-dir-main"]);
+    expect(addCalls).toEqual(["memory-root-main", "memory-alt-main", "memory-dir-main"]);
     expect(logWarnMock).toHaveBeenCalledWith(
       expect.stringContaining("suspected null-byte collection metadata"),
     );
@@ -467,7 +583,7 @@ describe("QmdMemoryManager", () => {
       "-n",
       String(resolved.qmd?.limits.maxResults),
       "-c",
-      "workspace",
+      "workspace-main",
     ]);
     expect(spawnMock.mock.calls.some((call) => call[1]?.[0] === "query")).toBe(false);
     expect(maxResults).toBeGreaterThan(0);
@@ -517,8 +633,8 @@ describe("QmdMemoryManager", () => {
         (args): args is string[] => Array.isArray(args) && ["search", "query"].includes(args[0]),
       );
     expect(searchAndQueryCalls).toEqual([
-      ["search", "test", "--json", "-n", String(maxResults), "-c", "workspace"],
-      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace"],
+      ["search", "test", "--json", "-n", String(maxResults), "-c", "workspace-main"],
+      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace-main"],
     ]);
     await manager.close();
   });
@@ -683,9 +799,9 @@ describe("QmdMemoryManager", () => {
       "-n",
       String(maxResults),
       "-c",
-      "workspace",
+      "workspace-main",
       "-c",
-      "notes",
+      "notes-main",
     ]);
     await manager.close();
   });
@@ -730,8 +846,8 @@ describe("QmdMemoryManager", () => {
       .map((call) => call[1] as string[])
       .filter((args) => args[0] === "query");
     expect(queryCalls).toEqual([
-      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace"],
-      ["query", "test", "--json", "-n", String(maxResults), "-c", "notes"],
+      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace-main"],
+      ["query", "test", "--json", "-n", String(maxResults), "-c", "notes-main"],
     ]);
     await manager.close();
   });
@@ -781,9 +897,19 @@ describe("QmdMemoryManager", () => {
       .map((call) => call[1] as string[])
       .filter((args) => args[0] === "search" || args[0] === "query");
     expect(searchAndQueryCalls).toEqual([
-      ["search", "test", "--json", "-n", String(maxResults), "-c", "workspace", "-c", "notes"],
-      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace"],
-      ["query", "test", "--json", "-n", String(maxResults), "-c", "notes"],
+      [
+        "search",
+        "test",
+        "--json",
+        "-n",
+        String(maxResults),
+        "-c",
+        "workspace-main",
+        "-c",
+        "notes-main",
+      ],
+      ["query", "test", "--json", "-n", String(maxResults), "-c", "workspace-main"],
+      ["query", "test", "--json", "-n", String(maxResults), "-c", "notes-main"],
     ]);
     await manager.close();
   });
@@ -914,7 +1040,7 @@ describe("QmdMemoryManager", () => {
 
     const textPath = path.join(workspaceDir, "secret.txt");
     await fs.writeFile(textPath, "nope", "utf-8");
-    await expect(manager.readFile({ relPath: "qmd/workspace/secret.txt" })).rejects.toThrow(
+    await expect(manager.readFile({ relPath: "qmd/workspace-main/secret.txt" })).rejects.toThrow(
       "path required",
     );
 
@@ -922,7 +1048,7 @@ describe("QmdMemoryManager", () => {
     await fs.writeFile(target, "ok", "utf-8");
     const link = path.join(workspaceDir, "link.md");
     await fs.symlink(target, link);
-    await expect(manager.readFile({ relPath: "qmd/workspace/link.md" })).rejects.toThrow(
+    await expect(manager.readFile({ relPath: "qmd/workspace-main/link.md" })).rejects.toThrow(
       "path required",
     );
 
@@ -1076,7 +1202,7 @@ describe("QmdMemoryManager", () => {
             }
             if (query.includes("hash LIKE ?")) {
               expect(arg).toBe(`${exactDocid}%`);
-              return { collection: "workspace", path: "notes/welcome.md" };
+              return { collection: "workspace-main", path: "notes/welcome.md" };
             }
             throw new Error(`unexpected sqlite query: ${query}`);
           },
diff --git a/src/memory/qmd-manager.ts b/src/memory/qmd-manager.ts
index 33fd5646824..3353b18d3e3 100644
--- a/src/memory/qmd-manager.ts
+++ b/src/memory/qmd-manager.ts
@@ -45,6 +45,11 @@ type SessionExporterConfig = {
   collectionName: string;
 };
 
+type ListedCollection = {
+  path?: string;
+  pattern?: string;
+};
+
 type QmdManagerMode = "full" | "status";
 
 export class QmdMemoryManager implements MemorySearchManager {
@@ -157,6 +162,9 @@ export class QmdMemoryManager implements MemorySearchManager {
     await fs.mkdir(this.xdgConfigHome, { recursive: true });
     await fs.mkdir(this.xdgCacheHome, { recursive: true });
     await fs.mkdir(path.dirname(this.indexPath), { recursive: true });
+    if (this.sessionExporter) {
+      await fs.mkdir(this.sessionExporter.dir, { recursive: true });
+    }
 
     // QMD stores its ML models under $XDG_CACHE_HOME/qmd/models/.  Because we
     // override XDG_CACHE_HOME to isolate the index per-agent, qmd would not
@@ -203,7 +211,7 @@ export class QmdMemoryManager implements MemorySearchManager {
     // QMD collections are persisted inside the index database and must be created
     // via the CLI. Prefer listing existing collections when supported, otherwise
     // fall back to best-effort idempotent `qmd collection add`.
-    const existing = new Set<string>();
+    const existing = new Map<string, ListedCollection>();
     try {
       const result = await this.runQmd(["collection", "list", "--json"], {
         timeoutMs: this.qmd.update.commandTimeoutMs,
@@ -212,11 +220,22 @@ export class QmdMemoryManager implements MemorySearchManager {
       if (Array.isArray(parsed)) {
         for (const entry of parsed) {
           if (typeof entry === "string") {
-            existing.add(entry);
+            existing.set(entry, {});
           } else if (entry && typeof entry === "object") {
             const name = (entry as { name?: unknown }).name;
             if (typeof name === "string") {
-              existing.add(name);
+              const listedPath = (entry as { path?: unknown }).path;
+              const listedPattern = (entry as { pattern?: unknown; mask?: unknown }).pattern;
+              const listedMask = (entry as { mask?: unknown }).mask;
+              existing.set(name, {
+                path: typeof listedPath === "string" ? listedPath : undefined,
+                pattern:
+                  typeof listedPattern === "string"
+                    ? listedPattern
+                    : typeof listedMask === "string"
+                      ? listedMask
+                      : undefined,
+              });
             }
           }
         }
@@ -226,10 +245,22 @@ export class QmdMemoryManager implements MemorySearchManager {
     }
 
     for (const collection of this.qmd.collections) {
-      if (existing.has(collection.name)) {
+      const listed = existing.get(collection.name);
+      if (listed && !this.shouldRebindCollection(collection, listed)) {
         continue;
       }
+      if (listed) {
+        try {
+          await this.removeCollection(collection.name);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (!this.isCollectionMissingError(message)) {
+            log.warn(`qmd collection remove failed for ${collection.name}: ${message}`);
+          }
+        }
+      }
       try {
+        await this.ensureCollectionPath(collection);
         await this.addCollection(collection.path, collection.name, collection.pattern);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -241,6 +272,21 @@ export class QmdMemoryManager implements MemorySearchManager {
     }
   }
 
+  private async ensureCollectionPath(collection: {
+    path: string;
+    pattern: string;
+    kind: "memory" | "custom" | "sessions";
+  }): Promise<void> {
+    if (!this.isDirectoryGlobPattern(collection.pattern)) {
+      return;
+    }
+    await fs.mkdir(collection.path, { recursive: true });
+  }
+
+  private isDirectoryGlobPattern(pattern: string): boolean {
+    return pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+  }
+
   private isCollectionAlreadyExistsError(message: string): boolean {
     const lower = message.toLowerCase();
     return lower.includes("already exists") || lower.includes("exists");
@@ -265,6 +311,35 @@ export class QmdMemoryManager implements MemorySearchManager {
     });
   }
 
+  private shouldRebindCollection(
+    collection: { kind: string; path: string; pattern: string },
+    listed: ListedCollection,
+  ): boolean {
+    if (!listed.path) {
+      // Older qmd versions may only return names from `collection list --json`.
+      // Force sessions collections to rebind so per-agent session export paths stay isolated.
+      return collection.kind === "sessions";
+    }
+    if (!this.pathsMatch(listed.path, collection.path)) {
+      return true;
+    }
+    if (typeof listed.pattern === "string" && listed.pattern !== collection.pattern) {
+      return true;
+    }
+    return false;
+  }
+
+  private pathsMatch(left: string, right: string): boolean {
+    const normalize = (value: string): string => {
+      const resolved = path.isAbsolute(value)
+        ? path.resolve(value)
+        : path.resolve(this.workspaceDir, value);
+      const normalized = path.normalize(resolved);
+      return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    };
+    return normalize(left) === normalize(right);
+  }
+
   private shouldRepairNullByteCollectionError(err: unknown): boolean {
     const message = err instanceof Error ? err.message : String(err);
     const lower = message.toLowerCase();
@@ -787,18 +862,25 @@ export class QmdMemoryManager implements MemorySearchManager {
 
   private pickSessionCollectionName(): string {
     const existing = new Set(this.qmd.collections.map((collection) => collection.name));
-    if (!existing.has("sessions")) {
-      return "sessions";
+    const base = `sessions-${this.sanitizeCollectionNameSegment(this.agentId)}`;
+    if (!existing.has(base)) {
+      return base;
     }
     let counter = 2;
-    let candidate = `sessions-${counter}`;
+    let candidate = `${base}-${counter}`;
     while (existing.has(candidate)) {
       counter += 1;
-      candidate = `sessions-${counter}`;
+      candidate = `${base}-${counter}`;
     }
     return candidate;
   }
 
+  private sanitizeCollectionNameSegment(input: string): string {
+    const lower = input.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+    const trimmed = lower.replace(/^-+|-+$/g, "");
+    return trimmed || "agent";
+  }
+
   private async resolveDocLocation(
     docid?: string,
   ): Promise<{ rel: string; abs: string; source: MemorySource } | null> {
diff --git a/src/memory/sync-memory-files.ts b/src/memory/sync-memory-files.ts
index 3988b613884..eee354bb6c1 100644
--- a/src/memory/sync-memory-files.ts
+++ b/src/memory/sync-memory-files.ts
@@ -1,24 +1,19 @@
 import type { DatabaseSync } from "node:sqlite";
+import type { SyncProgressState } from "./sync-progress.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { buildFileEntry, listMemoryFiles, type MemoryFileEntry } from "./internal.js";
 import { indexFileEntryIfChanged } from "./sync-index.js";
+import { bumpSyncProgressTotal } from "./sync-progress.js";
 import { deleteStaleIndexedPaths } from "./sync-stale.js";
 
 const log = createSubsystemLogger("memory");
 
-type ProgressState = {
-  completed: number;
-  total: number;
-  label?: string;
-  report: (update: { completed: number; total: number; label?: string }) => void;
-};
-
 export async function syncMemoryFiles(params: {
   workspaceDir: string;
   extraPaths?: string[];
   db: DatabaseSync;
   needsFullReindex: boolean;
-  progress?: ProgressState;
+  progress?: SyncProgressState;
   batchEnabled: boolean;
   concurrency: number;
   runWithConcurrency: <T>(tasks: Array<() => Promise<T>>, concurrency: number) => Promise<T[]>;
@@ -42,14 +37,11 @@ export async function syncMemoryFiles(params: {
   });
 
   const activePaths = new Set(fileEntries.map((entry) => entry.path));
-  if (params.progress) {
-    params.progress.total += fileEntries.length;
-    params.progress.report({
-      completed: params.progress.completed,
-      total: params.progress.total,
-      label: params.batchEnabled ? "Indexing memory files (batch)..." : "Indexing memory files…",
-    });
-  }
+  bumpSyncProgressTotal(
+    params.progress,
+    fileEntries.length,
+    params.batchEnabled ? "Indexing memory files (batch)..." : "Indexing memory files…",
+  );
 
   const tasks = fileEntries.map((entry) => async () => {
     await indexFileEntryIfChanged({
diff --git a/src/memory/sync-progress.ts b/src/memory/sync-progress.ts
new file mode 100644
index 00000000000..a67eb43540f
--- /dev/null
+++ b/src/memory/sync-progress.ts
@@ -0,0 +1,38 @@
+export type SyncProgressState = {
+  completed: number;
+  total: number;
+  label?: string;
+  report: (update: { completed: number; total: number; label?: string }) => void;
+};
+
+export function bumpSyncProgressTotal(
+  progress: SyncProgressState | undefined,
+  delta: number,
+  label?: string,
+) {
+  if (!progress) {
+    return;
+  }
+  progress.total += delta;
+  progress.report({
+    completed: progress.completed,
+    total: progress.total,
+    label,
+  });
+}
+
+export function bumpSyncProgressCompleted(
+  progress: SyncProgressState | undefined,
+  delta = 1,
+  label?: string,
+) {
+  if (!progress) {
+    return;
+  }
+  progress.completed += delta;
+  progress.report({
+    completed: progress.completed,
+    total: progress.total,
+    label,
+  });
+}
diff --git a/src/memory/sync-session-files.ts b/src/memory/sync-session-files.ts
index a087f3bf728..d0c7883b61c 100644
--- a/src/memory/sync-session-files.ts
+++ b/src/memory/sync-session-files.ts
@@ -1,5 +1,6 @@
 import type { DatabaseSync } from "node:sqlite";
 import type { SessionFileEntry } from "./session-files.js";
+import type { SyncProgressState } from "./sync-progress.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import {
   buildSessionEntry,
@@ -7,22 +8,16 @@ import {
   sessionPathForFile,
 } from "./session-files.js";
 import { indexFileEntryIfChanged } from "./sync-index.js";
+import { bumpSyncProgressCompleted, bumpSyncProgressTotal } from "./sync-progress.js";
 import { deleteStaleIndexedPaths } from "./sync-stale.js";
 
 const log = createSubsystemLogger("memory");
 
-type ProgressState = {
-  completed: number;
-  total: number;
-  label?: string;
-  report: (update: { completed: number; total: number; label?: string }) => void;
-};
-
 export async function syncSessionFiles(params: {
   agentId: string;
   db: DatabaseSync;
   needsFullReindex: boolean;
-  progress?: ProgressState;
+  progress?: SyncProgressState;
   batchEnabled: boolean;
   concurrency: number;
   runWithConcurrency: <T>(tasks: Array<() => Promise<T>>, concurrency: number) => Promise<T[]>;
@@ -46,35 +41,20 @@ export async function syncSessionFiles(params: {
     concurrency: params.concurrency,
   });
 
-  if (params.progress) {
-    params.progress.total += files.length;
-    params.progress.report({
-      completed: params.progress.completed,
-      total: params.progress.total,
-      label: params.batchEnabled ? "Indexing session files (batch)..." : "Indexing session files…",
-    });
-  }
+  bumpSyncProgressTotal(
+    params.progress,
+    files.length,
+    params.batchEnabled ? "Indexing session files (batch)..." : "Indexing session files…",
+  );
 
   const tasks = files.map((absPath) => async () => {
     if (!indexAll && !params.dirtyFiles.has(absPath)) {
-      if (params.progress) {
-        params.progress.completed += 1;
-        params.progress.report({
-          completed: params.progress.completed,
-          total: params.progress.total,
-        });
-      }
+      bumpSyncProgressCompleted(params.progress);
       return;
     }
     const entry = await buildSessionEntry(absPath);
     if (!entry) {
-      if (params.progress) {
-        params.progress.completed += 1;
-        params.progress.report({
-          completed: params.progress.completed,
-          total: params.progress.total,
-        });
-      }
+      bumpSyncProgressCompleted(params.progress);
       return;
     }
     await indexFileEntryIfChanged({
diff --git a/src/node-host/invoke.sanitize-env.test.ts b/src/node-host/invoke.sanitize-env.test.ts
index 27f092d0aae..589d6196029 100644
--- a/src/node-host/invoke.sanitize-env.test.ts
+++ b/src/node-host/invoke.sanitize-env.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { sanitizeEnv } from "./invoke.js";
+import { buildNodeInvokeResultParams } from "./runner.js";
 
 describe("node-host sanitizeEnv", () => {
   it("ignores PATH overrides", () => {
@@ -46,3 +47,34 @@ describe("node-host sanitizeEnv", () => {
     }
   });
 });
+
+describe("buildNodeInvokeResultParams", () => {
+  it("omits optional fields when null/undefined", () => {
+    const params = buildNodeInvokeResultParams(
+      { id: "invoke-1", nodeId: "node-1", command: "system.run" },
+      { ok: true, payloadJSON: null, error: null },
+    );
+
+    expect(params).toEqual({ id: "invoke-1", nodeId: "node-1", ok: true });
+    expect("payloadJSON" in params).toBe(false);
+    expect("error" in params).toBe(false);
+  });
+
+  it("includes payloadJSON when provided", () => {
+    const params = buildNodeInvokeResultParams(
+      { id: "invoke-2", nodeId: "node-2", command: "system.run" },
+      { ok: true, payloadJSON: '{"ok":true}' },
+    );
+
+    expect(params.payloadJSON).toBe('{"ok":true}');
+  });
+
+  it("includes payload when provided", () => {
+    const params = buildNodeInvokeResultParams(
+      { id: "invoke-3", nodeId: "node-3", command: "system.run" },
+      { ok: false, payload: { reason: "bad" } },
+    );
+
+    expect(params.payload).toEqual({ reason: "bad" });
+  });
+});
diff --git a/src/node-host/invoke.ts b/src/node-host/invoke.ts
index a610772fb9f..b0616e23b18 100644
--- a/src/node-host/invoke.ts
+++ b/src/node-host/invoke.ts
@@ -12,12 +12,12 @@ import {
   evaluateShellAllowlist,
   requiresExecApproval,
   normalizeExecApprovals,
+  mergeExecApprovalsSocketDefaults,
   recordAllowlistUse,
   resolveExecApprovals,
   resolveSafeBins,
   ensureExecApprovals,
   readExecApprovalsSnapshot,
-  resolveExecApprovalsSocketPath,
   saveExecApprovals,
   type ExecAsk,
   type ExecApprovalsFile,
@@ -422,18 +422,7 @@ export async function handleInvoke(
       const snapshot = readExecApprovalsSnapshot();
       requireExecApprovalsBaseHash(params, snapshot);
       const normalized = normalizeExecApprovals(params.file);
-      const currentSocketPath = snapshot.file.socket?.path?.trim();
-      const currentToken = snapshot.file.socket?.token?.trim();
-      const socketPath =
-        normalized.socket?.path?.trim() ?? currentSocketPath ?? resolveExecApprovalsSocketPath();
-      const token = normalized.socket?.token?.trim() ?? currentToken ?? "";
-      const next: ExecApprovalsFile = {
-        ...normalized,
-        socket: {
-          path: socketPath,
-          token,
-        },
-      };
+      const next = mergeExecApprovalsSocketDefaults({ normalized, current: snapshot.file });
       saveExecApprovals(next);
       const nextSnapshot = readExecApprovalsSnapshot();
       const payload: ExecApprovalsSnapshot = {
diff --git a/src/node-host/runner.test.ts b/src/node-host/runner.test.ts
deleted file mode 100644
index 932f811ed44..00000000000
--- a/src/node-host/runner.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { buildNodeInvokeResultParams } from "./runner.js";
-
-describe("buildNodeInvokeResultParams", () => {
-  test("omits optional fields when null/undefined", () => {
-    const params = buildNodeInvokeResultParams(
-      { id: "invoke-1", nodeId: "node-1", command: "system.run" },
-      { ok: true, payloadJSON: null, error: null },
-    );
-
-    expect(params).toEqual({ id: "invoke-1", nodeId: "node-1", ok: true });
-    expect("payloadJSON" in params).toBe(false);
-    expect("error" in params).toBe(false);
-  });
-
-  test("includes payloadJSON when provided", () => {
-    const params = buildNodeInvokeResultParams(
-      { id: "invoke-2", nodeId: "node-2", command: "system.run" },
-      { ok: true, payloadJSON: '{"ok":true}' },
-    );
-
-    expect(params.payloadJSON).toBe('{"ok":true}');
-  });
-
-  test("includes payload when provided", () => {
-    const params = buildNodeInvokeResultParams(
-      { id: "invoke-3", nodeId: "node-3", command: "system.run" },
-      { ok: false, payload: { reason: "bad" } },
-    );
-
-    expect(params.payload).toEqual({ reason: "bad" });
-  });
-});
diff --git a/src/pairing/pairing-messages.test.ts b/src/pairing/pairing-messages.test.ts
index e63083560a1..5480d333c51 100644
--- a/src/pairing/pairing-messages.test.ts
+++ b/src/pairing/pairing-messages.test.ts
@@ -1,20 +1,17 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { buildPairingReply } from "./pairing-messages.js";
 
 describe("buildPairingReply", () => {
-  let previousProfile: string | undefined;
+  let envSnapshot: ReturnType<typeof captureEnv>;
 
   beforeEach(() => {
-    previousProfile = process.env.OPENCLAW_PROFILE;
+    envSnapshot = captureEnv(["OPENCLAW_PROFILE"]);
     process.env.OPENCLAW_PROFILE = "isolated";
   });
 
   afterEach(() => {
-    if (previousProfile === undefined) {
-      delete process.env.OPENCLAW_PROFILE;
-      return;
-    }
-    process.env.OPENCLAW_PROFILE = previousProfile;
+    envSnapshot.restore();
   });
 
   const cases = [
diff --git a/src/pairing/pairing-store.test.ts b/src/pairing/pairing-store.test.ts
index ab667443818..163c99e0641 100644
--- a/src/pairing/pairing-store.test.ts
+++ b/src/pairing/pairing-store.test.ts
@@ -4,7 +4,14 @@ import os from "node:os";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import { resolveOAuthDir } from "../config/paths.js";
-import { listChannelPairingRequests, upsertChannelPairingRequest } from "./pairing-store.js";
+import { captureEnv } from "../test-utils/env.js";
+import {
+  addChannelAllowFromStoreEntry,
+  approveChannelPairingCode,
+  listChannelPairingRequests,
+  readChannelAllowFromStore,
+  upsertChannelPairingRequest,
+} from "./pairing-store.js";
 
 let fixtureRoot = "";
 let caseId = 0;
@@ -20,18 +27,14 @@ afterAll(async () => {
 });
 
 async function withTempStateDir<T>(fn: (stateDir: string) => Promise<T>) {
-  const previous = process.env.OPENCLAW_STATE_DIR;
+  const envSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
   const dir = path.join(fixtureRoot, `case-${caseId++}`);
   await fs.mkdir(dir, { recursive: true });
   process.env.OPENCLAW_STATE_DIR = dir;
   try {
     return await fn(dir);
   } finally {
-    if (previous === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previous;
-    }
+    envSnapshot.restore();
   }
 }
 
@@ -144,4 +147,75 @@ describe("pairing store", () => {
       expect(listIds).not.toContain("+15550000004");
     });
   });
+
+  it("stores allowFrom entries per account when accountId is provided", async () => {
+    await withTempStateDir(async () => {
+      await addChannelAllowFromStoreEntry({
+        channel: "telegram",
+        accountId: "yy",
+        entry: "12345",
+      });
+
+      const accountScoped = await readChannelAllowFromStore("telegram", process.env, "yy");
+      const channelScoped = await readChannelAllowFromStore("telegram");
+      expect(accountScoped).toContain("12345");
+      expect(channelScoped).not.toContain("12345");
+    });
+  });
+
+  it("approves pairing codes into account-scoped allowFrom via pairing metadata", async () => {
+    await withTempStateDir(async () => {
+      const created = await upsertChannelPairingRequest({
+        channel: "telegram",
+        accountId: "yy",
+        id: "12345",
+      });
+      expect(created.created).toBe(true);
+
+      const approved = await approveChannelPairingCode({
+        channel: "telegram",
+        code: created.code,
+      });
+      expect(approved?.id).toBe("12345");
+
+      const accountScoped = await readChannelAllowFromStore("telegram", process.env, "yy");
+      const channelScoped = await readChannelAllowFromStore("telegram");
+      expect(accountScoped).toContain("12345");
+      expect(channelScoped).not.toContain("12345");
+    });
+  });
+
+  it("reads legacy channel-scoped allowFrom for default account", async () => {
+    await withTempStateDir(async (stateDir) => {
+      const oauthDir = resolveOAuthDir(process.env, stateDir);
+      await fs.mkdir(oauthDir, { recursive: true });
+      await fs.writeFile(
+        path.join(oauthDir, "telegram-allowFrom.json"),
+        JSON.stringify(
+          {
+            version: 1,
+            allowFrom: ["1001"],
+          },
+          null,
+          2,
+        ) + "\n",
+        "utf8",
+      );
+      await fs.writeFile(
+        path.join(oauthDir, "telegram-default-allowFrom.json"),
+        JSON.stringify(
+          {
+            version: 1,
+            allowFrom: ["1002"],
+          },
+          null,
+          2,
+        ) + "\n",
+        "utf8",
+      );
+
+      const scoped = await readChannelAllowFromStore("telegram", process.env, "default");
+      expect(scoped).toEqual(["1002", "1001"]);
+    });
+  });
 });
diff --git a/src/pairing/pairing-store.ts b/src/pairing/pairing-store.ts
index d7fe3379a90..428acc289d4 100644
--- a/src/pairing/pairing-store.ts
+++ b/src/pairing/pairing-store.ts
@@ -66,11 +66,32 @@ function resolvePairingPath(channel: PairingChannel, env: NodeJS.ProcessEnv = pr
   return path.join(resolveCredentialsDir(env), `${safeChannelKey(channel)}-pairing.json`);
 }
 
+function safeAccountKey(accountId: string): string {
+  const raw = String(accountId).trim().toLowerCase();
+  if (!raw) {
+    throw new Error("invalid pairing account id");
+  }
+  const safe = raw.replace(/[\\/:*?"<>|]/g, "_").replace(/\.\./g, "_");
+  if (!safe || safe === "_") {
+    throw new Error("invalid pairing account id");
+  }
+  return safe;
+}
+
 function resolveAllowFromPath(
   channel: PairingChannel,
   env: NodeJS.ProcessEnv = process.env,
+  accountId?: string,
 ): string {
-  return path.join(resolveCredentialsDir(env), `${safeChannelKey(channel)}-allowFrom.json`);
+  const base = safeChannelKey(channel);
+  const normalizedAccountId = typeof accountId === "string" ? accountId.trim() : "";
+  if (!normalizedAccountId) {
+    return path.join(resolveCredentialsDir(env), `${base}-allowFrom.json`);
+  }
+  return path.join(
+    resolveCredentialsDir(env),
+    `${base}-${safeAccountKey(normalizedAccountId)}-allowFrom.json`,
+  );
 }
 
 async function readJsonFile<T>(
@@ -213,6 +234,31 @@ function normalizeAllowFromInput(channel: PairingChannel, entry: string | number
   return normalizeAllowEntry(channel, normalizeId(entry));
 }
 
+function dedupePreserveOrder(entries: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of entries) {
+    const normalized = String(entry).trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+async function readAllowFromStateForPath(
+  channel: PairingChannel,
+  filePath: string,
+): Promise<string[]> {
+  const { value } = await readJsonFile<AllowFromStore>(filePath, {
+    version: 1,
+    allowFrom: [],
+  });
+  return normalizeAllowFromList(channel, value);
+}
+
 async function readAllowFromState(params: {
   channel: PairingChannel;
   entry: string | number;
@@ -237,11 +283,12 @@ async function writeAllowFromState(filePath: string, allowFrom: string[]): Promi
 async function updateAllowFromStoreEntry(params: {
   channel: PairingChannel;
   entry: string | number;
+  accountId?: string;
   env?: NodeJS.ProcessEnv;
   apply: (current: string[], normalized: string) => string[] | null;
 }): Promise<{ changed: boolean; allowFrom: string[] }> {
   const env = params.env ?? process.env;
-  const filePath = resolveAllowFromPath(params.channel, env);
+  const filePath = resolveAllowFromPath(params.channel, env, params.accountId);
   return await withFileLock(
     filePath,
     { version: 1, allowFrom: [] } satisfies AllowFromStore,
@@ -267,23 +314,33 @@ async function updateAllowFromStoreEntry(params: {
 export async function readChannelAllowFromStore(
   channel: PairingChannel,
   env: NodeJS.ProcessEnv = process.env,
+  accountId?: string,
 ): Promise<string[]> {
-  const filePath = resolveAllowFromPath(channel, env);
-  const { value } = await readJsonFile<AllowFromStore>(filePath, {
-    version: 1,
-    allowFrom: [],
-  });
-  return normalizeAllowFromList(channel, value);
+  const normalizedAccountId = accountId?.trim().toLowerCase() ?? "";
+  if (!normalizedAccountId) {
+    const filePath = resolveAllowFromPath(channel, env);
+    return await readAllowFromStateForPath(channel, filePath);
+  }
+
+  const scopedPath = resolveAllowFromPath(channel, env, accountId);
+  const scopedEntries = await readAllowFromStateForPath(channel, scopedPath);
+  // Backward compatibility: legacy channel-level allowFrom store was unscoped.
+  // Keep honoring it alongside account-scoped files to prevent re-pair prompts after upgrades.
+  const legacyPath = resolveAllowFromPath(channel, env);
+  const legacyEntries = await readAllowFromStateForPath(channel, legacyPath);
+  return dedupePreserveOrder([...scopedEntries, ...legacyEntries]);
 }
 
 export async function addChannelAllowFromStoreEntry(params: {
   channel: PairingChannel;
   entry: string | number;
+  accountId?: string;
   env?: NodeJS.ProcessEnv;
 }): Promise<{ changed: boolean; allowFrom: string[] }> {
   return await updateAllowFromStoreEntry({
     channel: params.channel,
     entry: params.entry,
+    accountId: params.accountId,
     env: params.env,
     apply: (current, normalized) => {
       if (current.includes(normalized)) {
@@ -297,11 +354,13 @@ export async function addChannelAllowFromStoreEntry(params: {
 export async function removeChannelAllowFromStoreEntry(params: {
   channel: PairingChannel;
   entry: string | number;
+  accountId?: string;
   env?: NodeJS.ProcessEnv;
 }): Promise<{ changed: boolean; allowFrom: string[] }> {
   return await updateAllowFromStoreEntry({
     channel: params.channel,
     entry: params.entry,
+    accountId: params.accountId,
     env: params.env,
     apply: (current, normalized) => {
       const next = current.filter((entry) => entry !== normalized);
@@ -316,6 +375,7 @@ export async function removeChannelAllowFromStoreEntry(params: {
 export async function listChannelPairingRequests(
   channel: PairingChannel,
   env: NodeJS.ProcessEnv = process.env,
+  accountId?: string,
 ): Promise<PairingRequest[]> {
   const filePath = resolvePairingPath(channel, env);
   return await withFileLock(
@@ -342,7 +402,16 @@ export async function listChannelPairingRequests(
           requests: pruned,
         } satisfies PairingStore);
       }
-      return pruned
+      const normalizedAccountId = accountId?.trim().toLowerCase() || "";
+      const filtered = normalizedAccountId
+        ? pruned.filter(
+            (entry) =>
+              String(entry.meta?.accountId ?? "")
+                .trim()
+                .toLowerCase() === normalizedAccountId,
+          )
+        : pruned;
+      return filtered
         .filter(
           (r) =>
             r &&
@@ -359,6 +428,7 @@ export async function listChannelPairingRequests(
 export async function upsertChannelPairingRequest(params: {
   channel: PairingChannel;
   id: string | number;
+  accountId?: string;
   meta?: Record<string, string | undefined | null>;
   env?: NodeJS.ProcessEnv;
   /** Extension channels can pass their adapter directly to bypass registry lookup. */
@@ -377,7 +447,8 @@ export async function upsertChannelPairingRequest(params: {
       const now = new Date().toISOString();
       const nowMs = Date.now();
       const id = normalizeId(params.id);
-      const meta =
+      const normalizedAccountId = params.accountId?.trim();
+      const baseMeta =
         params.meta && typeof params.meta === "object"
           ? Object.fromEntries(
               Object.entries(params.meta)
@@ -385,6 +456,7 @@ export async function upsertChannelPairingRequest(params: {
                 .filter(([_, v]) => Boolean(v)),
             )
           : undefined;
+      const meta = normalizedAccountId ? { ...baseMeta, accountId: normalizedAccountId } : baseMeta;
 
       let reqs = Array.isArray(value.requests) ? value.requests : [];
       const { requests: prunedExpired, removed: expiredRemoved } = pruneExpiredRequests(
@@ -456,6 +528,7 @@ export async function upsertChannelPairingRequest(params: {
 export async function approveChannelPairingCode(params: {
   channel: PairingChannel;
   code: string;
+  accountId?: string;
   env?: NodeJS.ProcessEnv;
 }): Promise<{ id: string; entry?: PairingRequest } | null> {
   const env = params.env ?? process.env;
@@ -476,7 +549,20 @@ export async function approveChannelPairingCode(params: {
       const reqs = Array.isArray(value.requests) ? value.requests : [];
       const nowMs = Date.now();
       const { requests: pruned, removed } = pruneExpiredRequests(reqs, nowMs);
-      const idx = pruned.findIndex((r) => String(r.code ?? "").toUpperCase() === code);
+      const normalizedAccountId = params.accountId?.trim().toLowerCase() || "";
+      const idx = pruned.findIndex((r) => {
+        if (String(r.code ?? "").toUpperCase() !== code) {
+          return false;
+        }
+        if (!normalizedAccountId) {
+          return true;
+        }
+        return (
+          String(r.meta?.accountId ?? "")
+            .trim()
+            .toLowerCase() === normalizedAccountId
+        );
+      });
       if (idx < 0) {
         if (removed) {
           await writeJsonFile(filePath, {
@@ -495,9 +581,11 @@ export async function approveChannelPairingCode(params: {
         version: 1,
         requests: pruned,
       } satisfies PairingStore);
+      const entryAccountId = String(entry.meta?.accountId ?? "").trim() || undefined;
       await addChannelAllowFromStoreEntry({
         channel: params.channel,
         entry: entry.id,
+        accountId: params.accountId?.trim() || entryAccountId,
         env,
       });
       return { id: entry.id, entry };
diff --git a/src/plugin-sdk/agent-media-payload.ts b/src/plugin-sdk/agent-media-payload.ts
new file mode 100644
index 00000000000..98d12a8420b
--- /dev/null
+++ b/src/plugin-sdk/agent-media-payload.ts
@@ -0,0 +1,24 @@
+export type AgentMediaPayload = {
+  MediaPath?: string;
+  MediaType?: string;
+  MediaUrl?: string;
+  MediaPaths?: string[];
+  MediaUrls?: string[];
+  MediaTypes?: string[];
+};
+
+export function buildAgentMediaPayload(
+  mediaList: Array<{ path: string; contentType?: string | null }>,
+): AgentMediaPayload {
+  const first = mediaList[0];
+  const mediaPaths = mediaList.map((media) => media.path);
+  const mediaTypes = mediaList.map((media) => media.contentType).filter(Boolean) as string[];
+  return {
+    MediaPath: first?.path,
+    MediaType: first?.contentType ?? undefined,
+    MediaUrl: first?.path,
+    MediaPaths: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaUrls: mediaPaths.length > 0 ? mediaPaths : undefined,
+    MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+  };
+}
diff --git a/src/plugin-sdk/file-lock.ts b/src/plugin-sdk/file-lock.ts
index 2e38607da6d..9bbf2e5b6c9 100644
--- a/src/plugin-sdk/file-lock.ts
+++ b/src/plugin-sdk/file-lock.ts
@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isPidAlive } from "../shared/pid-alive.js";
 
 export type FileLockOptions = {
   retries: {
@@ -37,18 +38,6 @@ function resolveHeldLocks(): Map<string, HeldLock> {
 
 const HELD_LOCKS = resolveHeldLocks();
 
-function isAlive(pid: number): boolean {
-  if (!Number.isFinite(pid) || pid <= 0) {
-    return false;
-  }
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function computeDelayMs(retries: FileLockOptions["retries"], attempt: number): number {
   const base = Math.min(
     retries.maxTimeout,
@@ -85,7 +74,7 @@ async function resolveNormalizedFilePath(filePath: string): Promise<string> {
 
 async function isStaleLock(lockPath: string, staleMs: number): Promise<boolean> {
   const payload = await readLockPayload(lockPath);
-  if (payload?.pid && !isAlive(payload.pid)) {
+  if (payload?.pid && !isPidAlive(payload.pid)) {
     return true;
   }
   if (payload?.createdAt) {
diff --git a/src/plugin-sdk/index.ts b/src/plugin-sdk/index.ts
index 6a8d967244c..662a4fec95e 100644
--- a/src/plugin-sdk/index.ts
+++ b/src/plugin-sdk/index.ts
@@ -56,6 +56,8 @@ export type {
   ChannelThreadingContext,
   ChannelThreadingToolContext,
   ChannelToolSend,
+  BaseProbeResult,
+  BaseTokenResolution,
 } from "../channels/plugins/types.js";
 export type { ChannelConfigSchema, ChannelPlugin } from "../channels/plugins/types.plugin.js";
 export type {
@@ -81,6 +83,15 @@ export type { OpenClawConfig as ClawdbotConfig } from "../config/config.js";
 
 export type { FileLockHandle, FileLockOptions } from "./file-lock.js";
 export { acquireFileLock, withFileLock } from "./file-lock.js";
+export { normalizeWebhookPath, resolveWebhookPath } from "./webhook-path.js";
+export type { AgentMediaPayload } from "./agent-media-payload.js";
+export { buildAgentMediaPayload } from "./agent-media-payload.js";
+export {
+  buildBaseChannelStatusSummary,
+  collectStatusIssuesFromLastError,
+  createDefaultChannelRuntimeState,
+} from "./status-helpers.js";
+export { buildOauthProviderAuthResult } from "./provider-auth-result.js";
 export type { ChannelDock } from "../channels/dock.js";
 export { getChatChannelMeta } from "../channels/registry.js";
 export type {
diff --git a/src/plugin-sdk/provider-auth-result.ts b/src/plugin-sdk/provider-auth-result.ts
new file mode 100644
index 00000000000..c16c23cc15e
--- /dev/null
+++ b/src/plugin-sdk/provider-auth-result.ts
@@ -0,0 +1,47 @@
+import type { AuthProfileCredential } from "../agents/auth-profiles/types.js";
+import type { OpenClawConfig } from "../config/config.js";
+import type { ProviderAuthResult } from "../plugins/types.js";
+
+export function buildOauthProviderAuthResult(params: {
+  providerId: string;
+  defaultModel: string;
+  access: string;
+  refresh?: string | null;
+  expires?: number | null;
+  email?: string | null;
+  profilePrefix?: string;
+  credentialExtra?: Record<string, unknown>;
+  configPatch?: Partial<OpenClawConfig>;
+  notes?: string[];
+}): ProviderAuthResult {
+  const email = params.email ?? undefined;
+  const profilePrefix = params.profilePrefix ?? params.providerId;
+  const profileId = `${profilePrefix}:${email ?? "default"}`;
+
+  const credential: AuthProfileCredential = {
+    type: "oauth",
+    provider: params.providerId,
+    access: params.access,
+    ...(params.refresh ? { refresh: params.refresh } : {}),
+    ...(Number.isFinite(params.expires) ? { expires: params.expires as number } : {}),
+    ...(email ? { email } : {}),
+    ...params.credentialExtra,
+  } as AuthProfileCredential;
+
+  return {
+    profiles: [{ profileId, credential }],
+    configPatch:
+      params.configPatch ??
+      ({
+        agents: {
+          defaults: {
+            models: {
+              [params.defaultModel]: {},
+            },
+          },
+        },
+      } as Partial<OpenClawConfig>),
+    defaultModel: params.defaultModel,
+    notes: params.notes,
+  };
+}
diff --git a/src/plugin-sdk/status-helpers.ts b/src/plugin-sdk/status-helpers.ts
new file mode 100644
index 00000000000..945dca1bcbf
--- /dev/null
+++ b/src/plugin-sdk/status-helpers.ts
@@ -0,0 +1,57 @@
+import type { ChannelStatusIssue } from "../channels/plugins/types.js";
+
+export function createDefaultChannelRuntimeState<T extends Record<string, unknown>>(
+  accountId: string,
+  extra?: T,
+): {
+  accountId: string;
+  running: false;
+  lastStartAt: null;
+  lastStopAt: null;
+  lastError: null;
+} & T {
+  return {
+    accountId,
+    running: false,
+    lastStartAt: null,
+    lastStopAt: null,
+    lastError: null,
+    ...(extra ?? ({} as T)),
+  };
+}
+
+export function buildBaseChannelStatusSummary(snapshot: {
+  configured?: boolean | null;
+  running?: boolean | null;
+  lastStartAt?: number | null;
+  lastStopAt?: number | null;
+  lastError?: string | null;
+}) {
+  return {
+    configured: snapshot.configured ?? false,
+    running: snapshot.running ?? false,
+    lastStartAt: snapshot.lastStartAt ?? null,
+    lastStopAt: snapshot.lastStopAt ?? null,
+    lastError: snapshot.lastError ?? null,
+  };
+}
+
+export function collectStatusIssuesFromLastError(
+  channel: string,
+  accounts: Array<{ accountId: string; lastError?: unknown }>,
+): ChannelStatusIssue[] {
+  return accounts.flatMap((account) => {
+    const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+    if (!lastError) {
+      return [];
+    }
+    return [
+      {
+        channel,
+        accountId: account.accountId,
+        kind: "runtime",
+        message: `Channel error: ${lastError}`,
+      },
+    ];
+  });
+}
diff --git a/src/plugin-sdk/webhook-path.ts b/src/plugin-sdk/webhook-path.ts
new file mode 100644
index 00000000000..41e4bd0ba98
--- /dev/null
+++ b/src/plugin-sdk/webhook-path.ts
@@ -0,0 +1,31 @@
+export function normalizeWebhookPath(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (withSlash.length > 1 && withSlash.endsWith("/")) {
+    return withSlash.slice(0, -1);
+  }
+  return withSlash;
+}
+
+export function resolveWebhookPath(params: {
+  webhookPath?: string;
+  webhookUrl?: string;
+  defaultPath?: string | null;
+}): string | null {
+  const trimmedPath = params.webhookPath?.trim();
+  if (trimmedPath) {
+    return normalizeWebhookPath(trimmedPath);
+  }
+  if (params.webhookUrl?.trim()) {
+    try {
+      const parsed = new URL(params.webhookUrl);
+      return normalizeWebhookPath(parsed.pathname || "/");
+    } catch {
+      return null;
+    }
+  }
+  return params.defaultPath ?? null;
+}
diff --git a/src/plugins/hooks.ts b/src/plugins/hooks.ts
index 040ce1d35c8..d05774089c2 100644
--- a/src/plugins/hooks.ts
+++ b/src/plugins/hooks.ts
@@ -14,6 +14,8 @@ import type {
   PluginHookBeforeAgentStartEvent,
   PluginHookBeforeAgentStartResult,
   PluginHookBeforeCompactionEvent,
+  PluginHookLlmInputEvent,
+  PluginHookLlmOutputEvent,
   PluginHookBeforeResetEvent,
   PluginHookBeforeToolCallEvent,
   PluginHookBeforeToolCallResult,
@@ -41,6 +43,8 @@ export type {
   PluginHookAgentContext,
   PluginHookBeforeAgentStartEvent,
   PluginHookBeforeAgentStartResult,
+  PluginHookLlmInputEvent,
+  PluginHookLlmOutputEvent,
   PluginHookAgentEndEvent,
   PluginHookBeforeCompactionEvent,
   PluginHookBeforeResetEvent,
@@ -212,6 +216,24 @@ export function createHookRunner(registry: PluginRegistry, options: HookRunnerOp
     return runVoidHook("agent_end", event, ctx);
   }
 
+  /**
+   * Run llm_input hook.
+   * Allows plugins to observe the exact input payload sent to the LLM.
+   * Runs in parallel (fire-and-forget).
+   */
+  async function runLlmInput(event: PluginHookLlmInputEvent, ctx: PluginHookAgentContext) {
+    return runVoidHook("llm_input", event, ctx);
+  }
+
+  /**
+   * Run llm_output hook.
+   * Allows plugins to observe the exact output payload returned by the LLM.
+   * Runs in parallel (fire-and-forget).
+   */
+  async function runLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext) {
+    return runVoidHook("llm_output", event, ctx);
+  }
+
   /**
    * Run before_compaction hook.
    */
@@ -458,6 +480,8 @@ export function createHookRunner(registry: PluginRegistry, options: HookRunnerOp
   return {
     // Agent hooks
     runBeforeAgentStart,
+    runLlmInput,
+    runLlmOutput,
     runAgentEnd,
     runBeforeCompaction,
     runAfterCompaction,
diff --git a/src/plugins/loader.test.ts b/src/plugins/loader.test.ts
index f32d04d0d80..efc93d1abdb 100644
--- a/src/plugins/loader.test.ts
+++ b/src/plugins/loader.test.ts
@@ -66,7 +66,7 @@ describe("loadOpenClawPlugins", () => {
       id: "bundled",
       body: `export default { id: "bundled", register() {} };`,
       dir: bundledDir,
-      filename: "bundled.ts",
+      filename: "bundled.js",
     });
     process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = bundledDir;
 
@@ -121,9 +121,9 @@ describe("loadOpenClawPlugins", () => {
       outbound: { deliveryMode: "direct" }
     }
   });
-} };`,
+	} };`,
       dir: bundledDir,
-      filename: "telegram.ts",
+      filename: "telegram.js",
     });
     process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = bundledDir;
 
@@ -150,7 +150,7 @@ describe("loadOpenClawPlugins", () => {
       id: "memory-core",
       body: `export default { id: "memory-core", kind: "memory", register() {} };`,
       dir: bundledDir,
-      filename: "memory-core.ts",
+      filename: "memory-core.js",
     });
     process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = bundledDir;
 
@@ -180,7 +180,7 @@ describe("loadOpenClawPlugins", () => {
         name: "@openclaw/memory-core",
         version: "1.2.3",
         description: "Memory plugin package",
-        openclaw: { extensions: ["./index.ts"] },
+        openclaw: { extensions: ["./index.js"] },
       }),
       "utf-8",
     );
@@ -188,7 +188,7 @@ describe("loadOpenClawPlugins", () => {
       id: "memory-core",
       body: `export default { id: "memory-core", kind: "memory", name: "Memory (Core)", register() {} };`,
       dir: pluginDir,
-      filename: "index.ts",
+      filename: "index.js",
     });
 
     process.env.OPENCLAW_BUNDLED_PLUGINS_DIR = bundledDir;
diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts
index 9365f584fe3..1d16939b8a3 100644
--- a/src/plugins/loader.ts
+++ b/src/plugins/loader.ts
@@ -220,22 +220,30 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi
   });
   pushDiagnostics(registry.diagnostics, manifestRegistry.diagnostics);
 
-  const pluginSdkAlias = resolvePluginSdkAlias();
-  const pluginSdkAccountIdAlias = resolvePluginSdkAccountIdAlias();
-  const jiti = createJiti(import.meta.url, {
-    interopDefault: true,
-    extensions: [".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".js", ".mjs", ".cjs", ".json"],
-    ...(pluginSdkAlias || pluginSdkAccountIdAlias
-      ? {
-          alias: {
-            ...(pluginSdkAlias ? { "openclaw/plugin-sdk": pluginSdkAlias } : {}),
-            ...(pluginSdkAccountIdAlias
-              ? { "openclaw/plugin-sdk/account-id": pluginSdkAccountIdAlias }
-              : {}),
-          },
-        }
-      : {}),
-  });
+  // Lazy: avoid creating the Jiti loader when all plugins are disabled (common in unit tests).
+  let jitiLoader: ReturnType<typeof createJiti> | null = null;
+  const getJiti = () => {
+    if (jitiLoader) {
+      return jitiLoader;
+    }
+    const pluginSdkAlias = resolvePluginSdkAlias();
+    const pluginSdkAccountIdAlias = resolvePluginSdkAccountIdAlias();
+    jitiLoader = createJiti(import.meta.url, {
+      interopDefault: true,
+      extensions: [".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".js", ".mjs", ".cjs", ".json"],
+      ...(pluginSdkAlias || pluginSdkAccountIdAlias
+        ? {
+            alias: {
+              ...(pluginSdkAlias ? { "openclaw/plugin-sdk": pluginSdkAlias } : {}),
+              ...(pluginSdkAccountIdAlias
+                ? { "openclaw/plugin-sdk/account-id": pluginSdkAccountIdAlias }
+                : {}),
+            },
+          }
+        : {}),
+    });
+    return jitiLoader;
+  };
 
   const manifestByRoot = new Map(
     manifestRegistry.plugins.map((record) => [record.rootDir, record]),
@@ -312,7 +320,7 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi
 
     let mod: OpenClawPluginModule | null = null;
     try {
-      mod = jiti(candidate.source) as OpenClawPluginModule;
+      mod = getJiti()(candidate.source) as OpenClawPluginModule;
     } catch (err) {
       logger.error(`[plugins] ${record.id} failed to load from ${record.source}: ${String(err)}`);
       record.status = "error";
diff --git a/src/plugins/manifest-registry.ts b/src/plugins/manifest-registry.ts
index eb249066dad..fce573bafd7 100644
--- a/src/plugins/manifest-registry.ts
+++ b/src/plugins/manifest-registry.ts
@@ -61,6 +61,10 @@ const registryCache = new Map<string, { expiresAt: number; registry: PluginManif
 
 const DEFAULT_MANIFEST_CACHE_MS = 200;
 
+export function clearPluginManifestRegistryCache(): void {
+  registryCache.clear();
+}
+
 function resolveManifestCacheMs(env: NodeJS.ProcessEnv): number {
   const raw = env.OPENCLAW_PLUGIN_MANIFEST_CACHE_MS?.trim();
   if (raw === "" || raw === "0") {
@@ -89,7 +93,14 @@ function buildCacheKey(params: {
   plugins: NormalizedPluginsConfig;
 }): string {
   const workspaceKey = params.workspaceDir ? resolveUserPath(params.workspaceDir) : "";
-  return `${workspaceKey}::${JSON.stringify(params.plugins)}`;
+  // The manifest registry only depends on where plugins are discovered from (workspace + load paths).
+  // It does not depend on allow/deny/entries enable-state, so exclude those for higher cache hit rates.
+  const loadPaths = params.plugins.loadPaths
+    .map((p) => resolveUserPath(p))
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .toSorted();
+  return `${workspaceKey}::${JSON.stringify(loadPaths)}`;
 }
 
 function safeStatMtimeMs(filePath: string): number | null {
diff --git a/src/plugins/registry.ts b/src/plugins/registry.ts
index ef763910036..29f2f87aa85 100644
--- a/src/plugins/registry.ts
+++ b/src/plugins/registry.ts
@@ -143,8 +143,8 @@ export type PluginRegistryParams = {
   runtime: PluginRuntime;
 };
 
-export function createPluginRegistry(registryParams: PluginRegistryParams) {
-  const registry: PluginRegistry = {
+export function createEmptyPluginRegistry(): PluginRegistry {
+  return {
     plugins: [],
     tools: [],
     hooks: [],
@@ -159,6 +159,10 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
     commands: [],
     diagnostics: [],
   };
+}
+
+export function createPluginRegistry(registryParams: PluginRegistryParams) {
+  const registry = createEmptyPluginRegistry();
   const coreGatewayMethods = new Set(Object.keys(registryParams.coreGatewayHandlers ?? {}));
 
   const pushDiagnostic = (diag: PluginDiagnostic) => {
diff --git a/src/plugins/runtime.ts b/src/plugins/runtime.ts
index cebd88d415e..10177d74f46 100644
--- a/src/plugins/runtime.ts
+++ b/src/plugins/runtime.ts
@@ -1,20 +1,4 @@
-import type { PluginRegistry } from "./registry.js";
-
-const createEmptyRegistry = (): PluginRegistry => ({
-  plugins: [],
-  tools: [],
-  hooks: [],
-  typedHooks: [],
-  channels: [],
-  providers: [],
-  gatewayHandlers: {},
-  httpHandlers: [],
-  httpRoutes: [],
-  cliRegistrars: [],
-  services: [],
-  commands: [],
-  diagnostics: [],
-});
+import { createEmptyPluginRegistry, type PluginRegistry } from "./registry.js";
 
 const REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
 
@@ -29,7 +13,7 @@ const state: RegistryState = (() => {
   };
   if (!globalState[REGISTRY_STATE]) {
     globalState[REGISTRY_STATE] = {
-      registry: createEmptyRegistry(),
+      registry: createEmptyPluginRegistry(),
       key: null,
     };
   }
@@ -47,7 +31,7 @@ export function getActivePluginRegistry(): PluginRegistry | null {
 
 export function requireActivePluginRegistry(): PluginRegistry {
   if (!state.registry) {
-    state.registry = createEmptyRegistry();
+    state.registry = createEmptyPluginRegistry();
   }
   return state.registry;
 }
diff --git a/src/plugins/tools.optional.test.ts b/src/plugins/tools.optional.test.ts
index 614c0980179..7d68c06d7df 100644
--- a/src/plugins/tools.optional.test.ts
+++ b/src/plugins/tools.optional.test.ts
@@ -1,183 +1,157 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterAll, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { resolvePluginTools } from "./tools.js";
 
-type TempPlugin = { dir: string; file: string; id: string };
+type MockRegistryToolEntry = {
+  pluginId: string;
+  optional: boolean;
+  source: string;
+  factory: (ctx: unknown) => unknown;
+};
 
-const fixtureRoot = path.join(os.tmpdir(), `openclaw-plugin-tools-${randomUUID()}`);
-const EMPTY_PLUGIN_SCHEMA = { type: "object", additionalProperties: false, properties: {} };
+const loadOpenClawPluginsMock = vi.fn();
 
-function makeFixtureDir(id: string) {
-  const dir = path.join(fixtureRoot, id);
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
-}
+vi.mock("./loader.js", () => ({
+  loadOpenClawPlugins: (params: unknown) => loadOpenClawPluginsMock(params),
+}));
 
-function writePlugin(params: { id: string; body: string }): TempPlugin {
-  const dir = makeFixtureDir(params.id);
-  const file = path.join(dir, `${params.id}.js`);
-  fs.writeFileSync(file, params.body, "utf-8");
-  fs.writeFileSync(
-    path.join(dir, "openclaw.plugin.json"),
-    JSON.stringify(
-      {
-        id: params.id,
-        configSchema: EMPTY_PLUGIN_SCHEMA,
-      },
-      null,
-      2,
-    ),
-    "utf-8",
-  );
-  return { dir, file, id: params.id };
-}
-
-const pluginBody = `
-export default { register(api) {
-  api.registerTool(
-    {
-      name: "optional_tool",
-      description: "optional tool",
-      parameters: { type: "object", properties: {} },
-      async execute() {
-        return { content: [{ type: "text", text: "ok" }] };
-      },
-    },
-    { optional: true },
-  );
-} }
-`;
-
-const optionalDemoPlugin = writePlugin({ id: "optional-demo", body: pluginBody });
-const coreNameCollisionPlugin = writePlugin({ id: "message", body: pluginBody });
-const multiToolPlugin = writePlugin({
-  id: "multi",
-  body: `
-export default { register(api) {
-  api.registerTool({
-    name: "message",
-    description: "conflict",
-    parameters: { type: "object", properties: {} },
-    async execute() {
-      return { content: [{ type: "text", text: "nope" }] };
-    },
-  });
-  api.registerTool({
-    name: "other_tool",
-    description: "ok",
+function makeTool(name: string) {
+  return {
+    name,
+    description: `${name} tool`,
     parameters: { type: "object", properties: {} },
     async execute() {
       return { content: [{ type: "text", text: "ok" }] };
     },
-  });
-} }
-`,
-});
+  };
+}
 
-afterAll(() => {
-  try {
-    fs.rmSync(fixtureRoot, { recursive: true, force: true });
-  } catch {
-    // ignore cleanup failures
-  }
-});
+function createContext() {
+  return {
+    config: {
+      plugins: {
+        enabled: true,
+        allow: ["optional-demo", "message", "multi"],
+        load: { paths: ["/tmp/plugin.js"] },
+      },
+    },
+    workspaceDir: "/tmp",
+  };
+}
+
+function setRegistry(entries: MockRegistryToolEntry[]) {
+  const registry = {
+    tools: entries,
+    diagnostics: [] as Array<{
+      level: string;
+      pluginId: string;
+      source: string;
+      message: string;
+    }>,
+  };
+  loadOpenClawPluginsMock.mockReturnValue(registry);
+  return registry;
+}
 
 describe("resolvePluginTools optional tools", () => {
+  beforeEach(() => {
+    loadOpenClawPluginsMock.mockReset();
+  });
+
   it("skips optional tools without explicit allowlist", () => {
-    const tools = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [optionalDemoPlugin.file] },
-            allow: [optionalDemoPlugin.id],
-          },
-        },
-        workspaceDir: optionalDemoPlugin.dir,
+    setRegistry([
+      {
+        pluginId: "optional-demo",
+        optional: true,
+        source: "/tmp/optional-demo.js",
+        factory: () => makeTool("optional_tool"),
       },
+    ]);
+
+    const tools = resolvePluginTools({
+      context: createContext() as never,
     });
+
     expect(tools).toHaveLength(0);
   });
 
-  it("allows optional tools by name", () => {
-    const tools = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [optionalDemoPlugin.file] },
-            allow: [optionalDemoPlugin.id],
-          },
-        },
-        workspaceDir: optionalDemoPlugin.dir,
+  it("allows optional tools by tool name", () => {
+    setRegistry([
+      {
+        pluginId: "optional-demo",
+        optional: true,
+        source: "/tmp/optional-demo.js",
+        factory: () => makeTool("optional_tool"),
       },
+    ]);
+
+    const tools = resolvePluginTools({
+      context: createContext() as never,
       toolAllowlist: ["optional_tool"],
     });
-    expect(tools.map((tool) => tool.name)).toContain("optional_tool");
+
+    expect(tools.map((tool) => tool.name)).toEqual(["optional_tool"]);
   });
 
-  it("allows optional tools via plugin groups", () => {
-    const toolsAll = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [optionalDemoPlugin.file] },
-            allow: [optionalDemoPlugin.id],
-          },
-        },
-        workspaceDir: optionalDemoPlugin.dir,
+  it("allows optional tools via plugin-scoped allowlist entries", () => {
+    setRegistry([
+      {
+        pluginId: "optional-demo",
+        optional: true,
+        source: "/tmp/optional-demo.js",
+        factory: () => makeTool("optional_tool"),
       },
-      toolAllowlist: ["group:plugins"],
-    });
-    expect(toolsAll.map((tool) => tool.name)).toContain("optional_tool");
+    ]);
 
-    const toolsPlugin = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [optionalDemoPlugin.file] },
-            allow: [optionalDemoPlugin.id],
-          },
-        },
-        workspaceDir: optionalDemoPlugin.dir,
-      },
+    const toolsByPlugin = resolvePluginTools({
+      context: createContext() as never,
       toolAllowlist: ["optional-demo"],
     });
-    expect(toolsPlugin.map((tool) => tool.name)).toContain("optional_tool");
+    const toolsByGroup = resolvePluginTools({
+      context: createContext() as never,
+      toolAllowlist: ["group:plugins"],
+    });
+
+    expect(toolsByPlugin.map((tool) => tool.name)).toEqual(["optional_tool"]);
+    expect(toolsByGroup.map((tool) => tool.name)).toEqual(["optional_tool"]);
   });
 
   it("rejects plugin id collisions with core tool names", () => {
-    const tools = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [coreNameCollisionPlugin.file] },
-            allow: [coreNameCollisionPlugin.id],
-          },
-        },
-        workspaceDir: coreNameCollisionPlugin.dir,
+    const registry = setRegistry([
+      {
+        pluginId: "message",
+        optional: false,
+        source: "/tmp/message.js",
+        factory: () => makeTool("optional_tool"),
       },
+    ]);
+
+    const tools = resolvePluginTools({
+      context: createContext() as never,
       existingToolNames: new Set(["message"]),
-      toolAllowlist: ["message"],
     });
+
     expect(tools).toHaveLength(0);
+    expect(registry.diagnostics).toHaveLength(1);
+    expect(registry.diagnostics[0]?.message).toContain("plugin id conflicts with core tool name");
   });
 
   it("skips conflicting tool names but keeps other tools", () => {
-    const tools = resolvePluginTools({
-      context: {
-        config: {
-          plugins: {
-            load: { paths: [multiToolPlugin.file] },
-            allow: [multiToolPlugin.id],
-          },
-        },
-        workspaceDir: multiToolPlugin.dir,
+    const registry = setRegistry([
+      {
+        pluginId: "multi",
+        optional: false,
+        source: "/tmp/multi.js",
+        factory: () => [makeTool("message"), makeTool("other_tool")],
       },
+    ]);
+
+    const tools = resolvePluginTools({
+      context: createContext() as never,
       existingToolNames: new Set(["message"]),
     });
 
     expect(tools.map((tool) => tool.name)).toEqual(["other_tool"]);
+    expect(registry.diagnostics).toHaveLength(1);
+    expect(registry.diagnostics[0]?.message).toContain("plugin tool name conflict");
   });
 });
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
index 32a961df6e6..ad9d283ccd8 100644
--- a/src/plugins/types.ts
+++ b/src/plugins/types.ts
@@ -297,6 +297,8 @@ export type PluginDiagnostic = {
 
 export type PluginHookName =
   | "before_agent_start"
+  | "llm_input"
+  | "llm_output"
   | "agent_end"
   | "before_compaction"
   | "after_compaction"
@@ -332,6 +334,35 @@ export type PluginHookBeforeAgentStartResult = {
   prependContext?: string;
 };
 
+// llm_input hook
+export type PluginHookLlmInputEvent = {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  systemPrompt?: string;
+  prompt: string;
+  historyMessages: unknown[];
+  imagesCount: number;
+};
+
+// llm_output hook
+export type PluginHookLlmOutputEvent = {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  assistantTexts: string[];
+  lastAssistant?: unknown;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+  };
+};
+
 // agent_end hook
 export type PluginHookAgentEndEvent = {
   messages: unknown[];
@@ -498,6 +529,11 @@ export type PluginHookHandlerMap = {
     event: PluginHookBeforeAgentStartEvent,
     ctx: PluginHookAgentContext,
   ) => Promise<PluginHookBeforeAgentStartResult | void> | PluginHookBeforeAgentStartResult | void;
+  llm_input: (event: PluginHookLlmInputEvent, ctx: PluginHookAgentContext) => Promise<void> | void;
+  llm_output: (
+    event: PluginHookLlmOutputEvent,
+    ctx: PluginHookAgentContext,
+  ) => Promise<void> | void;
   agent_end: (event: PluginHookAgentEndEvent, ctx: PluginHookAgentContext) => Promise<void> | void;
   before_compaction: (
     event: PluginHookBeforeCompactionEvent,
diff --git a/src/plugins/wired-hooks-after-tool-call.e2e.test.ts b/src/plugins/wired-hooks-after-tool-call.e2e.test.ts
index cddbf3b42ba..91cfa51014f 100644
--- a/src/plugins/wired-hooks-after-tool-call.e2e.test.ts
+++ b/src/plugins/wired-hooks-after-tool-call.e2e.test.ts
@@ -20,6 +20,42 @@ vi.mock("../infra/agent-events.js", () => ({
   emitAgentEvent: vi.fn(),
 }));
 
+function createToolHandlerCtx(params: {
+  runId: string;
+  sessionKey?: string;
+  agentId?: string;
+  onBlockReplyFlush?: unknown;
+}) {
+  return {
+    params: {
+      runId: params.runId,
+      session: { messages: [] },
+      agentId: params.agentId,
+      sessionKey: params.sessionKey,
+      onBlockReplyFlush: params.onBlockReplyFlush,
+    },
+    state: {
+      toolMetaById: new Map<string, string | undefined>(),
+      toolMetas: [] as Array<{ toolName?: string; meta?: string }>,
+      toolSummaryById: new Set<string>(),
+      lastToolError: undefined,
+      pendingMessagingTexts: new Map<string, string>(),
+      pendingMessagingTargets: new Map<string, unknown>(),
+      messagingToolSentTexts: [] as string[],
+      messagingToolSentTextsNormalized: [] as string[],
+      messagingToolSentTargets: [] as unknown[],
+      blockBuffer: "",
+    },
+    log: { debug: vi.fn(), warn: vi.fn() },
+    flushBlockReplyBuffer: vi.fn(),
+    shouldEmitToolResult: () => false,
+    shouldEmitToolOutput: () => false,
+    emitToolSummary: vi.fn(),
+    emitToolOutput: vi.fn(),
+    trimMessagingToolSent: vi.fn(),
+  };
+}
+
 describe("after_tool_call hook wiring", () => {
   beforeEach(() => {
     hookMocks.runner.hasHooks.mockReset();
@@ -36,34 +72,11 @@ describe("after_tool_call hook wiring", () => {
     const { handleToolExecutionEnd, handleToolExecutionStart } =
       await import("../agents/pi-embedded-subscribe.handlers.tools.js");
 
-    const ctx = {
-      params: {
-        runId: "test-run-1",
-        session: { messages: [] },
-        agentId: "main",
-        sessionKey: "test-session",
-        onBlockReplyFlush: undefined,
-      },
-      state: {
-        toolMetaById: new Map<string, string | undefined>(),
-        toolMetas: [] as Array<{ toolName?: string; meta?: string }>,
-        toolSummaryById: new Set<string>(),
-        lastToolError: undefined,
-        pendingMessagingTexts: new Map<string, string>(),
-        pendingMessagingTargets: new Map<string, unknown>(),
-        messagingToolSentTexts: [] as string[],
-        messagingToolSentTextsNormalized: [] as string[],
-        messagingToolSentTargets: [] as unknown[],
-        blockBuffer: "",
-      },
-      log: { debug: vi.fn(), warn: vi.fn() },
-      flushBlockReplyBuffer: vi.fn(),
-      shouldEmitToolResult: () => false,
-      shouldEmitToolOutput: () => false,
-      emitToolSummary: vi.fn(),
-      emitToolOutput: vi.fn(),
-      trimMessagingToolSent: vi.fn(),
-    };
+    const ctx = createToolHandlerCtx({
+      runId: "test-run-1",
+      agentId: "main",
+      sessionKey: "test-session",
+    });
 
     await handleToolExecutionStart(
       ctx as never,
@@ -103,32 +116,7 @@ describe("after_tool_call hook wiring", () => {
     const { handleToolExecutionEnd, handleToolExecutionStart } =
       await import("../agents/pi-embedded-subscribe.handlers.tools.js");
 
-    const ctx = {
-      params: {
-        runId: "test-run-2",
-        session: { messages: [] },
-        onBlockReplyFlush: undefined,
-      },
-      state: {
-        toolMetaById: new Map<string, string | undefined>(),
-        toolMetas: [] as Array<{ toolName?: string; meta?: string }>,
-        toolSummaryById: new Set<string>(),
-        lastToolError: undefined,
-        pendingMessagingTexts: new Map<string, string>(),
-        pendingMessagingTargets: new Map<string, unknown>(),
-        messagingToolSentTexts: [] as string[],
-        messagingToolSentTextsNormalized: [] as string[],
-        messagingToolSentTargets: [] as unknown[],
-        blockBuffer: "",
-      },
-      log: { debug: vi.fn(), warn: vi.fn() },
-      flushBlockReplyBuffer: vi.fn(),
-      shouldEmitToolResult: () => false,
-      shouldEmitToolOutput: () => false,
-      emitToolSummary: vi.fn(),
-      emitToolOutput: vi.fn(),
-      trimMessagingToolSent: vi.fn(),
-    };
+    const ctx = createToolHandlerCtx({ runId: "test-run-2" });
 
     await handleToolExecutionStart(
       ctx as never,
@@ -163,26 +151,7 @@ describe("after_tool_call hook wiring", () => {
     const { handleToolExecutionEnd } =
       await import("../agents/pi-embedded-subscribe.handlers.tools.js");
 
-    const ctx = {
-      params: { runId: "r", session: { messages: [] } },
-      state: {
-        toolMetaById: new Map<string, string | undefined>(),
-        toolMetas: [] as Array<{ toolName?: string; meta?: string }>,
-        toolSummaryById: new Set<string>(),
-        lastToolError: undefined,
-        pendingMessagingTexts: new Map<string, string>(),
-        pendingMessagingTargets: new Map<string, unknown>(),
-        messagingToolSentTexts: [] as string[],
-        messagingToolSentTextsNormalized: [] as string[],
-        messagingToolSentTargets: [] as unknown[],
-      },
-      log: { debug: vi.fn(), warn: vi.fn() },
-      shouldEmitToolResult: () => false,
-      shouldEmitToolOutput: () => false,
-      emitToolSummary: vi.fn(),
-      emitToolOutput: vi.fn(),
-      trimMessagingToolSent: vi.fn(),
-    };
+    const ctx = createToolHandlerCtx({ runId: "r" });
 
     await handleToolExecutionEnd(
       ctx as never,
diff --git a/src/plugins/wired-hooks-llm.test.ts b/src/plugins/wired-hooks-llm.test.ts
new file mode 100644
index 00000000000..9311f31e30e
--- /dev/null
+++ b/src/plugins/wired-hooks-llm.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from "vitest";
+import type { PluginRegistry } from "./registry.js";
+import { createHookRunner } from "./hooks.js";
+
+function createMockRegistry(
+  hooks: Array<{ hookName: string; handler: (...args: unknown[]) => unknown }>,
+): PluginRegistry {
+  return {
+    hooks: hooks as never[],
+    typedHooks: hooks.map((h) => ({
+      pluginId: "test-plugin",
+      hookName: h.hookName,
+      handler: h.handler,
+      priority: 0,
+      source: "test",
+    })),
+    tools: [],
+    httpHandlers: [],
+    httpRoutes: [],
+    channelRegistrations: [],
+    gatewayHandlers: {},
+    cliRegistrars: [],
+    services: [],
+    providers: [],
+    commands: [],
+  } as unknown as PluginRegistry;
+}
+
+describe("llm hook runner methods", () => {
+  it("runLlmInput invokes registered llm_input hooks", async () => {
+    const handler = vi.fn();
+    const registry = createMockRegistry([{ hookName: "llm_input", handler }]);
+    const runner = createHookRunner(registry);
+
+    await runner.runLlmInput(
+      {
+        runId: "run-1",
+        sessionId: "session-1",
+        provider: "openai",
+        model: "gpt-5",
+        systemPrompt: "be helpful",
+        prompt: "hello",
+        historyMessages: [],
+        imagesCount: 0,
+      },
+      {
+        agentId: "main",
+        sessionId: "session-1",
+      },
+    );
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({ runId: "run-1", prompt: "hello" }),
+      expect.objectContaining({ sessionId: "session-1" }),
+    );
+  });
+
+  it("runLlmOutput invokes registered llm_output hooks", async () => {
+    const handler = vi.fn();
+    const registry = createMockRegistry([{ hookName: "llm_output", handler }]);
+    const runner = createHookRunner(registry);
+
+    await runner.runLlmOutput(
+      {
+        runId: "run-1",
+        sessionId: "session-1",
+        provider: "openai",
+        model: "gpt-5",
+        assistantTexts: ["hi"],
+        lastAssistant: { role: "assistant", content: "hi" },
+        usage: {
+          input: 10,
+          output: 20,
+          total: 30,
+        },
+      },
+      {
+        agentId: "main",
+        sessionId: "session-1",
+      },
+    );
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({ runId: "run-1", assistantTexts: ["hi"] }),
+      expect.objectContaining({ sessionId: "session-1" }),
+    );
+  });
+
+  it("hasHooks returns true for registered llm hooks", () => {
+    const registry = createMockRegistry([{ hookName: "llm_input", handler: vi.fn() }]);
+    const runner = createHookRunner(registry);
+
+    expect(runner.hasHooks("llm_input")).toBe(true);
+    expect(runner.hasHooks("llm_output")).toBe(false);
+  });
+});
diff --git a/src/process/child-process-bridge.test.ts b/src/process/child-process-bridge.test.ts
index 855b37ac2ea..9a8c2f5078f 100644
--- a/src/process/child-process-bridge.test.ts
+++ b/src/process/child-process-bridge.test.ts
@@ -1,11 +1,10 @@
 import { spawn } from "node:child_process";
-import net from "node:net";
 import path from "node:path";
 import process from "node:process";
 import { afterEach, describe, expect, it } from "vitest";
 import { attachChildProcessBridge } from "./child-process-bridge.js";
 
-function waitForLine(stream: NodeJS.ReadableStream, timeoutMs = 10_000): Promise<string> {
+function waitForLine(stream: NodeJS.ReadableStream, timeoutMs = 2000): Promise<string> {
   return new Promise((resolve, reject) => {
     let buffer = "";
 
@@ -40,28 +39,6 @@ function waitForLine(stream: NodeJS.ReadableStream, timeoutMs = 10_000): Promise
   });
 }
 
-function canConnect(port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = net.createConnection({ host: "127.0.0.1", port });
-    socket.once("connect", () => {
-      socket.end();
-      resolve(true);
-    });
-    socket.once("error", () => resolve(false));
-  });
-}
-
-async function waitForPortClosed(port: number, timeoutMs = 1_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() <= deadline) {
-    if (!(await canConnect(port))) {
-      return;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 10));
-  }
-  throw new Error("timeout waiting for port to close");
-}
-
 describe("attachChildProcessBridge", () => {
   const children: Array<{ kill: (signal?: NodeJS.Signals) => boolean }> = [];
   const detachments: Array<() => void> = [];
@@ -102,11 +79,8 @@ describe("attachChildProcessBridge", () => {
     if (!child.stdout) {
       throw new Error("expected stdout");
     }
-    const portLine = await waitForLine(child.stdout);
-    const port = Number(portLine);
-    expect(Number.isFinite(port)).toBe(true);
-
-    expect(await canConnect(port)).toBe(true);
+    const ready = await waitForLine(child.stdout);
+    expect(ready).toBe("ready");
 
     // Simulate systemd sending SIGTERM to the parent process.
     if (!addedSigterm) {
@@ -121,8 +95,5 @@ describe("attachChildProcessBridge", () => {
         resolve();
       });
     });
-
-    await waitForPortClosed(port);
-    expect(await canConnect(port)).toBe(false);
   }, 20_000);
 });
diff --git a/src/process/exec.test.ts b/src/process/exec.test.ts
index 7e1dd1f0232..e9a9754e8e2 100644
--- a/src/process/exec.test.ts
+++ b/src/process/exec.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { runCommandWithTimeout, shouldSpawnWithShell } from "./exec.js";
 
 describe("runCommandWithTimeout", () => {
@@ -11,21 +12,8 @@ describe("runCommandWithTimeout", () => {
     ).toBe(false);
   });
 
-  it("passes env overrides to child", async () => {
-    const result = await runCommandWithTimeout(
-      [process.execPath, "-e", 'process.stdout.write(process.env.OPENCLAW_TEST_ENV ?? "")'],
-      {
-        timeoutMs: 5_000,
-        env: { OPENCLAW_TEST_ENV: "ok" },
-      },
-    );
-
-    expect(result.code).toBe(0);
-    expect(result.stdout).toBe("ok");
-  });
-
   it("merges custom env with process.env", async () => {
-    const previous = process.env.OPENCLAW_BASE_ENV;
+    const envSnapshot = captureEnv(["OPENCLAW_BASE_ENV"]);
     process.env.OPENCLAW_BASE_ENV = "base";
     try {
       const result = await runCommandWithTimeout(
@@ -42,12 +30,55 @@ describe("runCommandWithTimeout", () => {
 
       expect(result.code).toBe(0);
       expect(result.stdout).toBe("base|ok");
+      expect(result.termination).toBe("exit");
     } finally {
-      if (previous === undefined) {
-        delete process.env.OPENCLAW_BASE_ENV;
-      } else {
-        process.env.OPENCLAW_BASE_ENV = previous;
-      }
+      envSnapshot.restore();
     }
   });
+
+  it("kills command when no output timeout elapses", async () => {
+    const result = await runCommandWithTimeout(
+      [process.execPath, "-e", "setTimeout(() => {}, 10_000)"],
+      {
+        timeoutMs: 5_000,
+        noOutputTimeoutMs: 50,
+      },
+    );
+
+    expect(result.termination).toBe("no-output-timeout");
+    expect(result.noOutputTimedOut).toBe(true);
+    expect(result.code).not.toBe(0);
+  });
+
+  it("resets no output timer when command keeps emitting output", async () => {
+    const result = await runCommandWithTimeout(
+      [
+        process.execPath,
+        "-e",
+        'let i=0; const t=setInterval(() => { process.stdout.write("."); i += 1; if (i >= 2) { clearInterval(t); process.exit(0); } }, 10);',
+      ],
+      {
+        timeoutMs: 5_000,
+        noOutputTimeoutMs: 160,
+      },
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.termination).toBe("exit");
+    expect(result.noOutputTimedOut).toBe(false);
+    expect(result.stdout.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("reports global timeout termination when overall timeout elapses", async () => {
+    const result = await runCommandWithTimeout(
+      [process.execPath, "-e", "setTimeout(() => {}, 10_000)"],
+      {
+        timeoutMs: 15,
+      },
+    );
+
+    expect(result.termination).toBe("timeout");
+    expect(result.noOutputTimedOut).toBe(false);
+    expect(result.code).not.toBe(0);
+  });
 });
diff --git a/src/process/exec.ts b/src/process/exec.ts
index 0cbd77263ac..6c4609e178e 100644
--- a/src/process/exec.ts
+++ b/src/process/exec.ts
@@ -76,11 +76,14 @@ export async function runExec(
 }
 
 export type SpawnResult = {
+  pid?: number;
   stdout: string;
   stderr: string;
   code: number | null;
   signal: NodeJS.Signals | null;
   killed: boolean;
+  termination: "exit" | "timeout" | "no-output-timeout" | "signal";
+  noOutputTimedOut?: boolean;
 };
 
 export type CommandOptions = {
@@ -89,6 +92,7 @@ export type CommandOptions = {
   input?: string;
   env?: NodeJS.ProcessEnv;
   windowsVerbatimArguments?: boolean;
+  noOutputTimeoutMs?: number;
 };
 
 export async function runCommandWithTimeout(
@@ -97,7 +101,7 @@ export async function runCommandWithTimeout(
 ): Promise<SpawnResult> {
   const options: CommandOptions =
     typeof optionsOrTimeout === "number" ? { timeoutMs: optionsOrTimeout } : optionsOrTimeout;
-  const { timeoutMs, cwd, input, env } = options;
+  const { timeoutMs, cwd, input, env, noOutputTimeoutMs } = options;
   const { windowsVerbatimArguments } = options;
   const hasInput = input !== undefined;
 
@@ -144,11 +148,45 @@ export async function runCommandWithTimeout(
     let stdout = "";
     let stderr = "";
     let settled = false;
+    let timedOut = false;
+    let noOutputTimedOut = false;
+    let noOutputTimer: NodeJS.Timeout | null = null;
+    const shouldTrackOutputTimeout =
+      typeof noOutputTimeoutMs === "number" &&
+      Number.isFinite(noOutputTimeoutMs) &&
+      noOutputTimeoutMs > 0;
+
+    const clearNoOutputTimer = () => {
+      if (!noOutputTimer) {
+        return;
+      }
+      clearTimeout(noOutputTimer);
+      noOutputTimer = null;
+    };
+
+    const armNoOutputTimer = () => {
+      if (!shouldTrackOutputTimeout || settled) {
+        return;
+      }
+      clearNoOutputTimer();
+      noOutputTimer = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        noOutputTimedOut = true;
+        if (typeof child.kill === "function") {
+          child.kill("SIGKILL");
+        }
+      }, Math.floor(noOutputTimeoutMs));
+    };
+
     const timer = setTimeout(() => {
+      timedOut = true;
       if (typeof child.kill === "function") {
         child.kill("SIGKILL");
       }
     }, timeoutMs);
+    armNoOutputTimer();
 
     if (hasInput && child.stdin) {
       child.stdin.write(input ?? "");
@@ -157,9 +195,11 @@ export async function runCommandWithTimeout(
 
     child.stdout?.on("data", (d) => {
       stdout += d.toString();
+      armNoOutputTimer();
     });
     child.stderr?.on("data", (d) => {
       stderr += d.toString();
+      armNoOutputTimer();
     });
     child.on("error", (err) => {
       if (settled) {
@@ -167,6 +207,7 @@ export async function runCommandWithTimeout(
       }
       settled = true;
       clearTimeout(timer);
+      clearNoOutputTimer();
       reject(err);
     });
     child.on("close", (code, signal) => {
@@ -175,7 +216,24 @@ export async function runCommandWithTimeout(
       }
       settled = true;
       clearTimeout(timer);
-      resolve({ stdout, stderr, code, signal, killed: child.killed });
+      clearNoOutputTimer();
+      const termination = noOutputTimedOut
+        ? "no-output-timeout"
+        : timedOut
+          ? "timeout"
+          : signal != null
+            ? "signal"
+            : "exit";
+      resolve({
+        pid: child.pid ?? undefined,
+        stdout,
+        stderr,
+        code,
+        signal,
+        killed: child.killed,
+        termination,
+        noOutputTimedOut,
+      });
     });
   });
 }
diff --git a/src/process/kill-tree.ts b/src/process/kill-tree.ts
new file mode 100644
index 00000000000..e3b5573faa5
--- /dev/null
+++ b/src/process/kill-tree.ts
@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Best-effort process-tree termination.
+ * - Windows: use taskkill /T to include descendants.
+ * - Unix: try process-group kill first, then direct pid kill.
+ */
+export function killProcessTree(pid: number): void {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return;
+  }
+
+  if (process.platform === "win32") {
+    try {
+      spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } catch {
+      // ignore taskkill failures
+    }
+    return;
+  }
+
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // process already gone or inaccessible
+    }
+  }
+}
diff --git a/src/process/restart-recovery.test.ts b/src/process/restart-recovery.test.ts
deleted file mode 100644
index 5091d7b9928..00000000000
--- a/src/process/restart-recovery.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { createRestartIterationHook } from "./restart-recovery.js";
-
-describe("restart-recovery", () => {
-  it("skips recovery on first iteration and runs on subsequent iterations", () => {
-    const onRestart = vi.fn();
-    const onIteration = createRestartIterationHook(onRestart);
-
-    expect(onIteration()).toBe(false);
-    expect(onRestart).not.toHaveBeenCalled();
-
-    expect(onIteration()).toBe(true);
-    expect(onRestart).toHaveBeenCalledTimes(1);
-
-    expect(onIteration()).toBe(true);
-    expect(onRestart).toHaveBeenCalledTimes(2);
-  });
-});
diff --git a/src/process/spawn-utils.test.ts b/src/process/spawn-utils.test.ts
index cb3e0dc1dc0..b5e134ca623 100644
--- a/src/process/spawn-utils.test.ts
+++ b/src/process/spawn-utils.test.ts
@@ -2,6 +2,7 @@ import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import { describe, expect, it, vi } from "vitest";
+import { createRestartIterationHook } from "./restart-recovery.js";
 import { spawnWithFallback } from "./spawn-utils.js";
 
 function createStubChild() {
@@ -61,3 +62,19 @@ describe("spawnWithFallback", () => {
     expect(spawnMock).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("restart-recovery", () => {
+  it("skips recovery on first iteration and runs on subsequent iterations", () => {
+    const onRestart = vi.fn();
+    const onIteration = createRestartIterationHook(onRestart);
+
+    expect(onIteration()).toBe(false);
+    expect(onRestart).not.toHaveBeenCalled();
+
+    expect(onIteration()).toBe(true);
+    expect(onRestart).toHaveBeenCalledTimes(1);
+
+    expect(onIteration()).toBe(true);
+    expect(onRestart).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/src/process/supervisor/adapters/child.test.ts b/src/process/supervisor/adapters/child.test.ts
new file mode 100644
index 00000000000..f69a67f141b
--- /dev/null
+++ b/src/process/supervisor/adapters/child.test.ts
@@ -0,0 +1,116 @@
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { spawnWithFallbackMock, killProcessTreeMock } = vi.hoisted(() => ({
+  spawnWithFallbackMock: vi.fn(),
+  killProcessTreeMock: vi.fn(),
+}));
+
+vi.mock("../../spawn-utils.js", () => ({
+  spawnWithFallback: (...args: unknown[]) => spawnWithFallbackMock(...args),
+}));
+
+vi.mock("../../kill-tree.js", () => ({
+  killProcessTree: (...args: unknown[]) => killProcessTreeMock(...args),
+}));
+
+function createStubChild(pid = 1234) {
+  const child = new EventEmitter() as ChildProcess;
+  child.stdin = new PassThrough() as ChildProcess["stdin"];
+  child.stdout = new PassThrough() as ChildProcess["stdout"];
+  child.stderr = new PassThrough() as ChildProcess["stderr"];
+  child.pid = pid;
+  child.killed = false;
+  const killMock = vi.fn(() => true);
+  child.kill = killMock as ChildProcess["kill"];
+  return { child, killMock };
+}
+
+describe("createChildAdapter", () => {
+  beforeEach(() => {
+    spawnWithFallbackMock.mockReset();
+    killProcessTreeMock.mockReset();
+  });
+
+  it("uses process-tree kill for default SIGKILL", async () => {
+    const { child, killMock } = createStubChild(4321);
+    spawnWithFallbackMock.mockResolvedValue({
+      child,
+      usedFallback: false,
+    });
+    const { createChildAdapter } = await import("./child.js");
+    const adapter = await createChildAdapter({
+      argv: ["node", "-e", "setTimeout(() => {}, 1000)"],
+      stdinMode: "pipe-open",
+    });
+
+    const spawnArgs = spawnWithFallbackMock.mock.calls[0]?.[0] as {
+      options?: { detached?: boolean };
+      fallbacks?: Array<{ options?: { detached?: boolean } }>;
+    };
+    expect(spawnArgs.options?.detached).toBe(true);
+    expect(spawnArgs.fallbacks?.[0]?.options?.detached).toBe(false);
+
+    adapter.kill();
+
+    expect(killProcessTreeMock).toHaveBeenCalledWith(4321);
+    expect(killMock).not.toHaveBeenCalled();
+  });
+
+  it("uses direct child.kill for non-SIGKILL signals", async () => {
+    const { child, killMock } = createStubChild(7654);
+    spawnWithFallbackMock.mockResolvedValue({
+      child,
+      usedFallback: false,
+    });
+    const { createChildAdapter } = await import("./child.js");
+    const adapter = await createChildAdapter({
+      argv: ["node", "-e", "setTimeout(() => {}, 1000)"],
+      stdinMode: "pipe-open",
+    });
+
+    adapter.kill("SIGTERM");
+
+    expect(killProcessTreeMock).not.toHaveBeenCalled();
+    expect(killMock).toHaveBeenCalledWith("SIGTERM");
+  });
+
+  it("keeps inherited env when no override env is provided", async () => {
+    const { child } = createStubChild(3333);
+    spawnWithFallbackMock.mockResolvedValue({
+      child,
+      usedFallback: false,
+    });
+    const { createChildAdapter } = await import("./child.js");
+    await createChildAdapter({
+      argv: ["node", "-e", "process.exit(0)"],
+      stdinMode: "pipe-open",
+    });
+
+    const spawnArgs = spawnWithFallbackMock.mock.calls[0]?.[0] as {
+      options?: { env?: NodeJS.ProcessEnv };
+    };
+    expect(spawnArgs.options?.env).toBeUndefined();
+  });
+
+  it("passes explicit env overrides as strings", async () => {
+    const { child } = createStubChild(4444);
+    spawnWithFallbackMock.mockResolvedValue({
+      child,
+      usedFallback: false,
+    });
+    const { createChildAdapter } = await import("./child.js");
+    await createChildAdapter({
+      argv: ["node", "-e", "process.exit(0)"],
+      env: { FOO: "bar", COUNT: "12", DROP_ME: undefined },
+      stdinMode: "pipe-open",
+    });
+
+    const spawnArgs = spawnWithFallbackMock.mock.calls[0]?.[0] as {
+      options?: { env?: Record<string, string> };
+    };
+    expect(spawnArgs.options?.env).toEqual({ FOO: "bar", COUNT: "12" });
+  });
+});
diff --git a/src/process/supervisor/adapters/child.ts b/src/process/supervisor/adapters/child.ts
new file mode 100644
index 00000000000..4bd5be0e06a
--- /dev/null
+++ b/src/process/supervisor/adapters/child.ts
@@ -0,0 +1,161 @@
+import type { ChildProcessWithoutNullStreams, SpawnOptions } from "node:child_process";
+import type { ManagedRunStdin } from "../types.js";
+import { killProcessTree } from "../../kill-tree.js";
+import { spawnWithFallback } from "../../spawn-utils.js";
+import { toStringEnv } from "./env.js";
+
+function resolveCommand(command: string): string {
+  if (process.platform !== "win32") {
+    return command;
+  }
+  const lower = command.toLowerCase();
+  if (lower.endsWith(".exe") || lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+    return command;
+  }
+  const basename = lower.split(/[\\/]/).pop() ?? lower;
+  if (basename === "npm" || basename === "pnpm" || basename === "yarn" || basename === "npx") {
+    return `${command}.cmd`;
+  }
+  return command;
+}
+
+export type ChildAdapter = {
+  pid?: number;
+  stdin?: ManagedRunStdin;
+  onStdout: (listener: (chunk: string) => void) => void;
+  onStderr: (listener: (chunk: string) => void) => void;
+  wait: () => Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+  kill: (signal?: NodeJS.Signals) => void;
+  dispose: () => void;
+};
+
+export async function createChildAdapter(params: {
+  argv: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  windowsVerbatimArguments?: boolean;
+  input?: string;
+  stdinMode?: "inherit" | "pipe-open" | "pipe-closed";
+}): Promise<ChildAdapter> {
+  const resolvedArgv = [...params.argv];
+  resolvedArgv[0] = resolveCommand(resolvedArgv[0] ?? "");
+
+  const stdinMode = params.stdinMode ?? (params.input !== undefined ? "pipe-closed" : "inherit");
+
+  const options: SpawnOptions = {
+    cwd: params.cwd,
+    env: params.env ? toStringEnv(params.env) : undefined,
+    stdio: ["pipe", "pipe", "pipe"],
+    detached: true,
+    windowsHide: true,
+    windowsVerbatimArguments: params.windowsVerbatimArguments,
+  };
+  if (stdinMode === "inherit") {
+    options.stdio = ["inherit", "pipe", "pipe"];
+  } else {
+    options.stdio = ["pipe", "pipe", "pipe"];
+  }
+
+  const spawned = await spawnWithFallback({
+    argv: resolvedArgv,
+    options,
+    fallbacks: [
+      {
+        label: "no-detach",
+        options: { detached: false },
+      },
+    ],
+  });
+
+  const child = spawned.child as ChildProcessWithoutNullStreams;
+  if (child.stdin) {
+    if (params.input !== undefined) {
+      child.stdin.write(params.input);
+      child.stdin.end();
+    } else if (stdinMode === "pipe-closed") {
+      child.stdin.end();
+    }
+  }
+
+  const stdin: ManagedRunStdin | undefined = child.stdin
+    ? {
+        destroyed: false,
+        write: (data: string, cb?: (err?: Error | null) => void) => {
+          try {
+            child.stdin.write(data, cb);
+          } catch (err) {
+            cb?.(err as Error);
+          }
+        },
+        end: () => {
+          try {
+            child.stdin.end();
+          } catch {
+            // ignore close errors
+          }
+        },
+        destroy: () => {
+          try {
+            child.stdin.destroy();
+          } catch {
+            // ignore destroy errors
+          }
+        },
+      }
+    : undefined;
+
+  const onStdout = (listener: (chunk: string) => void) => {
+    child.stdout.on("data", (chunk) => {
+      listener(chunk.toString());
+    });
+  };
+
+  const onStderr = (listener: (chunk: string) => void) => {
+    child.stderr.on("data", (chunk) => {
+      listener(chunk.toString());
+    });
+  };
+
+  const wait = async () =>
+    await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("close", (code, signal) => {
+        resolve({ code, signal });
+      });
+    });
+
+  const kill = (signal?: NodeJS.Signals) => {
+    const pid = child.pid ?? undefined;
+    if (signal === undefined || signal === "SIGKILL") {
+      if (pid) {
+        killProcessTree(pid);
+      } else {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // ignore kill errors
+        }
+      }
+      return;
+    }
+    try {
+      child.kill(signal);
+    } catch {
+      // ignore kill errors for non-kill signals
+    }
+  };
+
+  const dispose = () => {
+    child.removeAllListeners();
+  };
+
+  return {
+    pid: child.pid ?? undefined,
+    stdin,
+    onStdout,
+    onStderr,
+    wait,
+    kill,
+    dispose,
+  };
+}
diff --git a/src/process/supervisor/adapters/env.ts b/src/process/supervisor/adapters/env.ts
new file mode 100644
index 00000000000..31be350eabe
--- /dev/null
+++ b/src/process/supervisor/adapters/env.ts
@@ -0,0 +1,13 @@
+export function toStringEnv(env?: NodeJS.ProcessEnv): Record<string, string> {
+  if (!env) {
+    return {};
+  }
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) {
+      continue;
+    }
+    out[key] = String(value);
+  }
+  return out;
+}
diff --git a/src/process/supervisor/adapters/pty.test.ts b/src/process/supervisor/adapters/pty.test.ts
new file mode 100644
index 00000000000..c6753251be9
--- /dev/null
+++ b/src/process/supervisor/adapters/pty.test.ts
@@ -0,0 +1,169 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { spawnMock, ptyKillMock, killProcessTreeMock } = vi.hoisted(() => ({
+  spawnMock: vi.fn(),
+  ptyKillMock: vi.fn(),
+  killProcessTreeMock: vi.fn(),
+}));
+
+vi.mock("@lydell/node-pty", () => ({
+  spawn: (...args: unknown[]) => spawnMock(...args),
+}));
+
+vi.mock("../../kill-tree.js", () => ({
+  killProcessTree: (...args: unknown[]) => killProcessTreeMock(...args),
+}));
+
+function createStubPty(pid = 1234) {
+  let exitListener: ((event: { exitCode: number; signal?: number }) => void) | null = null;
+  return {
+    pid,
+    write: vi.fn(),
+    onData: vi.fn(() => ({ dispose: vi.fn() })),
+    onExit: vi.fn((listener: (event: { exitCode: number; signal?: number }) => void) => {
+      exitListener = listener;
+      return { dispose: vi.fn() };
+    }),
+    kill: (signal?: string) => ptyKillMock(signal),
+    emitExit: (event: { exitCode: number; signal?: number }) => {
+      exitListener?.(event);
+    },
+  };
+}
+
+describe("createPtyAdapter", () => {
+  beforeEach(() => {
+    spawnMock.mockReset();
+    ptyKillMock.mockReset();
+    killProcessTreeMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  it("forwards explicit signals to node-pty kill on non-Windows", async () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    try {
+      spawnMock.mockReturnValue(createStubPty());
+      const { createPtyAdapter } = await import("./pty.js");
+
+      const adapter = await createPtyAdapter({
+        shell: "bash",
+        args: ["-lc", "sleep 10"],
+      });
+
+      adapter.kill("SIGTERM");
+      expect(ptyKillMock).toHaveBeenCalledWith("SIGTERM");
+      expect(killProcessTreeMock).not.toHaveBeenCalled();
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, "platform", originalPlatform);
+      }
+    }
+  });
+
+  it("uses process-tree kill for SIGKILL by default", async () => {
+    spawnMock.mockReturnValue(createStubPty());
+    const { createPtyAdapter } = await import("./pty.js");
+
+    const adapter = await createPtyAdapter({
+      shell: "bash",
+      args: ["-lc", "sleep 10"],
+    });
+
+    adapter.kill();
+    expect(killProcessTreeMock).toHaveBeenCalledWith(1234);
+    expect(ptyKillMock).not.toHaveBeenCalled();
+  });
+
+  it("resolves wait when exit fires before wait is called", async () => {
+    const stub = createStubPty();
+    spawnMock.mockReturnValue(stub);
+    const { createPtyAdapter } = await import("./pty.js");
+
+    const adapter = await createPtyAdapter({
+      shell: "bash",
+      args: ["-lc", "exit 3"],
+    });
+
+    expect(stub.onExit).toHaveBeenCalledTimes(1);
+    stub.emitExit({ exitCode: 3, signal: 0 });
+    await expect(adapter.wait()).resolves.toEqual({ code: 3, signal: null });
+  });
+
+  it("keeps inherited env when no override env is provided", async () => {
+    const stub = createStubPty();
+    spawnMock.mockReturnValue(stub);
+    const { createPtyAdapter } = await import("./pty.js");
+
+    await createPtyAdapter({
+      shell: "bash",
+      args: ["-lc", "env"],
+    });
+
+    const spawnOptions = spawnMock.mock.calls[0]?.[2] as { env?: Record<string, string> };
+    expect(spawnOptions?.env).toBeUndefined();
+  });
+
+  it("passes explicit env overrides as strings", async () => {
+    const stub = createStubPty();
+    spawnMock.mockReturnValue(stub);
+    const { createPtyAdapter } = await import("./pty.js");
+
+    await createPtyAdapter({
+      shell: "bash",
+      args: ["-lc", "env"],
+      env: { FOO: "bar", COUNT: "12", DROP_ME: undefined },
+    });
+
+    const spawnOptions = spawnMock.mock.calls[0]?.[2] as { env?: Record<string, string> };
+    expect(spawnOptions?.env).toEqual({ FOO: "bar", COUNT: "12" });
+  });
+
+  it("does not pass a signal to node-pty on Windows", async () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    try {
+      spawnMock.mockReturnValue(createStubPty());
+      const { createPtyAdapter } = await import("./pty.js");
+
+      const adapter = await createPtyAdapter({
+        shell: "powershell.exe",
+        args: ["-NoLogo"],
+      });
+
+      adapter.kill("SIGTERM");
+      expect(ptyKillMock).toHaveBeenCalledWith(undefined);
+      expect(killProcessTreeMock).not.toHaveBeenCalled();
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, "platform", originalPlatform);
+      }
+    }
+  });
+
+  it("uses process-tree kill for SIGKILL on Windows", async () => {
+    const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    try {
+      spawnMock.mockReturnValue(createStubPty(4567));
+      const { createPtyAdapter } = await import("./pty.js");
+
+      const adapter = await createPtyAdapter({
+        shell: "powershell.exe",
+        args: ["-NoLogo"],
+      });
+
+      adapter.kill("SIGKILL");
+      expect(killProcessTreeMock).toHaveBeenCalledWith(4567);
+      expect(ptyKillMock).not.toHaveBeenCalled();
+    } finally {
+      if (originalPlatform) {
+        Object.defineProperty(process, "platform", originalPlatform);
+      }
+    }
+  });
+});
diff --git a/src/process/supervisor/adapters/pty.ts b/src/process/supervisor/adapters/pty.ts
new file mode 100644
index 00000000000..dca69f4a7bf
--- /dev/null
+++ b/src/process/supervisor/adapters/pty.ts
@@ -0,0 +1,184 @@
+import type { ManagedRunStdin } from "../types.js";
+import { killProcessTree } from "../../kill-tree.js";
+import { toStringEnv } from "./env.js";
+
+type PtyExitEvent = { exitCode: number; signal?: number };
+type PtyDisposable = { dispose: () => void };
+type PtySpawnHandle = {
+  pid: number;
+  write: (data: string | Buffer) => void;
+  onData: (listener: (value: string) => void) => PtyDisposable | void;
+  onExit: (listener: (event: PtyExitEvent) => void) => PtyDisposable | void;
+  kill: (signal?: string) => void;
+};
+type PtySpawn = (
+  file: string,
+  args: string[] | string,
+  options: {
+    name?: string;
+    cols?: number;
+    rows?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+  },
+) => PtySpawnHandle;
+
+type PtyModule = {
+  spawn?: PtySpawn;
+  default?: {
+    spawn?: PtySpawn;
+  };
+};
+
+export type PtyAdapter = {
+  pid?: number;
+  stdin?: ManagedRunStdin;
+  onStdout: (listener: (chunk: string) => void) => void;
+  onStderr: (listener: (chunk: string) => void) => void;
+  wait: () => Promise<{ code: number | null; signal: NodeJS.Signals | number | null }>;
+  kill: (signal?: NodeJS.Signals) => void;
+  dispose: () => void;
+};
+
+export async function createPtyAdapter(params: {
+  shell: string;
+  args: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  cols?: number;
+  rows?: number;
+  name?: string;
+}): Promise<PtyAdapter> {
+  const module = (await import("@lydell/node-pty")) as unknown as PtyModule;
+  const spawn = module.spawn ?? module.default?.spawn;
+  if (!spawn) {
+    throw new Error("PTY support is unavailable (node-pty spawn not found).");
+  }
+  const pty = spawn(params.shell, params.args, {
+    cwd: params.cwd,
+    env: params.env ? toStringEnv(params.env) : undefined,
+    name: params.name ?? process.env.TERM ?? "xterm-256color",
+    cols: params.cols ?? 120,
+    rows: params.rows ?? 30,
+  });
+
+  let dataListener: PtyDisposable | null = null;
+  let exitListener: PtyDisposable | null = null;
+  let waitResult: { code: number | null; signal: NodeJS.Signals | number | null } | null = null;
+  let resolveWait:
+    | ((value: { code: number | null; signal: NodeJS.Signals | number | null }) => void)
+    | null = null;
+  let waitPromise: Promise<{ code: number | null; signal: NodeJS.Signals | number | null }> | null =
+    null;
+
+  const settleWait = (value: { code: number | null; signal: NodeJS.Signals | number | null }) => {
+    if (waitResult) {
+      return;
+    }
+    waitResult = value;
+    if (resolveWait) {
+      const resolve = resolveWait;
+      resolveWait = null;
+      resolve(value);
+    }
+  };
+
+  exitListener =
+    pty.onExit((event) => {
+      const signal = event.signal && event.signal !== 0 ? event.signal : null;
+      settleWait({ code: event.exitCode ?? null, signal });
+    }) ?? null;
+
+  const stdin: ManagedRunStdin = {
+    destroyed: false,
+    write: (data, cb) => {
+      try {
+        pty.write(data);
+        cb?.(null);
+      } catch (err) {
+        cb?.(err as Error);
+      }
+    },
+    end: () => {
+      try {
+        const eof = process.platform === "win32" ? "\x1a" : "\x04";
+        pty.write(eof);
+      } catch {
+        // ignore EOF errors
+      }
+    },
+  };
+
+  const onStdout = (listener: (chunk: string) => void) => {
+    dataListener =
+      pty.onData((chunk) => {
+        listener(chunk.toString());
+      }) ?? null;
+  };
+
+  const onStderr = (_listener: (chunk: string) => void) => {
+    // PTY gives a unified output stream.
+  };
+
+  const wait = async () => {
+    if (waitResult) {
+      return waitResult;
+    }
+    if (!waitPromise) {
+      waitPromise = new Promise<{ code: number | null; signal: NodeJS.Signals | number | null }>(
+        (resolve) => {
+          resolveWait = resolve;
+          if (waitResult) {
+            const settled = waitResult;
+            resolveWait = null;
+            resolve(settled);
+          }
+        },
+      );
+    }
+    return waitPromise;
+  };
+
+  const kill = (signal: NodeJS.Signals = "SIGKILL") => {
+    try {
+      if (signal === "SIGKILL" && typeof pty.pid === "number" && pty.pid > 0) {
+        killProcessTree(pty.pid);
+      } else if (process.platform === "win32") {
+        pty.kill();
+      } else {
+        pty.kill(signal);
+      }
+    } catch {
+      // ignore kill errors
+    }
+    // Some PTY hosts do not emit `onExit` reliably after kill.
+    // Ensure waiters can progress on forced termination.
+    settleWait({ code: null, signal });
+  };
+
+  const dispose = () => {
+    try {
+      dataListener?.dispose();
+    } catch {
+      // ignore disposal errors
+    }
+    try {
+      exitListener?.dispose();
+    } catch {
+      // ignore disposal errors
+    }
+    dataListener = null;
+    exitListener = null;
+    settleWait({ code: null, signal: null });
+  };
+
+  return {
+    pid: pty.pid || undefined,
+    stdin,
+    onStdout,
+    onStderr,
+    wait,
+    kill,
+    dispose,
+  };
+}
diff --git a/src/process/supervisor/index.ts b/src/process/supervisor/index.ts
new file mode 100644
index 00000000000..42557ba5403
--- /dev/null
+++ b/src/process/supervisor/index.ts
@@ -0,0 +1,24 @@
+import type { ProcessSupervisor } from "./types.js";
+import { createProcessSupervisor } from "./supervisor.js";
+
+let singleton: ProcessSupervisor | null = null;
+
+export function getProcessSupervisor(): ProcessSupervisor {
+  if (singleton) {
+    return singleton;
+  }
+  singleton = createProcessSupervisor();
+  return singleton;
+}
+
+export { createProcessSupervisor } from "./supervisor.js";
+export type {
+  ManagedRun,
+  ProcessSupervisor,
+  RunExit,
+  RunRecord,
+  RunState,
+  SpawnInput,
+  SpawnMode,
+  TerminationReason,
+} from "./types.js";
diff --git a/src/process/supervisor/registry.test.ts b/src/process/supervisor/registry.test.ts
new file mode 100644
index 00000000000..64d56d33d1a
--- /dev/null
+++ b/src/process/supervisor/registry.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { createRunRegistry } from "./registry.js";
+
+describe("process supervisor run registry", () => {
+  it("finalize is idempotent and preserves first terminal metadata", () => {
+    const registry = createRunRegistry();
+    registry.add({
+      runId: "r1",
+      sessionId: "s1",
+      backendId: "b1",
+      state: "running",
+      startedAtMs: 1,
+      lastOutputAtMs: 1,
+      createdAtMs: 1,
+      updatedAtMs: 1,
+    });
+
+    const first = registry.finalize("r1", {
+      reason: "overall-timeout",
+      exitCode: null,
+      exitSignal: "SIGKILL",
+    });
+    const second = registry.finalize("r1", {
+      reason: "manual-cancel",
+      exitCode: 0,
+      exitSignal: null,
+    });
+
+    expect(first).not.toBeNull();
+    expect(first?.firstFinalize).toBe(true);
+    expect(first?.record.terminationReason).toBe("overall-timeout");
+    expect(first?.record.exitCode).toBeNull();
+    expect(first?.record.exitSignal).toBe("SIGKILL");
+
+    expect(second).not.toBeNull();
+    expect(second?.firstFinalize).toBe(false);
+    expect(second?.record.terminationReason).toBe("overall-timeout");
+    expect(second?.record.exitCode).toBeNull();
+    expect(second?.record.exitSignal).toBe("SIGKILL");
+  });
+
+  it("prunes oldest exited records once retention cap is exceeded", () => {
+    const registry = createRunRegistry({ maxExitedRecords: 2 });
+    registry.add({
+      runId: "r1",
+      sessionId: "s1",
+      backendId: "b1",
+      state: "running",
+      startedAtMs: 1,
+      lastOutputAtMs: 1,
+      createdAtMs: 1,
+      updatedAtMs: 1,
+    });
+    registry.add({
+      runId: "r2",
+      sessionId: "s2",
+      backendId: "b1",
+      state: "running",
+      startedAtMs: 2,
+      lastOutputAtMs: 2,
+      createdAtMs: 2,
+      updatedAtMs: 2,
+    });
+    registry.add({
+      runId: "r3",
+      sessionId: "s3",
+      backendId: "b1",
+      state: "running",
+      startedAtMs: 3,
+      lastOutputAtMs: 3,
+      createdAtMs: 3,
+      updatedAtMs: 3,
+    });
+
+    registry.finalize("r1", { reason: "exit", exitCode: 0, exitSignal: null });
+    registry.finalize("r2", { reason: "exit", exitCode: 0, exitSignal: null });
+    registry.finalize("r3", { reason: "exit", exitCode: 0, exitSignal: null });
+
+    expect(registry.get("r1")).toBeUndefined();
+    expect(registry.get("r2")?.state).toBe("exited");
+    expect(registry.get("r3")?.state).toBe("exited");
+  });
+});
diff --git a/src/process/supervisor/registry.ts b/src/process/supervisor/registry.ts
new file mode 100644
index 00000000000..02432af7c0b
--- /dev/null
+++ b/src/process/supervisor/registry.ts
@@ -0,0 +1,154 @@
+import type { RunRecord, RunState, TerminationReason } from "./types.js";
+
+function nowMs() {
+  return Date.now();
+}
+
+const DEFAULT_MAX_EXITED_RECORDS = 2_000;
+
+function resolveMaxExitedRecords(value?: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return DEFAULT_MAX_EXITED_RECORDS;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+export type RunRegistry = {
+  add: (record: RunRecord) => void;
+  get: (runId: string) => RunRecord | undefined;
+  list: () => RunRecord[];
+  listByScope: (scopeKey: string) => RunRecord[];
+  updateState: (
+    runId: string,
+    state: RunState,
+    patch?: Partial<Pick<RunRecord, "pid" | "terminationReason" | "exitCode" | "exitSignal">>,
+  ) => RunRecord | undefined;
+  touchOutput: (runId: string) => void;
+  finalize: (
+    runId: string,
+    exit: {
+      reason: TerminationReason;
+      exitCode: number | null;
+      exitSignal: NodeJS.Signals | number | null;
+    },
+  ) => { record: RunRecord; firstFinalize: boolean } | null;
+  delete: (runId: string) => void;
+};
+
+export function createRunRegistry(options?: { maxExitedRecords?: number }): RunRegistry {
+  const records = new Map<string, RunRecord>();
+  const maxExitedRecords = resolveMaxExitedRecords(options?.maxExitedRecords);
+
+  const pruneExitedRecords = () => {
+    if (!records.size) {
+      return;
+    }
+    let exited = 0;
+    for (const record of records.values()) {
+      if (record.state === "exited") {
+        exited += 1;
+      }
+    }
+    if (exited <= maxExitedRecords) {
+      return;
+    }
+    let remove = exited - maxExitedRecords;
+    for (const [runId, record] of records.entries()) {
+      if (remove <= 0) {
+        break;
+      }
+      if (record.state !== "exited") {
+        continue;
+      }
+      records.delete(runId);
+      remove -= 1;
+    }
+  };
+
+  const add: RunRegistry["add"] = (record) => {
+    records.set(record.runId, { ...record });
+  };
+
+  const get: RunRegistry["get"] = (runId) => {
+    const record = records.get(runId);
+    return record ? { ...record } : undefined;
+  };
+
+  const list: RunRegistry["list"] = () => {
+    return Array.from(records.values()).map((record) => ({ ...record }));
+  };
+
+  const listByScope: RunRegistry["listByScope"] = (scopeKey) => {
+    if (!scopeKey.trim()) {
+      return [];
+    }
+    return Array.from(records.values())
+      .filter((record) => record.scopeKey === scopeKey)
+      .map((record) => ({ ...record }));
+  };
+
+  const updateState: RunRegistry["updateState"] = (runId, state, patch) => {
+    const current = records.get(runId);
+    if (!current) {
+      return undefined;
+    }
+    const updatedAtMs = nowMs();
+    const next: RunRecord = {
+      ...current,
+      ...patch,
+      state,
+      updatedAtMs,
+      lastOutputAtMs: current.lastOutputAtMs,
+    };
+    records.set(runId, next);
+    return { ...next };
+  };
+
+  const touchOutput: RunRegistry["touchOutput"] = (runId) => {
+    const current = records.get(runId);
+    if (!current) {
+      return;
+    }
+    const ts = nowMs();
+    records.set(runId, {
+      ...current,
+      lastOutputAtMs: ts,
+      updatedAtMs: ts,
+    });
+  };
+
+  const finalize: RunRegistry["finalize"] = (runId, exit) => {
+    const current = records.get(runId);
+    if (!current) {
+      return null;
+    }
+    const firstFinalize = current.state !== "exited";
+    const ts = nowMs();
+    const next: RunRecord = {
+      ...current,
+      state: "exited",
+      terminationReason: current.terminationReason ?? exit.reason,
+      exitCode: current.exitCode !== undefined ? current.exitCode : exit.exitCode,
+      exitSignal: current.exitSignal !== undefined ? current.exitSignal : exit.exitSignal,
+      updatedAtMs: ts,
+    };
+    records.set(runId, next);
+    pruneExitedRecords();
+    return { record: { ...next }, firstFinalize };
+  };
+
+  const del: RunRegistry["delete"] = (runId) => {
+    records.delete(runId);
+  };
+
+  return {
+    add,
+    get,
+    list,
+    listByScope,
+    updateState,
+    touchOutput,
+    finalize,
+    delete: del,
+  };
+}
diff --git a/src/process/supervisor/supervisor.pty-command.test.ts b/src/process/supervisor/supervisor.pty-command.test.ts
new file mode 100644
index 00000000000..3fec62d4df9
--- /dev/null
+++ b/src/process/supervisor/supervisor.pty-command.test.ts
@@ -0,0 +1,76 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createPtyAdapterMock } = vi.hoisted(() => ({
+  createPtyAdapterMock: vi.fn(),
+}));
+
+vi.mock("../../agents/shell-utils.js", () => ({
+  getShellConfig: () => ({ shell: "sh", args: ["-c"] }),
+}));
+
+vi.mock("./adapters/pty.js", () => ({
+  createPtyAdapter: (...args: unknown[]) => createPtyAdapterMock(...args),
+}));
+
+function createStubPtyAdapter() {
+  return {
+    pid: 1234,
+    stdin: undefined,
+    onStdout: (_listener: (chunk: string) => void) => {
+      // no-op
+    },
+    onStderr: (_listener: (chunk: string) => void) => {
+      // no-op
+    },
+    wait: async () => ({ code: 0, signal: null }),
+    kill: (_signal?: NodeJS.Signals) => {
+      // no-op
+    },
+    dispose: () => {
+      // no-op
+    },
+  };
+}
+
+describe("process supervisor PTY command contract", () => {
+  beforeEach(() => {
+    createPtyAdapterMock.mockReset();
+  });
+
+  it("passes PTY command verbatim to shell args", async () => {
+    createPtyAdapterMock.mockResolvedValue(createStubPtyAdapter());
+    const { createProcessSupervisor } = await import("./supervisor.js");
+    const supervisor = createProcessSupervisor();
+    const command = `printf '%s\\n' "a b" && printf '%s\\n' '$HOME'`;
+
+    const run = await supervisor.spawn({
+      sessionId: "s1",
+      backendId: "test",
+      mode: "pty",
+      ptyCommand: command,
+      timeoutMs: 1_000,
+    });
+    const exit = await run.wait();
+
+    expect(exit.reason).toBe("exit");
+    expect(createPtyAdapterMock).toHaveBeenCalledTimes(1);
+    const params = createPtyAdapterMock.mock.calls[0]?.[0] as { args?: string[] };
+    expect(params.args).toEqual(["-c", command]);
+  });
+
+  it("rejects empty PTY command", async () => {
+    createPtyAdapterMock.mockResolvedValue(createStubPtyAdapter());
+    const { createProcessSupervisor } = await import("./supervisor.js");
+    const supervisor = createProcessSupervisor();
+
+    await expect(
+      supervisor.spawn({
+        sessionId: "s1",
+        backendId: "test",
+        mode: "pty",
+        ptyCommand: "   ",
+      }),
+    ).rejects.toThrow("PTY command cannot be empty");
+    expect(createPtyAdapterMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/process/supervisor/supervisor.test.ts b/src/process/supervisor/supervisor.test.ts
new file mode 100644
index 00000000000..30032c80b61
--- /dev/null
+++ b/src/process/supervisor/supervisor.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { createProcessSupervisor } from "./supervisor.js";
+
+describe("process supervisor", () => {
+  it("spawns child runs and captures output", async () => {
+    const supervisor = createProcessSupervisor();
+    const run = await supervisor.spawn({
+      sessionId: "s1",
+      backendId: "test",
+      mode: "child",
+      argv: [process.execPath, "-e", 'process.stdout.write("ok")'],
+      timeoutMs: 2_000,
+      stdinMode: "pipe-closed",
+    });
+    const exit = await run.wait();
+    expect(exit.reason).toBe("exit");
+    expect(exit.exitCode).toBe(0);
+    expect(exit.stdout).toBe("ok");
+  });
+
+  it("enforces no-output timeout for silent processes", async () => {
+    const supervisor = createProcessSupervisor();
+    const run = await supervisor.spawn({
+      sessionId: "s1",
+      backendId: "test",
+      mode: "child",
+      argv: [process.execPath, "-e", "setTimeout(() => {}, 10_000)"],
+      timeoutMs: 5_000,
+      noOutputTimeoutMs: 30,
+      stdinMode: "pipe-closed",
+    });
+    const exit = await run.wait();
+    expect(exit.reason).toBe("no-output-timeout");
+    expect(exit.noOutputTimedOut).toBe(true);
+    expect(exit.timedOut).toBe(true);
+  });
+
+  it("cancels prior scoped run when replaceExistingScope is enabled", async () => {
+    const supervisor = createProcessSupervisor();
+    const first = await supervisor.spawn({
+      sessionId: "s1",
+      backendId: "test",
+      scopeKey: "scope:a",
+      mode: "child",
+      argv: [process.execPath, "-e", "setTimeout(() => {}, 10_000)"],
+      timeoutMs: 10_000,
+      stdinMode: "pipe-open",
+    });
+
+    const second = await supervisor.spawn({
+      sessionId: "s1",
+      backendId: "test",
+      scopeKey: "scope:a",
+      replaceExistingScope: true,
+      mode: "child",
+      argv: [process.execPath, "-e", 'process.stdout.write("new")'],
+      timeoutMs: 2_000,
+      stdinMode: "pipe-closed",
+    });
+
+    const firstExit = await first.wait();
+    const secondExit = await second.wait();
+    expect(firstExit.reason === "manual-cancel" || firstExit.reason === "signal").toBe(true);
+    expect(secondExit.reason).toBe("exit");
+    expect(secondExit.stdout).toBe("new");
+  });
+
+  it("applies overall timeout even for near-immediate timer firing", async () => {
+    const supervisor = createProcessSupervisor();
+    const run = await supervisor.spawn({
+      sessionId: "s-timeout",
+      backendId: "test",
+      mode: "child",
+      argv: [process.execPath, "-e", "setTimeout(() => {}, 10_000)"],
+      timeoutMs: 1,
+      stdinMode: "pipe-closed",
+    });
+    const exit = await run.wait();
+    expect(exit.reason).toBe("overall-timeout");
+    expect(exit.timedOut).toBe(true);
+  });
+
+  it("can stream output without retaining it in RunExit payload", async () => {
+    const supervisor = createProcessSupervisor();
+    let streamed = "";
+    const run = await supervisor.spawn({
+      sessionId: "s-capture",
+      backendId: "test",
+      mode: "child",
+      argv: [process.execPath, "-e", 'process.stdout.write("streamed")'],
+      timeoutMs: 2_000,
+      stdinMode: "pipe-closed",
+      captureOutput: false,
+      onStdout: (chunk) => {
+        streamed += chunk;
+      },
+    });
+    const exit = await run.wait();
+    expect(streamed).toBe("streamed");
+    expect(exit.stdout).toBe("");
+  });
+});
diff --git a/src/process/supervisor/supervisor.ts b/src/process/supervisor/supervisor.ts
new file mode 100644
index 00000000000..dba0d7d3756
--- /dev/null
+++ b/src/process/supervisor/supervisor.ts
@@ -0,0 +1,282 @@
+import crypto from "node:crypto";
+import type {
+  ManagedRun,
+  ProcessSupervisor,
+  RunExit,
+  RunRecord,
+  SpawnInput,
+  TerminationReason,
+} from "./types.js";
+import { getShellConfig } from "../../agents/shell-utils.js";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { createChildAdapter } from "./adapters/child.js";
+import { createPtyAdapter } from "./adapters/pty.js";
+import { createRunRegistry } from "./registry.js";
+
+const log = createSubsystemLogger("process/supervisor");
+
+type ActiveRun = {
+  run: ManagedRun;
+  scopeKey?: string;
+};
+
+function clampTimeout(value?: number): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function isTimeoutReason(reason: TerminationReason) {
+  return reason === "overall-timeout" || reason === "no-output-timeout";
+}
+
+export function createProcessSupervisor(): ProcessSupervisor {
+  const registry = createRunRegistry();
+  const active = new Map<string, ActiveRun>();
+
+  const cancel = (runId: string, reason: TerminationReason = "manual-cancel") => {
+    const current = active.get(runId);
+    if (!current) {
+      return;
+    }
+    registry.updateState(runId, "exiting", {
+      terminationReason: reason,
+    });
+    current.run.cancel(reason);
+  };
+
+  const cancelScope = (scopeKey: string, reason: TerminationReason = "manual-cancel") => {
+    if (!scopeKey.trim()) {
+      return;
+    }
+    for (const [runId, run] of active.entries()) {
+      if (run.scopeKey !== scopeKey) {
+        continue;
+      }
+      cancel(runId, reason);
+    }
+  };
+
+  const spawn = async (input: SpawnInput): Promise<ManagedRun> => {
+    const runId = input.runId?.trim() || crypto.randomUUID();
+    if (input.replaceExistingScope && input.scopeKey?.trim()) {
+      cancelScope(input.scopeKey, "manual-cancel");
+    }
+    const startedAtMs = Date.now();
+    const record: RunRecord = {
+      runId,
+      sessionId: input.sessionId,
+      backendId: input.backendId,
+      scopeKey: input.scopeKey?.trim() || undefined,
+      state: "starting",
+      startedAtMs,
+      lastOutputAtMs: startedAtMs,
+      createdAtMs: startedAtMs,
+      updatedAtMs: startedAtMs,
+    };
+    registry.add(record);
+
+    let forcedReason: TerminationReason | null = null;
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+    let timeoutTimer: NodeJS.Timeout | null = null;
+    let noOutputTimer: NodeJS.Timeout | null = null;
+    const captureOutput = input.captureOutput !== false;
+
+    const overallTimeoutMs = clampTimeout(input.timeoutMs);
+    const noOutputTimeoutMs = clampTimeout(input.noOutputTimeoutMs);
+
+    const setForcedReason = (reason: TerminationReason) => {
+      if (forcedReason) {
+        return;
+      }
+      forcedReason = reason;
+      registry.updateState(runId, "exiting", { terminationReason: reason });
+    };
+
+    let cancelAdapter: ((reason: TerminationReason) => void) | null = null;
+
+    const requestCancel = (reason: TerminationReason) => {
+      setForcedReason(reason);
+      cancelAdapter?.(reason);
+    };
+
+    const touchOutput = () => {
+      registry.touchOutput(runId);
+      if (!noOutputTimeoutMs || settled) {
+        return;
+      }
+      if (noOutputTimer) {
+        clearTimeout(noOutputTimer);
+      }
+      noOutputTimer = setTimeout(() => {
+        requestCancel("no-output-timeout");
+      }, noOutputTimeoutMs);
+    };
+
+    try {
+      if (input.mode === "child" && input.argv.length === 0) {
+        throw new Error("spawn argv cannot be empty");
+      }
+      const adapter =
+        input.mode === "pty"
+          ? await (async () => {
+              const { shell, args: shellArgs } = getShellConfig();
+              const ptyCommand = input.ptyCommand.trim();
+              if (!ptyCommand) {
+                throw new Error("PTY command cannot be empty");
+              }
+              return await createPtyAdapter({
+                shell,
+                args: [...shellArgs, ptyCommand],
+                cwd: input.cwd,
+                env: input.env,
+              });
+            })()
+          : await createChildAdapter({
+              argv: input.argv,
+              cwd: input.cwd,
+              env: input.env,
+              windowsVerbatimArguments: input.windowsVerbatimArguments,
+              input: input.input,
+              stdinMode: input.stdinMode,
+            });
+
+      registry.updateState(runId, "running", { pid: adapter.pid });
+
+      const clearTimers = () => {
+        if (timeoutTimer) {
+          clearTimeout(timeoutTimer);
+          timeoutTimer = null;
+        }
+        if (noOutputTimer) {
+          clearTimeout(noOutputTimer);
+          noOutputTimer = null;
+        }
+      };
+
+      cancelAdapter = (_reason: TerminationReason) => {
+        if (settled) {
+          return;
+        }
+        adapter.kill("SIGKILL");
+      };
+
+      if (overallTimeoutMs) {
+        timeoutTimer = setTimeout(() => {
+          requestCancel("overall-timeout");
+        }, overallTimeoutMs);
+      }
+      if (noOutputTimeoutMs) {
+        noOutputTimer = setTimeout(() => {
+          requestCancel("no-output-timeout");
+        }, noOutputTimeoutMs);
+      }
+
+      adapter.onStdout((chunk) => {
+        if (captureOutput) {
+          stdout += chunk;
+        }
+        input.onStdout?.(chunk);
+        touchOutput();
+      });
+      adapter.onStderr((chunk) => {
+        if (captureOutput) {
+          stderr += chunk;
+        }
+        input.onStderr?.(chunk);
+        touchOutput();
+      });
+
+      const waitPromise = (async (): Promise<RunExit> => {
+        const result = await adapter.wait();
+        if (settled) {
+          return {
+            reason: forcedReason ?? "exit",
+            exitCode: result.code,
+            exitSignal: result.signal,
+            durationMs: Date.now() - startedAtMs,
+            stdout,
+            stderr,
+            timedOut: isTimeoutReason(forcedReason ?? "exit"),
+            noOutputTimedOut: forcedReason === "no-output-timeout",
+          };
+        }
+        settled = true;
+        clearTimers();
+        adapter.dispose();
+        active.delete(runId);
+
+        const reason: TerminationReason =
+          forcedReason ?? (result.signal != null ? ("signal" as const) : ("exit" as const));
+        const exit: RunExit = {
+          reason,
+          exitCode: result.code,
+          exitSignal: result.signal,
+          durationMs: Date.now() - startedAtMs,
+          stdout,
+          stderr,
+          timedOut: isTimeoutReason(forcedReason ?? reason),
+          noOutputTimedOut: forcedReason === "no-output-timeout",
+        };
+        registry.finalize(runId, {
+          reason: exit.reason,
+          exitCode: exit.exitCode,
+          exitSignal: exit.exitSignal,
+        });
+        return exit;
+      })().catch((err) => {
+        if (!settled) {
+          settled = true;
+          clearTimers();
+          active.delete(runId);
+          adapter.dispose();
+          registry.finalize(runId, {
+            reason: "spawn-error",
+            exitCode: null,
+            exitSignal: null,
+          });
+        }
+        throw err;
+      });
+
+      const managedRun: ManagedRun = {
+        runId,
+        pid: adapter.pid,
+        startedAtMs,
+        stdin: adapter.stdin,
+        wait: async () => await waitPromise,
+        cancel: (reason = "manual-cancel") => {
+          requestCancel(reason);
+        },
+      };
+
+      active.set(runId, {
+        run: managedRun,
+        scopeKey: input.scopeKey?.trim() || undefined,
+      });
+      return managedRun;
+    } catch (err) {
+      registry.finalize(runId, {
+        reason: "spawn-error",
+        exitCode: null,
+        exitSignal: null,
+      });
+      log.warn(`spawn failed: runId=${runId} reason=${String(err)}`);
+      throw err;
+    }
+  };
+
+  return {
+    spawn,
+    cancel,
+    cancelScope,
+    reconcileOrphans: async () => {
+      // Deliberate no-op: this supervisor uses in-memory ownership only.
+      // Active runs are not recovered after process restart in the current model.
+    },
+    getRecord: (runId: string) => registry.get(runId),
+  };
+}
diff --git a/src/process/supervisor/types.ts b/src/process/supervisor/types.ts
new file mode 100644
index 00000000000..04c571b08b2
--- /dev/null
+++ b/src/process/supervisor/types.ts
@@ -0,0 +1,96 @@
+export type RunState = "starting" | "running" | "exiting" | "exited";
+
+export type TerminationReason =
+  | "manual-cancel"
+  | "overall-timeout"
+  | "no-output-timeout"
+  | "spawn-error"
+  | "signal"
+  | "exit";
+
+export type RunRecord = {
+  runId: string;
+  sessionId: string;
+  backendId: string;
+  scopeKey?: string;
+  pid?: number;
+  processGroupId?: number;
+  startedAtMs: number;
+  lastOutputAtMs: number;
+  createdAtMs: number;
+  updatedAtMs: number;
+  state: RunState;
+  terminationReason?: TerminationReason;
+  exitCode?: number | null;
+  exitSignal?: NodeJS.Signals | number | null;
+};
+
+export type RunExit = {
+  reason: TerminationReason;
+  exitCode: number | null;
+  exitSignal: NodeJS.Signals | number | null;
+  durationMs: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  noOutputTimedOut: boolean;
+};
+
+export type ManagedRun = {
+  runId: string;
+  pid?: number;
+  startedAtMs: number;
+  stdin?: ManagedRunStdin;
+  wait: () => Promise<RunExit>;
+  cancel: (reason?: TerminationReason) => void;
+};
+
+export type SpawnMode = "child" | "pty";
+
+export type ManagedRunStdin = {
+  write: (data: string, cb?: (err?: Error | null) => void) => void;
+  end: () => void;
+  destroy?: () => void;
+  destroyed?: boolean;
+};
+
+type SpawnBaseInput = {
+  runId?: string;
+  sessionId: string;
+  backendId: string;
+  scopeKey?: string;
+  replaceExistingScope?: boolean;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+  noOutputTimeoutMs?: number;
+  /**
+   * When false, stdout/stderr are streamed via callbacks only and not retained in RunExit payload.
+   */
+  captureOutput?: boolean;
+  onStdout?: (chunk: string) => void;
+  onStderr?: (chunk: string) => void;
+};
+
+type SpawnChildInput = SpawnBaseInput & {
+  mode: "child";
+  argv: string[];
+  windowsVerbatimArguments?: boolean;
+  input?: string;
+  stdinMode?: "inherit" | "pipe-open" | "pipe-closed";
+};
+
+type SpawnPtyInput = SpawnBaseInput & {
+  mode: "pty";
+  ptyCommand: string;
+};
+
+export type SpawnInput = SpawnChildInput | SpawnPtyInput;
+
+export interface ProcessSupervisor {
+  spawn(input: SpawnInput): Promise<ManagedRun>;
+  cancel(runId: string, reason?: TerminationReason): void;
+  cancelScope(scopeKey: string, reason?: TerminationReason): void;
+  reconcileOrphans(): Promise<void>;
+  getRecord(runId: string): RunRecord | undefined;
+}
diff --git a/src/routing/bindings.ts b/src/routing/bindings.ts
index fadd193628d..9fc2ffb82d1 100644
--- a/src/routing/bindings.ts
+++ b/src/routing/bindings.ts
@@ -17,6 +17,33 @@ export function listBindings(cfg: OpenClawConfig): AgentBinding[] {
   return Array.isArray(cfg.bindings) ? cfg.bindings : [];
 }
 
+function resolveNormalizedBindingMatch(binding: AgentBinding): {
+  agentId: string;
+  accountId: string;
+  channelId: string;
+} | null {
+  if (!binding || typeof binding !== "object") {
+    return null;
+  }
+  const match = binding.match;
+  if (!match || typeof match !== "object") {
+    return null;
+  }
+  const channelId = normalizeBindingChannelId(match.channel);
+  if (!channelId) {
+    return null;
+  }
+  const accountId = typeof match.accountId === "string" ? match.accountId.trim() : "";
+  if (!accountId || accountId === "*") {
+    return null;
+  }
+  return {
+    agentId: normalizeAgentId(binding.agentId),
+    accountId: normalizeAccountId(accountId),
+    channelId,
+  };
+}
+
 export function listBoundAccountIds(cfg: OpenClawConfig, channelId: string): string[] {
   const normalizedChannel = normalizeBindingChannelId(channelId);
   if (!normalizedChannel) {
@@ -24,22 +51,11 @@ export function listBoundAccountIds(cfg: OpenClawConfig, channelId: string): str
   }
   const ids = new Set<string>();
   for (const binding of listBindings(cfg)) {
-    if (!binding || typeof binding !== "object") {
+    const resolved = resolveNormalizedBindingMatch(binding);
+    if (!resolved || resolved.channelId !== normalizedChannel) {
       continue;
     }
-    const match = binding.match;
-    if (!match || typeof match !== "object") {
-      continue;
-    }
-    const channel = normalizeBindingChannelId(match.channel);
-    if (!channel || channel !== normalizedChannel) {
-      continue;
-    }
-    const accountId = typeof match.accountId === "string" ? match.accountId.trim() : "";
-    if (!accountId || accountId === "*") {
-      continue;
-    }
-    ids.add(normalizeAccountId(accountId));
+    ids.add(resolved.accountId);
   }
   return Array.from(ids).toSorted((a, b) => a.localeCompare(b));
 }
@@ -54,25 +70,15 @@ export function resolveDefaultAgentBoundAccountId(
   }
   const defaultAgentId = normalizeAgentId(resolveDefaultAgentId(cfg));
   for (const binding of listBindings(cfg)) {
-    if (!binding || typeof binding !== "object") {
+    const resolved = resolveNormalizedBindingMatch(binding);
+    if (
+      !resolved ||
+      resolved.channelId !== normalizedChannel ||
+      resolved.agentId !== defaultAgentId
+    ) {
       continue;
     }
-    if (normalizeAgentId(binding.agentId) !== defaultAgentId) {
-      continue;
-    }
-    const match = binding.match;
-    if (!match || typeof match !== "object") {
-      continue;
-    }
-    const channel = normalizeBindingChannelId(match.channel);
-    if (!channel || channel !== normalizedChannel) {
-      continue;
-    }
-    const accountId = typeof match.accountId === "string" ? match.accountId.trim() : "";
-    if (!accountId || accountId === "*") {
-      continue;
-    }
-    return normalizeAccountId(accountId);
+    return resolved.accountId;
   }
   return null;
 }
@@ -80,30 +86,17 @@ export function resolveDefaultAgentBoundAccountId(
 export function buildChannelAccountBindings(cfg: OpenClawConfig) {
   const map = new Map<string, Map<string, string[]>>();
   for (const binding of listBindings(cfg)) {
-    if (!binding || typeof binding !== "object") {
+    const resolved = resolveNormalizedBindingMatch(binding);
+    if (!resolved) {
       continue;
     }
-    const match = binding.match;
-    if (!match || typeof match !== "object") {
-      continue;
+    const byAgent = map.get(resolved.channelId) ?? new Map<string, string[]>();
+    const list = byAgent.get(resolved.agentId) ?? [];
+    if (!list.includes(resolved.accountId)) {
+      list.push(resolved.accountId);
     }
-    const channelId = normalizeBindingChannelId(match.channel);
-    if (!channelId) {
-      continue;
-    }
-    const accountId = typeof match.accountId === "string" ? match.accountId.trim() : "";
-    if (!accountId || accountId === "*") {
-      continue;
-    }
-    const agentId = normalizeAgentId(binding.agentId);
-    const byAgent = map.get(channelId) ?? new Map<string, string[]>();
-    const list = byAgent.get(agentId) ?? [];
-    const normalizedAccountId = normalizeAccountId(accountId);
-    if (!list.includes(normalizedAccountId)) {
-      list.push(normalizedAccountId);
-    }
-    byAgent.set(agentId, list);
-    map.set(channelId, byAgent);
+    byAgent.set(resolved.agentId, list);
+    map.set(resolved.channelId, byAgent);
   }
   return map;
 }
diff --git a/src/routing/resolve-route.test.ts b/src/routing/resolve-route.test.ts
index 07d4bb79f4e..5cf2f3447d5 100644
--- a/src/routing/resolve-route.test.ts
+++ b/src/routing/resolve-route.test.ts
@@ -141,6 +141,17 @@ describe("resolveAgentRoute", () => {
     expect(route.matchedBy).toBe("binding.peer");
   });
 
+  test("coerces numeric peer ids to stable session keys", () => {
+    const cfg: OpenClawConfig = {};
+    const route = resolveAgentRoute({
+      cfg,
+      channel: "discord",
+      accountId: "default",
+      peer: { kind: "channel", id: 1468834856187203680n as unknown as string },
+    });
+    expect(route.sessionKey).toBe("agent:main:discord:channel:1468834856187203680");
+  });
+
   test("guild binding wins over account binding when peer not bound", () => {
     const cfg: OpenClawConfig = {
       bindings: [
diff --git a/src/routing/resolve-route.ts b/src/routing/resolve-route.ts
index 5cfa2bc6417..578a3ca8f8a 100644
--- a/src/routing/resolve-route.ts
+++ b/src/routing/resolve-route.ts
@@ -61,8 +61,14 @@ function normalizeToken(value: string | undefined | null): string {
   return (value ?? "").trim().toLowerCase();
 }
 
-function normalizeId(value: string | undefined | null): string {
-  return (value ?? "").trim();
+function normalizeId(value: unknown): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value).trim();
+  }
+  return "";
 }
 
 function normalizeAccountId(value: string | undefined | null): string {
diff --git a/src/routing/session-key.test.ts b/src/routing/session-key.test.ts
index 0ed385ab20d..5caed36e7fb 100644
--- a/src/routing/session-key.test.ts
+++ b/src/routing/session-key.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { getSubagentDepth, isCronSessionKey } from "../sessions/session-key-utils.js";
 import { classifySessionKeyShape } from "./session-key.js";
 
 describe("classifySessionKeyShape", () => {
@@ -39,3 +40,29 @@ describe("session key backward compatibility", () => {
     expect(classifySessionKeyShape("agent:main:discord:direct:user123")).toBe("agent");
   });
 });
+
+describe("getSubagentDepth", () => {
+  it("returns 0 for non-subagent session keys", () => {
+    expect(getSubagentDepth("agent:main:main")).toBe(0);
+    expect(getSubagentDepth("main")).toBe(0);
+    expect(getSubagentDepth(undefined)).toBe(0);
+  });
+
+  it("returns 2 for nested subagent session keys", () => {
+    expect(getSubagentDepth("agent:main:subagent:parent:subagent:child")).toBe(2);
+  });
+});
+
+describe("isCronSessionKey", () => {
+  it("matches base and run cron agent session keys", () => {
+    expect(isCronSessionKey("agent:main:cron:job-1")).toBe(true);
+    expect(isCronSessionKey("agent:main:cron:job-1:run:run-1")).toBe(true);
+  });
+
+  it("does not match non-cron sessions", () => {
+    expect(isCronSessionKey("agent:main:main")).toBe(false);
+    expect(isCronSessionKey("agent:main:subagent:worker")).toBe(false);
+    expect(isCronSessionKey("cron:job-1")).toBe(false);
+    expect(isCronSessionKey(undefined)).toBe(false);
+  });
+});
diff --git a/src/security/audit-channel.ts b/src/security/audit-channel.ts
index ee55f7b23a2..d8622126266 100644
--- a/src/security/audit-channel.ts
+++ b/src/security/audit-channel.ts
@@ -3,6 +3,10 @@ import type { ChannelId } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 import type { SecurityAuditFinding, SecurityAuditSeverity } from "./audit.js";
 import { resolveChannelDefaultAccountId } from "../channels/plugins/helpers.js";
+import {
+  isNumericTelegramUserId,
+  normalizeTelegramAllowFromEntry,
+} from "../channels/telegram/allow-from.js";
 import { formatCliCommand } from "../cli/command-format.js";
 import { resolveNativeCommandsEnabled, resolveNativeSkillsEnabled } from "../config/commands.js";
 import { readChannelAllowFromStore } from "../pairing/pairing-store.js";
@@ -14,18 +18,6 @@ function normalizeAllowFromList(list: Array<string | number> | undefined | null)
   return list.map((v) => String(v).trim()).filter(Boolean);
 }
 
-function normalizeTelegramAllowFromEntry(raw: unknown): string {
-  const base = typeof raw === "string" ? raw : typeof raw === "number" ? String(raw) : "";
-  return base
-    .trim()
-    .replace(/^(telegram|tg):/i, "")
-    .trim();
-}
-
-function isNumericTelegramUserId(raw: string): boolean {
-  return /^\d+$/.test(raw);
-}
-
 function classifyChannelWarningSeverity(message: string): SecurityAuditSeverity {
   const s = message.toLowerCase();
   if (
diff --git a/src/security/audit-extra.sync.test.ts b/src/security/audit-extra.sync.test.ts
index 88d374f2f38..3961abe46cb 100644
--- a/src/security/audit-extra.sync.test.ts
+++ b/src/security/audit-extra.sync.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectAttackSurfaceSummaryFindings } from "./audit-extra.sync.js";
+import { safeEqualSecret } from "./secret-equal.js";
 
 describe("collectAttackSurfaceSummaryFindings", () => {
   it("distinguishes external webhooks from internal hooks when only internal hooks are enabled", () => {
@@ -32,3 +33,23 @@ describe("collectAttackSurfaceSummaryFindings", () => {
     expect(finding.detail).toContain("hooks.internal: disabled");
   });
 });
+
+describe("safeEqualSecret", () => {
+  it("matches identical secrets", () => {
+    expect(safeEqualSecret("secret-token", "secret-token")).toBe(true);
+  });
+
+  it("rejects mismatched secrets", () => {
+    expect(safeEqualSecret("secret-token", "secret-tokEn")).toBe(false);
+  });
+
+  it("rejects different-length secrets", () => {
+    expect(safeEqualSecret("short", "much-longer")).toBe(false);
+  });
+
+  it("rejects missing values", () => {
+    expect(safeEqualSecret(undefined, "secret")).toBe(false);
+    expect(safeEqualSecret("secret", undefined)).toBe(false);
+    expect(safeEqualSecret(null, "secret")).toBe(false);
+  });
+});
diff --git a/src/security/audit-extra.sync.ts b/src/security/audit-extra.sync.ts
index 1ccc45d99c5..411920a9b99 100644
--- a/src/security/audit-extra.sync.ts
+++ b/src/security/audit-extra.sync.ts
@@ -11,6 +11,7 @@ import {
   resolveSandboxConfigForAgent,
   resolveSandboxToolPolicyForAgent,
 } from "../agents/sandbox.js";
+import { getBlockedBindReason } from "../agents/sandbox/validate-sandbox-security.js";
 import { resolveToolProfilePolicy } from "../agents/tool-policy.js";
 import { resolveBrowserConfig } from "../browser/config.js";
 import { formatCliCommand } from "../cli/command-format.js";
@@ -584,6 +585,104 @@ export function collectSandboxDockerNoopFindings(cfg: OpenClawConfig): SecurityA
   return findings;
 }
 
+export function collectSandboxDangerousConfigFindings(cfg: OpenClawConfig): SecurityAuditFinding[] {
+  const findings: SecurityAuditFinding[] = [];
+  const agents = Array.isArray(cfg.agents?.list) ? cfg.agents.list : [];
+
+  const configs: Array<{ source: string; docker: Record<string, unknown> }> = [];
+  const defaultDocker = cfg.agents?.defaults?.sandbox?.docker;
+  if (defaultDocker && typeof defaultDocker === "object") {
+    configs.push({
+      source: "agents.defaults.sandbox.docker",
+      docker: defaultDocker as Record<string, unknown>,
+    });
+  }
+  for (const entry of agents) {
+    if (!entry || typeof entry !== "object" || typeof entry.id !== "string") {
+      continue;
+    }
+    const agentDocker = entry.sandbox?.docker;
+    if (agentDocker && typeof agentDocker === "object") {
+      configs.push({
+        source: `agents.list.${entry.id}.sandbox.docker`,
+        docker: agentDocker as Record<string, unknown>,
+      });
+    }
+  }
+
+  for (const { source, docker } of configs) {
+    const binds = Array.isArray(docker.binds) ? docker.binds : [];
+    for (const bind of binds) {
+      if (typeof bind !== "string") {
+        continue;
+      }
+      const blocked = getBlockedBindReason(bind);
+      if (!blocked) {
+        continue;
+      }
+      if (blocked.kind === "non_absolute") {
+        findings.push({
+          checkId: "sandbox.bind_mount_non_absolute",
+          severity: "warn",
+          title: "Sandbox bind mount uses a non-absolute source path",
+          detail:
+            `${source}.binds contains "${bind}" which uses source path "${blocked.sourcePath}". ` +
+            "Non-absolute bind sources are hard to validate safely and may resolve unexpectedly.",
+          remediation: `Rewrite "${bind}" to use an absolute host path (for example: /home/user/project:/project:ro).`,
+        });
+        continue;
+      }
+      const verb = blocked.kind === "covers" ? "covers" : "targets";
+      findings.push({
+        checkId: "sandbox.dangerous_bind_mount",
+        severity: "critical",
+        title: "Dangerous bind mount in sandbox config",
+        detail:
+          `${source}.binds contains "${bind}" which ${verb} blocked path "${blocked.blockedPath}". ` +
+          "This can expose host system directories or the Docker socket to sandbox containers.",
+        remediation: `Remove "${bind}" from ${source}.binds. Use project-specific paths instead.`,
+      });
+    }
+
+    const network = typeof docker.network === "string" ? docker.network : undefined;
+    if (network && network.trim().toLowerCase() === "host") {
+      findings.push({
+        checkId: "sandbox.dangerous_network_mode",
+        severity: "critical",
+        title: "Network host mode in sandbox config",
+        detail: `${source}.network is "host" which bypasses container network isolation entirely.`,
+        remediation: `Set ${source}.network to "bridge" or "none".`,
+      });
+    }
+
+    const seccompProfile =
+      typeof docker.seccompProfile === "string" ? docker.seccompProfile : undefined;
+    if (seccompProfile && seccompProfile.trim().toLowerCase() === "unconfined") {
+      findings.push({
+        checkId: "sandbox.dangerous_seccomp_profile",
+        severity: "critical",
+        title: "Seccomp unconfined in sandbox config",
+        detail: `${source}.seccompProfile is "unconfined" which disables syscall filtering.`,
+        remediation: `Remove ${source}.seccompProfile or use a custom seccomp profile file.`,
+      });
+    }
+
+    const apparmorProfile =
+      typeof docker.apparmorProfile === "string" ? docker.apparmorProfile : undefined;
+    if (apparmorProfile && apparmorProfile.trim().toLowerCase() === "unconfined") {
+      findings.push({
+        checkId: "sandbox.dangerous_apparmor_profile",
+        severity: "critical",
+        title: "AppArmor unconfined in sandbox config",
+        detail: `${source}.apparmorProfile is "unconfined" which disables AppArmor enforcement.`,
+        remediation: `Remove ${source}.apparmorProfile or use a named AppArmor profile.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
 export function collectNodeDenyCommandPatternFindings(cfg: OpenClawConfig): SecurityAuditFinding[] {
   const findings: SecurityAuditFinding[] = [];
   const denyListRaw = cfg.gateway?.nodes?.denyCommands;
diff --git a/src/security/audit-extra.ts b/src/security/audit-extra.ts
index 1b507d6ae99..abd9efa0979 100644
--- a/src/security/audit-extra.ts
+++ b/src/security/audit-extra.ts
@@ -16,6 +16,7 @@ export {
   collectMinimalProfileOverrideFindings,
   collectModelHygieneFindings,
   collectNodeDenyCommandPatternFindings,
+  collectSandboxDangerousConfigFindings,
   collectSandboxDockerNoopFindings,
   collectSecretsInConfigFindings,
   collectSmallModelRiskFindings,
diff --git a/src/security/audit.test.ts b/src/security/audit.test.ts
index caad90b1ef7..09a82a31658 100644
--- a/src/security/audit.test.ts
+++ b/src/security/audit.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectPluginsCodeSafetyFindings } from "./audit-extra.js";
@@ -73,6 +73,26 @@ function successfulProbeResult(url: string) {
 }
 
 describe("security audit", () => {
+  let fixtureRoot = "";
+  let caseId = 0;
+
+  const makeTmpDir = async (label: string) => {
+    const dir = path.join(fixtureRoot, `case-${caseId++}-${label}`);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+  };
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-"));
+  });
+
+  afterAll(async () => {
+    if (!fixtureRoot) {
+      return;
+    }
+    await fs.rm(fixtureRoot, { recursive: true, force: true }).catch(() => undefined);
+  });
+
   it("includes an attack surface summary (info)", async () => {
     const cfg: OpenClawConfig = {
       channels: { whatsapp: { groupPolicy: "open" }, telegram: { groupPolicy: "allowlist" } },
@@ -290,7 +310,7 @@ describe("security audit", () => {
   });
 
   it("treats Windows ACL-only perms as secure", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-win-"));
+    const tmp = await makeTmpDir("win");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(stateDir, { recursive: true });
     const configPath = path.join(stateDir, "openclaw.json");
@@ -327,7 +347,7 @@ describe("security audit", () => {
   });
 
   it("flags Windows ACLs when Users can read the state dir", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-win-open-"));
+    const tmp = await makeTmpDir("win-open");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(stateDir, { recursive: true });
     const configPath = path.join(stateDir, "openclaw.json");
@@ -466,6 +486,48 @@ describe("security audit", () => {
     expect(res.findings.some((f) => f.checkId === "sandbox.docker_config_mode_off")).toBe(false);
   });
 
+  it("flags dangerous sandbox docker config (binds/network/seccomp/apparmor)", async () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        defaults: {
+          sandbox: {
+            mode: "all",
+            docker: {
+              binds: ["/etc/passwd:/mnt/passwd:ro", "/run:/run"],
+              network: "host",
+              seccompProfile: "unconfined",
+              apparmorProfile: "unconfined",
+            },
+          },
+        },
+      },
+    };
+
+    const res = await runSecurityAudit({
+      config: cfg,
+      includeFilesystem: false,
+      includeChannelSecurity: false,
+    });
+
+    expect(res.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ checkId: "sandbox.dangerous_bind_mount", severity: "critical" }),
+        expect.objectContaining({
+          checkId: "sandbox.dangerous_network_mode",
+          severity: "critical",
+        }),
+        expect.objectContaining({
+          checkId: "sandbox.dangerous_seccomp_profile",
+          severity: "critical",
+        }),
+        expect.objectContaining({
+          checkId: "sandbox.dangerous_apparmor_profile",
+          severity: "critical",
+        }),
+      ]),
+    );
+  });
+
   it("flags ineffective gateway.nodes.denyCommands entries", async () => {
     const cfg: OpenClawConfig = {
       gateway: {
@@ -831,7 +893,7 @@ describe("security audit", () => {
 
   it("flags Discord native commands without a guild user allowlist", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-discord-"));
+    const tmp = await makeTmpDir("discord");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -878,9 +940,7 @@ describe("security audit", () => {
 
   it("does not flag Discord slash commands when dm.allowFrom includes a Discord snowflake id", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(
-      path.join(os.tmpdir(), "openclaw-security-audit-discord-allowfrom-snowflake-"),
-    );
+    const tmp = await makeTmpDir("discord-allowfrom-snowflake");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -927,7 +987,7 @@ describe("security audit", () => {
 
   it("flags Discord slash commands when access-group enforcement is disabled and no users allowlist exists", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-discord-open-"));
+    const tmp = await makeTmpDir("discord-open");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -975,7 +1035,7 @@ describe("security audit", () => {
 
   it("flags Slack slash commands without a channel users allowlist", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-slack-"));
+    const tmp = await makeTmpDir("slack");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -1017,7 +1077,7 @@ describe("security audit", () => {
 
   it("flags Slack slash commands when access-group enforcement is disabled", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-slack-open-"));
+    const tmp = await makeTmpDir("slack-open");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -1060,7 +1120,7 @@ describe("security audit", () => {
 
   it("flags Telegram group commands without a sender allowlist", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-telegram-"));
+    const tmp = await makeTmpDir("telegram");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -1101,9 +1161,7 @@ describe("security audit", () => {
 
   it("warns when Telegram allowFrom entries are non-numeric (legacy @username configs)", async () => {
     const prevStateDir = process.env.OPENCLAW_STATE_DIR;
-    const tmp = await fs.mkdtemp(
-      path.join(os.tmpdir(), "openclaw-security-audit-telegram-invalid-allowfrom-"),
-    );
+    const tmp = await makeTmpDir("telegram-invalid-allowfrom");
     process.env.OPENCLAW_STATE_DIR = tmp;
     await fs.mkdir(path.join(tmp, "credentials"), { recursive: true, mode: 0o700 });
     try {
@@ -1413,7 +1471,7 @@ describe("security audit", () => {
   });
 
   it("flags group/world-readable config include files", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-"));
+    const tmp = await makeTmpDir("include-perms");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(stateDir, { recursive: true, mode: 0o700 });
 
@@ -1486,7 +1544,7 @@ describe("security audit", () => {
     delete process.env.TELEGRAM_BOT_TOKEN;
     delete process.env.SLACK_BOT_TOKEN;
     delete process.env.SLACK_APP_TOKEN;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-"));
+    const tmp = await makeTmpDir("extensions-no-allowlist");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(path.join(stateDir, "extensions", "some-plugin"), {
       recursive: true,
@@ -1533,71 +1591,63 @@ describe("security audit", () => {
   });
 
   it("flags enabled extensions when tool policy can expose plugin tools", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-plugins-"));
+    const tmp = await makeTmpDir("plugins-reachable");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(path.join(stateDir, "extensions", "some-plugin"), {
       recursive: true,
       mode: 0o700,
     });
 
-    try {
-      const cfg: OpenClawConfig = {
-        plugins: { allow: ["some-plugin"] },
-      };
-      const res = await runSecurityAudit({
-        config: cfg,
-        includeFilesystem: true,
-        includeChannelSecurity: false,
-        stateDir,
-        configPath: path.join(stateDir, "openclaw.json"),
-      });
+    const cfg: OpenClawConfig = {
+      plugins: { allow: ["some-plugin"] },
+    };
+    const res = await runSecurityAudit({
+      config: cfg,
+      includeFilesystem: true,
+      includeChannelSecurity: false,
+      stateDir,
+      configPath: path.join(stateDir, "openclaw.json"),
+    });
 
-      expect(res.findings).toEqual(
-        expect.arrayContaining([
-          expect.objectContaining({
-            checkId: "plugins.tools_reachable_permissive_policy",
-            severity: "warn",
-          }),
-        ]),
-      );
-    } finally {
-      await fs.rm(tmp, { recursive: true, force: true });
-    }
+    expect(res.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          checkId: "plugins.tools_reachable_permissive_policy",
+          severity: "warn",
+        }),
+      ]),
+    );
   });
 
   it("does not flag plugin tool reachability when profile is restrictive", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-plugins-"));
+    const tmp = await makeTmpDir("plugins-restrictive");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(path.join(stateDir, "extensions", "some-plugin"), {
       recursive: true,
       mode: 0o700,
     });
 
-    try {
-      const cfg: OpenClawConfig = {
-        plugins: { allow: ["some-plugin"] },
-        tools: { profile: "coding" },
-      };
-      const res = await runSecurityAudit({
-        config: cfg,
-        includeFilesystem: true,
-        includeChannelSecurity: false,
-        stateDir,
-        configPath: path.join(stateDir, "openclaw.json"),
-      });
+    const cfg: OpenClawConfig = {
+      plugins: { allow: ["some-plugin"] },
+      tools: { profile: "coding" },
+    };
+    const res = await runSecurityAudit({
+      config: cfg,
+      includeFilesystem: true,
+      includeChannelSecurity: false,
+      stateDir,
+      configPath: path.join(stateDir, "openclaw.json"),
+    });
 
-      expect(
-        res.findings.some((f) => f.checkId === "plugins.tools_reachable_permissive_policy"),
-      ).toBe(false);
-    } finally {
-      await fs.rm(tmp, { recursive: true, force: true });
-    }
+    expect(
+      res.findings.some((f) => f.checkId === "plugins.tools_reachable_permissive_policy"),
+    ).toBe(false);
   });
 
   it("flags unallowlisted extensions as critical when native skill commands are exposed", async () => {
     const prevDiscordToken = process.env.DISCORD_BOT_TOKEN;
     delete process.env.DISCORD_BOT_TOKEN;
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-audit-"));
+    const tmp = await makeTmpDir("extensions-critical");
     const stateDir = path.join(tmp, "state");
     await fs.mkdir(path.join(stateDir, "extensions", "some-plugin"), {
       recursive: true,
@@ -1636,7 +1686,7 @@ describe("security audit", () => {
   });
 
   it("flags plugins with dangerous code patterns (deep audit)", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-scanner-"));
+    const tmpDir = await makeTmpDir("audit-scanner-plugin");
     const pluginDir = path.join(tmpDir, "extensions", "evil-plugin");
     await fs.mkdir(path.join(pluginDir, ".hidden"), { recursive: true });
     await fs.writeFile(
@@ -1675,12 +1725,10 @@ describe("security audit", () => {
         (f) => f.checkId === "plugins.code_safety" && f.severity === "critical",
       ),
     ).toBe(true);
-
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
   });
 
   it("reports detailed code-safety issues for both plugins and skills", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-scanner-"));
+    const tmpDir = await makeTmpDir("audit-scanner-plugin-skill");
     const workspaceDir = path.join(tmpDir, "workspace");
     const pluginDir = path.join(tmpDir, "extensions", "evil-plugin");
     const skillDir = path.join(workspaceDir, "skills", "evil-skill");
@@ -1738,12 +1786,10 @@ description: test skill
     expect(skillFinding).toBeDefined();
     expect(skillFinding?.detail).toContain("dangerous-exec");
     expect(skillFinding?.detail).toMatch(/runner\.js:\d+/);
-
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
   });
 
   it("flags plugin extension entry path traversal in deep audit", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-scanner-"));
+    const tmpDir = await makeTmpDir("audit-scanner-escape");
     const pluginDir = path.join(tmpDir, "extensions", "escape-plugin");
     await fs.mkdir(pluginDir, { recursive: true });
     await fs.writeFile(
@@ -1755,18 +1801,8 @@ description: test skill
     );
     await fs.writeFile(path.join(pluginDir, "index.js"), "export {};");
 
-    const res = await runSecurityAudit({
-      config: {},
-      includeFilesystem: true,
-      includeChannelSecurity: false,
-      deep: true,
-      stateDir: tmpDir,
-      probeGatewayFn: async (opts) => successfulProbeResult(opts.url),
-    });
-
-    expect(res.findings.some((f) => f.checkId === "plugins.code_safety.entry_escape")).toBe(true);
-
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
+    const findings = await collectPluginsCodeSafetyFindings({ stateDir: tmpDir });
+    expect(findings.some((f) => f.checkId === "plugins.code_safety.entry_escape")).toBe(true);
   });
 
   it("reports scan_failed when plugin code scanner throws during deep audit", async () => {
@@ -1774,7 +1810,7 @@ description: test skill
       .spyOn(skillScanner, "scanDirectoryWithSummary")
       .mockRejectedValueOnce(new Error("boom"));
 
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-scanner-"));
+    const tmpDir = await makeTmpDir("audit-scanner-throws");
     try {
       const pluginDir = path.join(tmpDir, "extensions", "scanfail-plugin");
       await fs.mkdir(pluginDir, { recursive: true });
@@ -1791,7 +1827,6 @@ description: test skill
       expect(findings.some((f) => f.checkId === "plugins.code_safety.scan_failed")).toBe(true);
     } finally {
       scanSpy.mockRestore();
-      await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
     }
   });
 
diff --git a/src/security/audit.ts b/src/security/audit.ts
index 4487f53a9cb..7f08620ffe8 100644
--- a/src/security/audit.ts
+++ b/src/security/audit.ts
@@ -21,6 +21,7 @@ import {
   collectModelHygieneFindings,
   collectNodeDenyCommandPatternFindings,
   collectSmallModelRiskFindings,
+  collectSandboxDangerousConfigFindings,
   collectSandboxDockerNoopFindings,
   collectPluginsTrustFindings,
   collectSecretsInConfigFindings,
@@ -621,6 +622,7 @@ export async function runSecurityAudit(opts: SecurityAuditOptions): Promise<Secu
   findings.push(...collectHooksHardeningFindings(cfg, env));
   findings.push(...collectGatewayHttpSessionKeyOverrideFindings(cfg));
   findings.push(...collectSandboxDockerNoopFindings(cfg));
+  findings.push(...collectSandboxDangerousConfigFindings(cfg));
   findings.push(...collectNodeDenyCommandPatternFindings(cfg));
   findings.push(...collectMinimalProfileOverrideFindings(cfg));
   findings.push(...collectSecretsInConfigFindings(cfg));
diff --git a/src/security/fix.test.ts b/src/security/fix.test.ts
index 4347f993805..d9f691b47b3 100644
--- a/src/security/fix.test.ts
+++ b/src/security/fix.test.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixSecurityFootguns } from "./fix.js";
 
 const isWindows = process.platform === "win32";
@@ -15,10 +15,27 @@ const expectPerms = (actual: number, expected: number) => {
 };
 
 describe("security fix", () => {
+  let fixtureRoot = "";
+  let fixtureCount = 0;
+
+  const createStateDir = async (prefix: string) => {
+    const dir = path.join(fixtureRoot, `${prefix}-${fixtureCount++}`);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+  };
+
+  beforeAll(async () => {
+    fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-suite-"));
+  });
+
+  afterAll(async () => {
+    if (fixtureRoot) {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
   it("tightens groupPolicy + filesystem perms", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-"));
-    const stateDir = path.join(tmp, "state");
-    await fs.mkdir(stateDir, { recursive: true });
+    const stateDir = await createStateDir("tightens");
     await fs.chmod(stateDir, 0o755);
 
     const configPath = path.join(stateDir, "openclaw.json");
@@ -53,10 +70,10 @@ describe("security fix", () => {
     const env = {
       ...process.env,
       OPENCLAW_STATE_DIR: stateDir,
-      OPENCLAW_CONFIG_PATH: "",
+      OPENCLAW_CONFIG_PATH: configPath,
     };
 
-    const res = await fixSecurityFootguns({ env });
+    const res = await fixSecurityFootguns({ env, stateDir, configPath });
     expect(res.ok).toBe(true);
     expect(res.configWritten).toBe(true);
     expect(res.changes).toEqual(
@@ -88,9 +105,7 @@ describe("security fix", () => {
   });
 
   it("applies allowlist per-account and seeds WhatsApp groupAllowFrom from store", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-"));
-    const stateDir = path.join(tmp, "state");
-    await fs.mkdir(stateDir, { recursive: true });
+    const stateDir = await createStateDir("per-account");
 
     const configPath = path.join(stateDir, "openclaw.json");
     await fs.writeFile(
@@ -122,10 +137,10 @@ describe("security fix", () => {
     const env = {
       ...process.env,
       OPENCLAW_STATE_DIR: stateDir,
-      OPENCLAW_CONFIG_PATH: "",
+      OPENCLAW_CONFIG_PATH: configPath,
     };
 
-    const res = await fixSecurityFootguns({ env });
+    const res = await fixSecurityFootguns({ env, stateDir, configPath });
     expect(res.ok).toBe(true);
 
     const parsed = JSON.parse(await fs.readFile(configPath, "utf-8")) as Record<string, unknown>;
@@ -138,9 +153,7 @@ describe("security fix", () => {
   });
 
   it("does not seed WhatsApp groupAllowFrom if allowFrom is set", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-"));
-    const stateDir = path.join(tmp, "state");
-    await fs.mkdir(stateDir, { recursive: true });
+    const stateDir = await createStateDir("no-seed");
 
     const configPath = path.join(stateDir, "openclaw.json");
     await fs.writeFile(
@@ -168,10 +181,10 @@ describe("security fix", () => {
     const env = {
       ...process.env,
       OPENCLAW_STATE_DIR: stateDir,
-      OPENCLAW_CONFIG_PATH: "",
+      OPENCLAW_CONFIG_PATH: configPath,
     };
 
-    const res = await fixSecurityFootguns({ env });
+    const res = await fixSecurityFootguns({ env, stateDir, configPath });
     expect(res.ok).toBe(true);
 
     const parsed = JSON.parse(await fs.readFile(configPath, "utf-8")) as Record<string, unknown>;
@@ -181,9 +194,7 @@ describe("security fix", () => {
   });
 
   it("returns ok=false for invalid config but still tightens perms", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-"));
-    const stateDir = path.join(tmp, "state");
-    await fs.mkdir(stateDir, { recursive: true });
+    const stateDir = await createStateDir("invalid-config");
     await fs.chmod(stateDir, 0o755);
 
     const configPath = path.join(stateDir, "openclaw.json");
@@ -193,10 +204,10 @@ describe("security fix", () => {
     const env = {
       ...process.env,
       OPENCLAW_STATE_DIR: stateDir,
-      OPENCLAW_CONFIG_PATH: "",
+      OPENCLAW_CONFIG_PATH: configPath,
     };
 
-    const res = await fixSecurityFootguns({ env });
+    const res = await fixSecurityFootguns({ env, stateDir, configPath });
     expect(res.ok).toBe(false);
 
     const stateMode = (await fs.stat(stateDir)).mode & 0o777;
@@ -207,9 +218,7 @@ describe("security fix", () => {
   });
 
   it("tightens perms for credentials + agent auth/sessions + include files", async () => {
-    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-security-fix-"));
-    const stateDir = path.join(tmp, "state");
-    await fs.mkdir(stateDir, { recursive: true });
+    const stateDir = await createStateDir("includes");
 
     const includesDir = path.join(stateDir, "includes");
     await fs.mkdir(includesDir, { recursive: true });
@@ -250,10 +259,10 @@ describe("security fix", () => {
     const env = {
       ...process.env,
       OPENCLAW_STATE_DIR: stateDir,
-      OPENCLAW_CONFIG_PATH: "",
+      OPENCLAW_CONFIG_PATH: configPath,
     };
 
-    const res = await fixSecurityFootguns({ env });
+    const res = await fixSecurityFootguns({ env, stateDir, configPath });
     expect(res.ok).toBe(true);
 
     expectPerms((await fs.stat(credsDir)).mode & 0o777, 0o700);
diff --git a/src/security/secret-equal.test.ts b/src/security/secret-equal.test.ts
deleted file mode 100644
index e6c30e354ca..00000000000
--- a/src/security/secret-equal.test.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { safeEqualSecret } from "./secret-equal.js";
-
-describe("safeEqualSecret", () => {
-  it("matches identical secrets", () => {
-    expect(safeEqualSecret("secret-token", "secret-token")).toBe(true);
-  });
-
-  it("rejects mismatched secrets", () => {
-    expect(safeEqualSecret("secret-token", "secret-tokEn")).toBe(false);
-  });
-
-  it("rejects different-length secrets", () => {
-    expect(safeEqualSecret("short", "much-longer")).toBe(false);
-  });
-
-  it("rejects missing values", () => {
-    expect(safeEqualSecret(undefined, "secret")).toBe(false);
-    expect(safeEqualSecret("secret", undefined)).toBe(false);
-    expect(safeEqualSecret(null, "secret")).toBe(false);
-  });
-});
diff --git a/src/sessions/session-key-utils.test.ts b/src/sessions/session-key-utils.test.ts
deleted file mode 100644
index 3d9ce208649..00000000000
--- a/src/sessions/session-key-utils.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { getSubagentDepth, isCronSessionKey } from "./session-key-utils.js";
-
-describe("getSubagentDepth", () => {
-  it("returns 0 for non-subagent session keys", () => {
-    expect(getSubagentDepth("agent:main:main")).toBe(0);
-    expect(getSubagentDepth("main")).toBe(0);
-    expect(getSubagentDepth(undefined)).toBe(0);
-  });
-
-  it("returns 1 for depth-1 subagent session keys", () => {
-    expect(getSubagentDepth("agent:main:subagent:123")).toBe(1);
-  });
-
-  it("returns 2 for nested subagent session keys", () => {
-    expect(getSubagentDepth("agent:main:subagent:parent:subagent:child")).toBe(2);
-  });
-});
-
-describe("isCronSessionKey", () => {
-  it("matches base and run cron agent session keys", () => {
-    expect(isCronSessionKey("agent:main:cron:job-1")).toBe(true);
-    expect(isCronSessionKey("agent:main:cron:job-1:run:run-1")).toBe(true);
-  });
-
-  it("does not match non-cron sessions", () => {
-    expect(isCronSessionKey("agent:main:main")).toBe(false);
-    expect(isCronSessionKey("agent:main:subagent:worker")).toBe(false);
-    expect(isCronSessionKey("cron:job-1")).toBe(false);
-    expect(isCronSessionKey(undefined)).toBe(false);
-  });
-});
diff --git a/src/shared/chat-content.ts b/src/shared/chat-content.ts
new file mode 100644
index 00000000000..5f8541d9c68
--- /dev/null
+++ b/src/shared/chat-content.ts
@@ -0,0 +1,37 @@
+export function extractTextFromChatContent(
+  content: unknown,
+  opts?: { sanitizeText?: (text: string) => string },
+): string | null {
+  const normalize = (text: string) => text.replace(/\s+/g, " ").trim();
+
+  if (typeof content === "string") {
+    const value = opts?.sanitizeText ? opts.sanitizeText(content) : content;
+    const normalized = normalize(value);
+    return normalized ? normalized : null;
+  }
+
+  if (!Array.isArray(content)) {
+    return null;
+  }
+
+  const chunks: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") {
+      continue;
+    }
+    if ((block as { type?: unknown }).type !== "text") {
+      continue;
+    }
+    const text = (block as { text?: unknown }).text;
+    if (typeof text !== "string") {
+      continue;
+    }
+    const value = opts?.sanitizeText ? opts.sanitizeText(text) : text;
+    if (value.trim()) {
+      chunks.push(value);
+    }
+  }
+
+  const joined = normalize(chunks.join(" "));
+  return joined ? joined : null;
+}
diff --git a/src/shared/entry-status.ts b/src/shared/entry-status.ts
new file mode 100644
index 00000000000..0ac4ea29116
--- /dev/null
+++ b/src/shared/entry-status.ts
@@ -0,0 +1,56 @@
+import { resolveEmojiAndHomepage } from "./entry-metadata.js";
+import {
+  evaluateRequirementsFromMetadataWithRemote,
+  type RequirementConfigCheck,
+  type Requirements,
+  type RequirementsMetadata,
+} from "./requirements.js";
+
+export function evaluateEntryMetadataRequirements(params: {
+  always: boolean;
+  metadata?: (RequirementsMetadata & { emoji?: string; homepage?: string }) | null;
+  frontmatter?: {
+    emoji?: string;
+    homepage?: string;
+    website?: string;
+    url?: string;
+  } | null;
+  hasLocalBin: (bin: string) => boolean;
+  localPlatform: string;
+  remote?: {
+    hasBin?: (bin: string) => boolean;
+    hasAnyBin?: (bins: string[]) => boolean;
+    platforms?: string[];
+  };
+  isEnvSatisfied: (envName: string) => boolean;
+  isConfigSatisfied: (pathStr: string) => boolean;
+}): {
+  emoji?: string;
+  homepage?: string;
+  required: Requirements;
+  missing: Requirements;
+  requirementsSatisfied: boolean;
+  configChecks: RequirementConfigCheck[];
+} {
+  const { emoji, homepage } = resolveEmojiAndHomepage({
+    metadata: params.metadata,
+    frontmatter: params.frontmatter,
+  });
+  const { required, missing, eligible, configChecks } = evaluateRequirementsFromMetadataWithRemote({
+    always: params.always,
+    metadata: params.metadata ?? undefined,
+    hasLocalBin: params.hasLocalBin,
+    localPlatform: params.localPlatform,
+    remote: params.remote,
+    isEnvSatisfied: params.isEnvSatisfied,
+    isConfigSatisfied: params.isConfigSatisfied,
+  });
+  return {
+    ...(emoji ? { emoji } : {}),
+    ...(homepage ? { homepage } : {}),
+    required,
+    missing,
+    requirementsSatisfied: eligible,
+    configChecks,
+  };
+}
diff --git a/src/shared/frontmatter.test.ts b/src/shared/frontmatter.test.ts
deleted file mode 100644
index 78265a58574..00000000000
--- a/src/shared/frontmatter.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, test } from "vitest";
-import {
-  getFrontmatterString,
-  normalizeStringList,
-  parseFrontmatterBool,
-  resolveOpenClawManifestBlock,
-} from "./frontmatter.js";
-
-describe("shared/frontmatter", () => {
-  test("normalizeStringList handles strings and arrays", () => {
-    expect(normalizeStringList("a, b,,c")).toEqual(["a", "b", "c"]);
-    expect(normalizeStringList([" a ", "", "b"])).toEqual(["a", "b"]);
-    expect(normalizeStringList(null)).toEqual([]);
-  });
-
-  test("getFrontmatterString extracts strings only", () => {
-    expect(getFrontmatterString({ a: "b" }, "a")).toBe("b");
-    expect(getFrontmatterString({ a: 1 }, "a")).toBeUndefined();
-  });
-
-  test("parseFrontmatterBool respects fallback", () => {
-    expect(parseFrontmatterBool("true", false)).toBe(true);
-    expect(parseFrontmatterBool("false", true)).toBe(false);
-    expect(parseFrontmatterBool(undefined, true)).toBe(true);
-  });
-
-  test("resolveOpenClawManifestBlock parses JSON5 metadata and picks openclaw block", () => {
-    const frontmatter = {
-      metadata: "{ openclaw: { foo: 1, bar: 'baz' } }",
-    };
-    expect(resolveOpenClawManifestBlock({ frontmatter })).toEqual({ foo: 1, bar: "baz" });
-  });
-
-  test("resolveOpenClawManifestBlock returns undefined for invalid input", () => {
-    expect(resolveOpenClawManifestBlock({ frontmatter: {} })).toBeUndefined();
-    expect(
-      resolveOpenClawManifestBlock({ frontmatter: { metadata: "not-json5" } }),
-    ).toBeUndefined();
-    expect(
-      resolveOpenClawManifestBlock({ frontmatter: { metadata: "{ nope: { a: 1 } }" } }),
-    ).toBeUndefined();
-  });
-});
diff --git a/src/shared/frontmatter.ts b/src/shared/frontmatter.ts
index 8611744d9b1..2db4fb95117 100644
--- a/src/shared/frontmatter.ts
+++ b/src/shared/frontmatter.ts
@@ -58,3 +58,42 @@ export function resolveOpenClawManifestBlock(params: {
     return undefined;
   }
 }
+
+export type OpenClawManifestRequires = {
+  bins: string[];
+  anyBins: string[];
+  env: string[];
+  config: string[];
+};
+
+export function resolveOpenClawManifestRequires(
+  metadataObj: Record<string, unknown>,
+): OpenClawManifestRequires | undefined {
+  const requiresRaw =
+    typeof metadataObj.requires === "object" && metadataObj.requires !== null
+      ? (metadataObj.requires as Record<string, unknown>)
+      : undefined;
+  if (!requiresRaw) {
+    return undefined;
+  }
+  return {
+    bins: normalizeStringList(requiresRaw.bins),
+    anyBins: normalizeStringList(requiresRaw.anyBins),
+    env: normalizeStringList(requiresRaw.env),
+    config: normalizeStringList(requiresRaw.config),
+  };
+}
+
+export function resolveOpenClawManifestInstall<T>(
+  metadataObj: Record<string, unknown>,
+  parseInstallSpec: (input: unknown) => T | undefined,
+): T[] {
+  const installRaw = Array.isArray(metadataObj.install) ? (metadataObj.install as unknown[]) : [];
+  return installRaw
+    .map((entry) => parseInstallSpec(entry))
+    .filter((entry): entry is T => Boolean(entry));
+}
+
+export function resolveOpenClawManifestOs(metadataObj: Record<string, unknown>): string[] {
+  return normalizeStringList(metadataObj.os);
+}
diff --git a/src/shared/node-match.test.ts b/src/shared/node-match.test.ts
deleted file mode 100644
index d8d33f1bacb..00000000000
--- a/src/shared/node-match.test.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveNodeIdFromCandidates } from "./node-match.js";
-
-describe("resolveNodeIdFromCandidates", () => {
-  it("matches nodeId", () => {
-    expect(
-      resolveNodeIdFromCandidates(
-        [
-          { nodeId: "mac-123", displayName: "Mac Studio", remoteIp: "100.0.0.1" },
-          { nodeId: "pi-456", displayName: "Raspberry Pi", remoteIp: "100.0.0.2" },
-        ],
-        "pi-456",
-      ),
-    ).toBe("pi-456");
-  });
-
-  it("matches displayName using normalization", () => {
-    expect(
-      resolveNodeIdFromCandidates([{ nodeId: "mac-123", displayName: "Mac Studio" }], "mac studio"),
-    ).toBe("mac-123");
-  });
-
-  it("matches nodeId prefix (>=6 chars)", () => {
-    expect(resolveNodeIdFromCandidates([{ nodeId: "mac-abcdef" }], "mac-ab")).toBe("mac-abcdef");
-  });
-
-  it("throws unknown node with known list", () => {
-    expect(() =>
-      resolveNodeIdFromCandidates(
-        [
-          { nodeId: "mac-123", displayName: "Mac Studio", remoteIp: "100.0.0.1" },
-          { nodeId: "pi-456" },
-        ],
-        "nope",
-      ),
-    ).toThrow(/unknown node: nope.*known: /);
-  });
-
-  it("throws ambiguous node with matches list", () => {
-    expect(() =>
-      resolveNodeIdFromCandidates([{ nodeId: "mac-abcdef" }, { nodeId: "mac-abc999" }], "mac-abc"),
-    ).toThrow(/ambiguous node: mac-abc.*matches:/);
-  });
-});
diff --git a/src/shared/pid-alive.ts b/src/shared/pid-alive.ts
new file mode 100644
index 00000000000..a1e9c84eac7
--- /dev/null
+++ b/src/shared/pid-alive.ts
@@ -0,0 +1,11 @@
+export function isPidAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/src/shared/shared-misc.test.ts b/src/shared/shared-misc.test.ts
new file mode 100644
index 00000000000..298b3ff0a55
--- /dev/null
+++ b/src/shared/shared-misc.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it, test } from "vitest";
+import { extractTextFromChatContent } from "./chat-content.js";
+import {
+  getFrontmatterString,
+  normalizeStringList,
+  parseFrontmatterBool,
+  resolveOpenClawManifestBlock,
+} from "./frontmatter.js";
+import { resolveNodeIdFromCandidates } from "./node-match.js";
+
+describe("extractTextFromChatContent", () => {
+  it("normalizes string content", () => {
+    expect(extractTextFromChatContent("  hello\nworld  ")).toBe("hello world");
+  });
+
+  it("extracts text blocks from array content", () => {
+    expect(
+      extractTextFromChatContent([
+        { type: "text", text: " hello " },
+        { type: "image_url", image_url: "https://example.com" },
+        { type: "text", text: "world" },
+      ]),
+    ).toBe("hello world");
+  });
+
+  it("applies sanitizer when provided", () => {
+    expect(
+      extractTextFromChatContent("Here [Tool Call: foo (ID: 1)] ok", {
+        sanitizeText: (text) => text.replace(/\[Tool Call:[^\]]+\]\s*/g, ""),
+      }),
+    ).toBe("Here ok");
+  });
+});
+
+describe("shared/frontmatter", () => {
+  test("normalizeStringList handles strings and arrays", () => {
+    expect(normalizeStringList("a, b,,c")).toEqual(["a", "b", "c"]);
+    expect(normalizeStringList([" a ", "", "b"])).toEqual(["a", "b"]);
+    expect(normalizeStringList(null)).toEqual([]);
+  });
+
+  test("getFrontmatterString extracts strings only", () => {
+    expect(getFrontmatterString({ a: "b" }, "a")).toBe("b");
+    expect(getFrontmatterString({ a: 1 }, "a")).toBeUndefined();
+  });
+
+  test("parseFrontmatterBool respects fallback", () => {
+    expect(parseFrontmatterBool("true", false)).toBe(true);
+    expect(parseFrontmatterBool("false", true)).toBe(false);
+    expect(parseFrontmatterBool(undefined, true)).toBe(true);
+  });
+
+  test("resolveOpenClawManifestBlock parses JSON5 metadata and picks openclaw block", () => {
+    const frontmatter = {
+      metadata: "{ openclaw: { foo: 1, bar: 'baz' } }",
+    };
+    expect(resolveOpenClawManifestBlock({ frontmatter })).toEqual({ foo: 1, bar: "baz" });
+  });
+
+  test("resolveOpenClawManifestBlock returns undefined for invalid input", () => {
+    expect(resolveOpenClawManifestBlock({ frontmatter: {} })).toBeUndefined();
+    expect(
+      resolveOpenClawManifestBlock({ frontmatter: { metadata: "not-json5" } }),
+    ).toBeUndefined();
+    expect(
+      resolveOpenClawManifestBlock({ frontmatter: { metadata: "{ nope: { a: 1 } }" } }),
+    ).toBeUndefined();
+  });
+});
+
+describe("resolveNodeIdFromCandidates", () => {
+  it("matches nodeId", () => {
+    expect(
+      resolveNodeIdFromCandidates(
+        [
+          { nodeId: "mac-123", displayName: "Mac Studio", remoteIp: "100.0.0.1" },
+          { nodeId: "pi-456", displayName: "Raspberry Pi", remoteIp: "100.0.0.2" },
+        ],
+        "pi-456",
+      ),
+    ).toBe("pi-456");
+  });
+
+  it("matches displayName using normalization", () => {
+    expect(
+      resolveNodeIdFromCandidates([{ nodeId: "mac-123", displayName: "Mac Studio" }], "mac studio"),
+    ).toBe("mac-123");
+  });
+
+  it("matches nodeId prefix (>=6 chars)", () => {
+    expect(resolveNodeIdFromCandidates([{ nodeId: "mac-abcdef" }], "mac-ab")).toBe("mac-abcdef");
+  });
+
+  it("throws unknown node with known list", () => {
+    expect(() =>
+      resolveNodeIdFromCandidates(
+        [
+          { nodeId: "mac-123", displayName: "Mac Studio", remoteIp: "100.0.0.1" },
+          { nodeId: "pi-456" },
+        ],
+        "nope",
+      ),
+    ).toThrow(/unknown node: nope.*known: /);
+  });
+
+  it("throws ambiguous node with matches list", () => {
+    expect(() =>
+      resolveNodeIdFromCandidates([{ nodeId: "mac-abcdef" }, { nodeId: "mac-abc999" }], "mac-abc"),
+    ).toThrow(/ambiguous node: mac-abc.*matches:/);
+  });
+});
diff --git a/src/signal/daemon.test.ts b/src/signal/daemon.test.ts
deleted file mode 100644
index b83208654bf..00000000000
--- a/src/signal/daemon.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { classifySignalCliLogLine } from "./daemon.js";
-
-describe("classifySignalCliLogLine", () => {
-  it("treats INFO/DEBUG as log (even if emitted on stderr)", () => {
-    expect(classifySignalCliLogLine("INFO  DaemonCommand - Started")).toBe("log");
-    expect(classifySignalCliLogLine("DEBUG Something")).toBe("log");
-  });
-
-  it("treats WARN/ERROR as error", () => {
-    expect(classifySignalCliLogLine("WARN  Something")).toBe("error");
-    expect(classifySignalCliLogLine("WARNING Something")).toBe("error");
-    expect(classifySignalCliLogLine("ERROR Something")).toBe("error");
-  });
-
-  it("treats failures without explicit severity as error", () => {
-    expect(classifySignalCliLogLine("Failed to initialize HTTP Server - oops")).toBe("error");
-    expect(classifySignalCliLogLine('Exception in thread "main"')).toBe("error");
-  });
-
-  it("returns null for empty lines", () => {
-    expect(classifySignalCliLogLine("")).toBe(null);
-    expect(classifySignalCliLogLine("   ")).toBe(null);
-  });
-});
diff --git a/src/signal/monitor/event-handler.mention-gating.test.ts b/src/signal/monitor/event-handler.mention-gating.test.ts
index 6fb211f1ff2..7c45d3cf20a 100644
--- a/src/signal/monitor/event-handler.mention-gating.test.ts
+++ b/src/signal/monitor/event-handler.mention-gating.test.ts
@@ -18,6 +18,7 @@ vi.mock("../../auto-reply/dispatch.js", async (importOriginal) => {
 });
 
 import { createSignalEventHandler } from "./event-handler.js";
+import { renderSignalMentions } from "./mentions.js";
 
 function createBaseDeps(overrides: Record<string, unknown> = {}) {
   return {
@@ -270,3 +271,34 @@ describe("signal mention gating", () => {
     expect(capturedCtx?.WasMentioned).toBe(true);
   });
 });
+
+describe("renderSignalMentions", () => {
+  const PLACEHOLDER = "\uFFFC";
+
+  it("returns the original message when no mentions are provided", () => {
+    const message = `${PLACEHOLDER} ping`;
+    expect(renderSignalMentions(message, null)).toBe(message);
+    expect(renderSignalMentions(message, [])).toBe(message);
+  });
+
+  it("replaces placeholder code points using mention metadata", () => {
+    const message = `${PLACEHOLDER} hi ${PLACEHOLDER}!`;
+    const normalized = renderSignalMentions(message, [
+      { uuid: "abc-123", start: 0, length: 1 },
+      { number: "+15550005555", start: message.lastIndexOf(PLACEHOLDER), length: 1 },
+    ]);
+
+    expect(normalized).toBe("@abc-123 hi @+15550005555!");
+  });
+
+  it("skips mentions that lack identifiers or out-of-bounds spans", () => {
+    const message = `${PLACEHOLDER} hi`;
+    const normalized = renderSignalMentions(message, [
+      { name: "ignored" },
+      { uuid: "valid", start: 0, length: 1 },
+      { number: "+1555", start: 999, length: 1 },
+    ]);
+
+    expect(normalized).toBe("@valid hi");
+  });
+});
diff --git a/src/signal/monitor/mentions.test.ts b/src/signal/monitor/mentions.test.ts
deleted file mode 100644
index 1a30f6d2c33..00000000000
--- a/src/signal/monitor/mentions.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { renderSignalMentions } from "./mentions.js";
-
-const PLACEHOLDER = "\uFFFC";
-
-describe("renderSignalMentions", () => {
-  it("returns the original message when no mentions are provided", () => {
-    const message = `${PLACEHOLDER} ping`;
-    expect(renderSignalMentions(message, null)).toBe(message);
-    expect(renderSignalMentions(message, [])).toBe(message);
-  });
-
-  it("replaces placeholder code points using mention metadata", () => {
-    const message = `${PLACEHOLDER} hi ${PLACEHOLDER}!`;
-    const normalized = renderSignalMentions(message, [
-      { uuid: "abc-123", start: 0, length: 1 },
-      { number: "+15550005555", start: message.lastIndexOf(PLACEHOLDER), length: 1 },
-    ]);
-
-    expect(normalized).toBe("@abc-123 hi @+15550005555!");
-  });
-
-  it("skips mentions that lack identifiers or out-of-bounds spans", () => {
-    const message = `${PLACEHOLDER} hi`;
-    const normalized = renderSignalMentions(message, [
-      { name: "ignored" },
-      { uuid: "valid", start: 0, length: 1 },
-      { number: "+1555", start: 999, length: 1 },
-    ]);
-
-    expect(normalized).toBe("@valid hi");
-  });
-});
diff --git a/src/signal/probe.test.ts b/src/signal/probe.test.ts
index 5b813b8599b..7250c1de744 100644
--- a/src/signal/probe.test.ts
+++ b/src/signal/probe.test.ts
@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { classifySignalCliLogLine } from "./daemon.js";
 import { probeSignal } from "./probe.js";
 
 const signalCheckMock = vi.fn();
@@ -43,3 +44,26 @@ describe("probeSignal", () => {
     expect(res.version).toBe(null);
   });
 });
+
+describe("classifySignalCliLogLine", () => {
+  it("treats INFO/DEBUG as log (even if emitted on stderr)", () => {
+    expect(classifySignalCliLogLine("INFO  DaemonCommand - Started")).toBe("log");
+    expect(classifySignalCliLogLine("DEBUG Something")).toBe("log");
+  });
+
+  it("treats WARN/ERROR as error", () => {
+    expect(classifySignalCliLogLine("WARN  Something")).toBe("error");
+    expect(classifySignalCliLogLine("WARNING Something")).toBe("error");
+    expect(classifySignalCliLogLine("ERROR Something")).toBe("error");
+  });
+
+  it("treats failures without explicit severity as error", () => {
+    expect(classifySignalCliLogLine("Failed to initialize HTTP Server - oops")).toBe("error");
+    expect(classifySignalCliLogLine('Exception in thread "main"')).toBe("error");
+  });
+
+  it("returns null for empty lines", () => {
+    expect(classifySignalCliLogLine("")).toBe(null);
+    expect(classifySignalCliLogLine("   ")).toBe(null);
+  });
+});
diff --git a/src/signal/probe.ts b/src/signal/probe.ts
index 9a6238048ad..924f997015e 100644
--- a/src/signal/probe.ts
+++ b/src/signal/probe.ts
@@ -1,9 +1,8 @@
+import type { BaseProbeResult } from "../channels/plugins/types.js";
 import { signalCheck, signalRpcRequest } from "./client.js";
 
-export type SignalProbe = {
-  ok: boolean;
+export type SignalProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs: number;
   version?: string | null;
 };
diff --git a/src/slack/monitor.tool-result.forces-thread-replies-replytoid-is-set.test.ts b/src/slack/monitor.tool-result.forces-thread-replies-replytoid-is-set.test.ts
deleted file mode 100644
index 4743cd85188..00000000000
--- a/src/slack/monitor.tool-result.forces-thread-replies-replytoid-is-set.test.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { resetInboundDedupe } from "../auto-reply/reply/inbound-dedupe.js";
-import {
-  defaultSlackTestConfig,
-  getSlackClient,
-  getSlackHandlerOrThrow,
-  getSlackTestState,
-  resetSlackTestState,
-  runSlackMessageOnce,
-  startSlackMonitor,
-  stopSlackMonitor,
-} from "./monitor.test-helpers.js";
-
-const { monitorSlackProvider } = await import("./monitor.js");
-
-const slackTestState = getSlackTestState();
-const { sendMock, replyMock, reactMock, upsertPairingRequestMock } = slackTestState;
-
-beforeEach(() => {
-  resetInboundDedupe();
-  resetSlackTestState(defaultSlackTestConfig());
-});
-
-describe("monitorSlackProvider tool results", () => {
-  it("forces thread replies when replyToId is set", async () => {
-    replyMock.mockResolvedValue({ text: "forced reply", replyToId: "555" });
-    slackTestState.config = {
-      messages: {
-        responsePrefix: "PFX",
-        ackReaction: "👀",
-        ackReactionScope: "group-mentions",
-      },
-      channels: {
-        slack: {
-          dmPolicy: "open",
-          allowFrom: ["*"],
-          dm: { enabled: true },
-          replyToMode: "off",
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "789",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "555" });
-  });
-
-  it("reacts to mention-gated room messages when ackReaction is enabled", async () => {
-    replyMock.mockResolvedValue(undefined);
-    const client = getSlackClient();
-    if (!client) {
-      throw new Error("Slack client not registered");
-    }
-    const conversations = client.conversations as {
-      info: ReturnType<typeof vi.fn>;
-    };
-    conversations.info.mockResolvedValueOnce({
-      channel: { name: "general", is_channel: true },
-    });
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "<@bot-user> hello",
-        ts: "456",
-        channel: "C1",
-        channel_type: "channel",
-      },
-    });
-
-    expect(reactMock).toHaveBeenCalledWith({
-      channel: "C1",
-      timestamp: "456",
-      name: "👀",
-    });
-  });
-
-  it("replies with pairing code when dmPolicy is pairing and no allowFrom is set", async () => {
-    slackTestState.config = {
-      ...slackTestState.config,
-      channels: {
-        ...slackTestState.config.channels,
-        slack: {
-          ...slackTestState.config.channels?.slack,
-          dm: { enabled: true, policy: "pairing", allowFrom: [] },
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "123",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(replyMock).not.toHaveBeenCalled();
-    expect(upsertPairingRequestMock).toHaveBeenCalled();
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain("Your Slack user id: U1");
-    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain("Pairing code: PAIRCODE");
-  });
-
-  it("does not resend pairing code when a request is already pending", async () => {
-    slackTestState.config = {
-      ...slackTestState.config,
-      channels: {
-        ...slackTestState.config.channels,
-        slack: {
-          ...slackTestState.config.channels?.slack,
-          dm: { enabled: true, policy: "pairing", allowFrom: [] },
-        },
-      },
-    };
-    upsertPairingRequestMock
-      .mockResolvedValueOnce({ code: "PAIRCODE", created: true })
-      .mockResolvedValueOnce({ code: "PAIRCODE", created: false });
-
-    const { controller, run } = startSlackMonitor(monitorSlackProvider);
-    const handler = await getSlackHandlerOrThrow("message");
-
-    const baseEvent = {
-      type: "message",
-      user: "U1",
-      text: "hello",
-      ts: "123",
-      channel: "C1",
-      channel_type: "im",
-    };
-
-    await handler({ event: baseEvent });
-    await handler({ event: { ...baseEvent, ts: "124", text: "hello again" } });
-
-    await stopSlackMonitor({ controller, run });
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/slack/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts b/src/slack/monitor.tool-result.test.ts
similarity index 52%
rename from src/slack/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts
rename to src/slack/monitor.tool-result.test.ts
index f9fc21705c1..2e98b8e2653 100644
--- a/src/slack/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts
+++ b/src/slack/monitor.tool-result.test.ts
@@ -16,7 +16,7 @@ import {
 const { monitorSlackProvider } = await import("./monitor.js");
 
 const slackTestState = getSlackTestState();
-const { sendMock, replyMock } = slackTestState;
+const { sendMock, replyMock, reactMock, upsertPairingRequestMock } = slackTestState;
 
 beforeEach(() => {
   resetInboundDedupe();
@@ -439,4 +439,384 @@ describe("monitorSlackProvider tool results", () => {
     expect(sendMock).toHaveBeenCalledTimes(1);
     expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "456" });
   });
+
+  it("forces thread replies when replyToId is set", async () => {
+    replyMock.mockResolvedValue({ text: "forced reply", replyToId: "555" });
+    slackTestState.config = {
+      messages: {
+        responsePrefix: "PFX",
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+      },
+      channels: {
+        slack: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          dm: { enabled: true },
+          replyToMode: "off",
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "789",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(sendMock).toHaveBeenCalledTimes(1);
+    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "555" });
+  });
+
+  it("reacts to mention-gated room messages when ackReaction is enabled", async () => {
+    replyMock.mockResolvedValue(undefined);
+    const client = getSlackClient();
+    if (!client) {
+      throw new Error("Slack client not registered");
+    }
+    const conversations = client.conversations as {
+      info: ReturnType<typeof vi.fn>;
+    };
+    conversations.info.mockResolvedValueOnce({
+      channel: { name: "general", is_channel: true },
+    });
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "<@bot-user> hello",
+        ts: "456",
+        channel: "C1",
+        channel_type: "channel",
+      },
+    });
+
+    expect(reactMock).toHaveBeenCalledWith({
+      channel: "C1",
+      timestamp: "456",
+      name: "👀",
+    });
+  });
+
+  it("replies with pairing code when dmPolicy is pairing and no allowFrom is set", async () => {
+    slackTestState.config = {
+      ...slackTestState.config,
+      channels: {
+        ...slackTestState.config.channels,
+        slack: {
+          ...slackTestState.config.channels?.slack,
+          dm: { enabled: true, policy: "pairing", allowFrom: [] },
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "123",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(replyMock).not.toHaveBeenCalled();
+    expect(upsertPairingRequestMock).toHaveBeenCalled();
+    expect(sendMock).toHaveBeenCalledTimes(1);
+    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain("Your Slack user id: U1");
+    expect(String(sendMock.mock.calls[0]?.[1] ?? "")).toContain("Pairing code: PAIRCODE");
+  });
+
+  it("does not resend pairing code when a request is already pending", async () => {
+    slackTestState.config = {
+      ...slackTestState.config,
+      channels: {
+        ...slackTestState.config.channels,
+        slack: {
+          ...slackTestState.config.channels?.slack,
+          dm: { enabled: true, policy: "pairing", allowFrom: [] },
+        },
+      },
+    };
+    upsertPairingRequestMock
+      .mockResolvedValueOnce({ code: "PAIRCODE", created: true })
+      .mockResolvedValueOnce({ code: "PAIRCODE", created: false });
+
+    const { controller, run } = startSlackMonitor(monitorSlackProvider);
+    const handler = await getSlackHandlerOrThrow("message");
+
+    const baseEvent = {
+      type: "message",
+      user: "U1",
+      text: "hello",
+      ts: "123",
+      channel: "C1",
+      channel_type: "im",
+    };
+
+    await handler({ event: baseEvent });
+    await handler({ event: { ...baseEvent, ts: "124", text: "hello again" } });
+
+    await stopSlackMonitor({ controller, run });
+
+    expect(sendMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("threads top-level replies when replyToMode is all", async () => {
+    replyMock.mockResolvedValue({ text: "thread reply" });
+    slackTestState.config = {
+      messages: {
+        responsePrefix: "PFX",
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+      },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          replyToMode: "all",
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "123",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(sendMock).toHaveBeenCalledTimes(1);
+    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "123" });
+  });
+
+  it("treats parent_user_id as a thread reply even when thread_ts matches ts", async () => {
+    replyMock.mockResolvedValue({ text: "thread reply" });
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "123",
+        thread_ts: "123",
+        parent_user_id: "U2",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(replyMock).toHaveBeenCalledTimes(1);
+    const ctx = replyMock.mock.calls[0]?.[0] as {
+      SessionKey?: string;
+      ParentSessionKey?: string;
+    };
+    expect(ctx.SessionKey).toBe("agent:main:main:thread:123");
+    expect(ctx.ParentSessionKey).toBeUndefined();
+  });
+
+  it("keeps thread parent inheritance opt-in", async () => {
+    replyMock.mockResolvedValue({ text: "thread reply" });
+
+    slackTestState.config = {
+      messages: { responsePrefix: "PFX" },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          channels: { C1: { allow: true, requireMention: false } },
+          thread: { inheritParent: true },
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "123",
+        thread_ts: "111.222",
+        channel: "C1",
+        channel_type: "channel",
+      },
+    });
+
+    expect(replyMock).toHaveBeenCalledTimes(1);
+    const ctx = replyMock.mock.calls[0]?.[0] as {
+      SessionKey?: string;
+      ParentSessionKey?: string;
+    };
+    expect(ctx.SessionKey).toBe("agent:main:slack:channel:c1:thread:111.222");
+    expect(ctx.ParentSessionKey).toBe("agent:main:slack:channel:c1");
+  });
+
+  it("injects starter context for thread replies", async () => {
+    replyMock.mockResolvedValue({ text: "ok" });
+
+    const client = getSlackClient();
+    if (client?.conversations?.info) {
+      client.conversations.info.mockResolvedValue({
+        channel: { name: "general", is_channel: true },
+      });
+    }
+    if (client?.conversations?.replies) {
+      client.conversations.replies.mockResolvedValue({
+        messages: [{ text: "starter message", user: "U2", ts: "111.222" }],
+      });
+    }
+
+    slackTestState.config = {
+      messages: { responsePrefix: "PFX" },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          channels: { C1: { allow: true, requireMention: false } },
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "thread reply",
+        ts: "123.456",
+        thread_ts: "111.222",
+        channel: "C1",
+        channel_type: "channel",
+      },
+    });
+
+    expect(replyMock).toHaveBeenCalledTimes(1);
+    const ctx = replyMock.mock.calls[0]?.[0] as {
+      SessionKey?: string;
+      ParentSessionKey?: string;
+      ThreadStarterBody?: string;
+      ThreadLabel?: string;
+    };
+    expect(ctx.SessionKey).toBe("agent:main:slack:channel:c1:thread:111.222");
+    expect(ctx.ParentSessionKey).toBeUndefined();
+    expect(ctx.ThreadStarterBody).toContain("starter message");
+    expect(ctx.ThreadLabel).toContain("Slack thread #general");
+  });
+
+  it("scopes thread session keys to the routed agent", async () => {
+    replyMock.mockResolvedValue({ text: "ok" });
+    slackTestState.config = {
+      messages: { responsePrefix: "PFX" },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          channels: { C1: { allow: true, requireMention: false } },
+        },
+      },
+      bindings: [{ agentId: "support", match: { channel: "slack", teamId: "T1" } }],
+    };
+
+    const client = getSlackClient();
+    if (client?.auth?.test) {
+      client.auth.test.mockResolvedValue({
+        user_id: "bot-user",
+        team_id: "T1",
+      });
+    }
+    if (client?.conversations?.info) {
+      client.conversations.info.mockResolvedValue({
+        channel: { name: "general", is_channel: true },
+      });
+    }
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "thread reply",
+        ts: "123.456",
+        thread_ts: "111.222",
+        channel: "C1",
+        channel_type: "channel",
+      },
+    });
+
+    expect(replyMock).toHaveBeenCalledTimes(1);
+    const ctx = replyMock.mock.calls[0]?.[0] as {
+      SessionKey?: string;
+      ParentSessionKey?: string;
+    };
+    expect(ctx.SessionKey).toBe("agent:support:slack:channel:c1:thread:111.222");
+    expect(ctx.ParentSessionKey).toBeUndefined();
+  });
+
+  it("keeps replies in channel root when message is not threaded (replyToMode off)", async () => {
+    replyMock.mockResolvedValue({ text: "root reply" });
+    slackTestState.config = {
+      messages: {
+        responsePrefix: "PFX",
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+      },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          replyToMode: "off",
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "789",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(sendMock).toHaveBeenCalledTimes(1);
+    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: undefined });
+  });
+
+  it("threads first reply when replyToMode is first and message is not threaded", async () => {
+    replyMock.mockResolvedValue({ text: "first reply" });
+    slackTestState.config = {
+      messages: {
+        responsePrefix: "PFX",
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+      },
+      channels: {
+        slack: {
+          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
+          replyToMode: "first",
+        },
+      },
+    };
+
+    await runSlackMessageOnce(monitorSlackProvider, {
+      event: {
+        type: "message",
+        user: "U1",
+        text: "hello",
+        ts: "789",
+        channel: "C1",
+        channel_type: "im",
+      },
+    });
+
+    expect(sendMock).toHaveBeenCalledTimes(1);
+    // First reply starts a thread under the incoming message
+    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "789" });
+  });
 });
diff --git a/src/slack/monitor.tool-result.threads-top-level-replies-replytomode-is-all.test.ts b/src/slack/monitor.tool-result.threads-top-level-replies-replytomode-is-all.test.ts
deleted file mode 100644
index 7e2574d6967..00000000000
--- a/src/slack/monitor.tool-result.threads-top-level-replies-replytomode-is-all.test.ts
+++ /dev/null
@@ -1,272 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import { resetInboundDedupe } from "../auto-reply/reply/inbound-dedupe.js";
-import {
-  defaultSlackTestConfig,
-  getSlackClient,
-  getSlackTestState,
-  resetSlackTestState,
-  runSlackMessageOnce,
-} from "./monitor.test-helpers.js";
-
-const { monitorSlackProvider } = await import("./monitor.js");
-
-const slackTestState = getSlackTestState();
-const { sendMock, replyMock } = slackTestState;
-
-beforeEach(() => {
-  resetInboundDedupe();
-  resetSlackTestState(defaultSlackTestConfig());
-});
-
-describe("monitorSlackProvider tool results", () => {
-  it("threads top-level replies when replyToMode is all", async () => {
-    replyMock.mockResolvedValue({ text: "thread reply" });
-    slackTestState.config = {
-      messages: {
-        responsePrefix: "PFX",
-        ackReaction: "👀",
-        ackReactionScope: "group-mentions",
-      },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          replyToMode: "all",
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "123",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "123" });
-  });
-
-  it("treats parent_user_id as a thread reply even when thread_ts matches ts", async () => {
-    replyMock.mockResolvedValue({ text: "thread reply" });
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "123",
-        thread_ts: "123",
-        parent_user_id: "U2",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(replyMock).toHaveBeenCalledTimes(1);
-    const ctx = replyMock.mock.calls[0]?.[0] as {
-      SessionKey?: string;
-      ParentSessionKey?: string;
-    };
-    expect(ctx.SessionKey).toBe("agent:main:main:thread:123");
-    expect(ctx.ParentSessionKey).toBeUndefined();
-  });
-
-  it("keeps thread parent inheritance opt-in", async () => {
-    replyMock.mockResolvedValue({ text: "thread reply" });
-
-    slackTestState.config = {
-      messages: { responsePrefix: "PFX" },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          channels: { C1: { allow: true, requireMention: false } },
-          thread: { inheritParent: true },
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "123",
-        thread_ts: "111.222",
-        channel: "C1",
-        channel_type: "channel",
-      },
-    });
-
-    expect(replyMock).toHaveBeenCalledTimes(1);
-    const ctx = replyMock.mock.calls[0]?.[0] as {
-      SessionKey?: string;
-      ParentSessionKey?: string;
-    };
-    expect(ctx.SessionKey).toBe("agent:main:slack:channel:c1:thread:111.222");
-    expect(ctx.ParentSessionKey).toBe("agent:main:slack:channel:c1");
-  });
-
-  it("injects starter context for thread replies", async () => {
-    replyMock.mockResolvedValue({ text: "ok" });
-
-    const client = getSlackClient();
-    if (client?.conversations?.info) {
-      client.conversations.info.mockResolvedValue({
-        channel: { name: "general", is_channel: true },
-      });
-    }
-    if (client?.conversations?.replies) {
-      client.conversations.replies.mockResolvedValue({
-        messages: [{ text: "starter message", user: "U2", ts: "111.222" }],
-      });
-    }
-
-    slackTestState.config = {
-      messages: { responsePrefix: "PFX" },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          channels: { C1: { allow: true, requireMention: false } },
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "thread reply",
-        ts: "123.456",
-        thread_ts: "111.222",
-        channel: "C1",
-        channel_type: "channel",
-      },
-    });
-
-    expect(replyMock).toHaveBeenCalledTimes(1);
-    const ctx = replyMock.mock.calls[0]?.[0] as {
-      SessionKey?: string;
-      ParentSessionKey?: string;
-      ThreadStarterBody?: string;
-      ThreadLabel?: string;
-    };
-    expect(ctx.SessionKey).toBe("agent:main:slack:channel:c1:thread:111.222");
-    expect(ctx.ParentSessionKey).toBeUndefined();
-    expect(ctx.ThreadStarterBody).toContain("starter message");
-    expect(ctx.ThreadLabel).toContain("Slack thread #general");
-  });
-
-  it("scopes thread session keys to the routed agent", async () => {
-    replyMock.mockResolvedValue({ text: "ok" });
-    slackTestState.config = {
-      messages: { responsePrefix: "PFX" },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          channels: { C1: { allow: true, requireMention: false } },
-        },
-      },
-      bindings: [{ agentId: "support", match: { channel: "slack", teamId: "T1" } }],
-    };
-
-    const client = getSlackClient();
-    if (client?.auth?.test) {
-      client.auth.test.mockResolvedValue({
-        user_id: "bot-user",
-        team_id: "T1",
-      });
-    }
-    if (client?.conversations?.info) {
-      client.conversations.info.mockResolvedValue({
-        channel: { name: "general", is_channel: true },
-      });
-    }
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "thread reply",
-        ts: "123.456",
-        thread_ts: "111.222",
-        channel: "C1",
-        channel_type: "channel",
-      },
-    });
-
-    expect(replyMock).toHaveBeenCalledTimes(1);
-    const ctx = replyMock.mock.calls[0]?.[0] as {
-      SessionKey?: string;
-      ParentSessionKey?: string;
-    };
-    expect(ctx.SessionKey).toBe("agent:support:slack:channel:c1:thread:111.222");
-    expect(ctx.ParentSessionKey).toBeUndefined();
-  });
-
-  it("keeps replies in channel root when message is not threaded (replyToMode off)", async () => {
-    replyMock.mockResolvedValue({ text: "root reply" });
-    slackTestState.config = {
-      messages: {
-        responsePrefix: "PFX",
-        ackReaction: "👀",
-        ackReactionScope: "group-mentions",
-      },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          replyToMode: "off",
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "789",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: undefined });
-  });
-
-  it("threads first reply when replyToMode is first and message is not threaded", async () => {
-    replyMock.mockResolvedValue({ text: "first reply" });
-    slackTestState.config = {
-      messages: {
-        responsePrefix: "PFX",
-        ackReaction: "👀",
-        ackReactionScope: "group-mentions",
-      },
-      channels: {
-        slack: {
-          dm: { enabled: true, policy: "open", allowFrom: ["*"] },
-          replyToMode: "first",
-        },
-      },
-    };
-
-    await runSlackMessageOnce(monitorSlackProvider, {
-      event: {
-        type: "message",
-        user: "U1",
-        text: "hello",
-        ts: "789",
-        channel: "C1",
-        channel_type: "im",
-      },
-    });
-
-    expect(sendMock).toHaveBeenCalledTimes(1);
-    // First reply starts a thread under the incoming message
-    expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "789" });
-  });
-});
diff --git a/src/slack/monitor/channel-config.test.ts b/src/slack/monitor/channel-config.test.ts
deleted file mode 100644
index 9303605a99d..00000000000
--- a/src/slack/monitor/channel-config.test.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveSlackChannelConfig } from "./channel-config.js";
-
-describe("resolveSlackChannelConfig", () => {
-  it("uses defaultRequireMention when channels config is empty", () => {
-    const res = resolveSlackChannelConfig({
-      channelId: "C1",
-      channels: {},
-      defaultRequireMention: false,
-    });
-    expect(res).toEqual({ allowed: true, requireMention: false });
-  });
-
-  it("defaults defaultRequireMention to true when not provided", () => {
-    const res = resolveSlackChannelConfig({
-      channelId: "C1",
-      channels: {},
-    });
-    expect(res).toEqual({ allowed: true, requireMention: true });
-  });
-
-  it("prefers explicit channel/fallback requireMention over defaultRequireMention", () => {
-    const res = resolveSlackChannelConfig({
-      channelId: "C1",
-      channels: { "*": { requireMention: true } },
-      defaultRequireMention: false,
-    });
-    expect(res).toMatchObject({ requireMention: true });
-  });
-
-  it("uses wildcard entries when no direct channel config exists", () => {
-    const res = resolveSlackChannelConfig({
-      channelId: "C1",
-      channels: { "*": { allow: true, requireMention: false } },
-      defaultRequireMention: true,
-    });
-    expect(res).toMatchObject({
-      allowed: true,
-      requireMention: false,
-      matchKey: "*",
-      matchSource: "wildcard",
-    });
-  });
-
-  it("uses direct match metadata when channel config exists", () => {
-    const res = resolveSlackChannelConfig({
-      channelId: "C1",
-      channels: { C1: { allow: true, requireMention: false } },
-      defaultRequireMention: true,
-    });
-    expect(res).toMatchObject({
-      matchKey: "C1",
-      matchSource: "direct",
-    });
-  });
-});
diff --git a/src/slack/monitor/channel-config.ts b/src/slack/monitor/channel-config.ts
index 6d35cb1ae69..0d34209e422 100644
--- a/src/slack/monitor/channel-config.ts
+++ b/src/slack/monitor/channel-config.ts
@@ -19,6 +19,18 @@ export type SlackChannelConfigResolved = {
   matchSource?: ChannelMatchSource;
 };
 
+export type SlackChannelConfigEntry = {
+  enabled?: boolean;
+  allow?: boolean;
+  requireMention?: boolean;
+  allowBots?: boolean;
+  users?: Array<string | number>;
+  skills?: string[];
+  systemPrompt?: string;
+};
+
+export type SlackChannelConfigEntries = Record<string, SlackChannelConfigEntry>;
+
 function firstDefined<T>(...values: Array<T | undefined>) {
   for (const value of values) {
     if (typeof value !== "undefined") {
@@ -74,18 +86,7 @@ export function resolveSlackChannelLabel(params: { channelId?: string; channelNa
 export function resolveSlackChannelConfig(params: {
   channelId: string;
   channelName?: string;
-  channels?: Record<
-    string,
-    {
-      enabled?: boolean;
-      allow?: boolean;
-      requireMention?: boolean;
-      allowBots?: boolean;
-      users?: Array<string | number>;
-      skills?: string[];
-      systemPrompt?: string;
-    }
-  >;
+  channels?: SlackChannelConfigEntries;
   defaultRequireMention?: boolean;
 }): SlackChannelConfigResolved | null {
   const { channelId, channelName, channels, defaultRequireMention } = params;
diff --git a/src/slack/monitor/context.test.ts b/src/slack/monitor/context.test.ts
deleted file mode 100644
index 0afde23461c..00000000000
--- a/src/slack/monitor/context.test.ts
+++ /dev/null
@@ -1,119 +0,0 @@
-import type { App } from "@slack/bolt";
-import { describe, expect, it } from "vitest";
-import type { OpenClawConfig } from "../../config/config.js";
-import type { RuntimeEnv } from "../../runtime.js";
-import { createSlackMonitorContext, normalizeSlackChannelType } from "./context.js";
-
-const baseParams = () => ({
-  cfg: {} as OpenClawConfig,
-  accountId: "default",
-  botToken: "token",
-  app: { client: {} } as App,
-  runtime: {} as RuntimeEnv,
-  botUserId: "B1",
-  teamId: "T1",
-  apiAppId: "A1",
-  historyLimit: 0,
-  sessionScope: "per-sender" as const,
-  mainKey: "main",
-  dmEnabled: true,
-  dmPolicy: "open" as const,
-  allowFrom: [],
-  groupDmEnabled: true,
-  groupDmChannels: [],
-  defaultRequireMention: true,
-  groupPolicy: "open" as const,
-  useAccessGroups: false,
-  reactionMode: "off" as const,
-  reactionAllowlist: [],
-  replyToMode: "off" as const,
-  slashCommand: {
-    enabled: false,
-    name: "openclaw",
-    sessionPrefix: "slack:slash",
-    ephemeral: true,
-  },
-  textLimit: 4000,
-  ackReactionScope: "group-mentions",
-  mediaMaxBytes: 1,
-  removeAckAfterReply: false,
-});
-
-describe("normalizeSlackChannelType", () => {
-  it("infers channel types from ids when missing", () => {
-    expect(normalizeSlackChannelType(undefined, "C123")).toBe("channel");
-    expect(normalizeSlackChannelType(undefined, "D123")).toBe("im");
-    expect(normalizeSlackChannelType(undefined, "G123")).toBe("group");
-  });
-
-  it("prefers explicit channel_type values", () => {
-    expect(normalizeSlackChannelType("mpim", "C123")).toBe("mpim");
-  });
-});
-
-describe("resolveSlackSystemEventSessionKey", () => {
-  it("defaults missing channel_type to channel sessions", () => {
-    const ctx = createSlackMonitorContext(baseParams());
-    expect(ctx.resolveSlackSystemEventSessionKey({ channelId: "C123" })).toBe(
-      "agent:main:slack:channel:c123",
-    );
-  });
-});
-
-describe("isChannelAllowed with groupPolicy and channelsConfig", () => {
-  it("allows unlisted channels when groupPolicy is open even with channelsConfig entries", () => {
-    // Bug fix: when groupPolicy="open" and channels has some entries,
-    // unlisted channels should still be allowed (not blocked)
-    const ctx = createSlackMonitorContext({
-      ...baseParams(),
-      groupPolicy: "open",
-      channelsConfig: {
-        C_LISTED: { requireMention: true },
-      },
-    });
-    // Listed channel should be allowed
-    expect(ctx.isChannelAllowed({ channelId: "C_LISTED", channelType: "channel" })).toBe(true);
-    // Unlisted channel should ALSO be allowed when policy is "open"
-    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(true);
-  });
-
-  it("blocks unlisted channels when groupPolicy is allowlist", () => {
-    const ctx = createSlackMonitorContext({
-      ...baseParams(),
-      groupPolicy: "allowlist",
-      channelsConfig: {
-        C_LISTED: { requireMention: true },
-      },
-    });
-    // Listed channel should be allowed
-    expect(ctx.isChannelAllowed({ channelId: "C_LISTED", channelType: "channel" })).toBe(true);
-    // Unlisted channel should be blocked when policy is "allowlist"
-    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(false);
-  });
-
-  it("blocks explicitly denied channels even when groupPolicy is open", () => {
-    const ctx = createSlackMonitorContext({
-      ...baseParams(),
-      groupPolicy: "open",
-      channelsConfig: {
-        C_ALLOWED: { allow: true },
-        C_DENIED: { allow: false },
-      },
-    });
-    // Explicitly allowed channel
-    expect(ctx.isChannelAllowed({ channelId: "C_ALLOWED", channelType: "channel" })).toBe(true);
-    // Explicitly denied channel should be blocked even with open policy
-    expect(ctx.isChannelAllowed({ channelId: "C_DENIED", channelType: "channel" })).toBe(false);
-    // Unlisted channel should be allowed with open policy
-    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(true);
-  });
-
-  it("allows all channels when groupPolicy is open and channelsConfig is empty", () => {
-    const ctx = createSlackMonitorContext({
-      ...baseParams(),
-      groupPolicy: "open",
-      channelsConfig: undefined,
-    });
-    expect(ctx.isChannelAllowed({ channelId: "C_ANY", channelType: "channel" })).toBe(true);
-  });
-});
diff --git a/src/slack/monitor/context.ts b/src/slack/monitor/context.ts
index 57f5fbc2550..d95297e1e25 100644
--- a/src/slack/monitor/context.ts
+++ b/src/slack/monitor/context.ts
@@ -4,6 +4,7 @@ import type { OpenClawConfig, SlackReactionNotificationMode } from "../../config
 import type { DmPolicy, GroupPolicy } from "../../config/types.js";
 import type { RuntimeEnv } from "../../runtime.js";
 import type { SlackMessageEvent } from "../types.js";
+import type { SlackChannelConfigEntries } from "./channel-config.js";
 import { formatAllowlistMatchMeta } from "../../channels/allowlist-match.js";
 import { resolveSessionKey, type SessionScope } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
@@ -70,18 +71,7 @@ export type SlackMonitorContext = {
   groupDmEnabled: boolean;
   groupDmChannels: string[];
   defaultRequireMention: boolean;
-  channelsConfig?: Record<
-    string,
-    {
-      enabled?: boolean;
-      allow?: boolean;
-      requireMention?: boolean;
-      allowBots?: boolean;
-      users?: Array<string | number>;
-      skills?: string[];
-      systemPrompt?: string;
-    }
-  >;
+  channelsConfig?: SlackChannelConfigEntries;
   groupPolicy: GroupPolicy;
   useAccessGroups: boolean;
   reactionMode: SlackReactionNotificationMode;
diff --git a/src/slack/monitor/media.thread-starter-cache.test.ts b/src/slack/monitor/media.thread-starter-cache.test.ts
deleted file mode 100644
index 45278acfe62..00000000000
--- a/src/slack/monitor/media.thread-starter-cache.test.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { resetSlackThreadStarterCacheForTest, resolveSlackThreadStarter } from "./media.js";
-
-describe("resolveSlackThreadStarter cache", () => {
-  afterEach(() => {
-    resetSlackThreadStarterCacheForTest();
-    vi.useRealTimers();
-  });
-
-  it("returns cached thread starter without refetching within ttl", async () => {
-    const replies = vi.fn(async () => ({
-      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
-    }));
-    const client = {
-      conversations: { replies },
-    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
-
-    const first = await resolveSlackThreadStarter({
-      channelId: "C1",
-      threadTs: "1000.1",
-      client,
-    });
-    const second = await resolveSlackThreadStarter({
-      channelId: "C1",
-      threadTs: "1000.1",
-      client,
-    });
-
-    expect(first).toEqual(second);
-    expect(replies).toHaveBeenCalledTimes(1);
-  });
-
-  it("expires stale cache entries and refetches after ttl", async () => {
-    vi.useFakeTimers();
-    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
-
-    const replies = vi.fn(async () => ({
-      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
-    }));
-    const client = {
-      conversations: { replies },
-    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
-
-    await resolveSlackThreadStarter({
-      channelId: "C1",
-      threadTs: "1000.1",
-      client,
-    });
-
-    vi.setSystemTime(new Date("2026-01-01T07:00:00.000Z"));
-    await resolveSlackThreadStarter({
-      channelId: "C1",
-      threadTs: "1000.1",
-      client,
-    });
-
-    expect(replies).toHaveBeenCalledTimes(2);
-  });
-
-  it("evicts oldest entries once cache exceeds bounded size", async () => {
-    const replies = vi.fn(async () => ({
-      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
-    }));
-    const client = {
-      conversations: { replies },
-    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
-
-    // Cache cap is 2000; add enough distinct keys to force eviction of earliest keys.
-    for (let i = 0; i <= 2000; i += 1) {
-      await resolveSlackThreadStarter({
-        channelId: "C1",
-        threadTs: `1000.${i}`,
-        client,
-      });
-    }
-    const callsAfterFill = replies.mock.calls.length;
-
-    // Oldest key should be evicted and require fetch again.
-    await resolveSlackThreadStarter({
-      channelId: "C1",
-      threadTs: "1000.0",
-      client,
-    });
-
-    expect(replies.mock.calls.length).toBe(callsAfterFill + 1);
-  });
-});
diff --git a/src/slack/monitor/media.ts b/src/slack/monitor/media.ts
index c943b9daafd..8dcf6ecd053 100644
--- a/src/slack/monitor/media.ts
+++ b/src/slack/monitor/media.ts
@@ -1,17 +1,10 @@
 import type { WebClient as SlackWebClient } from "@slack/web-api";
 import type { FetchLike } from "../../media/fetch.js";
 import type { SlackFile } from "../types.js";
+import { normalizeHostname } from "../../infra/net/hostname.js";
 import { fetchRemoteMedia } from "../../media/fetch.js";
 import { saveMediaBuffer } from "../../media/store.js";
 
-function normalizeHostname(hostname: string): string {
-  const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
-  if (normalized.startsWith("[") && normalized.endsWith("]")) {
-    return normalized.slice(1, -1);
-  }
-  return normalized;
-}
-
 function isSlackHostname(hostname: string): boolean {
   const normalized = normalizeHostname(hostname);
   if (!normalized) {
diff --git a/src/slack/monitor/message-handler/prepare.sender-prefix.test.ts b/src/slack/monitor/message-handler/prepare.sender-prefix.test.ts
deleted file mode 100644
index 30cfdc1ef9d..00000000000
--- a/src/slack/monitor/message-handler/prepare.sender-prefix.test.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { SlackMonitorContext } from "../context.js";
-import { prepareSlackMessage } from "./prepare.js";
-
-describe("prepareSlackMessage sender prefix", () => {
-  it("prefixes channel bodies with sender label", async () => {
-    const ctx = {
-      cfg: {
-        agents: { defaults: { model: "anthropic/claude-opus-4-5", workspace: "/tmp/openclaw" } },
-        channels: { slack: {} },
-      },
-      accountId: "default",
-      botToken: "xoxb",
-      app: { client: {} },
-      runtime: {
-        log: vi.fn(),
-        error: vi.fn(),
-        exit: (code: number): never => {
-          throw new Error(`exit ${code}`);
-        },
-      },
-      botUserId: "BOT",
-      teamId: "T1",
-      apiAppId: "A1",
-      historyLimit: 0,
-      channelHistories: new Map(),
-      sessionScope: "per-sender",
-      mainKey: "agent:main:main",
-      dmEnabled: true,
-      dmPolicy: "open",
-      allowFrom: [],
-      groupDmEnabled: false,
-      groupDmChannels: [],
-      defaultRequireMention: true,
-      groupPolicy: "open",
-      useAccessGroups: false,
-      reactionMode: "off",
-      reactionAllowlist: [],
-      replyToMode: "off",
-      threadHistoryScope: "channel",
-      threadInheritParent: false,
-      slashCommand: { command: "/openclaw", enabled: true },
-      textLimit: 2000,
-      ackReactionScope: "off",
-      mediaMaxBytes: 1000,
-      removeAckAfterReply: false,
-      logger: { info: vi.fn(), warn: vi.fn() },
-      markMessageSeen: () => false,
-      shouldDropMismatchedSlackEvent: () => false,
-      resolveSlackSystemEventSessionKey: () => "agent:main:slack:channel:c1",
-      isChannelAllowed: () => true,
-      resolveChannelName: async () => ({
-        name: "general",
-        type: "channel",
-      }),
-      resolveUserName: async () => ({ name: "Alice" }),
-      setSlackThreadStatus: async () => undefined,
-    } satisfies SlackMonitorContext;
-
-    const result = await prepareSlackMessage({
-      ctx,
-      account: { accountId: "default", config: {} } as never,
-      message: {
-        type: "message",
-        channel: "C1",
-        channel_type: "channel",
-        text: "<@BOT> hello",
-        user: "U1",
-        ts: "1700000000.0001",
-        event_ts: "1700000000.0001",
-      } as never,
-      opts: { source: "message", wasMentioned: true },
-    });
-
-    expect(result).not.toBeNull();
-    const body = result?.ctxPayload.Body ?? "";
-    expect(body).toContain("Alice (U1): <@BOT> hello");
-  });
-
-  it("detects /new as control command when prefixed with Slack mention", async () => {
-    const ctx = {
-      cfg: {
-        agents: { defaults: { model: "anthropic/claude-opus-4-5", workspace: "/tmp/openclaw" } },
-        channels: { slack: { dm: { enabled: true, policy: "open", allowFrom: ["*"] } } },
-      },
-      accountId: "default",
-      botToken: "xoxb",
-      app: { client: {} },
-      runtime: {
-        log: vi.fn(),
-        error: vi.fn(),
-        exit: (code: number): never => {
-          throw new Error(`exit ${code}`);
-        },
-      },
-      botUserId: "BOT",
-      teamId: "T1",
-      apiAppId: "A1",
-      historyLimit: 0,
-      channelHistories: new Map(),
-      sessionScope: "per-sender",
-      mainKey: "agent:main:main",
-      dmEnabled: true,
-      dmPolicy: "open",
-      allowFrom: ["U1"],
-      groupDmEnabled: false,
-      groupDmChannels: [],
-      defaultRequireMention: true,
-      groupPolicy: "open",
-      useAccessGroups: true,
-      reactionMode: "off",
-      reactionAllowlist: [],
-      replyToMode: "off",
-      threadHistoryScope: "channel",
-      threadInheritParent: false,
-      slashCommand: {
-        enabled: false,
-        name: "openclaw",
-        sessionPrefix: "slack:slash",
-        ephemeral: true,
-      },
-      textLimit: 2000,
-      ackReactionScope: "off",
-      mediaMaxBytes: 1000,
-      removeAckAfterReply: false,
-      logger: { info: vi.fn(), warn: vi.fn() },
-      markMessageSeen: () => false,
-      shouldDropMismatchedSlackEvent: () => false,
-      resolveSlackSystemEventSessionKey: () => "agent:main:slack:channel:c1",
-      isChannelAllowed: () => true,
-      resolveChannelName: async () => ({ name: "general", type: "channel" }),
-      resolveUserName: async () => ({ name: "Alice" }),
-      setSlackThreadStatus: async () => undefined,
-    } satisfies SlackMonitorContext;
-
-    const result = await prepareSlackMessage({
-      ctx,
-      account: { accountId: "default", config: {} } as never,
-      message: {
-        type: "message",
-        channel: "C1",
-        channel_type: "channel",
-        text: "<@BOT> /new",
-        user: "U1",
-        ts: "1700000000.0002",
-        event_ts: "1700000000.0002",
-      } as never,
-      opts: { source: "message", wasMentioned: true },
-    });
-
-    expect(result).not.toBeNull();
-    expect(result?.ctxPayload.CommandAuthorized).toBe(true);
-  });
-});
diff --git a/src/slack/monitor/message-handler/prepare.inbound-contract.test.ts b/src/slack/monitor/message-handler/prepare.test.ts
similarity index 75%
rename from src/slack/monitor/message-handler/prepare.inbound-contract.test.ts
rename to src/slack/monitor/message-handler/prepare.test.ts
index 4e2023da6a2..91c9670e76b 100644
--- a/src/slack/monitor/message-handler/prepare.inbound-contract.test.ts
+++ b/src/slack/monitor/message-handler/prepare.test.ts
@@ -7,6 +7,7 @@ import type { OpenClawConfig } from "../../../config/config.js";
 import type { RuntimeEnv } from "../../../runtime.js";
 import type { ResolvedSlackAccount } from "../../accounts.js";
 import type { SlackMessageEvent } from "../../types.js";
+import type { SlackMonitorContext } from "../context.js";
 import { expectInboundContextContract } from "../../../../test/helpers/inbound-contract.js";
 import { resolveAgentRoute } from "../../../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../../../routing/session-key.js";
@@ -484,3 +485,154 @@ describe("slack prepareSlackMessage inbound contract", () => {
     expect(prepared!.ctxPayload.Body).not.toContain("parent_user_id");
   });
 });
+
+describe("prepareSlackMessage sender prefix", () => {
+  it("prefixes channel bodies with sender label", async () => {
+    const ctx = {
+      cfg: {
+        agents: { defaults: { model: "anthropic/claude-opus-4-5", workspace: "/tmp/openclaw" } },
+        channels: { slack: {} },
+      },
+      accountId: "default",
+      botToken: "xoxb",
+      app: { client: {} },
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: (code: number): never => {
+          throw new Error(`exit ${code}`);
+        },
+      },
+      botUserId: "BOT",
+      teamId: "T1",
+      apiAppId: "A1",
+      historyLimit: 0,
+      channelHistories: new Map(),
+      sessionScope: "per-sender",
+      mainKey: "agent:main:main",
+      dmEnabled: true,
+      dmPolicy: "open",
+      allowFrom: [],
+      groupDmEnabled: false,
+      groupDmChannels: [],
+      defaultRequireMention: true,
+      groupPolicy: "open",
+      useAccessGroups: false,
+      reactionMode: "off",
+      reactionAllowlist: [],
+      replyToMode: "off",
+      threadHistoryScope: "channel",
+      threadInheritParent: false,
+      slashCommand: { command: "/openclaw", enabled: true },
+      textLimit: 2000,
+      ackReactionScope: "off",
+      mediaMaxBytes: 1000,
+      removeAckAfterReply: false,
+      logger: { info: vi.fn(), warn: vi.fn() },
+      markMessageSeen: () => false,
+      shouldDropMismatchedSlackEvent: () => false,
+      resolveSlackSystemEventSessionKey: () => "agent:main:slack:channel:c1",
+      isChannelAllowed: () => true,
+      resolveChannelName: async () => ({
+        name: "general",
+        type: "channel",
+      }),
+      resolveUserName: async () => ({ name: "Alice" }),
+      setSlackThreadStatus: async () => undefined,
+    } satisfies SlackMonitorContext;
+
+    const result = await prepareSlackMessage({
+      ctx,
+      account: { accountId: "default", config: {} } as never,
+      message: {
+        type: "message",
+        channel: "C1",
+        channel_type: "channel",
+        text: "<@BOT> hello",
+        user: "U1",
+        ts: "1700000000.0001",
+        event_ts: "1700000000.0001",
+      } as never,
+      opts: { source: "message", wasMentioned: true },
+    });
+
+    expect(result).not.toBeNull();
+    const body = result?.ctxPayload.Body ?? "";
+    expect(body).toContain("Alice (U1): <@BOT> hello");
+  });
+
+  it("detects /new as control command when prefixed with Slack mention", async () => {
+    const ctx = {
+      cfg: {
+        agents: { defaults: { model: "anthropic/claude-opus-4-5", workspace: "/tmp/openclaw" } },
+        channels: { slack: { dm: { enabled: true, policy: "open", allowFrom: ["*"] } } },
+      },
+      accountId: "default",
+      botToken: "xoxb",
+      app: { client: {} },
+      runtime: {
+        log: vi.fn(),
+        error: vi.fn(),
+        exit: (code: number): never => {
+          throw new Error(`exit ${code}`);
+        },
+      },
+      botUserId: "BOT",
+      teamId: "T1",
+      apiAppId: "A1",
+      historyLimit: 0,
+      channelHistories: new Map(),
+      sessionScope: "per-sender",
+      mainKey: "agent:main:main",
+      dmEnabled: true,
+      dmPolicy: "open",
+      allowFrom: ["U1"],
+      groupDmEnabled: false,
+      groupDmChannels: [],
+      defaultRequireMention: true,
+      groupPolicy: "open",
+      useAccessGroups: true,
+      reactionMode: "off",
+      reactionAllowlist: [],
+      replyToMode: "off",
+      threadHistoryScope: "channel",
+      threadInheritParent: false,
+      slashCommand: {
+        enabled: false,
+        name: "openclaw",
+        sessionPrefix: "slack:slash",
+        ephemeral: true,
+      },
+      textLimit: 2000,
+      ackReactionScope: "off",
+      mediaMaxBytes: 1000,
+      removeAckAfterReply: false,
+      logger: { info: vi.fn(), warn: vi.fn() },
+      markMessageSeen: () => false,
+      shouldDropMismatchedSlackEvent: () => false,
+      resolveSlackSystemEventSessionKey: () => "agent:main:slack:channel:c1",
+      isChannelAllowed: () => true,
+      resolveChannelName: async () => ({ name: "general", type: "channel" }),
+      resolveUserName: async () => ({ name: "Alice" }),
+      setSlackThreadStatus: async () => undefined,
+    } satisfies SlackMonitorContext;
+
+    const result = await prepareSlackMessage({
+      ctx,
+      account: { accountId: "default", config: {} } as never,
+      message: {
+        type: "message",
+        channel: "C1",
+        channel_type: "channel",
+        text: "<@BOT> /new",
+        user: "U1",
+        ts: "1700000000.0002",
+        event_ts: "1700000000.0002",
+      } as never,
+      opts: { source: "message", wasMentioned: true },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.ctxPayload.CommandAuthorized).toBe(true);
+  });
+});
diff --git a/src/slack/monitor/message-handler/prepare.ts b/src/slack/monitor/message-handler/prepare.ts
index 7e3ccf5f978..d7296646d58 100644
--- a/src/slack/monitor/message-handler/prepare.ts
+++ b/src/slack/monitor/message-handler/prepare.ts
@@ -35,7 +35,6 @@ import { buildPairingReply } from "../../../pairing/pairing-messages.js";
 import { upsertChannelPairingRequest } from "../../../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../../../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../../../routing/session-key.js";
-import { buildUntrustedChannelMetadata } from "../../../security/channel-metadata.js";
 import { reactSlackMessage } from "../../actions.js";
 import { sendMessageSlack } from "../../send.js";
 import { resolveSlackThreadContext } from "../../threading.js";
@@ -49,6 +48,7 @@ import {
   resolveSlackThreadHistory,
   resolveSlackThreadStarter,
 } from "../media.js";
+import { resolveSlackRoomContextHints } from "../room-context.js";
 
 export async function prepareSlackMessage(params: {
   ctx: SlackMonitorContext;
@@ -348,7 +348,10 @@ export async function prepareSlackMessage(params: {
     return null;
   }
 
-  const ackReaction = resolveAckReaction(cfg, route.agentId);
+  const ackReaction = resolveAckReaction(cfg, route.agentId, {
+    channel: "slack",
+    accountId: account.accountId,
+  });
   const ackReactionValue = ackReaction ?? "";
 
   const shouldAckReaction = () =>
@@ -452,18 +455,11 @@ export async function prepareSlackMessage(params: {
 
   const slackTo = isDirectMessage ? `user:${message.user}` : `channel:${message.channel}`;
 
-  const untrustedChannelMetadata = isRoomish
-    ? buildUntrustedChannelMetadata({
-        source: "slack",
-        label: "Slack channel description",
-        entries: [channelInfo?.topic, channelInfo?.purpose],
-      })
-    : undefined;
-  const systemPromptParts = [channelConfig?.systemPrompt?.trim() || null].filter(
-    (entry): entry is string => Boolean(entry),
-  );
-  const groupSystemPrompt =
-    systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : undefined;
+  const { untrustedChannelMetadata, groupSystemPrompt } = resolveSlackRoomContextHints({
+    isRoomish,
+    channelInfo,
+    channelConfig,
+  });
 
   let threadStarterBody: string | undefined;
   let threadHistoryBody: string | undefined;
diff --git a/src/slack/monitor/monitor.test.ts b/src/slack/monitor/monitor.test.ts
new file mode 100644
index 00000000000..0194642f799
--- /dev/null
+++ b/src/slack/monitor/monitor.test.ts
@@ -0,0 +1,289 @@
+import type { App } from "@slack/bolt";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { RuntimeEnv } from "../../runtime.js";
+import type { SlackMessageEvent } from "../types.js";
+import { resolveSlackChannelConfig } from "./channel-config.js";
+import { createSlackMonitorContext, normalizeSlackChannelType } from "./context.js";
+import { resetSlackThreadStarterCacheForTest, resolveSlackThreadStarter } from "./media.js";
+import { createSlackThreadTsResolver } from "./thread-resolution.js";
+
+describe("resolveSlackChannelConfig", () => {
+  it("uses defaultRequireMention when channels config is empty", () => {
+    const res = resolveSlackChannelConfig({
+      channelId: "C1",
+      channels: {},
+      defaultRequireMention: false,
+    });
+    expect(res).toEqual({ allowed: true, requireMention: false });
+  });
+
+  it("defaults defaultRequireMention to true when not provided", () => {
+    const res = resolveSlackChannelConfig({
+      channelId: "C1",
+      channels: {},
+    });
+    expect(res).toEqual({ allowed: true, requireMention: true });
+  });
+
+  it("prefers explicit channel/fallback requireMention over defaultRequireMention", () => {
+    const res = resolveSlackChannelConfig({
+      channelId: "C1",
+      channels: { "*": { requireMention: true } },
+      defaultRequireMention: false,
+    });
+    expect(res).toMatchObject({ requireMention: true });
+  });
+
+  it("uses wildcard entries when no direct channel config exists", () => {
+    const res = resolveSlackChannelConfig({
+      channelId: "C1",
+      channels: { "*": { allow: true, requireMention: false } },
+      defaultRequireMention: true,
+    });
+    expect(res).toMatchObject({
+      allowed: true,
+      requireMention: false,
+      matchKey: "*",
+      matchSource: "wildcard",
+    });
+  });
+
+  it("uses direct match metadata when channel config exists", () => {
+    const res = resolveSlackChannelConfig({
+      channelId: "C1",
+      channels: { C1: { allow: true, requireMention: false } },
+      defaultRequireMention: true,
+    });
+    expect(res).toMatchObject({
+      matchKey: "C1",
+      matchSource: "direct",
+    });
+  });
+});
+
+const baseParams = () => ({
+  cfg: {} as OpenClawConfig,
+  accountId: "default",
+  botToken: "token",
+  app: { client: {} } as App,
+  runtime: {} as RuntimeEnv,
+  botUserId: "B1",
+  teamId: "T1",
+  apiAppId: "A1",
+  historyLimit: 0,
+  sessionScope: "per-sender" as const,
+  mainKey: "main",
+  dmEnabled: true,
+  dmPolicy: "open" as const,
+  allowFrom: [],
+  groupDmEnabled: true,
+  groupDmChannels: [],
+  defaultRequireMention: true,
+  groupPolicy: "open" as const,
+  useAccessGroups: false,
+  reactionMode: "off" as const,
+  reactionAllowlist: [],
+  replyToMode: "off" as const,
+  slashCommand: {
+    enabled: false,
+    name: "openclaw",
+    sessionPrefix: "slack:slash",
+    ephemeral: true,
+  },
+  textLimit: 4000,
+  ackReactionScope: "group-mentions",
+  mediaMaxBytes: 1,
+  removeAckAfterReply: false,
+});
+
+describe("normalizeSlackChannelType", () => {
+  it("infers channel types from ids when missing", () => {
+    expect(normalizeSlackChannelType(undefined, "C123")).toBe("channel");
+    expect(normalizeSlackChannelType(undefined, "D123")).toBe("im");
+    expect(normalizeSlackChannelType(undefined, "G123")).toBe("group");
+  });
+
+  it("prefers explicit channel_type values", () => {
+    expect(normalizeSlackChannelType("mpim", "C123")).toBe("mpim");
+  });
+});
+
+describe("resolveSlackSystemEventSessionKey", () => {
+  it("defaults missing channel_type to channel sessions", () => {
+    const ctx = createSlackMonitorContext(baseParams());
+    expect(ctx.resolveSlackSystemEventSessionKey({ channelId: "C123" })).toBe(
+      "agent:main:slack:channel:c123",
+    );
+  });
+});
+
+describe("isChannelAllowed with groupPolicy and channelsConfig", () => {
+  it("allows unlisted channels when groupPolicy is open even with channelsConfig entries", () => {
+    // Bug fix: when groupPolicy="open" and channels has some entries,
+    // unlisted channels should still be allowed (not blocked)
+    const ctx = createSlackMonitorContext({
+      ...baseParams(),
+      groupPolicy: "open",
+      channelsConfig: {
+        C_LISTED: { requireMention: true },
+      },
+    });
+    // Listed channel should be allowed
+    expect(ctx.isChannelAllowed({ channelId: "C_LISTED", channelType: "channel" })).toBe(true);
+    // Unlisted channel should ALSO be allowed when policy is "open"
+    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(true);
+  });
+
+  it("blocks unlisted channels when groupPolicy is allowlist", () => {
+    const ctx = createSlackMonitorContext({
+      ...baseParams(),
+      groupPolicy: "allowlist",
+      channelsConfig: {
+        C_LISTED: { requireMention: true },
+      },
+    });
+    // Listed channel should be allowed
+    expect(ctx.isChannelAllowed({ channelId: "C_LISTED", channelType: "channel" })).toBe(true);
+    // Unlisted channel should be blocked when policy is "allowlist"
+    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(false);
+  });
+
+  it("blocks explicitly denied channels even when groupPolicy is open", () => {
+    const ctx = createSlackMonitorContext({
+      ...baseParams(),
+      groupPolicy: "open",
+      channelsConfig: {
+        C_ALLOWED: { allow: true },
+        C_DENIED: { allow: false },
+      },
+    });
+    // Explicitly allowed channel
+    expect(ctx.isChannelAllowed({ channelId: "C_ALLOWED", channelType: "channel" })).toBe(true);
+    // Explicitly denied channel should be blocked even with open policy
+    expect(ctx.isChannelAllowed({ channelId: "C_DENIED", channelType: "channel" })).toBe(false);
+    // Unlisted channel should be allowed with open policy
+    expect(ctx.isChannelAllowed({ channelId: "C_UNLISTED", channelType: "channel" })).toBe(true);
+  });
+
+  it("allows all channels when groupPolicy is open and channelsConfig is empty", () => {
+    const ctx = createSlackMonitorContext({
+      ...baseParams(),
+      groupPolicy: "open",
+      channelsConfig: undefined,
+    });
+    expect(ctx.isChannelAllowed({ channelId: "C_ANY", channelType: "channel" })).toBe(true);
+  });
+});
+
+describe("resolveSlackThreadStarter cache", () => {
+  afterEach(() => {
+    resetSlackThreadStarterCacheForTest();
+    vi.useRealTimers();
+  });
+
+  it("returns cached thread starter without refetching within ttl", async () => {
+    const replies = vi.fn(async () => ({
+      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
+    }));
+    const client = {
+      conversations: { replies },
+    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
+
+    const first = await resolveSlackThreadStarter({
+      channelId: "C1",
+      threadTs: "1000.1",
+      client,
+    });
+    const second = await resolveSlackThreadStarter({
+      channelId: "C1",
+      threadTs: "1000.1",
+      client,
+    });
+
+    expect(first).toEqual(second);
+    expect(replies).toHaveBeenCalledTimes(1);
+  });
+
+  it("expires stale cache entries and refetches after ttl", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+    const replies = vi.fn(async () => ({
+      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
+    }));
+    const client = {
+      conversations: { replies },
+    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
+
+    await resolveSlackThreadStarter({
+      channelId: "C1",
+      threadTs: "1000.1",
+      client,
+    });
+
+    vi.setSystemTime(new Date("2026-01-01T07:00:00.000Z"));
+    await resolveSlackThreadStarter({
+      channelId: "C1",
+      threadTs: "1000.1",
+      client,
+    });
+
+    expect(replies).toHaveBeenCalledTimes(2);
+  });
+
+  it("evicts oldest entries once cache exceeds bounded size", async () => {
+    const replies = vi.fn(async () => ({
+      messages: [{ text: "root message", user: "U1", ts: "1000.1" }],
+    }));
+    const client = {
+      conversations: { replies },
+    } as unknown as Parameters<typeof resolveSlackThreadStarter>[0]["client"];
+
+    // Cache cap is 2000; add enough distinct keys to force eviction of earliest keys.
+    for (let i = 0; i <= 2000; i += 1) {
+      await resolveSlackThreadStarter({
+        channelId: "C1",
+        threadTs: `1000.${i}`,
+        client,
+      });
+    }
+    const callsAfterFill = replies.mock.calls.length;
+
+    // Oldest key should be evicted and require fetch again.
+    await resolveSlackThreadStarter({
+      channelId: "C1",
+      threadTs: "1000.0",
+      client,
+    });
+
+    expect(replies.mock.calls.length).toBe(callsAfterFill + 1);
+  });
+});
+
+describe("createSlackThreadTsResolver", () => {
+  it("caches resolved thread_ts lookups", async () => {
+    const historyMock = vi.fn().mockResolvedValue({
+      messages: [{ ts: "1", thread_ts: "9" }],
+    });
+    const resolver = createSlackThreadTsResolver({
+      // oxlint-disable-next-line typescript/no-explicit-any
+      client: { conversations: { history: historyMock } } as any,
+      cacheTtlMs: 60_000,
+      maxSize: 5,
+    });
+
+    const message = {
+      channel: "C1",
+      parent_user_id: "U2",
+      ts: "1",
+    } as SlackMessageEvent;
+
+    const first = await resolver.resolve({ message, source: "message" });
+    const second = await resolver.resolve({ message, source: "message" });
+
+    expect(first.thread_ts).toBe("9");
+    expect(second.thread_ts).toBe("9");
+    expect(historyMock).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/slack/monitor/provider.ts b/src/slack/monitor/provider.ts
index a5c3a38b22f..6362cfcc8a0 100644
--- a/src/slack/monitor/provider.ts
+++ b/src/slack/monitor/provider.ts
@@ -5,6 +5,7 @@ import type { MonitorSlackOpts } from "./types.js";
 import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { DEFAULT_GROUP_HISTORY_LIMIT } from "../../auto-reply/reply/history.js";
 import {
+  addAllowlistUserEntriesFromConfigEntry,
   buildAllowlistResolutionSummary,
   mergeAllowlist,
   patchAllowlistUsersInConfigEntries,
@@ -226,7 +227,7 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
   const handleSlackMessage = createSlackMessageHandler({ ctx, account });
 
   registerSlackMonitorEvents({ ctx, account, handleSlackMessage });
-  registerSlackMonitorSlashCommands({ ctx, account });
+  await registerSlackMonitorSlashCommands({ ctx, account });
   if (slackMode === "http" && slackHttpHandler) {
     unregisterHttpHandler = registerSlackHttpHandler({
       path: slackWebhookPath,
@@ -283,18 +284,17 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
             token: resolveToken,
             entries: allowEntries.map((entry) => String(entry)),
           });
-          const mapping: string[] = [];
-          const unresolved: string[] = [];
-          const additions: string[] = [];
-          for (const entry of resolvedUsers) {
-            if (entry.resolved && entry.id) {
-              const note = entry.note ? ` (${entry.note})` : "";
-              mapping.push(`${entry.input}→${entry.id}${note}`);
-              additions.push(entry.id);
-            } else {
-              unresolved.push(entry.input);
-            }
-          }
+          const { mapping, unresolved, additions } = buildAllowlistResolutionSummary(
+            resolvedUsers,
+            {
+              formatResolved: (entry) => {
+                const note = (entry as { note?: string }).note
+                  ? ` (${(entry as { note?: string }).note})`
+                  : "";
+                return `${entry.input}→${entry.id}${note}`;
+              },
+            },
+          );
           allowFrom = mergeAllowlist({ existing: allowFrom, additions });
           ctx.allowFrom = normalizeAllowList(allowFrom);
           summarizeMapping("slack users", mapping, unresolved, runtime);
@@ -306,19 +306,7 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
       if (channelsConfig && Object.keys(channelsConfig).length > 0) {
         const userEntries = new Set<string>();
         for (const channel of Object.values(channelsConfig)) {
-          if (!channel || typeof channel !== "object") {
-            continue;
-          }
-          const channelUsers = (channel as { users?: Array<string | number> }).users;
-          if (!Array.isArray(channelUsers)) {
-            continue;
-          }
-          for (const entry of channelUsers) {
-            const trimmed = String(entry).trim();
-            if (trimmed && trimmed !== "*") {
-              userEntries.add(trimmed);
-            }
-          }
+          addAllowlistUserEntriesFromConfigEntry(userEntries, channel);
         }
 
         if (userEntries.size > 0) {
diff --git a/src/slack/monitor/room-context.ts b/src/slack/monitor/room-context.ts
new file mode 100644
index 00000000000..65359136227
--- /dev/null
+++ b/src/slack/monitor/room-context.ts
@@ -0,0 +1,31 @@
+import { buildUntrustedChannelMetadata } from "../../security/channel-metadata.js";
+
+export function resolveSlackRoomContextHints(params: {
+  isRoomish: boolean;
+  channelInfo?: { topic?: string; purpose?: string };
+  channelConfig?: { systemPrompt?: string | null } | null;
+}): {
+  untrustedChannelMetadata?: ReturnType<typeof buildUntrustedChannelMetadata>;
+  groupSystemPrompt?: string;
+} {
+  if (!params.isRoomish) {
+    return {};
+  }
+
+  const untrustedChannelMetadata = buildUntrustedChannelMetadata({
+    source: "slack",
+    label: "Slack channel description",
+    entries: [params.channelInfo?.topic, params.channelInfo?.purpose],
+  });
+
+  const systemPromptParts = [params.channelConfig?.systemPrompt?.trim() || null].filter(
+    (entry): entry is string => Boolean(entry),
+  );
+  const groupSystemPrompt =
+    systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : undefined;
+
+  return {
+    untrustedChannelMetadata,
+    groupSystemPrompt,
+  };
+}
diff --git a/src/slack/monitor/slash.policy.test.ts b/src/slack/monitor/slash.policy.test.ts
deleted file mode 100644
index 108ed91f266..00000000000
--- a/src/slack/monitor/slash.policy.test.ts
+++ /dev/null
@@ -1,279 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { getSlackSlashMocks, resetSlackSlashMocks } from "./slash.test-harness.js";
-
-const { dispatchMock } = getSlackSlashMocks();
-
-beforeEach(() => {
-  resetSlackSlashMocks();
-});
-
-async function registerCommands(ctx: unknown, account: unknown) {
-  const { registerSlackMonitorSlashCommands } = await import("./slash.js");
-  registerSlackMonitorSlashCommands({ ctx: ctx as never, account: account as never });
-}
-
-function createHarness(overrides?: {
-  groupPolicy?: "open" | "allowlist";
-  channelsConfig?: Record<string, { allow?: boolean; requireMention?: boolean }>;
-  channelId?: string;
-  channelName?: string;
-  allowFrom?: string[];
-  useAccessGroups?: boolean;
-  resolveChannelName?: () => Promise<{ name?: string; type?: string }>;
-}) {
-  const commands = new Map<unknown, (args: unknown) => Promise<void>>();
-  const postEphemeral = vi.fn().mockResolvedValue({ ok: true });
-  const app = {
-    client: { chat: { postEphemeral } },
-    command: (name: unknown, handler: (args: unknown) => Promise<void>) => {
-      commands.set(name, handler);
-    },
-  };
-
-  const channelId = overrides?.channelId ?? "C_UNLISTED";
-  const channelName = overrides?.channelName ?? "unlisted";
-
-  const ctx = {
-    cfg: { commands: { native: false } },
-    runtime: {},
-    botToken: "bot-token",
-    botUserId: "bot",
-    teamId: "T1",
-    allowFrom: overrides?.allowFrom ?? ["*"],
-    dmEnabled: true,
-    dmPolicy: "open",
-    groupDmEnabled: false,
-    groupDmChannels: [],
-    defaultRequireMention: true,
-    groupPolicy: overrides?.groupPolicy ?? "open",
-    useAccessGroups: overrides?.useAccessGroups ?? true,
-    channelsConfig: overrides?.channelsConfig,
-    slashCommand: {
-      enabled: true,
-      name: "openclaw",
-      ephemeral: true,
-      sessionPrefix: "slack:slash",
-    },
-    textLimit: 4000,
-    app,
-    isChannelAllowed: () => true,
-    resolveChannelName:
-      overrides?.resolveChannelName ?? (async () => ({ name: channelName, type: "channel" })),
-    resolveUserName: async () => ({ name: "Ada" }),
-  } as unknown;
-
-  const account = { accountId: "acct", config: { commands: { native: false } } } as unknown;
-
-  return { commands, ctx, account, postEphemeral, channelId, channelName };
-}
-
-async function runSlashHandler(params: {
-  commands: Map<unknown, (args: unknown) => Promise<void>>;
-  command: Partial<{
-    user_id: string;
-    user_name: string;
-    channel_id: string;
-    channel_name: string;
-    text: string;
-    trigger_id: string;
-  }> &
-    Pick<{ channel_id: string; channel_name: string }, "channel_id" | "channel_name">;
-}): Promise<{ respond: ReturnType<typeof vi.fn>; ack: ReturnType<typeof vi.fn> }> {
-  const handler = [...params.commands.values()][0];
-  if (!handler) {
-    throw new Error("Missing slash handler");
-  }
-
-  const respond = vi.fn().mockResolvedValue(undefined);
-  const ack = vi.fn().mockResolvedValue(undefined);
-
-  await handler({
-    command: {
-      user_id: "U1",
-      user_name: "Ada",
-      text: "hello",
-      trigger_id: "t1",
-      ...params.command,
-    },
-    ack,
-    respond,
-  });
-
-  return { respond, ack };
-}
-
-describe("slack slash commands channel policy", () => {
-  it("allows unlisted channels when groupPolicy is open", async () => {
-    const { commands, ctx, account, channelId, channelName } = createHarness({
-      groupPolicy: "open",
-      channelsConfig: { C_LISTED: { requireMention: true } },
-      channelId: "C_UNLISTED",
-      channelName: "unlisted",
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: channelId,
-        channel_name: channelName,
-      },
-    });
-
-    expect(dispatchMock).toHaveBeenCalledTimes(1);
-    expect(respond).not.toHaveBeenCalledWith(
-      expect.objectContaining({ text: "This channel is not allowed." }),
-    );
-  });
-
-  it("blocks explicitly denied channels when groupPolicy is open", async () => {
-    const { commands, ctx, account, channelId, channelName } = createHarness({
-      groupPolicy: "open",
-      channelsConfig: { C_DENIED: { allow: false } },
-      channelId: "C_DENIED",
-      channelName: "denied",
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: channelId,
-        channel_name: channelName,
-      },
-    });
-
-    expect(dispatchMock).not.toHaveBeenCalled();
-    expect(respond).toHaveBeenCalledWith({
-      text: "This channel is not allowed.",
-      response_type: "ephemeral",
-    });
-  });
-
-  it("blocks unlisted channels when groupPolicy is allowlist", async () => {
-    const { commands, ctx, account, channelId, channelName } = createHarness({
-      groupPolicy: "allowlist",
-      channelsConfig: { C_LISTED: { requireMention: true } },
-      channelId: "C_UNLISTED",
-      channelName: "unlisted",
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: channelId,
-        channel_name: channelName,
-      },
-    });
-
-    expect(dispatchMock).not.toHaveBeenCalled();
-    expect(respond).toHaveBeenCalledWith({
-      text: "This channel is not allowed.",
-      response_type: "ephemeral",
-    });
-  });
-});
-
-describe("slack slash commands access groups", () => {
-  it("fails closed when channel type lookup returns empty for channels", async () => {
-    const { commands, ctx, account, channelId, channelName } = createHarness({
-      allowFrom: [],
-      channelId: "C_UNKNOWN",
-      channelName: "unknown",
-      resolveChannelName: async () => ({}),
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: channelId,
-        channel_name: channelName,
-      },
-    });
-
-    expect(dispatchMock).not.toHaveBeenCalled();
-    expect(respond).toHaveBeenCalledWith({
-      text: "You are not authorized to use this command.",
-      response_type: "ephemeral",
-    });
-  });
-
-  it("still treats D-prefixed channel ids as DMs when lookup fails", async () => {
-    const { commands, ctx, account } = createHarness({
-      allowFrom: [],
-      channelId: "D123",
-      channelName: "notdirectmessage",
-      resolveChannelName: async () => ({}),
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: "D123",
-        channel_name: "notdirectmessage",
-      },
-    });
-
-    expect(dispatchMock).toHaveBeenCalledTimes(1);
-    expect(respond).not.toHaveBeenCalledWith(
-      expect.objectContaining({ text: "You are not authorized to use this command." }),
-    );
-    const dispatchArg = dispatchMock.mock.calls[0]?.[0] as {
-      ctx?: { CommandAuthorized?: boolean };
-    };
-    expect(dispatchArg?.ctx?.CommandAuthorized).toBe(false);
-  });
-
-  it("computes CommandAuthorized for DM slash commands when dmPolicy is open", async () => {
-    const { commands, ctx, account } = createHarness({
-      allowFrom: ["U_OWNER"],
-      channelId: "D999",
-      channelName: "directmessage",
-      resolveChannelName: async () => ({ name: "directmessage", type: "im" }),
-    });
-    await registerCommands(ctx, account);
-
-    await runSlashHandler({
-      commands,
-      command: {
-        user_id: "U_ATTACKER",
-        user_name: "Mallory",
-        channel_id: "D999",
-        channel_name: "directmessage",
-      },
-    });
-
-    expect(dispatchMock).toHaveBeenCalledTimes(1);
-    const dispatchArg = dispatchMock.mock.calls[0]?.[0] as {
-      ctx?: { CommandAuthorized?: boolean };
-    };
-    expect(dispatchArg?.ctx?.CommandAuthorized).toBe(false);
-  });
-
-  it("enforces access-group gating when lookup fails for private channels", async () => {
-    const { commands, ctx, account, channelId, channelName } = createHarness({
-      allowFrom: [],
-      channelId: "G123",
-      channelName: "private",
-      resolveChannelName: async () => ({}),
-    });
-    await registerCommands(ctx, account);
-
-    const { respond } = await runSlashHandler({
-      commands,
-      command: {
-        channel_id: channelId,
-        channel_name: channelName,
-      },
-    });
-
-    expect(dispatchMock).not.toHaveBeenCalled();
-    expect(respond).toHaveBeenCalledWith({
-      text: "You are not authorized to use this command.",
-      response_type: "ephemeral",
-    });
-  });
-});
diff --git a/src/slack/monitor/slash.test-harness.ts b/src/slack/monitor/slash.test-harness.ts
index 20f4e65afee..9935b347897 100644
--- a/src/slack/monitor/slash.test-harness.ts
+++ b/src/slack/monitor/slash.test-harness.ts
@@ -5,6 +5,9 @@ const mocks = vi.hoisted(() => ({
   readAllowFromStoreMock: vi.fn(),
   upsertPairingRequestMock: vi.fn(),
   resolveAgentRouteMock: vi.fn(),
+  finalizeInboundContextMock: vi.fn(),
+  resolveConversationLabelMock: vi.fn(),
+  createReplyPrefixOptionsMock: vi.fn(),
 }));
 
 vi.mock("../../auto-reply/reply/provider-dispatcher.js", () => ({
@@ -20,15 +23,29 @@ vi.mock("../../routing/resolve-route.js", () => ({
   resolveAgentRoute: (...args: unknown[]) => mocks.resolveAgentRouteMock(...args),
 }));
 
-vi.mock("../../agents/identity.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../agents/identity.js")>();
-  return {
-    ...actual,
-    resolveEffectiveMessagesConfig: () => ({ responsePrefix: "" }),
-  };
-});
+vi.mock("../../auto-reply/reply/inbound-context.js", () => ({
+  finalizeInboundContext: (...args: unknown[]) => mocks.finalizeInboundContextMock(...args),
+}));
 
-export function getSlackSlashMocks() {
+vi.mock("../../channels/conversation-label.js", () => ({
+  resolveConversationLabel: (...args: unknown[]) => mocks.resolveConversationLabelMock(...args),
+}));
+
+vi.mock("../../channels/reply-prefix.js", () => ({
+  createReplyPrefixOptions: (...args: unknown[]) => mocks.createReplyPrefixOptionsMock(...args),
+}));
+
+type SlashHarnessMocks = {
+  dispatchMock: ReturnType<typeof vi.fn>;
+  readAllowFromStoreMock: ReturnType<typeof vi.fn>;
+  upsertPairingRequestMock: ReturnType<typeof vi.fn>;
+  resolveAgentRouteMock: ReturnType<typeof vi.fn>;
+  finalizeInboundContextMock: ReturnType<typeof vi.fn>;
+  resolveConversationLabelMock: ReturnType<typeof vi.fn>;
+  createReplyPrefixOptionsMock: ReturnType<typeof vi.fn>;
+};
+
+export function getSlackSlashMocks(): SlashHarnessMocks {
   return mocks;
 }
 
@@ -41,4 +58,7 @@ export function resetSlackSlashMocks() {
     sessionKey: "session:1",
     accountId: "acct",
   });
+  mocks.finalizeInboundContextMock.mockReset().mockImplementation((ctx: unknown) => ctx);
+  mocks.resolveConversationLabelMock.mockReset().mockReturnValue(undefined);
+  mocks.createReplyPrefixOptionsMock.mockReset().mockReturnValue({ onModelSelected: () => {} });
 }
diff --git a/src/slack/monitor/slash.command-arg-menus.test.ts b/src/slack/monitor/slash.test.ts
similarity index 50%
rename from src/slack/monitor/slash.command-arg-menus.test.ts
rename to src/slack/monitor/slash.test.ts
index 15931947973..2f9e9c69cfd 100644
--- a/src/slack/monitor/slash.command-arg-menus.test.ts
+++ b/src/slack/monitor/slash.test.ts
@@ -1,15 +1,69 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { getSlackSlashMocks, resetSlackSlashMocks } from "./slash.test-harness.js";
 
+vi.mock("../../auto-reply/commands-registry.js", () => {
+  const usageCommand = { key: "usage", nativeName: "usage" };
+
+  return {
+    buildCommandTextFromArgs: (
+      cmd: { nativeName?: string; key: string },
+      args?: { values?: Record<string, unknown> },
+    ) => {
+      const name = cmd.nativeName ?? cmd.key;
+      const mode = args?.values?.mode;
+      return typeof mode === "string" && mode.trim() ? `/${name} ${mode.trim()}` : `/${name}`;
+    },
+    findCommandByNativeName: (name: string) => {
+      return name.trim().toLowerCase() === "usage" ? usageCommand : undefined;
+    },
+    listNativeCommandSpecsForConfig: () => [
+      {
+        name: "usage",
+        description: "Usage",
+        acceptsArgs: true,
+        args: [],
+      },
+    ],
+    parseCommandArgs: () => ({ values: {} }),
+    resolveCommandArgMenu: (params: {
+      command?: { key?: string };
+      args?: { values?: unknown };
+    }) => {
+      if (params.command?.key !== "usage") {
+        return null;
+      }
+      const values = (params.args?.values ?? {}) as Record<string, unknown>;
+      if (typeof values.mode === "string" && values.mode.trim()) {
+        return null;
+      }
+      return {
+        arg: { name: "mode", description: "mode" },
+        choices: [
+          { value: "tokens", label: "tokens" },
+          { value: "cost", label: "cost" },
+        ],
+      };
+    },
+  };
+});
+
+type RegisterFn = (params: { ctx: unknown; account: unknown }) => Promise<void>;
+let registerSlackMonitorSlashCommands: RegisterFn;
+
 const { dispatchMock } = getSlackSlashMocks();
 
+beforeAll(async () => {
+  ({ registerSlackMonitorSlashCommands } = (await import("./slash.js")) as unknown as {
+    registerSlackMonitorSlashCommands: RegisterFn;
+  });
+});
+
 beforeEach(() => {
   resetSlackSlashMocks();
 });
 
 async function registerCommands(ctx: unknown, account: unknown) {
-  const { registerSlackMonitorSlashCommands } = await import("./slash.js");
-  registerSlackMonitorSlashCommands({ ctx: ctx as never, account: account as never });
+  await registerSlackMonitorSlashCommands({ ctx: ctx as never, account: account as never });
 }
 
 function encodeValue(parts: { command: string; arg: string; value: string; userId: string }) {
@@ -22,7 +76,7 @@ function encodeValue(parts: { command: string; arg: string; value: string; userI
   ].join("|");
 }
 
-function createHarness() {
+function createArgMenusHarness() {
   const commands = new Map<string, (args: unknown) => Promise<void>>();
   const actions = new Map<string, (args: unknown) => Promise<void>>();
 
@@ -38,7 +92,7 @@ function createHarness() {
   };
 
   const ctx = {
-    cfg: { commands: { native: true } },
+    cfg: { commands: { native: true, nativeSkills: false } },
     runtime: {},
     botToken: "bot-token",
     botUserId: "bot",
@@ -65,54 +119,36 @@ function createHarness() {
     resolveUserName: async () => ({ name: "Ada" }),
   } as unknown;
 
-  const account = { accountId: "acct", config: { commands: { native: true } } } as unknown;
+  const account = {
+    accountId: "acct",
+    config: { commands: { native: true, nativeSkills: false } },
+  } as unknown;
 
   return { commands, actions, postEphemeral, ctx, account };
 }
 
 describe("Slack native command argument menus", () => {
-  it("shows a button menu when required args are omitted", async () => {
-    const { commands, ctx, account } = createHarness();
-    await registerCommands(ctx, account);
+  let harness: ReturnType<typeof createArgMenusHarness>;
+  let argMenuHandler: (args: unknown) => Promise<void>;
 
-    const handler = commands.get("/usage");
-    if (!handler) {
-      throw new Error("Missing /usage handler");
+  beforeAll(async () => {
+    harness = createArgMenusHarness();
+    await registerCommands(harness.ctx, harness.account);
+
+    const argMenu = harness.actions.get("openclaw_cmdarg");
+    if (!argMenu) {
+      throw new Error("Missing arg-menu action handler");
     }
+    argMenuHandler = argMenu;
+  });
 
-    const respond = vi.fn().mockResolvedValue(undefined);
-    const ack = vi.fn().mockResolvedValue(undefined);
-
-    await handler({
-      command: {
-        user_id: "U1",
-        user_name: "Ada",
-        channel_id: "C1",
-        channel_name: "directmessage",
-        text: "",
-        trigger_id: "t1",
-      },
-      ack,
-      respond,
-    });
-
-    expect(respond).toHaveBeenCalledTimes(1);
-    const payload = respond.mock.calls[0]?.[0] as { blocks?: Array<{ type: string }> };
-    expect(payload.blocks?.[0]?.type).toBe("section");
-    expect(payload.blocks?.[1]?.type).toBe("actions");
+  beforeEach(() => {
+    harness.postEphemeral.mockClear();
   });
 
   it("dispatches the command when a menu button is clicked", async () => {
-    const { actions, ctx, account } = createHarness();
-    await registerCommands(ctx, account);
-
-    const handler = actions.get("openclaw_cmdarg");
-    if (!handler) {
-      throw new Error("Missing arg-menu action handler");
-    }
-
     const respond = vi.fn().mockResolvedValue(undefined);
-    await handler({
+    await argMenuHandler({
       ack: vi.fn().mockResolvedValue(undefined),
       action: {
         value: encodeValue({ command: "usage", arg: "mode", value: "tokens", userId: "U1" }),
@@ -131,16 +167,8 @@ describe("Slack native command argument menus", () => {
   });
 
   it("rejects menu clicks from other users", async () => {
-    const { actions, ctx, account } = createHarness();
-    await registerCommands(ctx, account);
-
-    const handler = actions.get("openclaw_cmdarg");
-    if (!handler) {
-      throw new Error("Missing arg-menu action handler");
-    }
-
     const respond = vi.fn().mockResolvedValue(undefined);
-    await handler({
+    await argMenuHandler({
       ack: vi.fn().mockResolvedValue(undefined),
       action: {
         value: encodeValue({ command: "usage", arg: "mode", value: "tokens", userId: "U1" }),
@@ -159,53 +187,4 @@ describe("Slack native command argument menus", () => {
       response_type: "ephemeral",
     });
   });
-
-  it("falls back to postEphemeral with token when respond is unavailable", async () => {
-    const { actions, postEphemeral, ctx, account } = createHarness();
-    await registerCommands(ctx, account);
-
-    const handler = actions.get("openclaw_cmdarg");
-    if (!handler) {
-      throw new Error("Missing arg-menu action handler");
-    }
-
-    await handler({
-      ack: vi.fn().mockResolvedValue(undefined),
-      action: { value: "garbage" },
-      body: { user: { id: "U1" }, channel: { id: "C1" } },
-    });
-
-    expect(postEphemeral).toHaveBeenCalledWith(
-      expect.objectContaining({
-        token: "bot-token",
-        channel: "C1",
-        user: "U1",
-      }),
-    );
-  });
-
-  it("treats malformed percent-encoding as an invalid button (no throw)", async () => {
-    const { actions, postEphemeral, ctx, account } = createHarness();
-    await registerCommands(ctx, account);
-
-    const handler = actions.get("openclaw_cmdarg");
-    if (!handler) {
-      throw new Error("Missing arg-menu action handler");
-    }
-
-    await handler({
-      ack: vi.fn().mockResolvedValue(undefined),
-      action: { value: "cmdarg|%E0%A4%A|mode|on|U1" },
-      body: { user: { id: "U1" }, channel: { id: "C1" } },
-    });
-
-    expect(postEphemeral).toHaveBeenCalledWith(
-      expect.objectContaining({
-        token: "bot-token",
-        channel: "C1",
-        user: "U1",
-        text: "Sorry, that button is no longer valid.",
-      }),
-    );
-  });
 });
diff --git a/src/slack/monitor/slash.ts b/src/slack/monitor/slash.ts
index 3ee2b30833d..4e14986d4f9 100644
--- a/src/slack/monitor/slash.ts
+++ b/src/slack/monitor/slash.ts
@@ -1,32 +1,18 @@
 import type { SlackActionMiddlewareArgs, SlackCommandMiddlewareArgs } from "@slack/bolt";
 import type { ChatCommandDefinition, CommandArgs } from "../../auto-reply/commands-registry.js";
+import type { ReplyPayload } from "../../auto-reply/types.js";
 import type { ResolvedSlackAccount } from "../accounts.js";
 import type { SlackMonitorContext } from "./context.js";
-import { resolveChunkMode } from "../../auto-reply/chunk.js";
-import {
-  buildCommandTextFromArgs,
-  findCommandByNativeName,
-  listNativeCommandSpecsForConfig,
-  parseCommandArgs,
-  resolveCommandArgMenu,
-} from "../../auto-reply/commands-registry.js";
-import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
-import { dispatchReplyWithDispatcher } from "../../auto-reply/reply/provider-dispatcher.js";
-import { listSkillCommandsForAgents } from "../../auto-reply/skill-commands.js";
 import { formatAllowlistMatchMeta } from "../../channels/allowlist-match.js";
 import { resolveCommandAuthorizedFromAuthorizers } from "../../channels/command-gating.js";
-import { resolveConversationLabel } from "../../channels/conversation-label.js";
-import { createReplyPrefixOptions } from "../../channels/reply-prefix.js";
 import { resolveNativeCommandsEnabled, resolveNativeSkillsEnabled } from "../../config/commands.js";
-import { resolveMarkdownTableMode } from "../../config/markdown-tables.js";
 import { danger, logVerbose } from "../../globals.js";
 import { buildPairingReply } from "../../pairing/pairing-messages.js";
 import {
   readChannelAllowFromStore,
   upsertChannelPairingRequest,
 } from "../../pairing/pairing-store.js";
-import { resolveAgentRoute } from "../../routing/resolve-route.js";
-import { buildUntrustedChannelMetadata } from "../../security/channel-metadata.js";
+import { chunkItems } from "../../utils/chunk-items.js";
 import {
   normalizeAllowList,
   normalizeAllowListLower,
@@ -37,22 +23,20 @@ import { resolveSlackChannelConfig, type SlackChannelConfigResolved } from "./ch
 import { buildSlackSlashCommandMatcher, resolveSlackSlashCommandConfig } from "./commands.js";
 import { normalizeSlackChannelType } from "./context.js";
 import { isSlackChannelAllowedByPolicy } from "./policy.js";
-import { deliverSlackSlashReplies } from "./replies.js";
+import { resolveSlackRoomContextHints } from "./room-context.js";
 
 type SlackBlock = { type: string; [key: string]: unknown };
 
 const SLACK_COMMAND_ARG_ACTION_ID = "openclaw_cmdarg";
 const SLACK_COMMAND_ARG_VALUE_PREFIX = "cmdarg";
 
-function chunkItems<T>(items: T[], size: number): T[][] {
-  if (size <= 0) {
-    return [items];
+type CommandsRegistry = typeof import("../../auto-reply/commands-registry.js");
+let commandsRegistry: CommandsRegistry | undefined;
+async function getCommandsRegistry(): Promise<CommandsRegistry> {
+  if (!commandsRegistry) {
+    commandsRegistry = await import("../../auto-reply/commands-registry.js");
   }
-  const rows: T[][] = [];
-  for (let i = 0; i < items.length; i += size) {
-    rows.push(items.slice(i, i + size));
-  }
-  return rows;
+  return commandsRegistry;
 }
 
 function encodeSlackCommandArgValue(parts: {
@@ -139,10 +123,10 @@ function buildSlackCommandArgMenuBlocks(params: {
   ];
 }
 
-export function registerSlackMonitorSlashCommands(params: {
+export async function registerSlackMonitorSlashCommands(params: {
   ctx: SlackMonitorContext;
   account: ResolvedSlackAccount;
-}) {
+}): Promise<void> {
   const { ctx, account } = params;
   const cfg = ctx.cfg;
   const runtime = ctx.runtime;
@@ -349,7 +333,8 @@ export function registerSlackMonitorSlashCommands(params: {
       }
 
       if (commandDefinition && supportsInteractiveArgMenus) {
-        const menu = resolveCommandArgMenu({
+        const reg = await getCommandsRegistry();
+        const menu = reg.resolveCommandArgMenu({
           command: commandDefinition,
           args: commandArgs,
           cfg,
@@ -376,6 +361,17 @@ export function registerSlackMonitorSlashCommands(params: {
 
       const channelName = channelInfo?.name;
       const roomLabel = channelName ? `#${channelName}` : `#${command.channel_id}`;
+      const [{ resolveAgentRoute }, { finalizeInboundContext }, { dispatchReplyWithDispatcher }] =
+        await Promise.all([
+          import("../../routing/resolve-route.js"),
+          import("../../auto-reply/reply/inbound-context.js"),
+          import("../../auto-reply/reply/provider-dispatcher.js"),
+        ]);
+      const [{ resolveConversationLabel }, { createReplyPrefixOptions }] = await Promise.all([
+        import("../../channels/conversation-label.js"),
+        import("../../channels/reply-prefix.js"),
+      ]);
+
       const route = resolveAgentRoute({
         cfg,
         channel: "slack",
@@ -387,18 +383,11 @@ export function registerSlackMonitorSlashCommands(params: {
         },
       });
 
-      const untrustedChannelMetadata = isRoomish
-        ? buildUntrustedChannelMetadata({
-            source: "slack",
-            label: "Slack channel description",
-            entries: [channelInfo?.topic, channelInfo?.purpose],
-          })
-        : undefined;
-      const systemPromptParts = [channelConfig?.systemPrompt?.trim() || null].filter(
-        (entry): entry is string => Boolean(entry),
-      );
-      const groupSystemPrompt =
-        systemPromptParts.length > 0 ? systemPromptParts.join("\n\n") : undefined;
+      const { untrustedChannelMetadata, groupSystemPrompt } = resolveSlackRoomContextHints({
+        isRoomish,
+        channelInfo,
+        channelConfig,
+      });
 
       const ctxPayload = finalizeInboundContext({
         Body: prompt,
@@ -451,37 +440,15 @@ export function registerSlackMonitorSlashCommands(params: {
         accountId: route.accountId,
       });
 
-      const { counts } = await dispatchReplyWithDispatcher({
-        ctx: ctxPayload,
-        cfg,
-        dispatcherOptions: {
-          ...prefixOptions,
-          deliver: async (payload) => {
-            await deliverSlackSlashReplies({
-              replies: [payload],
-              respond,
-              ephemeral: slashCommand.ephemeral,
-              textLimit: ctx.textLimit,
-              chunkMode: resolveChunkMode(cfg, "slack", route.accountId),
-              tableMode: resolveMarkdownTableMode({
-                cfg,
-                channel: "slack",
-                accountId: route.accountId,
-              }),
-            });
-          },
-          onError: (err, info) => {
-            runtime.error?.(danger(`slack slash ${info.kind} reply failed: ${String(err)}`));
-          },
-        },
-        replyOptions: {
-          skillFilter: channelConfig?.skills,
-          onModelSelected,
-        },
-      });
-      if (counts.final + counts.tool + counts.block === 0) {
+      const deliverSlashPayloads = async (replies: ReplyPayload[]) => {
+        const [{ deliverSlackSlashReplies }, { resolveChunkMode }, { resolveMarkdownTableMode }] =
+          await Promise.all([
+            import("./replies.js"),
+            import("../../auto-reply/chunk.js"),
+            import("../../config/markdown-tables.js"),
+          ]);
         await deliverSlackSlashReplies({
-          replies: [],
+          replies,
           respond,
           ephemeral: slashCommand.ephemeral,
           textLimit: ctx.textLimit,
@@ -492,6 +459,25 @@ export function registerSlackMonitorSlashCommands(params: {
             accountId: route.accountId,
           }),
         });
+      };
+
+      const { counts } = await dispatchReplyWithDispatcher({
+        ctx: ctxPayload,
+        cfg,
+        dispatcherOptions: {
+          ...prefixOptions,
+          deliver: async (payload) => deliverSlashPayloads([payload]),
+          onError: (err, info) => {
+            runtime.error?.(danger(`slack slash ${info.kind} reply failed: ${String(err)}`));
+          },
+        },
+        replyOptions: {
+          skillFilter: channelConfig?.skills,
+          onModelSelected,
+        },
+      });
+      if (counts.final + counts.tool + counts.block === 0) {
+        await deliverSlashPayloads([]);
       }
     } catch (err) {
       runtime.error?.(danger(`slack slash handler failed: ${String(err)}`));
@@ -512,25 +498,35 @@ export function registerSlackMonitorSlashCommands(params: {
     providerSetting: account.config.commands?.nativeSkills,
     globalSetting: cfg.commands?.nativeSkills,
   });
-  const skillCommands =
-    nativeEnabled && nativeSkillsEnabled ? listSkillCommandsForAgents({ cfg }) : [];
-  const nativeCommands = nativeEnabled
-    ? listNativeCommandSpecsForConfig(cfg, { skillCommands, provider: "slack" })
-    : [];
+
+  let reg: CommandsRegistry | undefined;
+  let nativeCommands: Array<{ name: string }> = [];
+  if (nativeEnabled) {
+    reg = await getCommandsRegistry();
+    const skillCommands = nativeSkillsEnabled
+      ? (await import("../../auto-reply/skill-commands.js")).listSkillCommandsForAgents({ cfg })
+      : [];
+    nativeCommands = reg.listNativeCommandSpecsForConfig(cfg, { skillCommands, provider: "slack" });
+  }
+
   if (nativeCommands.length > 0) {
+    const registry = reg;
+    if (!registry) {
+      throw new Error("Missing commands registry for native Slack commands.");
+    }
     for (const command of nativeCommands) {
       ctx.app.command(
         `/${command.name}`,
         async ({ command: cmd, ack, respond }: SlackCommandMiddlewareArgs) => {
-          const commandDefinition = findCommandByNativeName(command.name, "slack");
+          const commandDefinition = registry.findCommandByNativeName(command.name, "slack");
           const rawText = cmd.text?.trim() ?? "";
           const commandArgs = commandDefinition
-            ? parseCommandArgs(commandDefinition, rawText)
+            ? registry.parseCommandArgs(commandDefinition, rawText)
             : rawText
               ? ({ raw: rawText } satisfies CommandArgs)
               : undefined;
           const prompt = commandDefinition
-            ? buildCommandTextFromArgs(commandDefinition, commandArgs)
+            ? registry.buildCommandTextFromArgs(commandDefinition, commandArgs)
             : rawText
               ? `/${command.name} ${rawText}`
               : `/${command.name}`;
@@ -603,12 +599,13 @@ export function registerSlackMonitorSlashCommands(params: {
         });
         return;
       }
-      const commandDefinition = findCommandByNativeName(parsed.command, "slack");
+      const reg = await getCommandsRegistry();
+      const commandDefinition = reg.findCommandByNativeName(parsed.command, "slack");
       const commandArgs: CommandArgs = {
         values: { [parsed.arg]: parsed.value },
       };
       const prompt = commandDefinition
-        ? buildCommandTextFromArgs(commandDefinition, commandArgs)
+        ? reg.buildCommandTextFromArgs(commandDefinition, commandArgs)
         : `/${parsed.command} ${parsed.value}`;
       const user = body.user;
       const userName =
diff --git a/src/slack/monitor/thread-resolution.test.ts b/src/slack/monitor/thread-resolution.test.ts
deleted file mode 100644
index 5de8c74bd8f..00000000000
--- a/src/slack/monitor/thread-resolution.test.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { SlackMessageEvent } from "../types.js";
-import { createSlackThreadTsResolver } from "./thread-resolution.js";
-
-describe("createSlackThreadTsResolver", () => {
-  it("caches resolved thread_ts lookups", async () => {
-    const historyMock = vi.fn().mockResolvedValue({
-      messages: [{ ts: "1", thread_ts: "9" }],
-    });
-    const resolver = createSlackThreadTsResolver({
-      // oxlint-disable-next-line typescript/no-explicit-any
-      client: { conversations: { history: historyMock } } as any,
-      cacheTtlMs: 60_000,
-      maxSize: 5,
-    });
-
-    const message = {
-      channel: "C1",
-      parent_user_id: "U2",
-      ts: "1",
-    } as SlackMessageEvent;
-
-    const first = await resolver.resolve({ message, source: "message" });
-    const second = await resolver.resolve({ message, source: "message" });
-
-    expect(first.thread_ts).toBe("9");
-    expect(second.thread_ts).toBe("9");
-    expect(historyMock).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/slack/probe.ts b/src/slack/probe.ts
index cde5e515737..22857ca2bc6 100644
--- a/src/slack/probe.ts
+++ b/src/slack/probe.ts
@@ -1,29 +1,14 @@
+import type { BaseProbeResult } from "../channels/plugins/types.js";
+import { withTimeout } from "../utils/with-timeout.js";
 import { createSlackWebClient } from "./client.js";
 
-export type SlackProbe = {
-  ok: boolean;
+export type SlackProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs?: number | null;
   bot?: { id?: string; name?: string };
   team?: { id?: string; name?: string };
 };
 
-function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  if (!timeoutMs || timeoutMs <= 0) {
-    return promise;
-  }
-  let timer: NodeJS.Timeout | null = null;
-  const timeout = new Promise<T>((_, reject) => {
-    timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
-  });
-  return Promise.race([promise, timeout]).finally(() => {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  });
-}
-
 export async function probeSlack(token: string, timeoutMs = 2500): Promise<SlackProbe> {
   const client = createSlackWebClient(token);
   const start = Date.now();
diff --git a/src/telegram/audit.ts b/src/telegram/audit.ts
index 48e4a923f8b..b86953fa1b1 100644
--- a/src/telegram/audit.ts
+++ b/src/telegram/audit.ts
@@ -1,7 +1,5 @@
 import type { TelegramGroupConfig } from "../config/types.js";
 import { isRecord } from "../utils.js";
-import { fetchWithTimeout } from "../utils/fetch-timeout.js";
-import { makeProxyFetch } from "./proxy.js";
 
 const TELEGRAM_API_BASE = "https://api.telegram.org";
 
@@ -87,7 +85,12 @@ export async function auditTelegramGroupMembership(params: {
     };
   }
 
-  const fetcher = params.proxyUrl ? makeProxyFetch(params.proxyUrl) : fetch;
+  // Lazy import to avoid pulling `undici` (ProxyAgent) into cold-path callers that only need
+  // `collectTelegramUnmentionedGroupIds` (e.g. config audits).
+  const fetcher = params.proxyUrl
+    ? (await import("./proxy.js")).makeProxyFetch(params.proxyUrl)
+    : fetch;
+  const { fetchWithTimeout } = await import("../utils/fetch-timeout.js");
   const base = `${TELEGRAM_API_BASE}/bot${token}`;
   const groups: TelegramGroupMembershipAuditEntry[] = [];
 
diff --git a/src/telegram/bot-handlers.ts b/src/telegram/bot-handlers.ts
index 910956635d1..bd1a7bfa4bd 100644
--- a/src/telegram/bot-handlers.ts
+++ b/src/telegram/bot-handlers.ts
@@ -1,4 +1,5 @@
 import type { Message } from "@grammyjs/types";
+import type { TelegramGroupConfig, TelegramTopicConfig } from "../config/types.js";
 import type { TelegramMediaRef } from "./bot-message-context.js";
 import type { TelegramContext } from "./bot/types.js";
 import { resolveDefaultAgentId } from "../agents/agent-scope.js";
@@ -21,7 +22,11 @@ import { readChannelAllowFromStore } from "../pairing/pairing-store.js";
 import { resolveAgentRoute } from "../routing/resolve-route.js";
 import { resolveThreadSessionKeys } from "../routing/session-key.js";
 import { withTelegramApiErrorLogging } from "./api-logging.js";
-import { firstDefined, isSenderAllowed, normalizeAllowFromWithStore } from "./bot-access.js";
+import {
+  isSenderAllowed,
+  normalizeAllowFromWithStore,
+  type NormalizedAllowFrom,
+} from "./bot-access.js";
 import { RegisterTelegramHandlerParams } from "./bot-native-commands.js";
 import { MEDIA_GROUP_TIMEOUT_MS, type MediaGroupEntry } from "./bot-updates.js";
 import { resolveMedia } from "./bot/delivery.js";
@@ -29,7 +34,12 @@ import {
   buildTelegramGroupPeerId,
   buildTelegramParentPeer,
   resolveTelegramForumThreadId,
+  resolveTelegramGroupAllowFromContext,
 } from "./bot/helpers.js";
+import {
+  evaluateTelegramGroupBaseAccess,
+  evaluateTelegramGroupPolicyAccess,
+} from "./group-access.js";
 import { migrateTelegramGroupConfig } from "./group-migration.js";
 import { resolveTelegramInlineButtonsScope } from "./inline-buttons.js";
 import {
@@ -93,6 +103,30 @@ export const registerTelegramHandlers = ({
     debounceKey: string | null;
     botUsername?: string;
   };
+  const buildSyntheticTextMessage = (params: {
+    base: Message;
+    text: string;
+    date?: number;
+    from?: Message["from"];
+  }): Message => ({
+    ...params.base,
+    ...(params.from ? { from: params.from } : {}),
+    text: params.text,
+    caption: undefined,
+    caption_entities: undefined,
+    entities: undefined,
+    ...(params.date != null ? { date: params.date } : {}),
+  });
+  const buildSyntheticContext = (
+    ctx: Pick<TelegramContext, "me"> & { getFile?: unknown },
+    message: Message,
+  ): TelegramContext => {
+    const getFile =
+      typeof ctx.getFile === "function"
+        ? (ctx.getFile as TelegramContext["getFile"]).bind(ctx as object)
+        : async () => ({});
+    return { message, me: ctx.me, getFile };
+  };
   const inboundDebouncer = createInboundDebouncer<TelegramDebounceEntry>({
     debounceMs,
     buildKey: (entry) => entry.debounceKey,
@@ -124,19 +158,14 @@ export const registerTelegramHandlers = ({
       }
       const first = entries[0];
       const baseCtx = first.ctx;
-      const getFile =
-        typeof baseCtx.getFile === "function" ? baseCtx.getFile.bind(baseCtx) : async () => ({});
-      const syntheticMessage: Message = {
-        ...first.msg,
+      const syntheticMessage = buildSyntheticTextMessage({
+        base: first.msg,
         text: combinedText,
-        caption: undefined,
-        caption_entities: undefined,
-        entities: undefined,
         date: last.msg.date ?? first.msg.date,
-      };
+      });
       const messageIdOverride = last.msg.message_id ? String(last.msg.message_id) : undefined;
       await processMessage(
-        { message: syntheticMessage, me: baseCtx.me, getFile },
+        buildSyntheticContext(baseCtx, syntheticMessage),
         [],
         first.storeAllowFrom,
         messageIdOverride ? { messageIdOverride } : undefined,
@@ -226,7 +255,7 @@ export const registerTelegramHandlers = ({
         }
       }
 
-      const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
+      const storeAllowFrom = await loadStoreAllowFrom();
       await processMessage(primaryEntry.ctx, allMedia, storeAllowFrom);
     } catch (err) {
       runtime.error?.(danger(`media group handler failed: ${String(err)}`));
@@ -248,44 +277,187 @@ export const registerTelegramHandlers = ({
         return;
       }
 
-      const syntheticMessage: Message = {
-        ...first.msg,
+      const syntheticMessage = buildSyntheticTextMessage({
+        base: first.msg,
         text: combinedText,
-        caption: undefined,
-        caption_entities: undefined,
-        entities: undefined,
         date: last.msg.date ?? first.msg.date,
-      };
+      });
 
-      const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
+      const storeAllowFrom = await loadStoreAllowFrom();
       const baseCtx = first.ctx;
-      const getFile =
-        typeof baseCtx.getFile === "function" ? baseCtx.getFile.bind(baseCtx) : async () => ({});
 
-      await processMessage(
-        { message: syntheticMessage, me: baseCtx.me, getFile },
-        [],
-        storeAllowFrom,
-        { messageIdOverride: String(last.msg.message_id) },
-      );
+      await processMessage(buildSyntheticContext(baseCtx, syntheticMessage), [], storeAllowFrom, {
+        messageIdOverride: String(last.msg.message_id),
+      });
     } catch (err) {
       runtime.error?.(danger(`text fragment handler failed: ${String(err)}`));
     }
   };
 
+  const queueTextFragmentFlush = async (entry: TextFragmentEntry) => {
+    textFragmentProcessing = textFragmentProcessing
+      .then(async () => {
+        await flushTextFragments(entry);
+      })
+      .catch(() => undefined);
+    await textFragmentProcessing;
+  };
+
+  const runTextFragmentFlush = async (entry: TextFragmentEntry) => {
+    textFragmentBuffer.delete(entry.key);
+    await queueTextFragmentFlush(entry);
+  };
+
   const scheduleTextFragmentFlush = (entry: TextFragmentEntry) => {
     clearTimeout(entry.timer);
     entry.timer = setTimeout(async () => {
-      textFragmentBuffer.delete(entry.key);
-      textFragmentProcessing = textFragmentProcessing
-        .then(async () => {
-          await flushTextFragments(entry);
-        })
-        .catch(() => undefined);
-      await textFragmentProcessing;
+      await runTextFragmentFlush(entry);
     }, TELEGRAM_TEXT_FRAGMENT_MAX_GAP_MS);
   };
 
+  const enqueueMediaGroupFlush = async (mediaGroupId: string, entry: MediaGroupEntry) => {
+    mediaGroupBuffer.delete(mediaGroupId);
+    mediaGroupProcessing = mediaGroupProcessing
+      .then(async () => {
+        await processMediaGroup(entry);
+      })
+      .catch(() => undefined);
+    await mediaGroupProcessing;
+  };
+
+  const scheduleMediaGroupFlush = (mediaGroupId: string, entry: MediaGroupEntry) => {
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(async () => {
+      await enqueueMediaGroupFlush(mediaGroupId, entry);
+    }, mediaGroupTimeoutMs);
+  };
+
+  const getOrCreateMediaGroupEntry = (mediaGroupId: string) => {
+    const existing = mediaGroupBuffer.get(mediaGroupId);
+    if (existing) {
+      return existing;
+    }
+    const entry: MediaGroupEntry = {
+      messages: [],
+      timer: setTimeout(() => undefined, mediaGroupTimeoutMs),
+    };
+    mediaGroupBuffer.set(mediaGroupId, entry);
+    return entry;
+  };
+
+  const loadStoreAllowFrom = async () =>
+    readChannelAllowFromStore("telegram", process.env, accountId).catch(() => []);
+
+  const isAllowlistAuthorized = (
+    allow: NormalizedAllowFrom,
+    senderId: string,
+    senderUsername: string,
+  ) =>
+    allow.hasWildcard ||
+    (allow.hasEntries &&
+      isSenderAllowed({
+        allow,
+        senderId,
+        senderUsername,
+      }));
+
+  const shouldSkipGroupMessage = (params: {
+    isGroup: boolean;
+    chatId: string | number;
+    chatTitle?: string;
+    resolvedThreadId?: number;
+    senderId: string;
+    senderUsername: string;
+    effectiveGroupAllow: NormalizedAllowFrom;
+    hasGroupAllowOverride: boolean;
+    groupConfig?: TelegramGroupConfig;
+    topicConfig?: TelegramTopicConfig;
+  }) => {
+    const {
+      isGroup,
+      chatId,
+      chatTitle,
+      resolvedThreadId,
+      senderId,
+      senderUsername,
+      effectiveGroupAllow,
+      hasGroupAllowOverride,
+      groupConfig,
+      topicConfig,
+    } = params;
+    const baseAccess = evaluateTelegramGroupBaseAccess({
+      isGroup,
+      groupConfig,
+      topicConfig,
+      hasGroupAllowOverride,
+      effectiveGroupAllow,
+      senderId,
+      senderUsername,
+      enforceAllowOverride: true,
+      requireSenderForAllowOverride: true,
+    });
+    if (!baseAccess.allowed) {
+      if (baseAccess.reason === "group-disabled") {
+        logVerbose(`Blocked telegram group ${chatId} (group disabled)`);
+        return true;
+      }
+      if (baseAccess.reason === "topic-disabled") {
+        logVerbose(
+          `Blocked telegram topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`,
+        );
+        return true;
+      }
+      logVerbose(
+        `Blocked telegram group sender ${senderId || "unknown"} (group allowFrom override)`,
+      );
+      return true;
+    }
+    if (!isGroup) {
+      return false;
+    }
+    const policyAccess = evaluateTelegramGroupPolicyAccess({
+      isGroup,
+      chatId,
+      cfg,
+      telegramCfg,
+      topicConfig,
+      groupConfig,
+      effectiveGroupAllow,
+      senderId,
+      senderUsername,
+      resolveGroupPolicy,
+      enforcePolicy: true,
+      useTopicAndGroupOverrides: true,
+      enforceAllowlistAuthorization: true,
+      allowEmptyAllowlistEntries: false,
+      requireSenderForAllowlistAuthorization: true,
+      checkChatAllowlist: true,
+    });
+    if (!policyAccess.allowed) {
+      if (policyAccess.reason === "group-policy-disabled") {
+        logVerbose("Blocked telegram group message (groupPolicy: disabled)");
+        return true;
+      }
+      if (policyAccess.reason === "group-policy-allowlist-no-sender") {
+        logVerbose("Blocked telegram group message (no sender ID, groupPolicy: allowlist)");
+        return true;
+      }
+      if (policyAccess.reason === "group-policy-allowlist-empty") {
+        logVerbose(
+          "Blocked telegram group message (groupPolicy: allowlist, no group allowlist entries)",
+        );
+        return true;
+      }
+      if (policyAccess.reason === "group-policy-allowlist-unauthorized") {
+        logVerbose(`Blocked telegram group message from ${senderId} (groupPolicy: allowlist)`);
+        return true;
+      }
+      logger.info({ chatId, title: chatTitle, reason: "not-allowed" }, "skipping group message");
+      return true;
+    }
+    return false;
+  };
+
   bot.on("callback_query", async (ctx) => {
     const callback = ctx.callbackQuery;
     if (!callback) {
@@ -294,11 +466,15 @@ export const registerTelegramHandlers = ({
     if (shouldSkipUpdate(ctx)) {
       return;
     }
+    const answerCallbackQuery =
+      typeof (ctx as { answerCallbackQuery?: unknown }).answerCallbackQuery === "function"
+        ? () => ctx.answerCallbackQuery()
+        : () => bot.api.answerCallbackQuery(callback.id);
     // Answer immediately to prevent Telegram from retrying while we process
     await withTelegramApiErrorLogging({
       operation: "answerCallbackQuery",
       runtime,
-      fn: () => bot.api.answerCallbackQuery(callback.id),
+      fn: answerCallbackQuery,
     }).catch(() => {});
     try {
       const data = (callback.data ?? "").trim();
@@ -306,6 +482,38 @@ export const registerTelegramHandlers = ({
       if (!data || !callbackMessage) {
         return;
       }
+      const editCallbackMessage = async (
+        text: string,
+        params?: Parameters<typeof bot.api.editMessageText>[3],
+      ) => {
+        const editTextFn = (ctx as { editMessageText?: unknown }).editMessageText;
+        if (typeof editTextFn === "function") {
+          return await ctx.editMessageText(text, params);
+        }
+        return await bot.api.editMessageText(
+          callbackMessage.chat.id,
+          callbackMessage.message_id,
+          text,
+          params,
+        );
+      };
+      const deleteCallbackMessage = async () => {
+        const deleteFn = (ctx as { deleteMessage?: unknown }).deleteMessage;
+        if (typeof deleteFn === "function") {
+          return await ctx.deleteMessage();
+        }
+        return await bot.api.deleteMessage(callbackMessage.chat.id, callbackMessage.message_id);
+      };
+      const replyToCallbackChat = async (
+        text: string,
+        params?: Parameters<typeof bot.api.sendMessage>[2],
+      ) => {
+        const replyFn = (ctx as { reply?: unknown }).reply;
+        if (typeof replyFn === "function") {
+          return await ctx.reply(text, params);
+        }
+        return await bot.api.sendMessage(callbackMessage.chat.id, text, params);
+      };
 
       const inlineButtonsScope = resolveTelegramInlineButtonsScope({
         cfg,
@@ -327,17 +535,22 @@ export const registerTelegramHandlers = ({
 
       const messageThreadId = callbackMessage.message_thread_id;
       const isForum = callbackMessage.chat.is_forum === true;
-      const resolvedThreadId = resolveTelegramForumThreadId({
+      const groupAllowContext = await resolveTelegramGroupAllowFromContext({
+        chatId,
+        accountId,
         isForum,
         messageThreadId,
+        groupAllowFrom,
+        resolveTelegramGroupConfig,
       });
-      const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
-      const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
-      const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
-      const effectiveGroupAllow = normalizeAllowFromWithStore({
-        allowFrom: groupAllowOverride ?? groupAllowFrom,
+      const {
+        resolvedThreadId,
         storeAllowFrom,
-      });
+        groupConfig,
+        topicConfig,
+        effectiveGroupAllow,
+        hasGroupAllowOverride,
+      } = groupAllowContext;
       const effectiveDmAllow = normalizeAllowFromWithStore({
         allowFrom: telegramCfg.allowFrom,
         storeAllowFrom,
@@ -345,75 +558,21 @@ export const registerTelegramHandlers = ({
       const dmPolicy = telegramCfg.dmPolicy ?? "pairing";
       const senderId = callback.from?.id ? String(callback.from.id) : "";
       const senderUsername = callback.from?.username ?? "";
-
-      if (isGroup) {
-        if (groupConfig?.enabled === false) {
-          logVerbose(`Blocked telegram group ${chatId} (group disabled)`);
-          return;
-        }
-        if (topicConfig?.enabled === false) {
-          logVerbose(
-            `Blocked telegram topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`,
-          );
-          return;
-        }
-        if (typeof groupAllowOverride !== "undefined") {
-          const allowed =
-            senderId &&
-            isSenderAllowed({
-              allow: effectiveGroupAllow,
-              senderId,
-              senderUsername,
-            });
-          if (!allowed) {
-            logVerbose(
-              `Blocked telegram group sender ${senderId || "unknown"} (group allowFrom override)`,
-            );
-            return;
-          }
-        }
-        const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-        const groupPolicy = firstDefined(
-          topicConfig?.groupPolicy,
-          groupConfig?.groupPolicy,
-          telegramCfg.groupPolicy,
-          defaultGroupPolicy,
-          "open",
-        );
-        if (groupPolicy === "disabled") {
-          logVerbose(`Blocked telegram group message (groupPolicy: disabled)`);
-          return;
-        }
-        if (groupPolicy === "allowlist") {
-          if (!senderId) {
-            logVerbose(`Blocked telegram group message (no sender ID, groupPolicy: allowlist)`);
-            return;
-          }
-          if (!effectiveGroupAllow.hasEntries) {
-            logVerbose(
-              "Blocked telegram group message (groupPolicy: allowlist, no group allowlist entries)",
-            );
-            return;
-          }
-          if (
-            !isSenderAllowed({
-              allow: effectiveGroupAllow,
-              senderId,
-              senderUsername,
-            })
-          ) {
-            logVerbose(`Blocked telegram group message from ${senderId} (groupPolicy: allowlist)`);
-            return;
-          }
-        }
-        const groupAllowlist = resolveGroupPolicy(chatId);
-        if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
-          logger.info(
-            { chatId, title: callbackMessage.chat.title, reason: "not-allowed" },
-            "skipping group message",
-          );
-          return;
-        }
+      if (
+        shouldSkipGroupMessage({
+          isGroup,
+          chatId,
+          chatTitle: callbackMessage.chat.title,
+          resolvedThreadId,
+          senderId,
+          senderUsername,
+          effectiveGroupAllow,
+          hasGroupAllowOverride,
+          groupConfig,
+          topicConfig,
+        })
+      ) {
+        return;
       }
 
       if (inlineButtonsScope === "allowlist") {
@@ -422,27 +581,13 @@ export const registerTelegramHandlers = ({
             return;
           }
           if (dmPolicy !== "open") {
-            const allowed =
-              effectiveDmAllow.hasWildcard ||
-              (effectiveDmAllow.hasEntries &&
-                isSenderAllowed({
-                  allow: effectiveDmAllow,
-                  senderId,
-                  senderUsername,
-                }));
+            const allowed = isAllowlistAuthorized(effectiveDmAllow, senderId, senderUsername);
             if (!allowed) {
               return;
             }
           }
         } else {
-          const allowed =
-            effectiveGroupAllow.hasWildcard ||
-            (effectiveGroupAllow.hasEntries &&
-              isSenderAllowed({
-                allow: effectiveGroupAllow,
-                senderId,
-                senderUsername,
-              }));
+          const allowed = isAllowlistAuthorized(effectiveGroupAllow, senderId, senderUsername);
           if (!allowed) {
             return;
           }
@@ -479,12 +624,7 @@ export const registerTelegramHandlers = ({
             : undefined;
 
         try {
-          await bot.api.editMessageText(
-            callbackMessage.chat.id,
-            callbackMessage.message_id,
-            result.text,
-            keyboard ? { reply_markup: keyboard } : undefined,
-          );
+          await editCallbackMessage(result.text, keyboard ? { reply_markup: keyboard } : undefined);
         } catch (editErr) {
           const errStr = String(editErr);
           if (!errStr.includes("message is not modified")) {
@@ -506,23 +646,14 @@ export const registerTelegramHandlers = ({
         ) => {
           const keyboard = buildInlineKeyboard(buttons);
           try {
-            await bot.api.editMessageText(
-              callbackMessage.chat.id,
-              callbackMessage.message_id,
-              text,
-              keyboard ? { reply_markup: keyboard } : undefined,
-            );
+            await editCallbackMessage(text, keyboard ? { reply_markup: keyboard } : undefined);
           } catch (editErr) {
             const errStr = String(editErr);
             if (errStr.includes("no text in the message")) {
               try {
-                await bot.api.deleteMessage(callbackMessage.chat.id, callbackMessage.message_id);
+                await deleteCallbackMessage();
               } catch {}
-              await bot.api.sendMessage(
-                callbackMessage.chat.id,
-                text,
-                keyboard ? { reply_markup: keyboard } : undefined,
-              );
+              await replyToCallbackChat(text, keyboard ? { reply_markup: keyboard } : undefined);
             } else if (!errStr.includes("message is not modified")) {
               throw editErr;
             }
@@ -589,41 +720,27 @@ export const registerTelegramHandlers = ({
         if (modelCallback.type === "select") {
           const { provider, model } = modelCallback;
           // Process model selection as a synthetic message with /model command
-          const syntheticMessage: Message = {
-            ...callbackMessage,
+          const syntheticMessage = buildSyntheticTextMessage({
+            base: callbackMessage,
             from: callback.from,
             text: `/model ${provider}/${model}`,
-            caption: undefined,
-            caption_entities: undefined,
-            entities: undefined,
-          };
-          const getFile =
-            typeof ctx.getFile === "function" ? ctx.getFile.bind(ctx) : async () => ({});
-          await processMessage(
-            { message: syntheticMessage, me: ctx.me, getFile },
-            [],
-            storeAllowFrom,
-            {
-              forceWasMentioned: true,
-              messageIdOverride: callback.id,
-            },
-          );
+          });
+          await processMessage(buildSyntheticContext(ctx, syntheticMessage), [], storeAllowFrom, {
+            forceWasMentioned: true,
+            messageIdOverride: callback.id,
+          });
           return;
         }
 
         return;
       }
 
-      const syntheticMessage: Message = {
-        ...callbackMessage,
+      const syntheticMessage = buildSyntheticTextMessage({
+        base: callbackMessage,
         from: callback.from,
         text: data,
-        caption: undefined,
-        caption_entities: undefined,
-        entities: undefined,
-      };
-      const getFile = typeof ctx.getFile === "function" ? ctx.getFile.bind(ctx) : async () => ({});
-      await processMessage({ message: syntheticMessage, me: ctx.me, getFile }, [], storeAllowFrom, {
+      });
+      await processMessage(buildSyntheticContext(ctx, syntheticMessage), [], storeAllowFrom, {
         forceWasMentioned: true,
         messageIdOverride: callback.id,
       });
@@ -698,98 +815,40 @@ export const registerTelegramHandlers = ({
       const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup";
       const messageThreadId = msg.message_thread_id;
       const isForum = msg.chat.is_forum === true;
-      const resolvedThreadId = resolveTelegramForumThreadId({
+      const groupAllowContext = await resolveTelegramGroupAllowFromContext({
+        chatId,
+        accountId,
         isForum,
         messageThreadId,
+        groupAllowFrom,
+        resolveTelegramGroupConfig,
       });
-      const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
-      const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
-      const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
-      const effectiveGroupAllow = normalizeAllowFromWithStore({
-        allowFrom: groupAllowOverride ?? groupAllowFrom,
+      const {
+        resolvedThreadId,
         storeAllowFrom,
-      });
-      const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
+        groupConfig,
+        topicConfig,
+        effectiveGroupAllow,
+        hasGroupAllowOverride,
+      } = groupAllowContext;
 
-      if (isGroup) {
-        if (groupConfig?.enabled === false) {
-          logVerbose(`Blocked telegram group ${chatId} (group disabled)`);
-          return;
-        }
-        if (topicConfig?.enabled === false) {
-          logVerbose(
-            `Blocked telegram topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`,
-          );
-          return;
-        }
-        if (hasGroupAllowOverride) {
-          const senderId = msg.from?.id;
-          const senderUsername = msg.from?.username ?? "";
-          const allowed =
-            senderId != null &&
-            isSenderAllowed({
-              allow: effectiveGroupAllow,
-              senderId: String(senderId),
-              senderUsername,
-            });
-          if (!allowed) {
-            logVerbose(
-              `Blocked telegram group sender ${senderId ?? "unknown"} (group allowFrom override)`,
-            );
-            return;
-          }
-        }
-        // Group policy filtering: controls how group messages are handled
-        // - "open": groups bypass allowFrom, only mention-gating applies
-        // - "disabled": block all group messages entirely
-        // - "allowlist": only allow group messages from senders in groupAllowFrom/allowFrom
-        const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-        const groupPolicy = firstDefined(
-          topicConfig?.groupPolicy,
-          groupConfig?.groupPolicy,
-          telegramCfg.groupPolicy,
-          defaultGroupPolicy,
-          "open",
-        );
-        if (groupPolicy === "disabled") {
-          logVerbose(`Blocked telegram group message (groupPolicy: disabled)`);
-          return;
-        }
-        if (groupPolicy === "allowlist") {
-          // For allowlist mode, the sender (msg.from.id) must be in allowFrom
-          const senderId = msg.from?.id;
-          if (senderId == null) {
-            logVerbose(`Blocked telegram group message (no sender ID, groupPolicy: allowlist)`);
-            return;
-          }
-          if (!effectiveGroupAllow.hasEntries) {
-            logVerbose(
-              "Blocked telegram group message (groupPolicy: allowlist, no group allowlist entries)",
-            );
-            return;
-          }
-          const senderUsername = msg.from?.username ?? "";
-          if (
-            !isSenderAllowed({
-              allow: effectiveGroupAllow,
-              senderId: String(senderId),
-              senderUsername,
-            })
-          ) {
-            logVerbose(`Blocked telegram group message from ${senderId} (groupPolicy: allowlist)`);
-            return;
-          }
-        }
-
-        // Group allowlist based on configured group IDs.
-        const groupAllowlist = resolveGroupPolicy(chatId);
-        if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
-          logger.info(
-            { chatId, title: msg.chat.title, reason: "not-allowed" },
-            "skipping group message",
-          );
-          return;
-        }
+      const senderId = msg.from?.id != null ? String(msg.from.id) : "";
+      const senderUsername = msg.from?.username ?? "";
+      if (
+        shouldSkipGroupMessage({
+          isGroup,
+          chatId,
+          chatTitle: msg.chat.title,
+          resolvedThreadId,
+          senderId,
+          senderUsername,
+          effectiveGroupAllow,
+          hasGroupAllowOverride,
+          groupConfig,
+          topicConfig,
+        })
+      ) {
+        return;
       }
 
       // Text fragment handling - Telegram splits long pastes into multiple inbound messages (~4096 chars).
@@ -832,13 +891,7 @@ export const registerTelegramHandlers = ({
 
           // Not appendable (or limits exceeded): flush buffered entry first, then continue normally.
           clearTimeout(existing.timer);
-          textFragmentBuffer.delete(key);
-          textFragmentProcessing = textFragmentProcessing
-            .then(async () => {
-              await flushTextFragments(existing);
-            })
-            .catch(() => undefined);
-          await textFragmentProcessing;
+          await runTextFragmentFlush(existing);
         }
 
         const shouldStart = text.length >= TELEGRAM_TEXT_FRAGMENT_START_THRESHOLD_CHARS;
@@ -857,34 +910,9 @@ export const registerTelegramHandlers = ({
       // Media group handling - buffer multi-image messages
       const mediaGroupId = msg.media_group_id;
       if (mediaGroupId) {
-        const existing = mediaGroupBuffer.get(mediaGroupId);
-        if (existing) {
-          clearTimeout(existing.timer);
-          existing.messages.push({ msg, ctx });
-          existing.timer = setTimeout(async () => {
-            mediaGroupBuffer.delete(mediaGroupId);
-            mediaGroupProcessing = mediaGroupProcessing
-              .then(async () => {
-                await processMediaGroup(existing);
-              })
-              .catch(() => undefined);
-            await mediaGroupProcessing;
-          }, mediaGroupTimeoutMs);
-        } else {
-          const entry: MediaGroupEntry = {
-            messages: [{ msg, ctx }],
-            timer: setTimeout(async () => {
-              mediaGroupBuffer.delete(mediaGroupId);
-              mediaGroupProcessing = mediaGroupProcessing
-                .then(async () => {
-                  await processMediaGroup(entry);
-                })
-                .catch(() => undefined);
-              await mediaGroupProcessing;
-            }, mediaGroupTimeoutMs),
-          };
-          mediaGroupBuffer.set(mediaGroupId, entry);
-        }
+        const entry = getOrCreateMediaGroupEntry(mediaGroupId);
+        entry.messages.push({ msg, ctx });
+        scheduleMediaGroupFlush(mediaGroupId, entry);
         return;
       }
 
@@ -926,7 +954,6 @@ export const registerTelegramHandlers = ({
             },
           ]
         : [];
-      const senderId = msg.from?.id ? String(msg.from.id) : "";
       const conversationKey =
         resolvedThreadId != null ? `${chatId}:topic:${resolvedThreadId}` : String(chatId);
       const debounceKey = senderId
diff --git a/src/telegram/bot-message-context.ts b/src/telegram/bot-message-context.ts
index 9cd8f91106f..7961fb469ed 100644
--- a/src/telegram/bot-message-context.ts
+++ b/src/telegram/bot-message-context.ts
@@ -49,6 +49,7 @@ import {
   buildTelegramGroupPeerId,
   buildTelegramParentPeer,
   buildTypingThreadParams,
+  resolveTelegramMediaPlaceholder,
   expandTextLinks,
   normalizeForwardedContext,
   describeReplyTarget,
@@ -56,6 +57,7 @@ import {
   hasBotMention,
   resolveTelegramThreadSpec,
 } from "./bot/helpers.js";
+import { evaluateTelegramGroupBaseAccess } from "./group-access.js";
 
 export type TelegramMediaRef = {
   path: string;
@@ -192,15 +194,31 @@ export const buildTelegramMessageContext = async ({
     storeAllowFrom,
   });
   const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
-
-  if (isGroup && groupConfig?.enabled === false) {
-    logVerbose(`Blocked telegram group ${chatId} (group disabled)`);
-    return null;
-  }
-  if (isGroup && topicConfig?.enabled === false) {
-    logVerbose(
-      `Blocked telegram topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`,
-    );
+  const senderId = msg.from?.id ? String(msg.from.id) : "";
+  const senderUsername = msg.from?.username ?? "";
+  const baseAccess = evaluateTelegramGroupBaseAccess({
+    isGroup,
+    groupConfig,
+    topicConfig,
+    hasGroupAllowOverride,
+    effectiveGroupAllow,
+    senderId,
+    senderUsername,
+    enforceAllowOverride: true,
+    requireSenderForAllowOverride: false,
+  });
+  if (!baseAccess.allowed) {
+    if (baseAccess.reason === "group-disabled") {
+      logVerbose(`Blocked telegram group ${chatId} (group disabled)`);
+      return null;
+    }
+    if (baseAccess.reason === "topic-disabled") {
+      logVerbose(
+        `Blocked telegram topic ${chatId} (${resolvedThreadId ?? "unknown"}) (topic disabled)`,
+      );
+      return null;
+    }
+    logVerbose(`Blocked telegram group sender ${senderId || "unknown"} (group allowFrom override)`);
     return null;
   }
 
@@ -273,6 +291,7 @@ export const buildTelegramMessageContext = async ({
             const { code, created } = await upsertChannelPairingRequest({
               channel: "telegram",
               id: telegramUserId,
+              accountId: account.accountId,
               meta: {
                 username: from?.username,
                 firstName: from?.first_name,
@@ -319,21 +338,6 @@ export const buildTelegramMessageContext = async ({
   }
 
   const botUsername = primaryCtx.me?.username?.toLowerCase();
-  const senderId = msg.from?.id ? String(msg.from.id) : "";
-  const senderUsername = msg.from?.username ?? "";
-  if (isGroup && hasGroupAllowOverride) {
-    const allowed = isSenderAllowed({
-      allow: effectiveGroupAllow,
-      senderId,
-      senderUsername,
-    });
-    if (!allowed) {
-      logVerbose(
-        `Blocked telegram group sender ${senderId || "unknown"} (group allowFrom override)`,
-      );
-      return null;
-    }
-  }
   const allowForCommands = isGroup ? effectiveGroupAllow : effectiveDmAllow;
   const senderAllowedForCommands = isSenderAllowed({
     allow: allowForCommands,
@@ -353,20 +357,7 @@ export const buildTelegramMessageContext = async ({
   const commandAuthorized = commandGate.commandAuthorized;
   const historyKey = isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : undefined;
 
-  let placeholder = "";
-  if (msg.photo) {
-    placeholder = "<media:image>";
-  } else if (msg.video) {
-    placeholder = "<media:video>";
-  } else if (msg.video_note) {
-    placeholder = "<media:video>";
-  } else if (msg.audio || msg.voice) {
-    placeholder = "<media:audio>";
-  } else if (msg.document) {
-    placeholder = "<media:document>";
-  } else if (msg.sticker) {
-    placeholder = "<media:sticker>";
-  }
+  let placeholder = resolveTelegramMediaPlaceholder(msg) ?? "";
 
   // Check if sticker has a cached description - if so, use it instead of sending the image
   const cachedStickerDescription = allMedia[0]?.stickerMetadata?.cachedDescription;
@@ -502,7 +493,10 @@ export const buildTelegramMessageContext = async ({
   }
 
   // ACK reactions
-  const ackReaction = resolveAckReaction(cfg, route.agentId);
+  const ackReaction = resolveAckReaction(cfg, route.agentId, {
+    channel: "telegram",
+    accountId: account.accountId,
+  });
   const removeAckAfterReply = cfg.messages?.removeAckAfterReply ?? false;
   const shouldAckReaction = () =>
     Boolean(
diff --git a/src/telegram/bot-message-dispatch.test.ts b/src/telegram/bot-message-dispatch.test.ts
index 2548902072b..c5c98f3e006 100644
--- a/src/telegram/bot-message-dispatch.test.ts
+++ b/src/telegram/bot-message-dispatch.test.ts
@@ -113,6 +113,7 @@ describe("dispatchTelegramMessage draft streaming", () => {
   async function dispatchWithContext(params: {
     context: TelegramMessageContext;
     telegramCfg?: Parameters<typeof dispatchTelegramMessage>[0]["telegramCfg"];
+    streamMode?: Parameters<typeof dispatchTelegramMessage>[0]["streamMode"];
   }) {
     await dispatchTelegramMessage({
       context: params.context,
@@ -120,7 +121,7 @@ describe("dispatchTelegramMessage draft streaming", () => {
       cfg: {},
       runtime: createRuntime(),
       replyToMode: "first",
-      streamMode: "partial",
+      streamMode: params.streamMode ?? "partial",
       textLimit: 4096,
       telegramCfg: params.telegramCfg ?? {},
       opts: { token: "token" },
@@ -236,4 +237,26 @@ describe("dispatchTelegramMessage draft streaming", () => {
     expect(draftStream.clear).toHaveBeenCalledTimes(1);
     expect(draftStream.stop).toHaveBeenCalled();
   });
+
+  it("disables block streaming when streamMode is off", async () => {
+    dispatchReplyWithBufferedBlockDispatcher.mockImplementation(async ({ dispatcherOptions }) => {
+      await dispatcherOptions.deliver({ text: "Hello" }, { kind: "final" });
+      return { queuedFinal: true };
+    });
+    deliverReplies.mockResolvedValue({ delivered: true });
+
+    await dispatchWithContext({
+      context: createContext(),
+      streamMode: "off",
+    });
+
+    expect(createTelegramDraftStream).not.toHaveBeenCalled();
+    expect(dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyOptions: expect.objectContaining({
+          disableBlockStreaming: true,
+        }),
+      }),
+    );
+  });
 });
diff --git a/src/telegram/bot-message-dispatch.ts b/src/telegram/bot-message-dispatch.ts
index 3caef30df57..361a897185c 100644
--- a/src/telegram/bot-message-dispatch.ts
+++ b/src/telegram/bot-message-dispatch.ts
@@ -169,7 +169,7 @@ export const dispatchTelegramMessage = async ({
   const disableBlockStreaming =
     typeof telegramCfg.blockStreaming === "boolean"
       ? !telegramCfg.blockStreaming
-      : draftStream
+      : draftStream || streamMode === "off"
         ? true
         : undefined;
 
@@ -249,6 +249,25 @@ export const dispatchTelegramMessage = async ({
     skippedNonSilent: 0,
   };
   let finalizedViaPreviewMessage = false;
+  const clearGroupHistory = () => {
+    if (isGroup && historyKey) {
+      clearHistoryEntriesIfEnabled({ historyMap: groupHistories, historyKey, limit: historyLimit });
+    }
+  };
+  const deliveryBaseOptions = {
+    chatId: String(chatId),
+    token: opts.token,
+    runtime,
+    bot,
+    mediaLocalRoots,
+    replyToMode,
+    textLimit,
+    thread: threadSpec,
+    tableMode,
+    chunkMode,
+    linkPreview: telegramCfg.linkPreview,
+    replyQuoteText,
+  };
 
   let queuedFinal = false;
   try {
@@ -300,20 +319,9 @@ export const dispatchTelegramMessage = async ({
             }
           }
           const result = await deliverReplies({
+            ...deliveryBaseOptions,
             replies: [payload],
-            chatId: String(chatId),
-            token: opts.token,
-            runtime,
-            bot,
-            mediaLocalRoots,
-            replyToMode,
-            textLimit,
-            thread: threadSpec,
-            tableMode,
-            chunkMode,
             onVoiceRecording: sendRecordVoice,
-            linkPreview: telegramCfg.linkPreview,
-            replyQuoteText,
           });
           if (result.delivered) {
             deliveryState.delivered = true;
@@ -356,27 +364,14 @@ export const dispatchTelegramMessage = async ({
   if (!deliveryState.delivered && deliveryState.skippedNonSilent > 0) {
     const result = await deliverReplies({
       replies: [{ text: EMPTY_RESPONSE_FALLBACK }],
-      chatId: String(chatId),
-      token: opts.token,
-      runtime,
-      bot,
-      mediaLocalRoots,
-      replyToMode,
-      textLimit,
-      thread: threadSpec,
-      tableMode,
-      chunkMode,
-      linkPreview: telegramCfg.linkPreview,
-      replyQuoteText,
+      ...deliveryBaseOptions,
     });
     sentFallback = result.delivered;
   }
 
   const hasFinalResponse = queuedFinal || sentFallback;
   if (!hasFinalResponse) {
-    if (isGroup && historyKey) {
-      clearHistoryEntriesIfEnabled({ historyMap: groupHistories, historyKey, limit: historyLimit });
-    }
+    clearGroupHistory();
     return;
   }
   removeAckReactionAfterReply({
@@ -396,7 +391,5 @@ export const dispatchTelegramMessage = async ({
       });
     },
   });
-  if (isGroup && historyKey) {
-    clearHistoryEntriesIfEnabled({ historyMap: groupHistories, historyKey, limit: historyLimit });
-  }
+  clearGroupHistory();
 };
diff --git a/src/telegram/bot-native-commands.ts b/src/telegram/bot-native-commands.ts
index c2cbf894f45..f22d44c3b77 100644
--- a/src/telegram/bot-native-commands.ts
+++ b/src/telegram/bot-native-commands.ts
@@ -29,7 +29,6 @@ import { resolveTelegramCustomCommands } from "../config/telegram-custom-command
 import { danger, logVerbose } from "../globals.js";
 import { getChildLogger } from "../logging.js";
 import { getAgentScopedMediaLocalRoots } from "../media/local-roots.js";
-import { readChannelAllowFromStore } from "../pairing/pairing-store.js";
 import {
   executePluginCommand,
   getPluginCommandSpecs,
@@ -53,9 +52,13 @@ import {
   buildTelegramGroupFrom,
   buildTelegramGroupPeerId,
   buildTelegramParentPeer,
-  resolveTelegramForumThreadId,
+  resolveTelegramGroupAllowFromContext,
   resolveTelegramThreadSpec,
 } from "./bot/helpers.js";
+import {
+  evaluateTelegramGroupBaseAccess,
+  evaluateTelegramGroupPolicyAccess,
+} from "./group-access.js";
 import { buildInlineKeyboard } from "./send.js";
 
 const EMPTY_RESPONSE_FALLBACK = "No response generated. Please try again.";
@@ -128,6 +131,7 @@ async function resolveTelegramCommandAuth(params: {
   msg: NonNullable<TelegramNativeCommandContext["message"]>;
   bot: Bot;
   cfg: OpenClawConfig;
+  accountId: string;
   telegramCfg: TelegramAccountConfig;
   allowFrom?: Array<string | number>;
   groupAllowFrom?: Array<string | number>;
@@ -143,6 +147,7 @@ async function resolveTelegramCommandAuth(params: {
     msg,
     bot,
     cfg,
+    accountId,
     telegramCfg,
     allowFrom,
     groupAllowFrom,
@@ -155,80 +160,87 @@ async function resolveTelegramCommandAuth(params: {
   const isGroup = msg.chat.type === "group" || msg.chat.type === "supergroup";
   const messageThreadId = (msg as { message_thread_id?: number }).message_thread_id;
   const isForum = (msg.chat as { is_forum?: boolean }).is_forum === true;
-  const resolvedThreadId = resolveTelegramForumThreadId({
+  const groupAllowContext = await resolveTelegramGroupAllowFromContext({
+    chatId,
+    accountId,
     isForum,
     messageThreadId,
+    groupAllowFrom,
+    resolveTelegramGroupConfig,
   });
-  const storeAllowFrom = await readChannelAllowFromStore("telegram").catch(() => []);
-  const { groupConfig, topicConfig } = resolveTelegramGroupConfig(chatId, resolvedThreadId);
-  const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
-  const effectiveGroupAllow = normalizeAllowFromWithStore({
-    allowFrom: groupAllowOverride ?? groupAllowFrom,
+  const {
+    resolvedThreadId,
     storeAllowFrom,
-  });
-  const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
-  const senderIdRaw = msg.from?.id;
-  const senderId = senderIdRaw ? String(senderIdRaw) : "";
+    groupConfig,
+    topicConfig,
+    effectiveGroupAllow,
+    hasGroupAllowOverride,
+  } = groupAllowContext;
+  const senderId = msg.from?.id ? String(msg.from.id) : "";
   const senderUsername = msg.from?.username ?? "";
 
-  const isGroupSenderAllowed = () =>
-    senderIdRaw != null &&
-    isSenderAllowed({
-      allow: effectiveGroupAllow,
-      senderId: String(senderIdRaw),
-      senderUsername,
-    });
-
-  const rejectNotAuthorized = async () => {
+  const sendAuthMessage = async (text: string) => {
     await withTelegramApiErrorLogging({
       operation: "sendMessage",
-      fn: () => bot.api.sendMessage(chatId, "You are not authorized to use this command."),
+      fn: () => bot.api.sendMessage(chatId, text),
     });
     return null;
   };
+  const rejectNotAuthorized = async () => {
+    return await sendAuthMessage("You are not authorized to use this command.");
+  };
 
-  if (isGroup && groupConfig?.enabled === false) {
-    await withTelegramApiErrorLogging({
-      operation: "sendMessage",
-      fn: () => bot.api.sendMessage(chatId, "This group is disabled."),
-    });
-    return null;
+  const baseAccess = evaluateTelegramGroupBaseAccess({
+    isGroup,
+    groupConfig,
+    topicConfig,
+    hasGroupAllowOverride,
+    effectiveGroupAllow,
+    senderId,
+    senderUsername,
+    enforceAllowOverride: requireAuth,
+    requireSenderForAllowOverride: true,
+  });
+  if (!baseAccess.allowed) {
+    if (baseAccess.reason === "group-disabled") {
+      return await sendAuthMessage("This group is disabled.");
+    }
+    if (baseAccess.reason === "topic-disabled") {
+      return await sendAuthMessage("This topic is disabled.");
+    }
+    return await rejectNotAuthorized();
   }
-  if (isGroup && topicConfig?.enabled === false) {
-    await withTelegramApiErrorLogging({
-      operation: "sendMessage",
-      fn: () => bot.api.sendMessage(chatId, "This topic is disabled."),
-    });
-    return null;
-  }
-  if (requireAuth && isGroup && hasGroupAllowOverride) {
-    if (!isGroupSenderAllowed()) {
+
+  const policyAccess = evaluateTelegramGroupPolicyAccess({
+    isGroup,
+    chatId,
+    cfg,
+    telegramCfg,
+    topicConfig,
+    groupConfig,
+    effectiveGroupAllow,
+    senderId,
+    senderUsername,
+    resolveGroupPolicy,
+    enforcePolicy: useAccessGroups,
+    useTopicAndGroupOverrides: false,
+    enforceAllowlistAuthorization: requireAuth,
+    allowEmptyAllowlistEntries: true,
+    requireSenderForAllowlistAuthorization: true,
+    checkChatAllowlist: useAccessGroups,
+  });
+  if (!policyAccess.allowed) {
+    if (policyAccess.reason === "group-policy-disabled") {
+      return await sendAuthMessage("Telegram group commands are disabled.");
+    }
+    if (
+      policyAccess.reason === "group-policy-allowlist-no-sender" ||
+      policyAccess.reason === "group-policy-allowlist-unauthorized"
+    ) {
       return await rejectNotAuthorized();
     }
-  }
-
-  if (isGroup && useAccessGroups) {
-    const defaultGroupPolicy = cfg.channels?.defaults?.groupPolicy;
-    const groupPolicy = telegramCfg.groupPolicy ?? defaultGroupPolicy ?? "open";
-    if (groupPolicy === "disabled") {
-      await withTelegramApiErrorLogging({
-        operation: "sendMessage",
-        fn: () => bot.api.sendMessage(chatId, "Telegram group commands are disabled."),
-      });
-      return null;
-    }
-    if (groupPolicy === "allowlist" && requireAuth) {
-      if (!isGroupSenderAllowed()) {
-        return await rejectNotAuthorized();
-      }
-    }
-    const groupAllowlist = resolveGroupPolicy(chatId);
-    if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
-      await withTelegramApiErrorLogging({
-        operation: "sendMessage",
-        fn: () => bot.api.sendMessage(chatId, "This group is not allowed."),
-      });
-      return null;
+    if (policyAccess.reason === "group-chat-not-allowed") {
+      return await sendAuthMessage("This group is not allowed.");
     }
   }
 
@@ -247,11 +259,7 @@ async function resolveTelegramCommandAuth(params: {
     modeWhenAccessGroupsOff: "configured",
   });
   if (requireAuth && !commandAuthorized) {
-    await withTelegramApiErrorLogging({
-      operation: "sendMessage",
-      fn: () => bot.api.sendMessage(chatId, "You are not authorized to use this command."),
-    });
-    return null;
+    return await rejectNotAuthorized();
   }
 
   return {
@@ -352,6 +360,60 @@ export const registerTelegramNativeCommands = ({
   // Keep hidden commands callable by registering handlers for the full catalog.
   syncTelegramMenuCommands({ bot, runtime, commandsToRegister });
 
+  const resolveCommandRuntimeContext = (params: {
+    msg: NonNullable<TelegramNativeCommandContext["message"]>;
+    isGroup: boolean;
+    isForum: boolean;
+    resolvedThreadId?: number;
+  }) => {
+    const { msg, isGroup, isForum, resolvedThreadId } = params;
+    const chatId = msg.chat.id;
+    const messageThreadId = (msg as { message_thread_id?: number }).message_thread_id;
+    const threadSpec = resolveTelegramThreadSpec({
+      isGroup,
+      isForum,
+      messageThreadId,
+    });
+    const parentPeer = buildTelegramParentPeer({ isGroup, resolvedThreadId, chatId });
+    const route = resolveAgentRoute({
+      cfg,
+      channel: "telegram",
+      accountId,
+      peer: {
+        kind: isGroup ? "group" : "direct",
+        id: isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : String(chatId),
+      },
+      parentPeer,
+    });
+    const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
+    const tableMode = resolveMarkdownTableMode({
+      cfg,
+      channel: "telegram",
+      accountId: route.accountId,
+    });
+    const chunkMode = resolveChunkMode(cfg, "telegram", route.accountId);
+    return { chatId, threadSpec, route, mediaLocalRoots, tableMode, chunkMode };
+  };
+  const buildCommandDeliveryBaseOptions = (params: {
+    chatId: string | number;
+    mediaLocalRoots?: readonly string[];
+    threadSpec: ReturnType<typeof resolveTelegramThreadSpec>;
+    tableMode: ReturnType<typeof resolveMarkdownTableMode>;
+    chunkMode: ReturnType<typeof resolveChunkMode>;
+  }) => ({
+    chatId: String(params.chatId),
+    token: opts.token,
+    runtime,
+    bot,
+    mediaLocalRoots: params.mediaLocalRoots,
+    replyToMode,
+    textLimit,
+    thread: params.threadSpec,
+    tableMode: params.tableMode,
+    chunkMode: params.chunkMode,
+    linkPreview: telegramCfg.linkPreview,
+  });
+
   if (commandsToRegister.length > 0 || pluginCatalog.commands.length > 0) {
     if (typeof (bot as unknown as { command?: unknown }).command !== "function") {
       logVerbose("telegram: bot.command unavailable; skipping native handlers");
@@ -369,6 +431,7 @@ export const registerTelegramNativeCommands = ({
             msg,
             bot,
             cfg,
+            accountId,
             telegramCfg,
             allowFrom,
             groupAllowFrom,
@@ -391,11 +454,19 @@ export const registerTelegramNativeCommands = ({
             topicConfig,
             commandAuthorized,
           } = auth;
-          const messageThreadId = (msg as { message_thread_id?: number }).message_thread_id;
-          const threadSpec = resolveTelegramThreadSpec({
-            isGroup,
-            isForum,
-            messageThreadId,
+          const { threadSpec, route, mediaLocalRoots, tableMode, chunkMode } =
+            resolveCommandRuntimeContext({
+              msg,
+              isGroup,
+              isForum,
+              resolvedThreadId,
+            });
+          const deliveryBaseOptions = buildCommandDeliveryBaseOptions({
+            chatId,
+            mediaLocalRoots,
+            threadSpec,
+            tableMode,
+            chunkMode,
           });
           const threadParams = buildTelegramThreadParams(threadSpec) ?? {};
 
@@ -449,18 +520,6 @@ export const registerTelegramNativeCommands = ({
             });
             return;
           }
-          const parentPeer = buildTelegramParentPeer({ isGroup, resolvedThreadId, chatId });
-          const route = resolveAgentRoute({
-            cfg,
-            channel: "telegram",
-            accountId,
-            peer: {
-              kind: isGroup ? "group" : "direct",
-              id: isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : String(chatId),
-            },
-            parentPeer,
-          });
-          const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
           const baseSessionKey = route.sessionKey;
           // DMs: use raw messageThreadId for thread sessions (not resolvedThreadId which is for forums)
           const dmThreadId = threadSpec.scope === "dm" ? threadSpec.id : undefined;
@@ -472,11 +531,6 @@ export const registerTelegramNativeCommands = ({
                 })
               : null;
           const sessionKey = threadKeys?.sessionKey ?? baseSessionKey;
-          const tableMode = resolveMarkdownTableMode({
-            cfg,
-            channel: "telegram",
-            accountId: route.accountId,
-          });
           const skillFilter = firstDefined(topicConfig?.skills, groupConfig?.skills);
           const systemPromptParts = [
             groupConfig?.systemPrompt?.trim() || null,
@@ -524,7 +578,6 @@ export const registerTelegramNativeCommands = ({
             typeof telegramCfg.blockStreaming === "boolean"
               ? !telegramCfg.blockStreaming
               : undefined;
-          const chunkMode = resolveChunkMode(cfg, "telegram", route.accountId);
 
           const deliveryState = {
             delivered: false,
@@ -546,17 +599,7 @@ export const registerTelegramNativeCommands = ({
               deliver: async (payload, _info) => {
                 const result = await deliverReplies({
                   replies: [payload],
-                  chatId: String(chatId),
-                  token: opts.token,
-                  runtime,
-                  bot,
-                  mediaLocalRoots,
-                  replyToMode,
-                  textLimit,
-                  thread: threadSpec,
-                  tableMode,
-                  chunkMode,
-                  linkPreview: telegramCfg.linkPreview,
+                  ...deliveryBaseOptions,
                 });
                 if (result.delivered) {
                   deliveryState.delivered = true;
@@ -580,17 +623,7 @@ export const registerTelegramNativeCommands = ({
           if (!deliveryState.delivered && deliveryState.skippedNonSilent > 0) {
             await deliverReplies({
               replies: [{ text: EMPTY_RESPONSE_FALLBACK }],
-              chatId: String(chatId),
-              token: opts.token,
-              runtime,
-              bot,
-              mediaLocalRoots,
-              replyToMode,
-              textLimit,
-              thread: threadSpec,
-              tableMode,
-              chunkMode,
-              linkPreview: telegramCfg.linkPreview,
+              ...deliveryBaseOptions,
             });
           }
         });
@@ -621,6 +654,7 @@ export const registerTelegramNativeCommands = ({
             msg,
             bot,
             cfg,
+            accountId,
             telegramCfg,
             allowFrom,
             groupAllowFrom,
@@ -633,24 +667,20 @@ export const registerTelegramNativeCommands = ({
             return;
           }
           const { senderId, commandAuthorized, isGroup, isForum, resolvedThreadId } = auth;
-          const messageThreadId = (msg as { message_thread_id?: number }).message_thread_id;
-          const threadSpec = resolveTelegramThreadSpec({
-            isGroup,
-            isForum,
-            messageThreadId,
+          const { threadSpec, mediaLocalRoots, tableMode, chunkMode } =
+            resolveCommandRuntimeContext({
+              msg,
+              isGroup,
+              isForum,
+              resolvedThreadId,
+            });
+          const deliveryBaseOptions = buildCommandDeliveryBaseOptions({
+            chatId,
+            mediaLocalRoots,
+            threadSpec,
+            tableMode,
+            chunkMode,
           });
-          const parentPeer = buildTelegramParentPeer({ isGroup, resolvedThreadId, chatId });
-          const route = resolveAgentRoute({
-            cfg,
-            channel: "telegram",
-            accountId,
-            peer: {
-              kind: isGroup ? "group" : "direct",
-              id: isGroup ? buildTelegramGroupPeerId(chatId, resolvedThreadId) : String(chatId),
-            },
-            parentPeer,
-          });
-          const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
           const from = isGroup
             ? buildTelegramGroupFrom(chatId, threadSpec.id)
             : `telegram:${chatId}`;
@@ -669,26 +699,10 @@ export const registerTelegramNativeCommands = ({
             accountId,
             messageThreadId: threadSpec.id,
           });
-          const tableMode = resolveMarkdownTableMode({
-            cfg,
-            channel: "telegram",
-            accountId: route.accountId,
-          });
-          const chunkMode = resolveChunkMode(cfg, "telegram", route.accountId);
 
           await deliverReplies({
             replies: [result],
-            chatId: String(chatId),
-            token: opts.token,
-            runtime,
-            bot,
-            mediaLocalRoots,
-            replyToMode,
-            textLimit,
-            thread: threadSpec,
-            tableMode,
-            chunkMode,
-            linkPreview: telegramCfg.linkPreview,
+            ...deliveryBaseOptions,
           });
         });
       }
diff --git a/src/telegram/bot.create-telegram-bot.accepts-group-messages-mentionpatterns-match-without-botusername.test.ts b/src/telegram/bot.create-telegram-bot.accepts-group-messages-mentionpatterns-match-without-botusername.test.ts
deleted file mode 100644
index 5768753b4f9..00000000000
--- a/src/telegram/bot.create-telegram-bot.accepts-group-messages-mentionpatterns-match-without-botusername.test.ts
+++ /dev/null
@@ -1,286 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { escapeRegExp, formatEnvelopeTimestamp } from "../../test/helpers/envelope-timestamp.js";
-import {
-  getOnHandler,
-  getLoadConfigMock,
-  onSpy,
-  replySpy,
-  sendMessageSpy,
-  setMessageReactionSpy,
-  setMyCommandsSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-const ORIGINAL_TZ = process.env.TZ;
-describe("createTelegramBot", () => {
-  function resetHarnessSpies() {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    sendMessageSpy.mockReset();
-    setMessageReactionSpy.mockReset();
-    setMyCommandsSpy.mockReset();
-  }
-
-  function getMessageHandler() {
-    createTelegramBot({ token: "tok" });
-    return getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-  }
-
-  async function dispatchMessage(params: {
-    message: Record<string, unknown>;
-    me?: Record<string, unknown>;
-  }) {
-    const handler = getMessageHandler();
-    await handler({
-      message: params.message,
-      me: params.me ?? { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-  }
-
-  beforeEach(() => {
-    process.env.TZ = "UTC";
-  });
-  afterEach(() => {
-    process.env.TZ = ORIGINAL_TZ;
-  });
-
-  // groupPolicy tests
-
-  it("accepts group messages when mentionPatterns match (without @botUsername)", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          envelopeTimezone: "utc",
-        },
-      },
-      identity: { name: "Bert" },
-      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "group", title: "Test Group" },
-        text: "bert: introduce yourself",
-        date: 1736380800,
-        message_id: 1,
-        from: { id: 9, first_name: "Ada" },
-      },
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.WasMentioned).toBe(true);
-    expect(payload.SenderName).toBe("Ada");
-    expect(payload.SenderId).toBe("9");
-    const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
-    const timestampPattern = escapeRegExp(expectedTimestamp);
-    expect(payload.Body).toMatch(
-      new RegExp(`^\\[Telegram Test Group id:7 (\\+\\d+[smhd] )?${timestampPattern}\\]`),
-    );
-  });
-
-  it("accepts group messages when mentionPatterns match even if another user is mentioned", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          envelopeTimezone: "utc",
-        },
-      },
-      identity: { name: "Bert" },
-      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "group", title: "Test Group" },
-        text: "bert: hello @alice",
-        entities: [{ type: "mention", offset: 12, length: 6 }],
-        date: 1736380800,
-        message_id: 3,
-        from: { id: 9, first_name: "Ada" },
-      },
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    expect(replySpy.mock.calls[0][0].WasMentioned).toBe(true);
-  });
-
-  it("keeps group envelope headers stable (sender identity is separate)", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          envelopeTimezone: "utc",
-        },
-      },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 42, type: "group", title: "Ops" },
-        text: "hello",
-        date: 1736380800,
-        message_id: 2,
-        from: {
-          id: 99,
-          first_name: "Ada",
-          last_name: "Lovelace",
-          username: "ada",
-        },
-      },
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.SenderName).toBe("Ada Lovelace");
-    expect(payload.SenderId).toBe("99");
-    expect(payload.SenderUsername).toBe("ada");
-    const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
-    const timestampPattern = escapeRegExp(expectedTimestamp);
-    expect(payload.Body).toMatch(
-      new RegExp(`^\\[Telegram Ops id:42 (\\+\\d+[smhd] )?${timestampPattern}\\]`),
-    );
-  });
-  it("reacts to mention-gated group messages when ackReaction is enabled", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      messages: {
-        ackReaction: "👀",
-        ackReactionScope: "group-mentions",
-        groupChat: { mentionPatterns: ["\\bbert\\b"] },
-      },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "group", title: "Test Group" },
-        text: "bert hello",
-        date: 1736380800,
-        message_id: 123,
-        from: { id: 9, first_name: "Ada" },
-      },
-    });
-
-    expect(setMessageReactionSpy).toHaveBeenCalledWith(7, 123, [{ type: "emoji", emoji: "👀" }]);
-  });
-  it("clears native commands when disabled", () => {
-    resetHarnessSpies();
-    loadConfig.mockReturnValue({
-      commands: { native: false },
-    });
-
-    createTelegramBot({ token: "tok" });
-
-    expect(setMyCommandsSpy).toHaveBeenCalledWith([]);
-  });
-  it("skips group messages when requireMention is enabled and no mention matches", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "group", title: "Test Group" },
-        text: "hello everyone",
-        date: 1736380800,
-        message_id: 2,
-        from: { id: 9, first_name: "Ada" },
-      },
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("allows group messages when requireMention is enabled but mentions cannot be detected", async () => {
-    resetHarnessSpies();
-
-    loadConfig.mockReturnValue({
-      messages: { groupChat: { mentionPatterns: [] } },
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "group", title: "Test Group" },
-        text: "hello everyone",
-        date: 1736380800,
-        message_id: 3,
-        from: { id: 9, first_name: "Ada" },
-      },
-      me: {},
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.WasMentioned).toBe(false);
-  });
-  it("includes reply-to context when a Telegram reply is received", async () => {
-    resetHarnessSpies();
-
-    await dispatchMessage({
-      message: {
-        chat: { id: 7, type: "private" },
-        text: "Sure, see below",
-        date: 1736380800,
-        reply_to_message: {
-          message_id: 9001,
-          text: "Can you summarize this?",
-          from: { first_name: "Ada" },
-        },
-      },
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.Body).toContain("[Replying to Ada id:9001]");
-    expect(payload.Body).toContain("Can you summarize this?");
-    expect(payload.ReplyToId).toBe("9001");
-    expect(payload.ReplyToBody).toBe("Can you summarize this?");
-    expect(payload.ReplyToSender).toBe("Ada");
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.applies-topic-skill-filters-system-prompts.test.ts b/src/telegram/bot.create-telegram-bot.applies-topic-skill-filters-system-prompts.test.ts
deleted file mode 100644
index bf7486644bb..00000000000
--- a/src/telegram/bot.create-telegram-bot.applies-topic-skill-filters-system-prompts.test.ts
+++ /dev/null
@@ -1,187 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  commandSpy,
-  getOnHandler,
-  getLoadConfigMock,
-  makeForumGroupMessageCtx,
-  onSpy,
-  replySpy,
-  sendMessageSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("applies topic skill filters and system prompts", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: {
-            "-1001234567890": {
-              requireMention: false,
-              systemPrompt: "Group prompt",
-              skills: ["group-skill"],
-              topics: {
-                "99": {
-                  skills: [],
-                  systemPrompt: "Topic prompt",
-                },
-              },
-            },
-          },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.GroupSystemPrompt).toBe("Group prompt\n\nTopic prompt");
-    const opts = replySpy.mock.calls[0][1];
-    expect(opts?.skillFilter).toEqual([]);
-  });
-  it("passes message_thread_id to topic replies", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    commandSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({ text: "response" });
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
-
-    expect(sendMessageSpy).toHaveBeenCalledWith(
-      "-1001234567890",
-      expect.any(String),
-      expect.objectContaining({ message_thread_id: 99 }),
-    );
-  });
-  it("threads native command replies inside topics", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    commandSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({ text: "response" });
-
-    loadConfig.mockReturnValue({
-      commands: { native: true },
-      channels: {
-        telegram: {
-          dmPolicy: "open",
-          allowFrom: ["*"],
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    expect(commandSpy).toHaveBeenCalled();
-    const handler = commandSpy.mock.calls[0][1] as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      ...makeForumGroupMessageCtx({ threadId: 99, text: "/status" }),
-      match: "",
-    });
-
-    expect(sendMessageSpy).toHaveBeenCalledWith(
-      "-1001234567890",
-      expect.any(String),
-      expect.objectContaining({ message_thread_id: 99 }),
-    );
-  });
-  it("skips tool summaries for native slash commands", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    commandSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockImplementation(async (_ctx, opts) => {
-      await opts?.onToolResult?.({ text: "tool update" });
-      return { text: "final reply" };
-    });
-
-    loadConfig.mockReturnValue({
-      commands: { native: true },
-      channels: {
-        telegram: {
-          dmPolicy: "open",
-          allowFrom: ["*"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const verboseHandler = commandSpy.mock.calls.find((call) => call[0] === "verbose")?.[1] as
-      | ((ctx: Record<string, unknown>) => Promise<void>)
-      | undefined;
-    if (!verboseHandler) {
-      throw new Error("verbose command handler missing");
-    }
-
-    await verboseHandler({
-      message: {
-        chat: { id: 12345, type: "private" },
-        from: { id: 12345, username: "testuser" },
-        text: "/verbose on",
-        date: 1736380800,
-        message_id: 42,
-      },
-      match: "on",
-    });
-
-    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
-    expect(sendMessageSpy.mock.calls[0]?.[1]).toContain("final reply");
-  });
-  it("dedupes duplicate message updates by update_id", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"] },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    const ctx = {
-      update: { update_id: 111 },
-      message: {
-        chat: { id: 123, type: "private" },
-        from: { id: 456, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-        message_id: 42,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    };
-
-    await handler(ctx);
-    await handler(ctx);
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.blocks-all-group-messages-grouppolicy-is.test.ts b/src/telegram/bot.create-telegram-bot.blocks-all-group-messages-grouppolicy-is.test.ts
deleted file mode 100644
index 40bee194b61..00000000000
--- a/src/telegram/bot.create-telegram-bot.blocks-all-group-messages-grouppolicy-is.test.ts
+++ /dev/null
@@ -1,216 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getLoadConfigMock,
-  getOnHandler,
-  onSpy,
-  replySpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("blocks all group messages when groupPolicy is 'disabled'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "disabled",
-          allowFrom: ["123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" },
-        text: "@openclaw_bot hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    // Should NOT call getReplyFromConfig because groupPolicy is disabled
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("blocks group messages from senders not in allowFrom when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["123456789"], // Does not include sender 999999
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 999999, username: "notallowed" }, // Not in allowFrom
-        text: "@openclaw_bot hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("allows group messages from senders in allowFrom (by ID) when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["123456789"],
-          groups: { "*": { requireMention: false } }, // Skip mention check
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" }, // In allowFrom
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("blocks group messages when allowFrom is configured with @username entries (numeric IDs required)", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["@testuser"], // By username
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 12345, username: "testuser" }, // Username matches @testuser
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(0);
-  });
-  it("allows group messages from telegram:-prefixed allowFrom entries when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["telegram:77112533"],
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 77112533, username: "mneves" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows group messages from tg:-prefixed allowFrom entries case-insensitively when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["TG:77112533"],
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 77112533, username: "mneves" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows all group messages when groupPolicy is 'open'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 999999, username: "random" }, // Random sender
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.dedupes-duplicate-callback-query-updates-by-update.test.ts b/src/telegram/bot.create-telegram-bot.dedupes-duplicate-callback-query-updates-by-update.test.ts
deleted file mode 100644
index 00e60d85118..00000000000
--- a/src/telegram/bot.create-telegram-bot.dedupes-duplicate-callback-query-updates-by-update.test.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getOnHandler,
-  getLoadConfigMock,
-  onSpy,
-  replySpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("dedupes duplicate callback_query updates by update_id", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"] },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("callback_query") as (
-      ctx: Record<string, unknown>,
-    ) => Promise<void>;
-
-    const ctx = {
-      update: { update_id: 222 },
-      callbackQuery: {
-        id: "cb-1",
-        data: "ping",
-        from: { id: 789, username: "testuser" },
-        message: {
-          chat: { id: 123, type: "private" },
-          date: 1736380800,
-          message_id: 9001,
-        },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({}),
-    };
-
-    await handler(ctx);
-    await handler(ctx);
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows distinct callback_query ids without update_id", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"] },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("callback_query") as (
-      ctx: Record<string, unknown>,
-    ) => Promise<void>;
-
-    await handler({
-      callbackQuery: {
-        id: "cb-1",
-        data: "ping",
-        from: { id: 789, username: "testuser" },
-        message: {
-          chat: { id: 123, type: "private" },
-          date: 1736380800,
-          message_id: 9001,
-        },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({}),
-    });
-
-    await handler({
-      callbackQuery: {
-        id: "cb-2",
-        data: "ping",
-        from: { id: 789, username: "testuser" },
-        message: {
-          chat: { id: 123, type: "private" },
-          date: 1736380800,
-          message_id: 9001,
-        },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({}),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(2);
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.installs-grammy-throttler.test.ts b/src/telegram/bot.create-telegram-bot.installs-grammy-throttler.test.ts
deleted file mode 100644
index d0f02368840..00000000000
--- a/src/telegram/bot.create-telegram-bot.installs-grammy-throttler.test.ts
+++ /dev/null
@@ -1,324 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { escapeRegExp, formatEnvelopeTimestamp } from "../../test/helpers/envelope-timestamp.js";
-import {
-  answerCallbackQuerySpy,
-  botCtorSpy,
-  getLoadConfigMock,
-  getLoadWebMediaMock,
-  getOnHandler,
-  getReadChannelAllowFromStoreMock,
-  getUpsertChannelPairingRequestMock,
-  middlewareUseSpy,
-  onSpy,
-  replySpy,
-  sendAnimationSpy,
-  sendChatActionSpy,
-  sendMessageSpy,
-  sendPhotoSpy,
-  sequentializeKey,
-  sequentializeSpy,
-  setMessageReactionSpy,
-  setMyCommandsSpy,
-  throttlerSpy,
-  useSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot, getTelegramSequentialKey } from "./bot.js";
-import { resolveTelegramFetch } from "./fetch.js";
-
-const loadConfig = getLoadConfigMock();
-const loadWebMedia = getLoadWebMediaMock();
-const readChannelAllowFromStore = getReadChannelAllowFromStoreMock();
-const upsertChannelPairingRequest = getUpsertChannelPairingRequestMock();
-
-const ORIGINAL_TZ = process.env.TZ;
-
-describe("createTelegramBot", () => {
-  beforeEach(() => {
-    process.env.TZ = "UTC";
-    loadConfig.mockReturnValue({
-      agents: {
-        defaults: {
-          envelopeTimezone: "utc",
-        },
-      },
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"] },
-      },
-    });
-    loadWebMedia.mockReset();
-    sendAnimationSpy.mockReset();
-    sendPhotoSpy.mockReset();
-    setMessageReactionSpy.mockReset();
-    answerCallbackQuerySpy.mockReset();
-    setMyCommandsSpy.mockReset();
-    middlewareUseSpy.mockReset();
-    sequentializeSpy.mockReset();
-    botCtorSpy.mockReset();
-  });
-  afterEach(() => {
-    process.env.TZ = ORIGINAL_TZ;
-  });
-
-  // groupPolicy tests
-
-  it("installs grammY throttler", () => {
-    createTelegramBot({ token: "tok" });
-    expect(throttlerSpy).toHaveBeenCalledTimes(1);
-    expect(useSpy).toHaveBeenCalledWith("throttler");
-  });
-  it("uses wrapped fetch when global fetch is available", () => {
-    const originalFetch = globalThis.fetch;
-    const fetchSpy = vi.fn() as unknown as typeof fetch;
-    globalThis.fetch = fetchSpy;
-    try {
-      createTelegramBot({ token: "tok" });
-      const fetchImpl = resolveTelegramFetch();
-      expect(fetchImpl).toBeTypeOf("function");
-      expect(fetchImpl).not.toBe(fetchSpy);
-      const clientFetch = (botCtorSpy.mock.calls[0]?.[1] as { client?: { fetch?: unknown } })
-        ?.client?.fetch;
-      expect(clientFetch).toBeTypeOf("function");
-      expect(clientFetch).not.toBe(fetchSpy);
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
-  });
-  it("passes timeoutSeconds even without a custom fetch", () => {
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"], timeoutSeconds: 60 },
-      },
-    });
-    createTelegramBot({ token: "tok" });
-    expect(botCtorSpy).toHaveBeenCalledWith(
-      "tok",
-      expect.objectContaining({
-        client: expect.objectContaining({ timeoutSeconds: 60 }),
-      }),
-    );
-  });
-  it("prefers per-account timeoutSeconds overrides", () => {
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          dmPolicy: "open",
-          allowFrom: ["*"],
-          timeoutSeconds: 60,
-          accounts: {
-            foo: { timeoutSeconds: 61 },
-          },
-        },
-      },
-    });
-    createTelegramBot({ token: "tok", accountId: "foo" });
-    expect(botCtorSpy).toHaveBeenCalledWith(
-      "tok",
-      expect.objectContaining({
-        client: expect.objectContaining({ timeoutSeconds: 61 }),
-      }),
-    );
-  });
-  it("sequentializes updates by chat and thread", () => {
-    createTelegramBot({ token: "tok" });
-    expect(sequentializeSpy).toHaveBeenCalledTimes(1);
-    expect(middlewareUseSpy).toHaveBeenCalledWith(sequentializeSpy.mock.results[0]?.value);
-    expect(sequentializeKey).toBe(getTelegramSequentialKey);
-    expect(getTelegramSequentialKey({ message: { chat: { id: 123 } } })).toBe("telegram:123");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123, type: "private" }, message_thread_id: 9 },
-      }),
-    ).toBe("telegram:123:topic:9");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123, type: "supergroup" }, message_thread_id: 9 },
-      }),
-    ).toBe("telegram:123");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123, type: "supergroup", is_forum: true } },
-      }),
-    ).toBe("telegram:123:topic:1");
-    expect(
-      getTelegramSequentialKey({
-        update: { message: { chat: { id: 555 } } },
-      }),
-    ).toBe("telegram:555");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123 }, text: "/stop" },
-      }),
-    ).toBe("telegram:123:control");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123 }, text: "/status" },
-      }),
-    ).toBe("telegram:123:control");
-    expect(
-      getTelegramSequentialKey({
-        message: { chat: { id: 123 }, text: "stop" },
-      }),
-    ).toBe("telegram:123:control");
-  });
-  it("routes callback_query payloads as messages and answers callbacks", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    createTelegramBot({ token: "tok" });
-    const callbackHandler = onSpy.mock.calls.find((call) => call[0] === "callback_query")?.[1] as (
-      ctx: Record<string, unknown>,
-    ) => Promise<void>;
-    expect(callbackHandler).toBeDefined();
-
-    await callbackHandler({
-      callbackQuery: {
-        id: "cbq-1",
-        data: "cmd:option_a",
-        from: { id: 9, first_name: "Ada", username: "ada_bot" },
-        message: {
-          chat: { id: 1234, type: "private" },
-          date: 1736380800,
-          message_id: 10,
-        },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.Body).toContain("cmd:option_a");
-    expect(answerCallbackQuerySpy).toHaveBeenCalledWith("cbq-1");
-  });
-  it("wraps inbound message with Telegram envelope", async () => {
-    const originalTz = process.env.TZ;
-    process.env.TZ = "Europe/Vienna";
-
-    try {
-      onSpy.mockReset();
-      replySpy.mockReset();
-
-      createTelegramBot({ token: "tok" });
-      expect(onSpy).toHaveBeenCalledWith("message", expect.any(Function));
-      const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-      const message = {
-        chat: { id: 1234, type: "private" },
-        text: "hello world",
-        date: 1736380800, // 2025-01-09T00:00:00Z
-        from: {
-          first_name: "Ada",
-          last_name: "Lovelace",
-          username: "ada_bot",
-        },
-      };
-      await handler({
-        message,
-        me: { username: "openclaw_bot" },
-        getFile: async () => ({ download: async () => new Uint8Array() }),
-      });
-
-      expect(replySpy).toHaveBeenCalledTimes(1);
-      const payload = replySpy.mock.calls[0][0];
-      const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
-      const timestampPattern = escapeRegExp(expectedTimestamp);
-      expect(payload.Body).toMatch(
-        new RegExp(
-          `^\\[Telegram Ada Lovelace \\(@ada_bot\\) id:1234 (\\+\\d+[smhd] )?${timestampPattern}\\]`,
-        ),
-      );
-      expect(payload.Body).toContain("hello world");
-    } finally {
-      process.env.TZ = originalTz;
-    }
-  });
-  it("requests pairing by default for unknown DM senders", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: { telegram: { dmPolicy: "pairing" } },
-    });
-    readChannelAllowFromStore.mockResolvedValue([]);
-    upsertChannelPairingRequest.mockResolvedValue({
-      code: "PAIRME12",
-      created: true,
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 1234, type: "private" },
-        text: "hello",
-        date: 1736380800,
-        from: { id: 999, username: "random" },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
-    expect(sendMessageSpy.mock.calls[0]?.[0]).toBe(1234);
-    const pairingText = String(sendMessageSpy.mock.calls[0]?.[1]);
-    expect(pairingText).toContain("Your Telegram user id: 999");
-    expect(pairingText).toContain("Pairing code:");
-    expect(pairingText).toContain("PAIRME12");
-    expect(pairingText).toContain("openclaw pairing approve telegram PAIRME12");
-    expect(pairingText).not.toContain("<code>");
-  });
-  it("does not resend pairing code when a request is already pending", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: { telegram: { dmPolicy: "pairing" } },
-    });
-    readChannelAllowFromStore.mockResolvedValue([]);
-    upsertChannelPairingRequest
-      .mockResolvedValueOnce({ code: "PAIRME12", created: true })
-      .mockResolvedValueOnce({ code: "PAIRME12", created: false });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    const message = {
-      chat: { id: 1234, type: "private" },
-      text: "hello",
-      date: 1736380800,
-      from: { id: 999, username: "random" },
-    };
-
-    await handler({
-      message,
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-    await handler({
-      message: { ...message, text: "hello again" },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
-  });
-  it("triggers typing cue via onReplyStart", async () => {
-    onSpy.mockReset();
-    sendChatActionSpy.mockReset();
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-    await handler({
-      message: { chat: { id: 42, type: "private" }, text: "hi" },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendChatActionSpy).toHaveBeenCalledWith(42, "typing", undefined);
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.matches-tg-prefixed-allowfrom-entries-case-insensitively.test.ts b/src/telegram/bot.create-telegram-bot.matches-tg-prefixed-allowfrom-entries-case-insensitively.test.ts
deleted file mode 100644
index 8e3717949fe..00000000000
--- a/src/telegram/bot.create-telegram-bot.matches-tg-prefixed-allowfrom-entries-case-insensitively.test.ts
+++ /dev/null
@@ -1,197 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getLoadConfigMock,
-  getOnHandler,
-  makeForumGroupMessageCtx,
-  onSpy,
-  replySpy,
-  sendChatActionSpy,
-  sendMessageSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("matches tg:-prefixed allowFrom entries case-insensitively in group allowlist", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["TG:123456789"], // Prefixed format (case-insensitive)
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" }, // Matches after stripping tg: prefix
-        text: "hello from prefixed user",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    // Should call reply because sender ID matches after stripping tg: prefix
-    expect(replySpy).toHaveBeenCalled();
-  });
-  it("blocks group messages when groupPolicy allowlist has no groupAllowFrom", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("allows control commands with TG-prefixed groupAllowFrom entries", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          groupAllowFrom: ["  TG:123456789  "],
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" },
-        text: "/status",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("isolates forum topic sessions and carries thread metadata", async () => {
-    onSpy.mockReset();
-    sendChatActionSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.SessionKey).toContain("telegram:group:-1001234567890:topic:99");
-    expect(payload.From).toBe("telegram:group:-1001234567890:topic:99");
-    expect(payload.MessageThreadId).toBe(99);
-    expect(payload.IsForum).toBe(true);
-    expect(sendChatActionSpy).toHaveBeenCalledWith(-1001234567890, "typing", {
-      message_thread_id: 99,
-    });
-  });
-  it("falls back to General topic thread id for typing in forums", async () => {
-    onSpy.mockReset();
-    sendChatActionSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler(makeForumGroupMessageCtx({ threadId: undefined }));
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    expect(sendChatActionSpy).toHaveBeenCalledWith(-1001234567890, "typing", {
-      message_thread_id: 1,
-    });
-  });
-  it("routes General topic replies using thread id 1", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({ text: "response" });
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: {
-          id: -1001234567890,
-          type: "supergroup",
-          title: "Forum Group",
-          is_forum: true,
-        },
-        from: { id: 12345, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-        message_id: 42,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
-    const sendParams = sendMessageSpy.mock.calls[0]?.[2] as { message_thread_id?: number };
-    expect(sendParams?.message_thread_id).toBeUndefined();
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.matches-usernames-case-insensitively-grouppolicy-is.test.ts b/src/telegram/bot.create-telegram-bot.matches-usernames-case-insensitively-grouppolicy-is.test.ts
deleted file mode 100644
index c4d434249ff..00000000000
--- a/src/telegram/bot.create-telegram-bot.matches-usernames-case-insensitively-grouppolicy-is.test.ts
+++ /dev/null
@@ -1,266 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getLoadConfigMock,
-  getOnHandler,
-  onSpy,
-  replySpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("blocks @username allowFrom entries when groupPolicy is 'allowlist' (numeric IDs required)", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["@TestUser"], // Uppercase in config
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 12345, username: "testuser" }, // Lowercase in message
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(0);
-  });
-  it("allows direct messages regardless of groupPolicy", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "disabled", // Even with disabled, DMs should work
-          allowFrom: ["123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123456789, type: "private" }, // Direct message
-        from: { id: 123456789, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows direct messages with tg/Telegram-prefixed allowFrom entries", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          allowFrom: ["  TG:123456789  "],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123456789, type: "private" }, // Direct message
-        from: { id: 123456789, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows direct messages with telegram:-prefixed allowFrom entries", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          allowFrom: ["telegram:123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123456789, type: "private" },
-        from: { id: 123456789, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("matches direct message allowFrom against sender user id when chat id differs", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          allowFrom: ["123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 777777777, type: "private" },
-        from: { id: 123456789, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("falls back to direct message chat id when sender user id is missing", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          allowFrom: ["123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123456789, type: "private" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows group messages with wildcard in allowFrom when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["*"], // Wildcard allows everyone
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 999999, username: "random" }, // Random sender, but wildcard allows
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("blocks group messages with no sender ID when groupPolicy is 'allowlist'", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["123456789"],
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        // No `from` field (e.g., channel post or anonymous admin)
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("matches telegram:-prefixed allowFrom entries in group allowlist", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "allowlist",
-          allowFrom: ["telegram:123456789"], // Prefixed format
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: -100123456789, type: "group", title: "Test Group" },
-        from: { id: 123456789, username: "testuser" }, // Matches after stripping prefix
-        text: "hello from prefixed user",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    // Should call reply because sender ID matches after stripping telegram: prefix
-    expect(replySpy).toHaveBeenCalled();
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.routes-dms-by-telegram-accountid-binding.test.ts b/src/telegram/bot.create-telegram-bot.routes-dms-by-telegram-accountid-binding.test.ts
deleted file mode 100644
index 44f11894953..00000000000
--- a/src/telegram/bot.create-telegram-bot.routes-dms-by-telegram-accountid-binding.test.ts
+++ /dev/null
@@ -1,340 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  getLoadConfigMock,
-  getLoadWebMediaMock,
-  getOnHandler,
-  onSpy,
-  replySpy,
-  sendAnimationSpy,
-  sendPhotoSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-const loadWebMedia = getLoadWebMediaMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("routes DMs by telegram accountId binding", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          accounts: {
-            opie: {
-              botToken: "tok-opie",
-              dmPolicy: "open",
-            },
-          },
-        },
-      },
-      bindings: [
-        {
-          agentId: "opie",
-          match: { channel: "telegram", accountId: "opie" },
-        },
-      ],
-    });
-
-    createTelegramBot({ token: "tok", accountId: "opie" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123, type: "private" },
-        from: { id: 999, username: "testuser" },
-        text: "hello",
-        date: 1736380800,
-        message_id: 42,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    expect(payload.AccountId).toBe("opie");
-    expect(payload.SessionKey).toBe("agent:opie:main");
-  });
-  it("allows per-group requireMention override", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: {
-            "*": { requireMention: true },
-            "123": { requireMention: false },
-          },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123, type: "group", title: "Dev Chat" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("allows per-topic requireMention override", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: {
-            "*": { requireMention: true },
-            "-1001234567890": {
-              requireMention: true,
-              topics: {
-                "99": { requireMention: false },
-              },
-            },
-          },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: {
-          id: -1001234567890,
-          type: "supergroup",
-          title: "Forum Group",
-          is_forum: true,
-        },
-        text: "hello",
-        date: 1736380800,
-        message_thread_id: 99,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("honors groups default when no explicit group override exists", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 456, type: "group", title: "Ops" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("does not block group messages when bot username is unknown", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 789, type: "group", title: "No Me" },
-        text: "hello",
-        date: 1736380800,
-      },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-  it("routes forum topic messages using parent group binding", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    // Binding specifies the base group ID without topic suffix.
-    // The fix passes parentPeer to resolveAgentRoute so the binding matches
-    // even when the actual peer id includes the topic suffix.
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-      agents: {
-        list: [{ id: "forum-agent" }],
-      },
-      bindings: [
-        {
-          agentId: "forum-agent",
-          match: {
-            channel: "telegram",
-            peer: { kind: "group", id: "-1001234567890" },
-          },
-        },
-      ],
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    // Message comes from a forum topic (has message_thread_id and is_forum=true)
-    await handler({
-      message: {
-        chat: {
-          id: -1001234567890,
-          type: "supergroup",
-          title: "Forum Group",
-          is_forum: true,
-        },
-        text: "hello from topic",
-        date: 1736380800,
-        message_id: 42,
-        message_thread_id: 99,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    // Should route to forum-agent via parent peer binding inheritance
-    expect(payload.SessionKey).toContain("agent:forum-agent:");
-  });
-
-  it("prefers specific topic binding over parent group binding", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    // Both a specific topic binding and a parent group binding are configured.
-    // The specific topic binding should take precedence.
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: false } },
-        },
-      },
-      agents: {
-        list: [{ id: "topic-agent" }, { id: "group-agent" }],
-      },
-      bindings: [
-        {
-          agentId: "topic-agent",
-          match: {
-            channel: "telegram",
-            peer: { kind: "group", id: "-1001234567890:topic:99" },
-          },
-        },
-        {
-          agentId: "group-agent",
-          match: {
-            channel: "telegram",
-            peer: { kind: "group", id: "-1001234567890" },
-          },
-        },
-      ],
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    // Message from topic 99 - should match the specific topic binding
-    await handler({
-      message: {
-        chat: {
-          id: -1001234567890,
-          type: "supergroup",
-          title: "Forum Group",
-          is_forum: true,
-        },
-        text: "hello from topic 99",
-        date: 1736380800,
-        message_id: 42,
-        message_thread_id: 99,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-    const payload = replySpy.mock.calls[0][0];
-    // Should route to topic-agent (exact match) not group-agent (parent)
-    expect(payload.SessionKey).toContain("agent:topic-agent:");
-  });
-
-  it("sends GIF replies as animations", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-
-    replySpy.mockResolvedValueOnce({
-      text: "caption",
-      mediaUrl: "https://example.com/fun",
-    });
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("GIF89a"),
-      contentType: "image/gif",
-      fileName: "fun.gif",
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 1234, type: "private" },
-        text: "hello world",
-        date: 1736380800,
-        message_id: 5,
-        from: { first_name: "Ada" },
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendAnimationSpy).toHaveBeenCalledTimes(1);
-    expect(sendAnimationSpy).toHaveBeenCalledWith("1234", expect.anything(), {
-      caption: "caption",
-      parse_mode: "HTML",
-      reply_to_message_id: undefined,
-    });
-    expect(sendPhotoSpy).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.sends-replies-without-native-reply-threading.test.ts b/src/telegram/bot.create-telegram-bot.sends-replies-without-native-reply-threading.test.ts
deleted file mode 100644
index c2ac3b9ed5c..00000000000
--- a/src/telegram/bot.create-telegram-bot.sends-replies-without-native-reply-threading.test.ts
+++ /dev/null
@@ -1,224 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import {
-  getOnHandler,
-  getLoadConfigMock,
-  onSpy,
-  replySpy,
-  sendMessageSpy,
-} from "./bot.create-telegram-bot.test-harness.js";
-import { createTelegramBot } from "./bot.js";
-
-const loadConfig = getLoadConfigMock();
-
-describe("createTelegramBot", () => {
-  // groupPolicy tests
-
-  it("sends replies without native reply threading", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({ text: "a".repeat(4500) });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-    await handler({
-      message: {
-        chat: { id: 5, type: "private" },
-        text: "hi",
-        date: 1736380800,
-        message_id: 101,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
-    for (const call of sendMessageSpy.mock.calls) {
-      expect(call[2]?.reply_to_message_id).toBeUndefined();
-    }
-  });
-  it("honors replyToMode=first for threaded replies", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({
-      text: "a".repeat(4500),
-      replyToId: "101",
-    });
-
-    createTelegramBot({ token: "tok", replyToMode: "first" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-    await handler({
-      message: {
-        chat: { id: 5, type: "private" },
-        text: "hi",
-        date: 1736380800,
-        message_id: 101,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
-    const [first, ...rest] = sendMessageSpy.mock.calls;
-    expect(first?.[2]?.reply_to_message_id).toBe(101);
-    for (const call of rest) {
-      expect(call[2]?.reply_to_message_id).toBeUndefined();
-    }
-  });
-  it("prefixes final replies with responsePrefix", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({ text: "final reply" });
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { dmPolicy: "open", allowFrom: ["*"] },
-      },
-      messages: { responsePrefix: "PFX" },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-    await handler({
-      message: {
-        chat: { id: 5, type: "private" },
-        text: "hi",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
-    expect(sendMessageSpy.mock.calls[0][1]).toBe("PFX final reply");
-  });
-  it("honors replyToMode=all for threaded replies", async () => {
-    onSpy.mockReset();
-    sendMessageSpy.mockReset();
-    replySpy.mockReset();
-    replySpy.mockResolvedValue({
-      text: "a".repeat(4500),
-      replyToId: "101",
-    });
-
-    createTelegramBot({ token: "tok", replyToMode: "all" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-    await handler({
-      message: {
-        chat: { id: 5, type: "private" },
-        text: "hi",
-        date: 1736380800,
-        message_id: 101,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
-    for (const call of sendMessageSpy.mock.calls) {
-      expect(call[2]?.reply_to_message_id).toBe(101);
-    }
-  });
-  it("blocks group messages when telegram.groups is set without a wildcard", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groups: {
-            "123": { requireMention: false },
-          },
-        },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 456, type: "group", title: "Ops" },
-        text: "@openclaw_bot hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("skips group messages without mention when requireMention is enabled", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: { groups: { "*": { requireMention: true } } },
-      },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123, type: "group", title: "Dev Chat" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).not.toHaveBeenCalled();
-  });
-  it("honors routed group activation from session store", async () => {
-    onSpy.mockReset();
-    replySpy.mockReset();
-    const storeDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-telegram-"));
-    const storePath = path.join(storeDir, "sessions.json");
-    fs.writeFileSync(
-      storePath,
-      JSON.stringify({
-        "agent:ops:telegram:group:123": { groupActivation: "always" },
-      }),
-      "utf-8",
-    );
-    loadConfig.mockReturnValue({
-      channels: {
-        telegram: {
-          groupPolicy: "open",
-          groups: { "*": { requireMention: true } },
-        },
-      },
-      bindings: [
-        {
-          agentId: "ops",
-          match: {
-            channel: "telegram",
-            peer: { kind: "group", id: "123" },
-          },
-        },
-      ],
-      session: { store: storePath },
-    });
-
-    createTelegramBot({ token: "tok" });
-    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
-
-    await handler({
-      message: {
-        chat: { id: 123, type: "group", title: "Routing" },
-        text: "hello",
-        date: 1736380800,
-      },
-      me: { username: "openclaw_bot" },
-      getFile: async () => ({ download: async () => new Uint8Array() }),
-    });
-
-    expect(replySpy).toHaveBeenCalledTimes(1);
-  });
-});
diff --git a/src/telegram/bot.create-telegram-bot.test-harness.ts b/src/telegram/bot.create-telegram-bot.test-harness.ts
index 7eb9aaf8745..2bb54660538 100644
--- a/src/telegram/bot.create-telegram-bot.test-harness.ts
+++ b/src/telegram/bot.create-telegram-bot.test-harness.ts
@@ -76,6 +76,35 @@ vi.mock("../pairing/pairing-store.js", () => ({
   upsertChannelPairingRequest,
 }));
 
+const skillCommandsHoisted = vi.hoisted(() => ({
+  listSkillCommandsForAgents: vi.fn(() => []),
+}));
+export const listSkillCommandsForAgents = skillCommandsHoisted.listSkillCommandsForAgents;
+
+vi.mock("../auto-reply/skill-commands.js", () => ({
+  listSkillCommandsForAgents,
+}));
+
+const systemEventsHoisted = vi.hoisted(() => ({
+  enqueueSystemEventSpy: vi.fn(),
+}));
+export const enqueueSystemEventSpy: AnyMock = systemEventsHoisted.enqueueSystemEventSpy;
+
+vi.mock("../infra/system-events.js", () => ({
+  enqueueSystemEvent: enqueueSystemEventSpy,
+}));
+
+const sentMessageCacheHoisted = vi.hoisted(() => ({
+  wasSentByBot: vi.fn(() => false),
+}));
+export const wasSentByBot = sentMessageCacheHoisted.wasSentByBot;
+
+vi.mock("./sent-message-cache.js", () => ({
+  wasSentByBot,
+  recordSentMessage: vi.fn(),
+  clearSentMessageCache: vi.fn(),
+}));
+
 export const useSpy: MockFn<(arg: unknown) => void> = vi.fn();
 export const middlewareUseSpy: AnyMock = vi.fn();
 export const onSpy: AnyMock = vi.fn();
@@ -84,9 +113,9 @@ export const commandSpy: AnyMock = vi.fn();
 export const botCtorSpy: AnyMock = vi.fn();
 export const answerCallbackQuerySpy: AnyAsyncMock = vi.fn(async () => undefined);
 export const sendChatActionSpy: AnyMock = vi.fn();
+export const editMessageTextSpy: AnyAsyncMock = vi.fn(async () => ({ message_id: 88 }));
 export const setMessageReactionSpy: AnyAsyncMock = vi.fn(async () => undefined);
 export const setMyCommandsSpy: AnyAsyncMock = vi.fn(async () => undefined);
-export const deleteMyCommandsSpy: AnyAsyncMock = vi.fn(async () => undefined);
 export const getMeSpy: AnyAsyncMock = vi.fn(async () => ({
   username: "openclaw_bot",
   has_topics_enabled: true,
@@ -99,9 +128,9 @@ type ApiStub = {
   config: { use: (arg: unknown) => void };
   answerCallbackQuery: typeof answerCallbackQuerySpy;
   sendChatAction: typeof sendChatActionSpy;
+  editMessageText: typeof editMessageTextSpy;
   setMessageReaction: typeof setMessageReactionSpy;
   setMyCommands: typeof setMyCommandsSpy;
-  deleteMyCommands: typeof deleteMyCommandsSpy;
   getMe: typeof getMeSpy;
   sendMessage: typeof sendMessageSpy;
   sendAnimation: typeof sendAnimationSpy;
@@ -112,9 +141,9 @@ const apiStub: ApiStub = {
   config: { use: useSpy },
   answerCallbackQuery: answerCallbackQuerySpy,
   sendChatAction: sendChatActionSpy,
+  editMessageText: editMessageTextSpy,
   setMessageReaction: setMessageReactionSpy,
   setMyCommands: setMyCommandsSpy,
-  deleteMyCommands: deleteMyCommandsSpy,
   getMe: getMeSpy,
   sendMessage: sendMessageSpy,
   sendAnimation: sendAnimationSpy,
@@ -228,16 +257,31 @@ export function makeForumGroupMessageCtx(params?: {
 
 beforeEach(() => {
   resetInboundDedupe();
+  loadConfig.mockReset();
   loadConfig.mockReturnValue({
+    agents: {
+      defaults: {
+        envelopeTimezone: "utc",
+      },
+    },
     channels: {
       telegram: { dmPolicy: "open", allowFrom: ["*"] },
     },
   });
   loadWebMedia.mockReset();
+  readChannelAllowFromStore.mockReset();
+  readChannelAllowFromStore.mockResolvedValue([]);
+  upsertChannelPairingRequest.mockReset();
+  upsertChannelPairingRequest.mockResolvedValue({ code: "PAIRCODE", created: true } as const);
   onSpy.mockReset();
   commandSpy.mockReset();
   stopSpy.mockReset();
   useSpy.mockReset();
+  replySpy.mockReset();
+  replySpy.mockImplementation(async (_ctx, opts) => {
+    await opts?.onReplyStart?.();
+    return undefined;
+  });
 
   sendAnimationSpy.mockReset();
   sendAnimationSpy.mockResolvedValue({ message_id: 78 });
@@ -254,13 +298,18 @@ beforeEach(() => {
   sendChatActionSpy.mockResolvedValue(undefined);
   setMyCommandsSpy.mockReset();
   setMyCommandsSpy.mockResolvedValue(undefined);
-  deleteMyCommandsSpy.mockReset();
-  deleteMyCommandsSpy.mockResolvedValue(undefined);
   getMeSpy.mockReset();
   getMeSpy.mockResolvedValue({
     username: "openclaw_bot",
     has_topics_enabled: true,
   });
+  editMessageTextSpy.mockReset();
+  editMessageTextSpy.mockResolvedValue({ message_id: 88 });
+  enqueueSystemEventSpy.mockReset();
+  wasSentByBot.mockReset();
+  wasSentByBot.mockReturnValue(false);
+  listSkillCommandsForAgents.mockReset();
+  listSkillCommandsForAgents.mockReturnValue([]);
   middlewareUseSpy.mockReset();
   sequentializeSpy.mockReset();
   botCtorSpy.mockReset();
diff --git a/src/telegram/bot.create-telegram-bot.test.ts b/src/telegram/bot.create-telegram-bot.test.ts
new file mode 100644
index 00000000000..8704eebeb7e
--- /dev/null
+++ b/src/telegram/bot.create-telegram-bot.test.ts
@@ -0,0 +1,1881 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { escapeRegExp, formatEnvelopeTimestamp } from "../../test/helpers/envelope-timestamp.js";
+import {
+  answerCallbackQuerySpy,
+  botCtorSpy,
+  commandSpy,
+  getLoadConfigMock,
+  getLoadWebMediaMock,
+  getOnHandler,
+  getReadChannelAllowFromStoreMock,
+  getUpsertChannelPairingRequestMock,
+  makeForumGroupMessageCtx,
+  middlewareUseSpy,
+  onSpy,
+  replySpy,
+  sendAnimationSpy,
+  sendChatActionSpy,
+  sendMessageSpy,
+  sendPhotoSpy,
+  sequentializeKey,
+  sequentializeSpy,
+  setMessageReactionSpy,
+  setMyCommandsSpy,
+  throttlerSpy,
+  useSpy,
+} from "./bot.create-telegram-bot.test-harness.js";
+import { createTelegramBot, getTelegramSequentialKey } from "./bot.js";
+import { resolveTelegramFetch } from "./fetch.js";
+
+const loadConfig = getLoadConfigMock();
+const loadWebMedia = getLoadWebMediaMock();
+const readChannelAllowFromStore = getReadChannelAllowFromStoreMock();
+const upsertChannelPairingRequest = getUpsertChannelPairingRequestMock();
+
+const ORIGINAL_TZ = process.env.TZ;
+
+describe("createTelegramBot", () => {
+  beforeEach(() => {
+    process.env.TZ = "UTC";
+  });
+  afterEach(() => {
+    process.env.TZ = ORIGINAL_TZ;
+  });
+
+  // groupPolicy tests
+
+  it("installs grammY throttler", () => {
+    createTelegramBot({ token: "tok" });
+    expect(throttlerSpy).toHaveBeenCalledTimes(1);
+    expect(useSpy).toHaveBeenCalledWith("throttler");
+  });
+  it("uses wrapped fetch when global fetch is available", () => {
+    const originalFetch = globalThis.fetch;
+    const fetchSpy = vi.fn() as unknown as typeof fetch;
+    globalThis.fetch = fetchSpy;
+    try {
+      createTelegramBot({ token: "tok" });
+      const fetchImpl = resolveTelegramFetch();
+      expect(fetchImpl).toBeTypeOf("function");
+      expect(fetchImpl).not.toBe(fetchSpy);
+      const clientFetch = (botCtorSpy.mock.calls[0]?.[1] as { client?: { fetch?: unknown } })
+        ?.client?.fetch;
+      expect(clientFetch).toBeTypeOf("function");
+      expect(clientFetch).not.toBe(fetchSpy);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+  it("applies global and per-account timeoutSeconds", () => {
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: { dmPolicy: "open", allowFrom: ["*"], timeoutSeconds: 60 },
+      },
+    });
+    createTelegramBot({ token: "tok" });
+    expect(botCtorSpy).toHaveBeenCalledWith(
+      "tok",
+      expect.objectContaining({
+        client: expect.objectContaining({ timeoutSeconds: 60 }),
+      }),
+    );
+    botCtorSpy.mockClear();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          timeoutSeconds: 60,
+          accounts: {
+            foo: { timeoutSeconds: 61 },
+          },
+        },
+      },
+    });
+    createTelegramBot({ token: "tok", accountId: "foo" });
+    expect(botCtorSpy).toHaveBeenCalledWith(
+      "tok",
+      expect.objectContaining({
+        client: expect.objectContaining({ timeoutSeconds: 61 }),
+      }),
+    );
+  });
+  it("sequentializes updates by chat and thread", () => {
+    createTelegramBot({ token: "tok" });
+    expect(sequentializeSpy).toHaveBeenCalledTimes(1);
+    expect(middlewareUseSpy).toHaveBeenCalledWith(sequentializeSpy.mock.results[0]?.value);
+    expect(sequentializeKey).toBe(getTelegramSequentialKey);
+    expect(getTelegramSequentialKey({ message: { chat: { id: 123 } } })).toBe("telegram:123");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123, type: "private" }, message_thread_id: 9 },
+      }),
+    ).toBe("telegram:123:topic:9");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123, type: "supergroup" }, message_thread_id: 9 },
+      }),
+    ).toBe("telegram:123");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123, type: "supergroup", is_forum: true } },
+      }),
+    ).toBe("telegram:123:topic:1");
+    expect(
+      getTelegramSequentialKey({
+        update: { message: { chat: { id: 555 } } },
+      }),
+    ).toBe("telegram:555");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "/stop" },
+      }),
+    ).toBe("telegram:123:control");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "/status" },
+      }),
+    ).toBe("telegram:123");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "stop" },
+      }),
+    ).toBe("telegram:123:control");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "stop please" },
+      }),
+    ).toBe("telegram:123");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "/abort" },
+      }),
+    ).toBe("telegram:123");
+    expect(
+      getTelegramSequentialKey({
+        message: { chat: { id: 123 }, text: "/abort now" },
+      }),
+    ).toBe("telegram:123");
+  });
+  it("routes callback_query payloads as messages and answers callbacks", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    createTelegramBot({ token: "tok" });
+    const callbackHandler = onSpy.mock.calls.find((call) => call[0] === "callback_query")?.[1] as (
+      ctx: Record<string, unknown>,
+    ) => Promise<void>;
+    expect(callbackHandler).toBeDefined();
+
+    await callbackHandler({
+      callbackQuery: {
+        id: "cbq-1",
+        data: "cmd:option_a",
+        from: { id: 9, first_name: "Ada", username: "ada_bot" },
+        message: {
+          chat: { id: 1234, type: "private" },
+          date: 1736380800,
+          message_id: 10,
+        },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.Body).toContain("cmd:option_a");
+    expect(answerCallbackQuerySpy).toHaveBeenCalledWith("cbq-1");
+  });
+  it("wraps inbound message with Telegram envelope", async () => {
+    const originalTz = process.env.TZ;
+    process.env.TZ = "Europe/Vienna";
+
+    try {
+      onSpy.mockReset();
+      replySpy.mockReset();
+
+      createTelegramBot({ token: "tok" });
+      expect(onSpy).toHaveBeenCalledWith("message", expect.any(Function));
+      const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+      const message = {
+        chat: { id: 1234, type: "private" },
+        text: "hello world",
+        date: 1736380800, // 2025-01-09T00:00:00Z
+        from: {
+          first_name: "Ada",
+          last_name: "Lovelace",
+          username: "ada_bot",
+        },
+      };
+      await handler({
+        message,
+        me: { username: "openclaw_bot" },
+        getFile: async () => ({ download: async () => new Uint8Array() }),
+      });
+
+      expect(replySpy).toHaveBeenCalledTimes(1);
+      const payload = replySpy.mock.calls[0][0];
+      const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
+      const timestampPattern = escapeRegExp(expectedTimestamp);
+      expect(payload.Body).toMatch(
+        new RegExp(
+          `^\\[Telegram Ada Lovelace \\(@ada_bot\\) id:1234 (\\+\\d+[smhd] )?${timestampPattern}\\]`,
+        ),
+      );
+      expect(payload.Body).toContain("hello world");
+    } finally {
+      process.env.TZ = originalTz;
+    }
+  });
+  it("requests pairing by default for unknown DM senders", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: { telegram: { dmPolicy: "pairing" } },
+    });
+    readChannelAllowFromStore.mockResolvedValue([]);
+    upsertChannelPairingRequest.mockResolvedValue({
+      code: "PAIRME12",
+      created: true,
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 1234, type: "private" },
+        text: "hello",
+        date: 1736380800,
+        from: { id: 999, username: "random" },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
+    expect(sendMessageSpy.mock.calls[0]?.[0]).toBe(1234);
+    const pairingText = String(sendMessageSpy.mock.calls[0]?.[1]);
+    expect(pairingText).toContain("Your Telegram user id: 999");
+    expect(pairingText).toContain("Pairing code:");
+    expect(pairingText).toContain("PAIRME12");
+    expect(pairingText).toContain("openclaw pairing approve telegram PAIRME12");
+    expect(pairingText).not.toContain("<code>");
+  });
+  it("does not resend pairing code when a request is already pending", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: { telegram: { dmPolicy: "pairing" } },
+    });
+    readChannelAllowFromStore.mockResolvedValue([]);
+    upsertChannelPairingRequest
+      .mockResolvedValueOnce({ code: "PAIRME12", created: true })
+      .mockResolvedValueOnce({ code: "PAIRME12", created: false });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    const message = {
+      chat: { id: 1234, type: "private" },
+      text: "hello",
+      date: 1736380800,
+      from: { id: 999, username: "random" },
+    };
+
+    await handler({
+      message,
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+    await handler({
+      message: { ...message, text: "hello again" },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
+  });
+  it("triggers typing cue via onReplyStart", async () => {
+    onSpy.mockReset();
+    sendChatActionSpy.mockReset();
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+    await handler({
+      message: { chat: { id: 42, type: "private" }, text: "hi" },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendChatActionSpy).toHaveBeenCalledWith(42, "typing", undefined);
+  });
+
+  it("dedupes duplicate callback_query updates by update_id", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: { dmPolicy: "open", allowFrom: ["*"] },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("callback_query") as (
+      ctx: Record<string, unknown>,
+    ) => Promise<void>;
+
+    const ctx = {
+      update: { update_id: 222 },
+      callbackQuery: {
+        id: "cb-1",
+        data: "ping",
+        from: { id: 789, username: "testuser" },
+        message: {
+          chat: { id: 123, type: "private" },
+          date: 1736380800,
+          message_id: 9001,
+        },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({}),
+    };
+
+    await handler(ctx);
+    await handler(ctx);
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows distinct callback_query ids without update_id", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: { dmPolicy: "open", allowFrom: ["*"] },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("callback_query") as (
+      ctx: Record<string, unknown>,
+    ) => Promise<void>;
+
+    await handler({
+      callbackQuery: {
+        id: "cb-1",
+        data: "ping",
+        from: { id: 789, username: "testuser" },
+        message: {
+          chat: { id: 123, type: "private" },
+          date: 1736380800,
+          message_id: 9001,
+        },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({}),
+    });
+
+    await handler({
+      callbackQuery: {
+        id: "cb-2",
+        data: "ping",
+        from: { id: 789, username: "testuser" },
+        message: {
+          chat: { id: 123, type: "private" },
+          date: 1736380800,
+          message_id: 9001,
+        },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({}),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("blocks all group messages when groupPolicy is 'disabled'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "disabled",
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 123456789, username: "testuser" },
+        text: "@openclaw_bot hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("blocks group messages from senders not in allowFrom when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 999999, username: "notallowed" },
+        text: "@openclaw_bot hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("allows group messages from senders in allowFrom (by ID) when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["123456789"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("blocks group messages when allowFrom is configured with @username entries (numeric IDs required)", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["@testuser"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 12345, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(0);
+  });
+  it("allows group messages from telegram:-prefixed allowFrom entries when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["telegram:77112533"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 77112533, username: "mneves" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows group messages from tg:-prefixed allowFrom entries case-insensitively when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["TG:77112533"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 77112533, username: "mneves" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows all group messages when groupPolicy is 'open'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 999999, username: "random" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("routes DMs by telegram accountId binding", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          accounts: {
+            opie: {
+              botToken: "tok-opie",
+              dmPolicy: "open",
+            },
+          },
+        },
+      },
+      bindings: [
+        {
+          agentId: "opie",
+          match: { channel: "telegram", accountId: "opie" },
+        },
+      ],
+    });
+
+    createTelegramBot({ token: "tok", accountId: "opie" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123, type: "private" },
+        from: { id: 999, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+        message_id: 42,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.AccountId).toBe("opie");
+    expect(payload.SessionKey).toBe("agent:opie:main");
+  });
+  it("allows per-group requireMention override", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: {
+            "*": { requireMention: true },
+            "123": { requireMention: false },
+          },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123, type: "group", title: "Dev Chat" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows per-topic requireMention override", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: {
+            "*": { requireMention: true },
+            "-1001234567890": {
+              requireMention: true,
+              topics: {
+                "99": { requireMention: false },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: {
+          id: -1001234567890,
+          type: "supergroup",
+          title: "Forum Group",
+          is_forum: true,
+        },
+        text: "hello",
+        date: 1736380800,
+        message_thread_id: 99,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("honors groups default when no explicit group override exists", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 456, type: "group", title: "Ops" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("does not block group messages when bot username is unknown", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 789, type: "group", title: "No Me" },
+        text: "hello",
+        date: 1736380800,
+      },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("routes forum topic messages using parent group binding", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+      agents: {
+        list: [{ id: "forum-agent" }],
+      },
+      bindings: [
+        {
+          agentId: "forum-agent",
+          match: {
+            channel: "telegram",
+            peer: { kind: "group", id: "-1001234567890" },
+          },
+        },
+      ],
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: {
+          id: -1001234567890,
+          type: "supergroup",
+          title: "Forum Group",
+          is_forum: true,
+        },
+        text: "hello from topic",
+        date: 1736380800,
+        message_id: 42,
+        message_thread_id: 99,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.SessionKey).toContain("agent:forum-agent:");
+  });
+  it("prefers specific topic binding over parent group binding", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+      agents: {
+        list: [{ id: "topic-agent" }, { id: "group-agent" }],
+      },
+      bindings: [
+        {
+          agentId: "topic-agent",
+          match: {
+            channel: "telegram",
+            peer: { kind: "group", id: "-1001234567890:topic:99" },
+          },
+        },
+        {
+          agentId: "group-agent",
+          match: {
+            channel: "telegram",
+            peer: { kind: "group", id: "-1001234567890" },
+          },
+        },
+      ],
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: {
+          id: -1001234567890,
+          type: "supergroup",
+          title: "Forum Group",
+          is_forum: true,
+        },
+        text: "hello from topic 99",
+        date: 1736380800,
+        message_id: 42,
+        message_thread_id: 99,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.SessionKey).toContain("agent:topic-agent:");
+  });
+
+  it("sends GIF replies as animations", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    replySpy.mockResolvedValueOnce({
+      text: "caption",
+      mediaUrl: "https://example.com/fun",
+    });
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("GIF89a"),
+      contentType: "image/gif",
+      fileName: "fun.gif",
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 1234, type: "private" },
+        text: "hello world",
+        date: 1736380800,
+        message_id: 5,
+        from: { first_name: "Ada" },
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendAnimationSpy).toHaveBeenCalledTimes(1);
+    expect(sendAnimationSpy).toHaveBeenCalledWith("1234", expect.anything(), {
+      caption: "caption",
+      parse_mode: "HTML",
+      reply_to_message_id: undefined,
+    });
+    expect(sendPhotoSpy).not.toHaveBeenCalled();
+  });
+
+  function resetHarnessSpies() {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    sendMessageSpy.mockReset();
+    setMessageReactionSpy.mockReset();
+    setMyCommandsSpy.mockReset();
+  }
+  function getMessageHandler() {
+    createTelegramBot({ token: "tok" });
+    return getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+  }
+  async function dispatchMessage(params: {
+    message: Record<string, unknown>;
+    me?: Record<string, unknown>;
+  }) {
+    const handler = getMessageHandler();
+    await handler({
+      message: params.message,
+      me: params.me ?? { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+  }
+
+  it("accepts group messages when mentionPatterns match (without @botUsername)", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      agents: {
+        defaults: {
+          envelopeTimezone: "utc",
+        },
+      },
+      identity: { name: "Bert" },
+      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "group", title: "Test Group" },
+        text: "bert: introduce yourself",
+        date: 1736380800,
+        message_id: 1,
+        from: { id: 9, first_name: "Ada" },
+      },
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.WasMentioned).toBe(true);
+    expect(payload.SenderName).toBe("Ada");
+    expect(payload.SenderId).toBe("9");
+    const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
+    const timestampPattern = escapeRegExp(expectedTimestamp);
+    expect(payload.Body).toMatch(
+      new RegExp(`^\\[Telegram Test Group id:7 (\\+\\d+[smhd] )?${timestampPattern}\\]`),
+    );
+  });
+  it("accepts group messages when mentionPatterns match even if another user is mentioned", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      agents: {
+        defaults: {
+          envelopeTimezone: "utc",
+        },
+      },
+      identity: { name: "Bert" },
+      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "group", title: "Test Group" },
+        text: "bert: hello @alice",
+        entities: [{ type: "mention", offset: 12, length: 6 }],
+        date: 1736380800,
+        message_id: 3,
+        from: { id: 9, first_name: "Ada" },
+      },
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    expect(replySpy.mock.calls[0][0].WasMentioned).toBe(true);
+  });
+  it("keeps group envelope headers stable (sender identity is separate)", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      agents: {
+        defaults: {
+          envelopeTimezone: "utc",
+        },
+      },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 42, type: "group", title: "Ops" },
+        text: "hello",
+        date: 1736380800,
+        message_id: 2,
+        from: {
+          id: 99,
+          first_name: "Ada",
+          last_name: "Lovelace",
+          username: "ada",
+        },
+      },
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.SenderName).toBe("Ada Lovelace");
+    expect(payload.SenderId).toBe("99");
+    expect(payload.SenderUsername).toBe("ada");
+    const expectedTimestamp = formatEnvelopeTimestamp(new Date("2025-01-09T00:00:00Z"));
+    const timestampPattern = escapeRegExp(expectedTimestamp);
+    expect(payload.Body).toMatch(
+      new RegExp(`^\\[Telegram Ops id:42 (\\+\\d+[smhd] )?${timestampPattern}\\]`),
+    );
+  });
+  it("reacts to mention-gated group messages when ackReaction is enabled", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      messages: {
+        ackReaction: "👀",
+        ackReactionScope: "group-mentions",
+        groupChat: { mentionPatterns: ["\\bbert\\b"] },
+      },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "group", title: "Test Group" },
+        text: "bert hello",
+        date: 1736380800,
+        message_id: 123,
+        from: { id: 9, first_name: "Ada" },
+      },
+    });
+
+    expect(setMessageReactionSpy).toHaveBeenCalledWith(7, 123, [{ type: "emoji", emoji: "👀" }]);
+  });
+  it("clears native commands when disabled", () => {
+    resetHarnessSpies();
+    loadConfig.mockReturnValue({
+      commands: { native: false },
+    });
+
+    createTelegramBot({ token: "tok" });
+
+    expect(setMyCommandsSpy).toHaveBeenCalledWith([]);
+  });
+  it("skips group messages when requireMention is enabled and no mention matches", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      messages: { groupChat: { mentionPatterns: ["\\bbert\\b"] } },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "group", title: "Test Group" },
+        text: "hello everyone",
+        date: 1736380800,
+        message_id: 2,
+        from: { id: 9, first_name: "Ada" },
+      },
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("allows group messages when requireMention is enabled but mentions cannot be detected", async () => {
+    resetHarnessSpies();
+
+    loadConfig.mockReturnValue({
+      messages: { groupChat: { mentionPatterns: [] } },
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "group", title: "Test Group" },
+        text: "hello everyone",
+        date: 1736380800,
+        message_id: 3,
+        from: { id: 9, first_name: "Ada" },
+      },
+      me: {},
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.WasMentioned).toBe(false);
+  });
+  it("includes reply-to context when a Telegram reply is received", async () => {
+    resetHarnessSpies();
+
+    await dispatchMessage({
+      message: {
+        chat: { id: 7, type: "private" },
+        text: "Sure, see below",
+        date: 1736380800,
+        reply_to_message: {
+          message_id: 9001,
+          text: "Can you summarize this?",
+          from: { first_name: "Ada" },
+        },
+      },
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.Body).toContain("[Replying to Ada id:9001]");
+    expect(payload.Body).toContain("Can you summarize this?");
+    expect(payload.ReplyToId).toBe("9001");
+    expect(payload.ReplyToBody).toBe("Can you summarize this?");
+    expect(payload.ReplyToSender).toBe("Ada");
+  });
+
+  it("matches tg:-prefixed allowFrom entries case-insensitively in group allowlist", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["TG:123456789"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello from prefixed user",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalled();
+  });
+  it("blocks group messages when groupPolicy allowlist has no groupAllowFrom", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("allows control commands with TG-prefixed groupAllowFrom entries", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          groupAllowFrom: ["  TG:123456789  "],
+          groups: { "*": { requireMention: true } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 123456789, username: "testuser" },
+        text: "/status",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("isolates forum topic sessions and carries thread metadata", async () => {
+    onSpy.mockReset();
+    sendChatActionSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.SessionKey).toContain("telegram:group:-1001234567890:topic:99");
+    expect(payload.From).toBe("telegram:group:-1001234567890:topic:99");
+    expect(payload.MessageThreadId).toBe(99);
+    expect(payload.IsForum).toBe(true);
+    expect(sendChatActionSpy).toHaveBeenCalledWith(-1001234567890, "typing", {
+      message_thread_id: 99,
+    });
+  });
+  it("falls back to General topic thread id for typing in forums", async () => {
+    onSpy.mockReset();
+    sendChatActionSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler(makeForumGroupMessageCtx({ threadId: undefined }));
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    expect(sendChatActionSpy).toHaveBeenCalledWith(-1001234567890, "typing", {
+      message_thread_id: 1,
+    });
+  });
+  it("routes General topic replies using thread id 1", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({ text: "response" });
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: {
+          id: -1001234567890,
+          type: "supergroup",
+          title: "Forum Group",
+          is_forum: true,
+        },
+        from: { id: 12345, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+        message_id: 42,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
+    const sendParams = sendMessageSpy.mock.calls[0]?.[2] as { message_thread_id?: number };
+    expect(sendParams?.message_thread_id).toBeUndefined();
+  });
+
+  it("allows direct messages regardless of groupPolicy", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "disabled",
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123456789, type: "private" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows direct messages with tg/Telegram-prefixed allowFrom entries", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          allowFrom: ["  TG:123456789  "],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123456789, type: "private" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("matches direct message allowFrom against sender user id when chat id differs", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 777777777, type: "private" },
+        from: { id: 123456789, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("falls back to direct message chat id when sender user id is missing", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123456789, type: "private" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("allows group messages with wildcard in allowFrom when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["*"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        from: { id: 999999, username: "random" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+  it("blocks group messages with no sender ID when groupPolicy is 'allowlist'", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "allowlist",
+          allowFrom: ["123456789"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: -100123456789, type: "group", title: "Test Group" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("sends replies without native reply threading", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({ text: "a".repeat(4500) });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+    await handler({
+      message: {
+        chat: { id: 5, type: "private" },
+        text: "hi",
+        date: 1736380800,
+        message_id: 101,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
+    for (const call of sendMessageSpy.mock.calls) {
+      expect(
+        (call[2] as { reply_to_message_id?: number } | undefined)?.reply_to_message_id,
+      ).toBeUndefined();
+    }
+  });
+  it("honors replyToMode=first for threaded replies", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({
+      text: "a".repeat(4500),
+      replyToId: "101",
+    });
+
+    createTelegramBot({ token: "tok", replyToMode: "first" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+    await handler({
+      message: {
+        chat: { id: 5, type: "private" },
+        text: "hi",
+        date: 1736380800,
+        message_id: 101,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
+    const [first, ...rest] = sendMessageSpy.mock.calls;
+    expect((first?.[2] as { reply_to_message_id?: number } | undefined)?.reply_to_message_id).toBe(
+      101,
+    );
+    for (const call of rest) {
+      expect(
+        (call[2] as { reply_to_message_id?: number } | undefined)?.reply_to_message_id,
+      ).toBeUndefined();
+    }
+  });
+  it("prefixes final replies with responsePrefix", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({ text: "final reply" });
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: { dmPolicy: "open", allowFrom: ["*"] },
+      },
+      messages: { responsePrefix: "PFX" },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+    await handler({
+      message: {
+        chat: { id: 5, type: "private" },
+        text: "hi",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
+    expect(sendMessageSpy.mock.calls[0][1]).toBe("PFX final reply");
+  });
+  it("honors replyToMode=all for threaded replies", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({
+      text: "a".repeat(4500),
+      replyToId: "101",
+    });
+
+    createTelegramBot({ token: "tok", replyToMode: "all" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+    await handler({
+      message: {
+        chat: { id: 5, type: "private" },
+        text: "hi",
+        date: 1736380800,
+        message_id: 101,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(sendMessageSpy.mock.calls.length).toBeGreaterThan(1);
+    for (const call of sendMessageSpy.mock.calls) {
+      expect((call[2] as { reply_to_message_id?: number } | undefined)?.reply_to_message_id).toBe(
+        101,
+      );
+    }
+  });
+  it("blocks group messages when telegram.groups is set without a wildcard", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groups: {
+            "123": { requireMention: false },
+          },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 456, type: "group", title: "Ops" },
+        text: "@openclaw_bot hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).not.toHaveBeenCalled();
+  });
+  it("honors routed group activation from session store", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+    const storeDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-telegram-"));
+    const storePath = path.join(storeDir, "sessions.json");
+    fs.writeFileSync(
+      storePath,
+      JSON.stringify({
+        "agent:ops:telegram:group:123": { groupActivation: "always" },
+      }),
+      "utf-8",
+    );
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: true } },
+        },
+      },
+      bindings: [
+        {
+          agentId: "ops",
+          match: {
+            channel: "telegram",
+            peer: { kind: "group", id: "123" },
+          },
+        },
+      ],
+      session: { store: storePath },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      message: {
+        chat: { id: 123, type: "group", title: "Routing" },
+        text: "hello",
+        date: 1736380800,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    });
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies topic skill filters and system prompts", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: {
+            "-1001234567890": {
+              requireMention: false,
+              systemPrompt: "Group prompt",
+              skills: ["group-skill"],
+              topics: {
+                "99": {
+                  skills: [],
+                  systemPrompt: "Topic prompt",
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+    const payload = replySpy.mock.calls[0][0];
+    expect(payload.GroupSystemPrompt).toBe("Group prompt\n\nTopic prompt");
+    const opts = replySpy.mock.calls[0][1] as { skillFilter?: unknown };
+    expect(opts?.skillFilter).toEqual([]);
+  });
+  it("passes message_thread_id to topic replies", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    commandSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({ text: "response" });
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: {
+          groupPolicy: "open",
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler(makeForumGroupMessageCtx({ threadId: 99 }));
+
+    expect(sendMessageSpy).toHaveBeenCalledWith(
+      "-1001234567890",
+      expect.any(String),
+      expect.objectContaining({ message_thread_id: 99 }),
+    );
+  });
+  it("threads native command replies inside topics", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    commandSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockResolvedValue({ text: "response" });
+
+    loadConfig.mockReturnValue({
+      commands: { native: true },
+      channels: {
+        telegram: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          groups: { "*": { requireMention: false } },
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    expect(commandSpy).toHaveBeenCalled();
+    const handler = commandSpy.mock.calls[0][1] as (ctx: Record<string, unknown>) => Promise<void>;
+
+    await handler({
+      ...makeForumGroupMessageCtx({ threadId: 99, text: "/status" }),
+      match: "",
+    });
+
+    expect(sendMessageSpy).toHaveBeenCalledWith(
+      "-1001234567890",
+      expect.any(String),
+      expect.objectContaining({ message_thread_id: 99 }),
+    );
+  });
+  it("skips tool summaries for native slash commands", async () => {
+    onSpy.mockReset();
+    sendMessageSpy.mockReset();
+    commandSpy.mockReset();
+    replySpy.mockReset();
+    replySpy.mockImplementation(async (_ctx, opts) => {
+      await opts?.onToolResult?.({ text: "tool update" });
+      return { text: "final reply" };
+    });
+
+    loadConfig.mockReturnValue({
+      commands: { native: true },
+      channels: {
+        telegram: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+        },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const verboseHandler = commandSpy.mock.calls.find((call) => call[0] === "verbose")?.[1] as
+      | ((ctx: Record<string, unknown>) => Promise<void>)
+      | undefined;
+    if (!verboseHandler) {
+      throw new Error("verbose command handler missing");
+    }
+
+    await verboseHandler({
+      message: {
+        chat: { id: 12345, type: "private" },
+        from: { id: 12345, username: "testuser" },
+        text: "/verbose on",
+        date: 1736380800,
+        message_id: 42,
+      },
+      match: "on",
+    });
+
+    expect(sendMessageSpy).toHaveBeenCalledTimes(1);
+    expect(sendMessageSpy.mock.calls[0]?.[1]).toContain("final reply");
+  });
+  it("dedupes duplicate message updates by update_id", async () => {
+    onSpy.mockReset();
+    replySpy.mockReset();
+
+    loadConfig.mockReturnValue({
+      channels: {
+        telegram: { dmPolicy: "open", allowFrom: ["*"] },
+      },
+    });
+
+    createTelegramBot({ token: "tok" });
+    const handler = getOnHandler("message") as (ctx: Record<string, unknown>) => Promise<void>;
+
+    const ctx = {
+      update: { update_id: 111 },
+      message: {
+        chat: { id: 123, type: "private" },
+        from: { id: 456, username: "testuser" },
+        text: "hello",
+        date: 1736380800,
+        message_id: 42,
+      },
+      me: { username: "openclaw_bot" },
+      getFile: async () => ({ download: async () => new Uint8Array() }),
+    };
+
+    await handler(ctx);
+    await handler(ctx);
+
+    expect(replySpy).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/telegram/bot.test.ts b/src/telegram/bot.test.ts
index d8cf574673f..96d9bd32219 100644
--- a/src/telegram/bot.test.ts
+++ b/src/telegram/bot.test.ts
@@ -1,180 +1,38 @@
-import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { escapeRegExp, formatEnvelopeTimestamp } from "../../test/helpers/envelope-timestamp.js";
 import { expectInboundContextContract } from "../../test/helpers/inbound-contract.js";
 import {
   listNativeCommandSpecs,
   listNativeCommandSpecsForConfig,
 } from "../auto-reply/commands-registry.js";
-import { resetInboundDedupe } from "../auto-reply/reply/inbound-dedupe.js";
+import {
+  answerCallbackQuerySpy,
+  commandSpy,
+  editMessageTextSpy,
+  enqueueSystemEventSpy,
+  getLoadConfigMock,
+  getReadChannelAllowFromStoreMock,
+  getOnHandler,
+  listSkillCommandsForAgents,
+  onSpy,
+  replySpy,
+  sendMessageSpy,
+  setMyCommandsSpy,
+  wasSentByBot,
+} from "./bot.create-telegram-bot.test-harness.js";
 import { createTelegramBot } from "./bot.js";
 
-let replyModule: typeof import("../auto-reply/reply.js");
-const { listSkillCommandsForAgents } = vi.hoisted(() => ({
-  listSkillCommandsForAgents: vi.fn(() => []),
-}));
-vi.mock("../auto-reply/skill-commands.js", () => ({
-  listSkillCommandsForAgents,
-}));
-
-const { sessionStorePath } = vi.hoisted(() => ({
-  sessionStorePath: `/tmp/openclaw-telegram-bot-${Math.random().toString(16).slice(2)}.json`,
-}));
+const loadConfig = getLoadConfigMock();
+const readChannelAllowFromStore = getReadChannelAllowFromStoreMock();
 
 function resolveSkillCommands(config: Parameters<typeof listNativeCommandSpecsForConfig>[0]) {
   return listSkillCommandsForAgents({ cfg: config });
 }
 
-const { loadWebMedia } = vi.hoisted(() => ({
-  loadWebMedia: vi.fn(),
-}));
-
-vi.mock("../web/media.js", () => ({
-  loadWebMedia,
-}));
-
-const { loadConfig } = vi.hoisted(() => ({
-  loadConfig: vi.fn(() => ({})),
-}));
-vi.mock("../config/config.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../config/config.js")>();
-  return {
-    ...actual,
-    loadConfig,
-  };
-});
-
-vi.mock("../config/sessions.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../config/sessions.js")>();
-  return {
-    ...actual,
-    resolveStorePath: vi.fn((storePath) => storePath ?? sessionStorePath),
-  };
-});
-
-const { readChannelAllowFromStore, upsertChannelPairingRequest } = vi.hoisted(() => ({
-  readChannelAllowFromStore: vi.fn(async () => [] as string[]),
-  upsertChannelPairingRequest: vi.fn(async () => ({
-    code: "PAIRCODE",
-    created: true,
-  })),
-}));
-
-vi.mock("../pairing/pairing-store.js", () => ({
-  readChannelAllowFromStore,
-  upsertChannelPairingRequest,
-}));
-
-const { enqueueSystemEvent } = vi.hoisted(() => ({
-  enqueueSystemEvent: vi.fn(),
-}));
-vi.mock("../infra/system-events.js", () => ({
-  enqueueSystemEvent,
-}));
-
-const { wasSentByBot } = vi.hoisted(() => ({
-  wasSentByBot: vi.fn(() => false),
-}));
-vi.mock("./sent-message-cache.js", () => ({
-  wasSentByBot,
-  recordSentMessage: vi.fn(),
-  clearSentMessageCache: vi.fn(),
-}));
-
-const useSpy = vi.fn();
-const middlewareUseSpy = vi.fn();
-const onSpy = vi.fn();
-const stopSpy = vi.fn();
-const commandSpy = vi.fn();
-const botCtorSpy = vi.fn();
-const answerCallbackQuerySpy = vi.fn(async () => undefined);
-const sendChatActionSpy = vi.fn();
-const editMessageTextSpy = vi.fn(async () => ({ message_id: 88 }));
-const setMessageReactionSpy = vi.fn(async () => undefined);
-const setMyCommandsSpy = vi.fn(async () => undefined);
-const sendMessageSpy = vi.fn(async () => ({ message_id: 77 }));
-const sendAnimationSpy = vi.fn(async () => ({ message_id: 78 }));
-const sendPhotoSpy = vi.fn(async () => ({ message_id: 79 }));
-type ApiStub = {
-  config: { use: (arg: unknown) => void };
-  answerCallbackQuery: typeof answerCallbackQuerySpy;
-  sendChatAction: typeof sendChatActionSpy;
-  editMessageText: typeof editMessageTextSpy;
-  setMessageReaction: typeof setMessageReactionSpy;
-  setMyCommands: typeof setMyCommandsSpy;
-  sendMessage: typeof sendMessageSpy;
-  sendAnimation: typeof sendAnimationSpy;
-  sendPhoto: typeof sendPhotoSpy;
-};
-const apiStub: ApiStub = {
-  config: { use: useSpy },
-  answerCallbackQuery: answerCallbackQuerySpy,
-  sendChatAction: sendChatActionSpy,
-  editMessageText: editMessageTextSpy,
-  setMessageReaction: setMessageReactionSpy,
-  setMyCommands: setMyCommandsSpy,
-  sendMessage: sendMessageSpy,
-  sendAnimation: sendAnimationSpy,
-  sendPhoto: sendPhotoSpy,
-};
-
-vi.mock("grammy", () => ({
-  Bot: class {
-    api = apiStub;
-    use = middlewareUseSpy;
-    on = onSpy;
-    stop = stopSpy;
-    command = commandSpy;
-    catch = vi.fn();
-    constructor(
-      public token: string,
-      public options?: { client?: { fetch?: typeof fetch } },
-    ) {
-      botCtorSpy(token, options);
-    }
-  },
-  InputFile: class {},
-  webhookCallback: vi.fn(),
-}));
-
-const sequentializeMiddleware = vi.fn();
-const sequentializeSpy = vi.fn(() => sequentializeMiddleware);
-vi.mock("@grammyjs/runner", () => ({
-  sequentialize: (_keyFn: (ctx: unknown) => string) => {
-    return sequentializeSpy();
-  },
-}));
-
-const throttlerSpy = vi.fn(() => "throttler");
-
-vi.mock("@grammyjs/transformer-throttler", () => ({
-  apiThrottler: () => throttlerSpy(),
-}));
-
-vi.mock("../auto-reply/reply.js", () => {
-  const replySpy = vi.fn(async (_ctx, opts) => {
-    await opts?.onReplyStart?.();
-    return undefined;
-  });
-  return { getReplyFromConfig: replySpy, __replySpy: replySpy };
-});
-
-const getOnHandler = (event: string) => {
-  const handler = onSpy.mock.calls.find((call) => call[0] === event)?.[1];
-  if (!handler) {
-    throw new Error(`Missing handler for event: ${event}`);
-  }
-  return handler as (ctx: Record<string, unknown>) => Promise<void>;
-};
-
 const ORIGINAL_TZ = process.env.TZ;
 describe("createTelegramBot", () => {
-  beforeAll(async () => {
-    replyModule = await import("../auto-reply/reply.js");
-  });
-
   beforeEach(() => {
     process.env.TZ = "UTC";
-    resetInboundDedupe();
     loadConfig.mockReturnValue({
       agents: {
         defaults: {
@@ -185,17 +43,6 @@ describe("createTelegramBot", () => {
         telegram: { dmPolicy: "open", allowFrom: ["*"] },
       },
     });
-    loadWebMedia.mockReset();
-    sendAnimationSpy.mockReset();
-    sendPhotoSpy.mockReset();
-    setMessageReactionSpy.mockReset();
-    answerCallbackQuerySpy.mockReset();
-    editMessageTextSpy.mockReset();
-    setMyCommandsSpy.mockReset();
-    wasSentByBot.mockReset();
-    middlewareUseSpy.mockReset();
-    sequentializeSpy.mockReset();
-    botCtorSpy.mockReset();
   });
   afterEach(() => {
     process.env.TZ = ORIGINAL_TZ;
@@ -304,7 +151,6 @@ describe("createTelegramBot", () => {
 
   it("blocks callback_query when inline buttons are allowlist-only and sender not authorized", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     createTelegramBot({
@@ -426,7 +272,6 @@ describe("createTelegramBot", () => {
 
   it("includes sender identity in group envelope headers", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     loadConfig.mockReturnValue({
@@ -479,7 +324,6 @@ describe("createTelegramBot", () => {
   it("uses quote text when a Telegram partial reply is received", async () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     createTelegramBot({ token: "tok" });
@@ -515,7 +359,6 @@ describe("createTelegramBot", () => {
   it("handles quote-only replies without reply metadata", async () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     createTelegramBot({ token: "tok" });
@@ -546,7 +389,6 @@ describe("createTelegramBot", () => {
   it("uses external_reply quote text for partial replies", async () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     createTelegramBot({ token: "tok" });
@@ -581,7 +423,6 @@ describe("createTelegramBot", () => {
 
   it("accepts group replies to the bot without explicit mention when requireMention is enabled", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     loadConfig.mockReturnValue({
       channels: {
@@ -614,7 +455,6 @@ describe("createTelegramBot", () => {
 
   it("inherits group allowlist + requireMention in topics", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     loadConfig.mockReturnValue({
       channels: {
@@ -658,7 +498,6 @@ describe("createTelegramBot", () => {
 
   it("prefers topic allowFrom over group allowFrom", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     loadConfig.mockReturnValue({
       channels: {
@@ -701,7 +540,6 @@ describe("createTelegramBot", () => {
 
   it("allows group messages for per-group groupPolicy open override (global groupPolicy allowlist)", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     loadConfig.mockReturnValue({
       channels: {
@@ -737,7 +575,6 @@ describe("createTelegramBot", () => {
 
   it("blocks control commands from unauthorized senders in per-group open groups", async () => {
     onSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     loadConfig.mockReturnValue({
       channels: {
@@ -774,7 +611,6 @@ describe("createTelegramBot", () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
     commandSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     replySpy.mockResolvedValue({ text: "response" });
 
@@ -817,7 +653,6 @@ describe("createTelegramBot", () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
     commandSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
     replySpy.mockResolvedValue({ text: "response" });
 
@@ -862,7 +697,6 @@ describe("createTelegramBot", () => {
     onSpy.mockReset();
     sendMessageSpy.mockReset();
     commandSpy.mockReset();
-    const replySpy = replyModule.__replySpy as unknown as ReturnType<typeof vi.fn>;
     replySpy.mockReset();
 
     loadConfig.mockReturnValue({
@@ -910,7 +744,7 @@ describe("createTelegramBot", () => {
 
   it("enqueues system event for reaction", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
 
     loadConfig.mockReturnValue({
       channels: {
@@ -935,8 +769,8 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
-    expect(enqueueSystemEvent).toHaveBeenCalledWith(
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledWith(
       "Telegram reaction added: 👍 by Ada (@ada_bot) on msg 42",
       expect.objectContaining({
         contextKey: expect.stringContaining("telegram:reaction:add:1234:42:9"),
@@ -946,7 +780,7 @@ describe("createTelegramBot", () => {
 
   it("skips reaction when reactionNotifications is off", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(true);
 
     loadConfig.mockReturnValue({
@@ -972,12 +806,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).not.toHaveBeenCalled();
+    expect(enqueueSystemEventSpy).not.toHaveBeenCalled();
   });
 
   it("defaults reactionNotifications to own", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(true);
 
     loadConfig.mockReturnValue({
@@ -1003,12 +837,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
   });
 
   it("allows reaction in all mode regardless of message sender", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(false);
 
     loadConfig.mockReturnValue({
@@ -1034,8 +868,8 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
-    expect(enqueueSystemEvent).toHaveBeenCalledWith(
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledWith(
       "Telegram reaction added: 🎉 by Ada on msg 99",
       expect.any(Object),
     );
@@ -1043,7 +877,7 @@ describe("createTelegramBot", () => {
 
   it("skips reaction in own mode when message is not sent by bot", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(false);
 
     loadConfig.mockReturnValue({
@@ -1069,12 +903,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).not.toHaveBeenCalled();
+    expect(enqueueSystemEventSpy).not.toHaveBeenCalled();
   });
 
   it("allows reaction in own mode when message is sent by bot", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(true);
 
     loadConfig.mockReturnValue({
@@ -1100,12 +934,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
   });
 
   it("skips reaction from bot users", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
     wasSentByBot.mockReturnValue(true);
 
     loadConfig.mockReturnValue({
@@ -1131,12 +965,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).not.toHaveBeenCalled();
+    expect(enqueueSystemEventSpy).not.toHaveBeenCalled();
   });
 
   it("skips reaction removal (only processes added reactions)", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
 
     loadConfig.mockReturnValue({
       channels: {
@@ -1161,12 +995,12 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).not.toHaveBeenCalled();
+    expect(enqueueSystemEventSpy).not.toHaveBeenCalled();
   });
 
   it("routes forum group reactions to the general topic (thread id not available on reactions)", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
 
     loadConfig.mockReturnValue({
       channels: {
@@ -1193,8 +1027,8 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
-    expect(enqueueSystemEvent).toHaveBeenCalledWith(
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledWith(
       "Telegram reaction added: 🔥 by Bob (@bob_user) on msg 100",
       expect.objectContaining({
         sessionKey: expect.stringContaining("telegram:group:5678:topic:1"),
@@ -1205,7 +1039,7 @@ describe("createTelegramBot", () => {
 
   it("uses correct session key for forum group reactions in general topic", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
 
     loadConfig.mockReturnValue({
       channels: {
@@ -1231,8 +1065,8 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
-    expect(enqueueSystemEvent).toHaveBeenCalledWith(
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledWith(
       "Telegram reaction added: 👀 by Bob on msg 101",
       expect.objectContaining({
         sessionKey: expect.stringContaining("telegram:group:5678:topic:1"),
@@ -1243,7 +1077,7 @@ describe("createTelegramBot", () => {
 
   it("uses correct session key for regular group reactions without topic", async () => {
     onSpy.mockReset();
-    enqueueSystemEvent.mockReset();
+    enqueueSystemEventSpy.mockReset();
 
     loadConfig.mockReturnValue({
       channels: {
@@ -1268,8 +1102,8 @@ describe("createTelegramBot", () => {
       },
     });
 
-    expect(enqueueSystemEvent).toHaveBeenCalledTimes(1);
-    expect(enqueueSystemEvent).toHaveBeenCalledWith(
+    expect(enqueueSystemEventSpy).toHaveBeenCalledTimes(1);
+    expect(enqueueSystemEventSpy).toHaveBeenCalledWith(
       "Telegram reaction added: ❤️ by Charlie on msg 200",
       expect.objectContaining({
         sessionKey: expect.stringContaining("telegram:group:9999"),
@@ -1277,7 +1111,7 @@ describe("createTelegramBot", () => {
       }),
     );
     // Verify session key does NOT contain :topic:
-    const sessionKey = enqueueSystemEvent.mock.calls[0][1].sessionKey;
+    const sessionKey = enqueueSystemEventSpy.mock.calls[0][1].sessionKey;
     expect(sessionKey).not.toContain(":topic:");
   });
 });
diff --git a/src/telegram/bot.ts b/src/telegram/bot.ts
index b5b46316812..aaba2475903 100644
--- a/src/telegram/bot.ts
+++ b/src/telegram/bot.ts
@@ -7,7 +7,7 @@ import type { OpenClawConfig, ReplyToMode } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { resolveDefaultAgentId } from "../agents/agent-scope.js";
 import { resolveTextChunkLimit } from "../auto-reply/chunk.js";
-import { isControlCommandMessage } from "../auto-reply/command-detection.js";
+import { isAbortRequestText } from "../auto-reply/reply/abort.js";
 import { DEFAULT_GROUP_HISTORY_LIMIT, type HistoryEntry } from "../auto-reply/reply/history.js";
 import {
   isNativeCommandsExplicitlyDisabled,
@@ -90,10 +90,7 @@ export function getTelegramSequentialKey(ctx: {
   const chatId = msg?.chat?.id ?? ctx.chat?.id;
   const rawText = msg?.text ?? msg?.caption;
   const botUsername = ctx.me?.username;
-  if (
-    rawText &&
-    isControlCommandMessage(rawText, undefined, botUsername ? { botUsername } : undefined)
-  ) {
+  if (isAbortRequestText(rawText, botUsername ? { botUsername } : undefined)) {
     if (typeof chatId === "number") {
       return `telegram:${chatId}:control`;
     }
diff --git a/src/telegram/bot/delivery.test.ts b/src/telegram/bot/delivery.test.ts
index 7d61f05284c..c1a008b1133 100644
--- a/src/telegram/bot/delivery.test.ts
+++ b/src/telegram/bot/delivery.test.ts
@@ -169,7 +169,7 @@ describe("deliverReplies", () => {
     );
   });
 
-  it("keeps message_thread_id=1 when allowed", async () => {
+  it("does not include message_thread_id for DMs (threads don't exist in private chats)", async () => {
     const runtime = { error: vi.fn(), log: vi.fn() };
     const sendMessage = vi.fn().mockResolvedValue({
       message_id: 4,
@@ -191,7 +191,7 @@ describe("deliverReplies", () => {
     expect(sendMessage).toHaveBeenCalledWith(
       "123",
       expect.any(String),
-      expect.objectContaining({
+      expect.not.objectContaining({
         message_thread_id: 1,
       }),
     );
diff --git a/src/telegram/bot/delivery.ts b/src/telegram/bot/delivery.ts
index a70e554f38d..0379e205abf 100644
--- a/src/telegram/bot/delivery.ts
+++ b/src/telegram/bot/delivery.ts
@@ -26,6 +26,7 @@ import { cacheSticker, getCachedSticker } from "../sticker-cache.js";
 import { resolveTelegramVoiceSend } from "../voice.js";
 import {
   buildTelegramThreadParams,
+  resolveTelegramMediaPlaceholder,
   resolveTelegramReplyId,
   type TelegramThreadSpec,
 } from "./helpers.js";
@@ -309,6 +310,16 @@ export async function resolveMedia(
   stickerMetadata?: StickerMetadata;
 } | null> {
   const msg = ctx.message;
+  const downloadAndSaveTelegramFile = async (filePath: string, fetchImpl: typeof fetch) => {
+    const url = `https://api.telegram.org/file/bot${token}/${filePath}`;
+    const fetched = await fetchRemoteMedia({
+      url,
+      fetchImpl,
+      filePathHint: filePath,
+    });
+    const originalName = fetched.fileName ?? filePath;
+    return saveMediaBuffer(fetched.buffer, fetched.contentType, "inbound", maxBytes, originalName);
+  };
 
   // Handle stickers separately - only static stickers (WEBP) are supported
   if (msg.sticker) {
@@ -333,20 +344,7 @@ export async function resolveMedia(
         logVerbose("telegram: fetch not available for sticker download");
         return null;
       }
-      const url = `https://api.telegram.org/file/bot${token}/${file.file_path}`;
-      const fetched = await fetchRemoteMedia({
-        url,
-        fetchImpl,
-        filePathHint: file.file_path,
-      });
-      const originalName = fetched.fileName ?? file.file_path;
-      const saved = await saveMediaBuffer(
-        fetched.buffer,
-        fetched.contentType,
-        "inbound",
-        maxBytes,
-        originalName,
-      );
+      const saved = await downloadAndSaveTelegramFile(file.file_path, fetchImpl);
 
       // Check sticker cache for existing description
       const cached = sticker.file_unique_id ? getCachedSticker(sticker.file_unique_id) : null;
@@ -431,30 +429,8 @@ export async function resolveMedia(
   if (!fetchImpl) {
     throw new Error("fetch is not available; set channels.telegram.proxy in config");
   }
-  const url = `https://api.telegram.org/file/bot${token}/${file.file_path}`;
-  const fetched = await fetchRemoteMedia({
-    url,
-    fetchImpl,
-    filePathHint: file.file_path,
-  });
-  const originalName = fetched.fileName ?? file.file_path;
-  const saved = await saveMediaBuffer(
-    fetched.buffer,
-    fetched.contentType,
-    "inbound",
-    maxBytes,
-    originalName,
-  );
-  let placeholder = "<media:document>";
-  if (msg.photo) {
-    placeholder = "<media:image>";
-  } else if (msg.video) {
-    placeholder = "<media:video>";
-  } else if (msg.video_note) {
-    placeholder = "<media:video>";
-  } else if (msg.audio || msg.voice) {
-    placeholder = "<media:audio>";
-  }
+  const saved = await downloadAndSaveTelegramFile(file.file_path, fetchImpl);
+  const placeholder = resolveTelegramMediaPlaceholder(msg) ?? "<media:document>";
   return { path: saved.path, contentType: saved.contentType, placeholder };
 }
 
diff --git a/src/telegram/bot/helpers.test.ts b/src/telegram/bot/helpers.test.ts
index 526d2ec3aad..d0f91345da9 100644
--- a/src/telegram/bot/helpers.test.ts
+++ b/src/telegram/bot/helpers.test.ts
@@ -43,9 +43,24 @@ describe("buildTelegramThreadParams", () => {
     });
   });
 
-  it("keeps thread id=1 for dm threads", () => {
-    expect(buildTelegramThreadParams({ id: 1, scope: "dm" })).toEqual({
-      message_thread_id: 1,
+  it("skips thread id for dm threads (DMs don't have threads)", () => {
+    expect(buildTelegramThreadParams({ id: 1, scope: "dm" })).toBeUndefined();
+    expect(buildTelegramThreadParams({ id: 2, scope: "dm" })).toBeUndefined();
+  });
+
+  it("normalizes and skips thread id for dm threads even with edge values", () => {
+    expect(buildTelegramThreadParams({ id: 0, scope: "dm" })).toBeUndefined();
+    expect(buildTelegramThreadParams({ id: -1, scope: "dm" })).toBeUndefined();
+    expect(buildTelegramThreadParams({ id: 1.9, scope: "dm" })).toBeUndefined();
+  });
+
+  it("handles thread id 0 for non-dm scopes", () => {
+    // id=0 should be included for forum and none scopes (not falsy)
+    expect(buildTelegramThreadParams({ id: 0, scope: "forum" })).toEqual({
+      message_thread_id: 0,
+    });
+    expect(buildTelegramThreadParams({ id: 0, scope: "none" })).toEqual({
+      message_thread_id: 0,
     });
   });
 
diff --git a/src/telegram/bot/helpers.ts b/src/telegram/bot/helpers.ts
index b9f0706b63d..a39d5f15d6a 100644
--- a/src/telegram/bot/helpers.ts
+++ b/src/telegram/bot/helpers.ts
@@ -1,6 +1,13 @@
 import type { Chat, Message, MessageOrigin, User } from "@grammyjs/types";
+import type { TelegramGroupConfig, TelegramTopicConfig } from "../../config/types.js";
 import type { TelegramStreamMode } from "./types.js";
 import { formatLocationText, type NormalizedLocation } from "../../channels/location.js";
+import { readChannelAllowFromStore } from "../../pairing/pairing-store.js";
+import {
+  firstDefined,
+  normalizeAllowFromWithStore,
+  type NormalizedAllowFrom,
+} from "../bot-access.js";
 
 const TELEGRAM_GENERAL_TOPIC_ID = 1;
 
@@ -9,6 +16,55 @@ export type TelegramThreadSpec = {
   scope: "dm" | "forum" | "none";
 };
 
+export async function resolveTelegramGroupAllowFromContext(params: {
+  chatId: string | number;
+  accountId?: string;
+  isForum?: boolean;
+  messageThreadId?: number | null;
+  groupAllowFrom?: Array<string | number>;
+  resolveTelegramGroupConfig: (
+    chatId: string | number,
+    messageThreadId?: number,
+  ) => { groupConfig?: TelegramGroupConfig; topicConfig?: TelegramTopicConfig };
+}): Promise<{
+  resolvedThreadId?: number;
+  storeAllowFrom: string[];
+  groupConfig?: TelegramGroupConfig;
+  topicConfig?: TelegramTopicConfig;
+  groupAllowOverride?: Array<string | number>;
+  effectiveGroupAllow: NormalizedAllowFrom;
+  hasGroupAllowOverride: boolean;
+}> {
+  const resolvedThreadId = resolveTelegramForumThreadId({
+    isForum: params.isForum,
+    messageThreadId: params.messageThreadId,
+  });
+  const storeAllowFrom = await readChannelAllowFromStore(
+    "telegram",
+    process.env,
+    params.accountId,
+  ).catch(() => []);
+  const { groupConfig, topicConfig } = params.resolveTelegramGroupConfig(
+    params.chatId,
+    resolvedThreadId,
+  );
+  const groupAllowOverride = firstDefined(topicConfig?.allowFrom, groupConfig?.allowFrom);
+  const effectiveGroupAllow = normalizeAllowFromWithStore({
+    allowFrom: groupAllowOverride ?? params.groupAllowFrom,
+    storeAllowFrom,
+  });
+  const hasGroupAllowOverride = typeof groupAllowOverride !== "undefined";
+  return {
+    resolvedThreadId,
+    storeAllowFrom,
+    groupConfig,
+    topicConfig,
+    groupAllowOverride,
+    effectiveGroupAllow,
+    hasGroupAllowOverride,
+  };
+}
+
 /**
  * Resolve the thread ID for Telegram forum topics.
  * For non-forum groups, returns undefined even if messageThreadId is present
@@ -56,17 +112,34 @@ export function resolveTelegramThreadSpec(params: {
 
 /**
  * Build thread params for Telegram API calls (messages, media).
+ *
+ * IMPORTANT: Thread IDs behave differently based on chat type:
+ * - DMs (private chats): Never send thread_id (threads don't exist)
+ * - Forum topics: Skip thread_id=1 (General topic), include others
+ * - Regular groups: Thread IDs are ignored by Telegram
+ *
  * General forum topic (id=1) must be treated like a regular supergroup send:
  * Telegram rejects sendMessage/sendMedia with message_thread_id=1 ("thread not found").
+ *
+ * @param thread - Thread specification with ID and scope
+ * @returns API params object or undefined if thread_id should be omitted
  */
 export function buildTelegramThreadParams(thread?: TelegramThreadSpec | null) {
-  if (!thread?.id) {
+  if (thread?.id == null) {
     return undefined;
   }
   const normalized = Math.trunc(thread.id);
-  if (normalized === TELEGRAM_GENERAL_TOPIC_ID && thread.scope === "forum") {
+
+  // Never send thread_id for DMs (threads don't exist in private chats)
+  if (thread.scope === "dm") {
     return undefined;
   }
+
+  // Telegram rejects message_thread_id=1 for General forum topic
+  if (normalized === TELEGRAM_GENERAL_TOPIC_ID) {
+    return undefined;
+  }
+
   return { message_thread_id: normalized };
 }
 
@@ -124,6 +197,33 @@ export function buildSenderName(msg: Message) {
   return name || undefined;
 }
 
+export function resolveTelegramMediaPlaceholder(
+  msg:
+    | Pick<Message, "photo" | "video" | "video_note" | "audio" | "voice" | "document" | "sticker">
+    | undefined
+    | null,
+): string | undefined {
+  if (!msg) {
+    return undefined;
+  }
+  if (msg.photo) {
+    return "<media:image>";
+  }
+  if (msg.video || msg.video_note) {
+    return "<media:video>";
+  }
+  if (msg.audio || msg.voice) {
+    return "<media:audio>";
+  }
+  if (msg.document) {
+    return "<media:document>";
+  }
+  if (msg.sticker) {
+    return "<media:sticker>";
+  }
+  return undefined;
+}
+
 export function buildSenderLabel(msg: Message, senderId?: number | string) {
   const name = buildSenderName(msg);
   const username = msg.from?.username ? `@${msg.from.username}` : undefined;
@@ -245,15 +345,8 @@ export function describeReplyTarget(msg: Message): TelegramReplyTarget | null {
     const replyBody = (replyLike.text ?? replyLike.caption ?? "").trim();
     body = replyBody;
     if (!body) {
-      if (replyLike.photo) {
-        body = "<media:image>";
-      } else if (replyLike.video) {
-        body = "<media:video>";
-      } else if (replyLike.audio || replyLike.voice) {
-        body = "<media:audio>";
-      } else if (replyLike.document) {
-        body = "<media:document>";
-      } else {
+      body = resolveTelegramMediaPlaceholder(replyLike) ?? "";
+      if (!body) {
         const locationData = extractTelegramLocation(replyLike);
         if (locationData) {
           body = formatLocationText(locationData);
diff --git a/src/telegram/download.test.ts b/src/telegram/download.test.ts
deleted file mode 100644
index 5738877ca1c..00000000000
--- a/src/telegram/download.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { downloadTelegramFile, getTelegramFile, type TelegramFileInfo } from "./download.js";
-
-describe("telegram download", () => {
-  it("fetches file info", async () => {
-    const json = vi.fn().mockResolvedValue({ ok: true, result: { file_path: "photos/1.jpg" } });
-    vi.spyOn(global, "fetch" as never).mockResolvedValueOnce({
-      ok: true,
-      status: 200,
-      statusText: "OK",
-      json,
-    } as Response);
-    const info = await getTelegramFile("tok", "fid");
-    expect(info.file_path).toBe("photos/1.jpg");
-  });
-
-  it("downloads and saves", async () => {
-    const info: TelegramFileInfo = {
-      file_id: "fid",
-      file_path: "photos/1.jpg",
-    };
-    const arrayBuffer = async () => new Uint8Array([1, 2, 3, 4]).buffer;
-    vi.spyOn(global, "fetch" as never).mockResolvedValueOnce({
-      ok: true,
-      status: 200,
-      statusText: "OK",
-      body: true,
-      arrayBuffer,
-      headers: { get: () => "image/jpeg" },
-    } as Response);
-    const saved = await downloadTelegramFile("tok", info, 1024 * 1024);
-    expect(saved.path).toBeTruthy();
-    expect(saved.contentType).toBe("image/jpeg");
-  });
-});
diff --git a/src/telegram/download.ts b/src/telegram/download.ts
deleted file mode 100644
index 8da41eab312..00000000000
--- a/src/telegram/download.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { detectMime } from "../media/mime.js";
-import { type SavedMedia, saveMediaBuffer } from "../media/store.js";
-
-export type TelegramFileInfo = {
-  file_id: string;
-  file_unique_id?: string;
-  file_size?: number;
-  file_path?: string;
-};
-
-export async function getTelegramFile(
-  token: string,
-  fileId: string,
-  timeoutMs = 30_000,
-): Promise<TelegramFileInfo> {
-  const res = await fetch(
-    `https://api.telegram.org/bot${token}/getFile?file_id=${encodeURIComponent(fileId)}`,
-    { signal: AbortSignal.timeout(timeoutMs) },
-  );
-  if (!res.ok) {
-    throw new Error(`getFile failed: ${res.status} ${res.statusText}`);
-  }
-  const json = (await res.json()) as { ok: boolean; result?: TelegramFileInfo };
-  if (!json.ok || !json.result?.file_path) {
-    throw new Error("getFile returned no file_path");
-  }
-  return json.result;
-}
-
-export async function downloadTelegramFile(
-  token: string,
-  info: TelegramFileInfo,
-  maxBytes?: number,
-  timeoutMs = 60_000,
-): Promise<SavedMedia> {
-  if (!info.file_path) {
-    throw new Error("file_path missing");
-  }
-  const url = `https://api.telegram.org/file/bot${token}/${info.file_path}`;
-  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
-  if (!res.ok || !res.body) {
-    throw new Error(`Failed to download telegram file: HTTP ${res.status}`);
-  }
-  const array = Buffer.from(await res.arrayBuffer());
-  const mime = await detectMime({
-    buffer: array,
-    headerMime: res.headers.get("content-type"),
-    filePath: info.file_path,
-  });
-  // save with inbound subdir
-  const saved = await saveMediaBuffer(array, mime, "inbound", maxBytes, info.file_path);
-  // Ensure extension matches mime if possible
-  if (!saved.contentType && mime) {
-    saved.contentType = mime;
-  }
-  return saved;
-}
diff --git a/src/telegram/draft-stream.test.ts b/src/telegram/draft-stream.test.ts
index 0c4cc74ad4f..c8ad4ed7ce6 100644
--- a/src/telegram/draft-stream.test.ts
+++ b/src/telegram/draft-stream.test.ts
@@ -94,7 +94,7 @@ describe("createTelegramDraftStream", () => {
     await vi.waitFor(() => expect(api.sendMessage).toHaveBeenCalledWith(123, "Hello", undefined));
   });
 
-  it("keeps message_thread_id for dm threads and clears preview on cleanup", async () => {
+  it("omits message_thread_id for dm threads and clears preview on cleanup", async () => {
     const api = {
       sendMessage: vi.fn().mockResolvedValue({ message_id: 17 }),
       editMessageText: vi.fn().mockResolvedValue(true),
@@ -108,9 +108,7 @@ describe("createTelegramDraftStream", () => {
     });
 
     stream.update("Hello");
-    await vi.waitFor(() =>
-      expect(api.sendMessage).toHaveBeenCalledWith(123, "Hello", { message_thread_id: 1 }),
-    );
+    await vi.waitFor(() => expect(api.sendMessage).toHaveBeenCalledWith(123, "Hello", undefined));
     await stream.clear();
 
     expect(api.deleteMessage).toHaveBeenCalledWith(123, 17);
diff --git a/src/telegram/fetch.test.ts b/src/telegram/fetch.test.ts
index 285e189ff1a..c20d3ad5e9a 100644
--- a/src/telegram/fetch.test.ts
+++ b/src/telegram/fetch.test.ts
@@ -11,21 +11,21 @@ vi.mock("node:net", async () => {
   };
 });
 
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  resetTelegramFetchStateForTests();
+  setDefaultAutoSelectFamily.mockReset();
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+  if (originalFetch) {
+    globalThis.fetch = originalFetch;
+  } else {
+    delete (globalThis as { fetch?: typeof fetch }).fetch;
+  }
+});
+
 describe("resolveTelegramFetch", () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    resetTelegramFetchStateForTests();
-    setDefaultAutoSelectFamily.mockReset();
-    vi.unstubAllEnvs();
-    vi.clearAllMocks();
-    if (originalFetch) {
-      globalThis.fetch = originalFetch;
-    } else {
-      delete (globalThis as { fetch?: typeof fetch }).fetch;
-    }
-  });
-
   it("returns wrapped global fetch when available", async () => {
     const fetchMock = vi.fn(async () => ({}));
     globalThis.fetch = fetchMock as unknown as typeof fetch;
diff --git a/src/telegram/group-access.ts b/src/telegram/group-access.ts
new file mode 100644
index 00000000000..02375218171
--- /dev/null
+++ b/src/telegram/group-access.ts
@@ -0,0 +1,141 @@
+import type { OpenClawConfig } from "../config/config.js";
+import type { ChannelGroupPolicy } from "../config/group-policy.js";
+import type {
+  TelegramAccountConfig,
+  TelegramGroupConfig,
+  TelegramTopicConfig,
+} from "../config/types.js";
+import { isSenderAllowed, type NormalizedAllowFrom } from "./bot-access.js";
+import { firstDefined } from "./bot-access.js";
+
+export type TelegramGroupBaseBlockReason =
+  | "group-disabled"
+  | "topic-disabled"
+  | "group-override-unauthorized";
+
+export type TelegramGroupBaseAccessResult =
+  | { allowed: true }
+  | { allowed: false; reason: TelegramGroupBaseBlockReason };
+
+export const evaluateTelegramGroupBaseAccess = (params: {
+  isGroup: boolean;
+  groupConfig?: TelegramGroupConfig;
+  topicConfig?: TelegramTopicConfig;
+  hasGroupAllowOverride: boolean;
+  effectiveGroupAllow: NormalizedAllowFrom;
+  senderId?: string;
+  senderUsername?: string;
+  enforceAllowOverride: boolean;
+  requireSenderForAllowOverride: boolean;
+}): TelegramGroupBaseAccessResult => {
+  if (!params.isGroup) {
+    return { allowed: true };
+  }
+  if (params.groupConfig?.enabled === false) {
+    return { allowed: false, reason: "group-disabled" };
+  }
+  if (params.topicConfig?.enabled === false) {
+    return { allowed: false, reason: "topic-disabled" };
+  }
+  if (!params.enforceAllowOverride || !params.hasGroupAllowOverride) {
+    return { allowed: true };
+  }
+
+  const senderId = params.senderId ?? "";
+  if (params.requireSenderForAllowOverride && !senderId) {
+    return { allowed: false, reason: "group-override-unauthorized" };
+  }
+
+  const allowed = isSenderAllowed({
+    allow: params.effectiveGroupAllow,
+    senderId,
+    senderUsername: params.senderUsername ?? "",
+  });
+  if (!allowed) {
+    return { allowed: false, reason: "group-override-unauthorized" };
+  }
+  return { allowed: true };
+};
+
+export type TelegramGroupPolicyBlockReason =
+  | "group-policy-disabled"
+  | "group-policy-allowlist-no-sender"
+  | "group-policy-allowlist-empty"
+  | "group-policy-allowlist-unauthorized"
+  | "group-chat-not-allowed";
+
+export type TelegramGroupPolicyAccessResult =
+  | { allowed: true; groupPolicy: "open" | "disabled" | "allowlist" }
+  | {
+      allowed: false;
+      reason: TelegramGroupPolicyBlockReason;
+      groupPolicy: "open" | "disabled" | "allowlist";
+    };
+
+export const evaluateTelegramGroupPolicyAccess = (params: {
+  isGroup: boolean;
+  chatId: string | number;
+  cfg: OpenClawConfig;
+  telegramCfg: TelegramAccountConfig;
+  topicConfig?: TelegramTopicConfig;
+  groupConfig?: TelegramGroupConfig;
+  effectiveGroupAllow: NormalizedAllowFrom;
+  senderId?: string;
+  senderUsername?: string;
+  resolveGroupPolicy: (chatId: string | number) => ChannelGroupPolicy;
+  enforcePolicy: boolean;
+  useTopicAndGroupOverrides: boolean;
+  enforceAllowlistAuthorization: boolean;
+  allowEmptyAllowlistEntries: boolean;
+  requireSenderForAllowlistAuthorization: boolean;
+  checkChatAllowlist: boolean;
+}): TelegramGroupPolicyAccessResult => {
+  const fallbackPolicy =
+    firstDefined(
+      params.telegramCfg.groupPolicy,
+      params.cfg.channels?.defaults?.groupPolicy,
+      "open",
+    ) ?? "open";
+  const groupPolicy = params.useTopicAndGroupOverrides
+    ? (firstDefined(
+        params.topicConfig?.groupPolicy,
+        params.groupConfig?.groupPolicy,
+        params.telegramCfg.groupPolicy,
+        params.cfg.channels?.defaults?.groupPolicy,
+        "open",
+      ) ?? "open")
+    : fallbackPolicy;
+
+  if (!params.isGroup || !params.enforcePolicy) {
+    return { allowed: true, groupPolicy };
+  }
+  if (groupPolicy === "disabled") {
+    return { allowed: false, reason: "group-policy-disabled", groupPolicy };
+  }
+  if (groupPolicy === "allowlist" && params.enforceAllowlistAuthorization) {
+    const senderId = params.senderId ?? "";
+    if (params.requireSenderForAllowlistAuthorization && !senderId) {
+      return { allowed: false, reason: "group-policy-allowlist-no-sender", groupPolicy };
+    }
+    if (!params.allowEmptyAllowlistEntries && !params.effectiveGroupAllow.hasEntries) {
+      return { allowed: false, reason: "group-policy-allowlist-empty", groupPolicy };
+    }
+    const senderUsername = params.senderUsername ?? "";
+    if (
+      !isSenderAllowed({
+        allow: params.effectiveGroupAllow,
+        senderId,
+        senderUsername,
+      })
+    ) {
+      return { allowed: false, reason: "group-policy-allowlist-unauthorized", groupPolicy };
+    }
+  }
+  if (params.checkChatAllowlist) {
+    const groupAllowlist = params.resolveGroupPolicy(params.chatId);
+    if (groupAllowlist.allowlistEnabled && !groupAllowlist.allowed) {
+      return { allowed: false, reason: "group-chat-not-allowed", groupPolicy };
+    }
+  }
+  return { allowed: true, groupPolicy };
+};
diff --git a/src/telegram/group-migration.ts b/src/telegram/group-migration.ts
index 085aeabaf6f..921e34d5a9b 100644
--- a/src/telegram/group-migration.ts
+++ b/src/telegram/group-migration.ts
@@ -66,24 +66,19 @@ export function migrateTelegramGroupConfig(params: {
   let migrated = false;
   let skippedExisting = false;
 
-  const accountGroups = resolveAccountGroups(params.cfg, params.accountId).groups;
-  if (accountGroups) {
-    const result = migrateTelegramGroupsInPlace(accountGroups, params.oldChatId, params.newChatId);
-    if (result.migrated) {
-      migrated = true;
-      scopes.push("account");
-    }
-    if (result.skippedExisting) {
-      skippedExisting = true;
-    }
-  }
+  const migrationTargets: Array<{
+    scope: MigrationScope;
+    groups: TelegramGroups | undefined;
+  }> = [
+    { scope: "account", groups: resolveAccountGroups(params.cfg, params.accountId).groups },
+    { scope: "global", groups: params.cfg.channels?.telegram?.groups },
+  ];
 
-  const globalGroups = params.cfg.channels?.telegram?.groups;
-  if (globalGroups) {
-    const result = migrateTelegramGroupsInPlace(globalGroups, params.oldChatId, params.newChatId);
+  for (const target of migrationTargets) {
+    const result = migrateTelegramGroupsInPlace(target.groups, params.oldChatId, params.newChatId);
     if (result.migrated) {
       migrated = true;
-      scopes.push("global");
+      scopes.push(target.scope);
     }
     if (result.skippedExisting) {
       skippedExisting = true;
diff --git a/src/telegram/index.ts b/src/telegram/index.ts
deleted file mode 100644
index 5ffb8dacaf6..00000000000
--- a/src/telegram/index.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export { createTelegramBot, createTelegramWebhookCallback } from "./bot.js";
-export { monitorTelegramProvider } from "./monitor.js";
-export { reactMessageTelegram, sendMessageTelegram, sendPollTelegram } from "./send.js";
-export { startTelegramWebhook } from "./webhook.js";
diff --git a/src/telegram/inline-buttons.ts b/src/telegram/inline-buttons.ts
index 1cf770d0a8f..1137d61d1cd 100644
--- a/src/telegram/inline-buttons.ts
+++ b/src/telegram/inline-buttons.ts
@@ -1,7 +1,6 @@
 import type { OpenClawConfig } from "../config/config.js";
 import type { TelegramInlineButtonsScope } from "../config/types.telegram.js";
 import { listTelegramAccountIds, resolveTelegramAccount } from "./accounts.js";
-import { parseTelegramTarget } from "./targets.js";
 
 const DEFAULT_INLINE_BUTTONS_SCOPE: TelegramInlineButtonsScope = "allowlist";
 
@@ -65,17 +64,4 @@ export function isTelegramInlineButtonsEnabled(params: {
   );
 }
 
-export function resolveTelegramTargetChatType(target: string): "direct" | "group" | "unknown" {
-  if (!target.trim()) {
-    return "unknown";
-  }
-  const parsed = parseTelegramTarget(target);
-  const chatId = parsed.chatId.trim();
-  if (!chatId) {
-    return "unknown";
-  }
-  if (/^-?\d+$/.test(chatId)) {
-    return chatId.startsWith("-") ? "group" : "direct";
-  }
-  return "unknown";
-}
+export { resolveTelegramTargetChatType } from "./targets.js";
diff --git a/src/telegram/monitor.test.ts b/src/telegram/monitor.test.ts
index bc36774d3d6..59fe7731096 100644
--- a/src/telegram/monitor.test.ts
+++ b/src/telegram/monitor.test.ts
@@ -219,4 +219,27 @@ describe("monitorTelegramProvider (grammY)", () => {
     );
     expect(runSpy).not.toHaveBeenCalled();
   });
+
+  it("falls back to configured webhookSecret when not passed explicitly", async () => {
+    await monitorTelegramProvider({
+      token: "tok",
+      useWebhook: true,
+      webhookUrl: "https://example.test/telegram",
+      config: {
+        agents: { defaults: { maxConcurrent: 2 } },
+        channels: {
+          telegram: {
+            webhookSecret: "secret-from-config",
+          },
+        },
+      },
+    });
+
+    expect(startTelegramWebhookSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        secret: "secret-from-config",
+      }),
+    );
+    expect(runSpy).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/telegram/monitor.ts b/src/telegram/monitor.ts
index f5f015d0243..d243ca37fa0 100644
--- a/src/telegram/monitor.ts
+++ b/src/telegram/monitor.ts
@@ -158,7 +158,7 @@ export async function monitorTelegramProvider(opts: MonitorTelegramOpts = {}) {
         config: cfg,
         path: opts.webhookPath,
         port: opts.webhookPort,
-        secret: opts.webhookSecret,
+        secret: opts.webhookSecret ?? account.config.webhookSecret,
         host: opts.webhookHost ?? account.config.webhookHost,
         runtime: opts.runtime as RuntimeEnv,
         fetch: proxyFetch,
diff --git a/src/telegram/probe.ts b/src/telegram/probe.ts
index cc65f987f5e..f988733f0ee 100644
--- a/src/telegram/probe.ts
+++ b/src/telegram/probe.ts
@@ -1,12 +1,11 @@
+import type { BaseProbeResult } from "../channels/plugins/types.js";
 import { fetchWithTimeout } from "../utils/fetch-timeout.js";
 import { makeProxyFetch } from "./proxy.js";
 
 const TELEGRAM_API_BASE = "https://api.telegram.org";
 
-export type TelegramProbe = {
-  ok: boolean;
+export type TelegramProbe = BaseProbeResult & {
   status?: number | null;
-  error?: string | null;
   elapsedMs: number;
   bot?: {
     id?: number | null;
diff --git a/src/telegram/send.caption-split.test.ts b/src/telegram/send.caption-split.test.ts
deleted file mode 100644
index 564f3138880..00000000000
--- a/src/telegram/send.caption-split.test.ts
+++ /dev/null
@@ -1,357 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import {
-  getTelegramSendTestMocks,
-  importTelegramSendModule,
-  installTelegramSendTestHooks,
-} from "./send.test-harness.js";
-
-installTelegramSendTestHooks();
-
-const { loadWebMedia } = getTelegramSendTestMocks();
-const { sendMessageTelegram } = await importTelegramSendModule();
-
-describe("sendMessageTelegram caption splitting", () => {
-  it("splits long captions into media + text messages when text exceeds 1024 chars", async () => {
-    const chatId = "123";
-    // Generate text longer than 1024 characters
-    const longText = "A".repeat(1100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 70,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 71,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    const res = await sendMessageTelegram(chatId, longText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-    });
-
-    // Media should be sent first without caption
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: undefined,
-    });
-    // Then text sent as separate message (HTML formatting)
-    expect(sendMessage).toHaveBeenCalledWith(chatId, longText, {
-      parse_mode: "HTML",
-    });
-    // Returns the text message ID (the "main" content)
-    expect(res.messageId).toBe("71");
-  });
-
-  it("uses caption when text is within 1024 char limit", async () => {
-    const chatId = "123";
-    // Text exactly at 1024 characters should still use caption
-    const shortText = "B".repeat(1024);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 72,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn();
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    const res = await sendMessageTelegram(chatId, shortText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-    });
-
-    // Caption should be included with media
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: shortText,
-      parse_mode: "HTML",
-    });
-    // No separate text message needed
-    expect(sendMessage).not.toHaveBeenCalled();
-    expect(res.messageId).toBe("72");
-  });
-
-  it("renders markdown in media captions", async () => {
-    const chatId = "123";
-    const caption = "hi **boss**";
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 90,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto } as unknown as {
-      sendPhoto: typeof sendPhoto;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, caption, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-    });
-
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: "hi <b>boss</b>",
-      parse_mode: "HTML",
-    });
-  });
-
-  it("preserves thread params when splitting long captions", async () => {
-    const chatId = "-1001234567890";
-    const longText = "C".repeat(1100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 73,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 74,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, longText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-      messageThreadId: 271,
-      replyToMessageId: 500,
-    });
-
-    // Media sent with thread params but no caption
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: undefined,
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-    });
-    // Text message also includes thread params (HTML formatting)
-    expect(sendMessage).toHaveBeenCalledWith(chatId, longText, {
-      parse_mode: "HTML",
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-    });
-  });
-
-  it("puts reply_markup only on follow-up text when splitting", async () => {
-    const chatId = "123";
-    const longText = "D".repeat(1100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 75,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 76,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, longText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-      buttons: [[{ text: "Click me", callback_data: "action:click" }]],
-    });
-
-    // Media sent WITHOUT reply_markup
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: undefined,
-    });
-    // Follow-up text has the reply_markup
-    expect(sendMessage).toHaveBeenCalledWith(chatId, longText, {
-      parse_mode: "HTML",
-      reply_markup: {
-        inline_keyboard: [[{ text: "Click me", callback_data: "action:click" }]],
-      },
-    });
-  });
-
-  it("includes thread params and reply_markup on follow-up text when splitting", async () => {
-    const chatId = "-1001234567890";
-    const longText = "F".repeat(1100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 78,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 79,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, longText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-      messageThreadId: 271,
-      replyToMessageId: 500,
-      buttons: [[{ text: "Click me", callback_data: "action:click" }]],
-    });
-
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: undefined,
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-    });
-    expect(sendMessage).toHaveBeenCalledWith(chatId, longText, {
-      parse_mode: "HTML",
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-      reply_markup: {
-        inline_keyboard: [[{ text: "Click me", callback_data: "action:click" }]],
-      },
-    });
-  });
-
-  it("wraps chat-not-found errors from follow-up message", async () => {
-    const chatId = "123";
-    const longText = "G".repeat(1100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 80,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockRejectedValue(new Error("400: Bad Request: chat not found"));
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await expect(
-      sendMessageTelegram(chatId, longText, {
-        token: "tok",
-        api,
-        mediaUrl: "https://example.com/photo.jpg",
-      }),
-    ).rejects.toThrow(/Telegram send failed: chat not found \(chat_id=123\)\./);
-  });
-
-  it("does not send follow-up text when caption is empty", async () => {
-    const chatId = "123";
-    const emptyText = "   ";
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 81,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn();
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    const res = await sendMessageTelegram(chatId, emptyText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-    });
-
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: undefined,
-    });
-    expect(sendMessage).not.toHaveBeenCalled();
-    expect(res.messageId).toBe("81");
-  });
-
-  it("keeps reply_markup on media when not splitting", async () => {
-    const chatId = "123";
-    const shortText = "E".repeat(100);
-
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 77,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn();
-    const api = { sendPhoto, sendMessage } as unknown as {
-      sendPhoto: typeof sendPhoto;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, shortText, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-      buttons: [[{ text: "Click me", callback_data: "action:click" }]],
-    });
-
-    // Media sent WITH reply_markup when not splitting
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: shortText,
-      parse_mode: "HTML",
-      reply_markup: {
-        inline_keyboard: [[{ text: "Click me", callback_data: "action:click" }]],
-      },
-    });
-    expect(sendMessage).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/telegram/send.edit-message.test.ts b/src/telegram/send.edit-message.test.ts
deleted file mode 100644
index 8ee5a3e56a6..00000000000
--- a/src/telegram/send.edit-message.test.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { botApi, botCtorSpy } = vi.hoisted(() => ({
-  botApi: {
-    editMessageText: vi.fn(),
-  },
-  botCtorSpy: vi.fn(),
-}));
-
-vi.mock("grammy", () => ({
-  Bot: class {
-    api = botApi;
-    constructor(public token: string) {
-      botCtorSpy(token);
-    }
-  },
-  InputFile: class {},
-}));
-
-import { editMessageTelegram } from "./send.js";
-
-describe("editMessageTelegram", () => {
-  beforeEach(() => {
-    botApi.editMessageText.mockReset();
-    botCtorSpy.mockReset();
-  });
-
-  it("keeps existing buttons when buttons is undefined (no reply_markup)", async () => {
-    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
-
-    await editMessageTelegram("123", 1, "hi", {
-      token: "tok",
-      cfg: {},
-    });
-
-    expect(botCtorSpy).toHaveBeenCalledWith("tok");
-    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
-    const call = botApi.editMessageText.mock.calls[0] ?? [];
-    const params = call[3] as Record<string, unknown>;
-    expect(params).toEqual(expect.objectContaining({ parse_mode: "HTML" }));
-    expect(params).not.toHaveProperty("reply_markup");
-  });
-
-  it("removes buttons when buttons is empty (reply_markup.inline_keyboard = [])", async () => {
-    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
-
-    await editMessageTelegram("123", 1, "hi", {
-      token: "tok",
-      cfg: {},
-      buttons: [],
-    });
-
-    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
-    const params = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
-    expect(params).toEqual(
-      expect.objectContaining({
-        parse_mode: "HTML",
-        reply_markup: { inline_keyboard: [] },
-      }),
-    );
-  });
-
-  it("falls back to plain text when Telegram HTML parse fails (and preserves reply_markup)", async () => {
-    botApi.editMessageText
-      .mockRejectedValueOnce(new Error("400: Bad Request: can't parse entities"))
-      .mockResolvedValueOnce({ message_id: 1, chat: { id: "123" } });
-
-    await editMessageTelegram("123", 1, "<bad> html", {
-      token: "tok",
-      cfg: {},
-      buttons: [],
-    });
-
-    expect(botApi.editMessageText).toHaveBeenCalledTimes(2);
-
-    const firstParams = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
-    expect(firstParams).toEqual(
-      expect.objectContaining({
-        parse_mode: "HTML",
-        reply_markup: { inline_keyboard: [] },
-      }),
-    );
-
-    const secondParams = (botApi.editMessageText.mock.calls[1] ?? [])[3] as Record<string, unknown>;
-    expect(secondParams).toEqual(
-      expect.objectContaining({
-        reply_markup: { inline_keyboard: [] },
-      }),
-    );
-  });
-
-  it("disables link previews when linkPreview is false", async () => {
-    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
-
-    await editMessageTelegram("123", 1, "https://example.com", {
-      token: "tok",
-      cfg: {},
-      linkPreview: false,
-    });
-
-    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
-    const params = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
-    expect(params).toEqual(
-      expect.objectContaining({
-        parse_mode: "HTML",
-        link_preview_options: { is_disabled: true },
-      }),
-    );
-  });
-});
diff --git a/src/telegram/send.poll.test.ts b/src/telegram/send.poll.test.ts
deleted file mode 100644
index 31bc1dc909a..00000000000
--- a/src/telegram/send.poll.test.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import type { Bot } from "grammy";
-import { describe, expect, it, vi } from "vitest";
-import { sendPollTelegram } from "./send.js";
-
-describe("sendPollTelegram", () => {
-  it("maps durationSeconds to open_period", async () => {
-    const api = {
-      sendPoll: vi.fn(async () => ({ message_id: 123, chat: { id: 555 }, poll: { id: "p1" } })),
-    };
-
-    const res = await sendPollTelegram(
-      "123",
-      { question: " Q ", options: [" A ", "B "], durationSeconds: 60 },
-      { token: "t", api: api as unknown as Bot["api"] },
-    );
-
-    expect(res).toEqual({ messageId: "123", chatId: "555", pollId: "p1" });
-    expect(api.sendPoll).toHaveBeenCalledTimes(1);
-    expect(api.sendPoll.mock.calls[0]?.[0]).toBe("123");
-    expect(api.sendPoll.mock.calls[0]?.[1]).toBe("Q");
-    expect(api.sendPoll.mock.calls[0]?.[2]).toEqual(["A", "B"]);
-    expect(api.sendPoll.mock.calls[0]?.[3]).toMatchObject({ open_period: 60 });
-  });
-
-  it("retries without message_thread_id on thread-not-found", async () => {
-    const api = {
-      sendPoll: vi.fn(
-        async (_chatId: string, _question: string, _options: string[], params: unknown) => {
-          const p = params as { message_thread_id?: unknown } | undefined;
-          if (p?.message_thread_id) {
-            throw new Error("400: Bad Request: message thread not found");
-          }
-          return { message_id: 1, chat: { id: 2 }, poll: { id: "p2" } };
-        },
-      ),
-    };
-
-    const res = await sendPollTelegram(
-      "123",
-      { question: "Q", options: ["A", "B"] },
-      { token: "t", api: api as unknown as Bot["api"], messageThreadId: 99 },
-    );
-
-    expect(res).toEqual({ messageId: "1", chatId: "2", pollId: "p2" });
-    expect(api.sendPoll).toHaveBeenCalledTimes(2);
-    expect(api.sendPoll.mock.calls[0]?.[3]).toMatchObject({ message_thread_id: 99 });
-    expect(api.sendPoll.mock.calls[1]?.[3]?.message_thread_id).toBeUndefined();
-  });
-
-  it("rejects durationHours for Telegram polls", async () => {
-    const api = { sendPoll: vi.fn() };
-
-    await expect(
-      sendPollTelegram(
-        "123",
-        { question: "Q", options: ["A", "B"], durationHours: 1 },
-        { token: "t", api: api as unknown as Bot["api"] },
-      ),
-    ).rejects.toThrow(/durationHours is not supported/i);
-
-    expect(api.sendPoll).not.toHaveBeenCalled();
-  });
-});
diff --git a/src/telegram/send.preserves-thread-params-plain-text-fallback.test.ts b/src/telegram/send.preserves-thread-params-plain-text-fallback.test.ts
deleted file mode 100644
index 2f9e7d05710..00000000000
--- a/src/telegram/send.preserves-thread-params-plain-text-fallback.test.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-const { botApi, botCtorSpy } = vi.hoisted(() => ({
-  botApi: {
-    sendMessage: vi.fn(),
-    setMessageReaction: vi.fn(),
-  },
-  botCtorSpy: vi.fn(),
-}));
-
-const { loadWebMedia } = vi.hoisted(() => ({
-  loadWebMedia: vi.fn(),
-}));
-
-vi.mock("../web/media.js", () => ({
-  loadWebMedia,
-}));
-
-vi.mock("grammy", () => ({
-  Bot: class {
-    api = botApi;
-    catch = vi.fn();
-    constructor(
-      public token: string,
-      public options?: { client?: { fetch?: typeof fetch } },
-    ) {
-      botCtorSpy(token, options);
-    }
-  },
-  InputFile: class {},
-}));
-
-import { reactMessageTelegram, sendMessageTelegram } from "./send.js";
-
-describe("buildInlineKeyboard", () => {
-  it("preserves thread params in plain text fallback", async () => {
-    const chatId = "-1001234567890";
-    const parseErr = new Error(
-      "400: Bad Request: can't parse entities: Can't find end of the entity",
-    );
-    const sendMessage = vi
-      .fn()
-      .mockRejectedValueOnce(parseErr)
-      .mockResolvedValueOnce({
-        message_id: 60,
-        chat: { id: chatId },
-      });
-    const api = { sendMessage } as unknown as {
-      sendMessage: typeof sendMessage;
-    };
-
-    const res = await sendMessageTelegram(chatId, "_bad markdown_", {
-      token: "tok",
-      api,
-      messageThreadId: 271,
-      replyToMessageId: 100,
-    });
-
-    // First call: with HTML + thread params
-    expect(sendMessage).toHaveBeenNthCalledWith(1, chatId, "<i>bad markdown</i>", {
-      parse_mode: "HTML",
-      message_thread_id: 271,
-      reply_to_message_id: 100,
-    });
-    // Second call: plain text BUT still with thread params (critical!)
-    expect(sendMessage).toHaveBeenNthCalledWith(2, chatId, "_bad markdown_", {
-      message_thread_id: 271,
-      reply_to_message_id: 100,
-    });
-    expect(res.messageId).toBe("60");
-  });
-
-  it("includes thread params in media messages", async () => {
-    const chatId = "-1001234567890";
-    const sendPhoto = vi.fn().mockResolvedValue({
-      message_id: 58,
-      chat: { id: chatId },
-    });
-    const api = { sendPhoto } as unknown as {
-      sendPhoto: typeof sendPhoto;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-image"),
-      contentType: "image/jpeg",
-      fileName: "photo.jpg",
-    });
-
-    await sendMessageTelegram(chatId, "photo in topic", {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/photo.jpg",
-      messageThreadId: 99,
-    });
-
-    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: "photo in topic",
-      parse_mode: "HTML",
-      message_thread_id: 99,
-    });
-  });
-});
-
-describe("reactMessageTelegram", () => {
-  it("sends emoji reactions", async () => {
-    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
-    const api = { setMessageReaction } as unknown as {
-      setMessageReaction: typeof setMessageReaction;
-    };
-
-    await reactMessageTelegram("telegram:123", "456", "✅", {
-      token: "tok",
-      api,
-    });
-
-    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, [{ type: "emoji", emoji: "✅" }]);
-  });
-
-  it("removes reactions when emoji is empty", async () => {
-    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
-    const api = { setMessageReaction } as unknown as {
-      setMessageReaction: typeof setMessageReaction;
-    };
-
-    await reactMessageTelegram("123", 456, "", {
-      token: "tok",
-      api,
-    });
-
-    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, []);
-  });
-
-  it("removes reactions when remove flag is set", async () => {
-    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
-    const api = { setMessageReaction } as unknown as {
-      setMessageReaction: typeof setMessageReaction;
-    };
-
-    await reactMessageTelegram("123", 456, "✅", {
-      token: "tok",
-      api,
-      remove: true,
-    });
-
-    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, []);
-  });
-});
diff --git a/src/telegram/send.test-harness.ts b/src/telegram/send.test-harness.ts
index 528ec2fb5fa..f211d39368d 100644
--- a/src/telegram/send.test-harness.ts
+++ b/src/telegram/send.test-harness.ts
@@ -3,10 +3,16 @@ import type { MockFn } from "../test-utils/vitest-mock-fn.js";
 
 const { botApi, botCtorSpy } = vi.hoisted(() => ({
   botApi: {
+    deleteMessage: vi.fn(),
+    editMessageText: vi.fn(),
     sendMessage: vi.fn(),
+    sendPoll: vi.fn(),
     sendPhoto: vi.fn(),
+    sendVoice: vi.fn(),
+    sendAudio: vi.fn(),
     sendVideo: vi.fn(),
     sendVideoNote: vi.fn(),
+    sendAnimation: vi.fn(),
     setMessageReaction: vi.fn(),
     sendSticker: vi.fn(),
   },
diff --git a/src/telegram/send.returns-undefined-empty-input.test.ts b/src/telegram/send.test.ts
similarity index 57%
rename from src/telegram/send.returns-undefined-empty-input.test.ts
rename to src/telegram/send.test.ts
index d0d9eb7cd47..7cd8b337c0e 100644
--- a/src/telegram/send.returns-undefined-empty-input.test.ts
+++ b/src/telegram/send.test.ts
@@ -1,15 +1,55 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Bot } from "grammy";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   getTelegramSendTestMocks,
   importTelegramSendModule,
   installTelegramSendTestHooks,
 } from "./send.test-harness.js";
+import { clearSentMessageCache, recordSentMessage, wasSentByBot } from "./sent-message-cache.js";
 
 installTelegramSendTestHooks();
 
 const { botApi, botCtorSpy, loadConfig, loadWebMedia } = getTelegramSendTestMocks();
-const { buildInlineKeyboard, sendMessageTelegram, sendStickerTelegram } =
-  await importTelegramSendModule();
+const {
+  buildInlineKeyboard,
+  editMessageTelegram,
+  reactMessageTelegram,
+  sendMessageTelegram,
+  sendPollTelegram,
+  sendStickerTelegram,
+} = await importTelegramSendModule();
+
+describe("sent-message-cache", () => {
+  afterEach(() => {
+    clearSentMessageCache();
+  });
+
+  it("records and retrieves sent messages", () => {
+    recordSentMessage(123, 1);
+    recordSentMessage(123, 2);
+    recordSentMessage(456, 10);
+
+    expect(wasSentByBot(123, 1)).toBe(true);
+    expect(wasSentByBot(123, 2)).toBe(true);
+    expect(wasSentByBot(456, 10)).toBe(true);
+    expect(wasSentByBot(123, 3)).toBe(false);
+    expect(wasSentByBot(789, 1)).toBe(false);
+  });
+
+  it("handles string chat IDs", () => {
+    recordSentMessage("123", 1);
+    expect(wasSentByBot("123", 1)).toBe(true);
+    expect(wasSentByBot(123, 1)).toBe(true);
+  });
+
+  it("clears cache", () => {
+    recordSentMessage(123, 1);
+    expect(wasSentByBot(123, 1)).toBe(true);
+
+    clearSentMessageCache();
+    expect(wasSentByBot(123, 1)).toBe(false);
+  });
+});
 
 describe("buildInlineKeyboard", () => {
   it("returns undefined for empty input", () => {
@@ -229,6 +269,322 @@ describe("sendMessageTelegram", () => {
     );
   });
 
+  it("preserves thread params in plain text fallback", async () => {
+    const chatId = "-1001234567890";
+    const parseErr = new Error(
+      "400: Bad Request: can't parse entities: Can't find end of the entity",
+    );
+    const sendMessage = vi
+      .fn()
+      .mockRejectedValueOnce(parseErr)
+      .mockResolvedValueOnce({
+        message_id: 60,
+        chat: { id: chatId },
+      });
+    const api = { sendMessage } as unknown as {
+      sendMessage: typeof sendMessage;
+    };
+
+    const res = await sendMessageTelegram(chatId, "_bad markdown_", {
+      token: "tok",
+      api,
+      messageThreadId: 271,
+      replyToMessageId: 100,
+    });
+
+    expect(sendMessage).toHaveBeenNthCalledWith(1, chatId, "<i>bad markdown</i>", {
+      parse_mode: "HTML",
+      message_thread_id: 271,
+      reply_to_message_id: 100,
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(2, chatId, "_bad markdown_", {
+      message_thread_id: 271,
+      reply_to_message_id: 100,
+    });
+    expect(res.messageId).toBe("60");
+  });
+
+  it("includes thread params in media messages", async () => {
+    const chatId = "-1001234567890";
+    const sendPhoto = vi.fn().mockResolvedValue({
+      message_id: 58,
+      chat: { id: chatId },
+    });
+    const api = { sendPhoto } as unknown as {
+      sendPhoto: typeof sendPhoto;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-image"),
+      contentType: "image/jpeg",
+      fileName: "photo.jpg",
+    });
+
+    await sendMessageTelegram(chatId, "photo in topic", {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/photo.jpg",
+      messageThreadId: 99,
+    });
+
+    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
+      caption: "photo in topic",
+      parse_mode: "HTML",
+      message_thread_id: 99,
+    });
+  });
+
+  it("splits long captions into media + text messages when text exceeds 1024 chars", async () => {
+    const chatId = "123";
+    const longText = "A".repeat(1100);
+
+    const sendPhoto = vi.fn().mockResolvedValue({
+      message_id: 70,
+      chat: { id: chatId },
+    });
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 71,
+      chat: { id: chatId },
+    });
+    const api = { sendPhoto, sendMessage } as unknown as {
+      sendPhoto: typeof sendPhoto;
+      sendMessage: typeof sendMessage;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-image"),
+      contentType: "image/jpeg",
+      fileName: "photo.jpg",
+    });
+
+    const res = await sendMessageTelegram(chatId, longText, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/photo.jpg",
+    });
+
+    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
+      caption: undefined,
+    });
+    expect(sendMessage).toHaveBeenCalledWith(chatId, longText, {
+      parse_mode: "HTML",
+    });
+    expect(res.messageId).toBe("71");
+  });
+
+  it("uses caption when text is within 1024 char limit", async () => {
+    const chatId = "123";
+    const shortText = "B".repeat(1024);
+
+    const sendPhoto = vi.fn().mockResolvedValue({
+      message_id: 72,
+      chat: { id: chatId },
+    });
+    const sendMessage = vi.fn();
+    const api = { sendPhoto, sendMessage } as unknown as {
+      sendPhoto: typeof sendPhoto;
+      sendMessage: typeof sendMessage;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-image"),
+      contentType: "image/jpeg",
+      fileName: "photo.jpg",
+    });
+
+    const res = await sendMessageTelegram(chatId, shortText, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/photo.jpg",
+    });
+
+    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
+      caption: shortText,
+      parse_mode: "HTML",
+    });
+    expect(sendMessage).not.toHaveBeenCalled();
+    expect(res.messageId).toBe("72");
+  });
+
+  it("renders markdown in media captions", async () => {
+    const chatId = "123";
+    const caption = "hi **boss**";
+
+    const sendPhoto = vi.fn().mockResolvedValue({
+      message_id: 90,
+      chat: { id: chatId },
+    });
+    const api = { sendPhoto } as unknown as {
+      sendPhoto: typeof sendPhoto;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-image"),
+      contentType: "image/jpeg",
+      fileName: "photo.jpg",
+    });
+
+    await sendMessageTelegram(chatId, caption, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/photo.jpg",
+    });
+
+    expect(sendPhoto).toHaveBeenCalledWith(chatId, expect.anything(), {
+      caption: "hi <b>boss</b>",
+      parse_mode: "HTML",
+    });
+  });
+
+  it("sends video as video note when asVideoNote is true", async () => {
+    const chatId = "123";
+    const text = "ignored caption context";
+
+    const sendVideoNote = vi.fn().mockResolvedValue({
+      message_id: 101,
+      chat: { id: chatId },
+    });
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 102,
+      chat: { id: chatId },
+    });
+    const api = { sendVideoNote, sendMessage } as unknown as {
+      sendVideoNote: typeof sendVideoNote;
+      sendMessage: typeof sendMessage;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-video"),
+      contentType: "video/mp4",
+      fileName: "video.mp4",
+    });
+
+    const res = await sendMessageTelegram(chatId, text, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/video.mp4",
+      asVideoNote: true,
+    });
+
+    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {});
+    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
+      parse_mode: "HTML",
+    });
+    expect(res.messageId).toBe("102");
+  });
+
+  it("sends regular video when asVideoNote is false", async () => {
+    const chatId = "123";
+    const text = "my caption";
+
+    const sendVideo = vi.fn().mockResolvedValue({
+      message_id: 201,
+      chat: { id: chatId },
+    });
+    const api = { sendVideo } as unknown as {
+      sendVideo: typeof sendVideo;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-video"),
+      contentType: "video/mp4",
+      fileName: "video.mp4",
+    });
+
+    const res = await sendMessageTelegram(chatId, text, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/video.mp4",
+      asVideoNote: false,
+    });
+
+    expect(sendVideo).toHaveBeenCalledWith(chatId, expect.anything(), {
+      caption: expect.any(String),
+      parse_mode: "HTML",
+    });
+    expect(res.messageId).toBe("201");
+  });
+
+  it("adds reply_markup to separate text message for video notes", async () => {
+    const chatId = "123";
+    const text = "Check this out";
+
+    const sendVideoNote = vi.fn().mockResolvedValue({
+      message_id: 301,
+      chat: { id: chatId },
+    });
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 302,
+      chat: { id: chatId },
+    });
+    const api = { sendVideoNote, sendMessage } as unknown as {
+      sendVideoNote: typeof sendVideoNote;
+      sendMessage: typeof sendMessage;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-video"),
+      contentType: "video/mp4",
+      fileName: "video.mp4",
+    });
+
+    await sendMessageTelegram(chatId, text, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/video.mp4",
+      asVideoNote: true,
+      buttons: [[{ text: "Btn", callback_data: "dat" }]],
+    });
+
+    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {});
+    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
+      parse_mode: "HTML",
+      reply_markup: {
+        inline_keyboard: [[{ text: "Btn", callback_data: "dat" }]],
+      },
+    });
+  });
+
+  it("threads video note and text message correctly", async () => {
+    const chatId = "123";
+    const text = "Threaded reply";
+
+    const sendVideoNote = vi.fn().mockResolvedValue({
+      message_id: 401,
+      chat: { id: chatId },
+    });
+    const sendMessage = vi.fn().mockResolvedValue({
+      message_id: 402,
+      chat: { id: chatId },
+    });
+    const api = { sendVideoNote, sendMessage } as unknown as {
+      sendVideoNote: typeof sendVideoNote;
+      sendMessage: typeof sendMessage;
+    };
+
+    loadWebMedia.mockResolvedValueOnce({
+      buffer: Buffer.from("fake-video"),
+      contentType: "video/mp4",
+      fileName: "video.mp4",
+    });
+
+    await sendMessageTelegram(chatId, text, {
+      token: "tok",
+      api,
+      mediaUrl: "https://example.com/video.mp4",
+      asVideoNote: true,
+      replyToMessageId: 999,
+    });
+
+    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {
+      reply_to_message_id: 999,
+    });
+    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
+      parse_mode: "HTML",
+      reply_to_message_id: 999,
+    });
+  });
+
   it("retries on transient errors with retry_after", async () => {
     vi.useFakeTimers();
     const chatId = "123";
@@ -583,30 +939,6 @@ describe("sendMessageTelegram", () => {
     });
   });
 
-  it("includes both thread and reply params for forum topic replies", async () => {
-    const chatId = "-1001234567890";
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 57,
-      chat: { id: chatId },
-    });
-    const api = { sendMessage } as unknown as {
-      sendMessage: typeof sendMessage;
-    };
-
-    await sendMessageTelegram(chatId, "forum reply", {
-      token: "tok",
-      api,
-      messageThreadId: 271,
-      replyToMessageId: 500,
-    });
-
-    expect(sendMessage).toHaveBeenCalledWith(chatId, "forum reply", {
-      parse_mode: "HTML",
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-    });
-  });
-
   it("retries media sends without message_thread_id when thread is missing", async () => {
     const chatId = "123";
     const threadErr = new Error("400: Bad Request: message thread not found");
@@ -647,6 +979,51 @@ describe("sendMessageTelegram", () => {
   });
 });
 
+describe("reactMessageTelegram", () => {
+  it("sends emoji reactions", async () => {
+    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
+    const api = { setMessageReaction } as unknown as {
+      setMessageReaction: typeof setMessageReaction;
+    };
+
+    await reactMessageTelegram("telegram:123", "456", "✅", {
+      token: "tok",
+      api,
+    });
+
+    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, [{ type: "emoji", emoji: "✅" }]);
+  });
+
+  it("removes reactions when emoji is empty", async () => {
+    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
+    const api = { setMessageReaction } as unknown as {
+      setMessageReaction: typeof setMessageReaction;
+    };
+
+    await reactMessageTelegram("123", 456, "", {
+      token: "tok",
+      api,
+    });
+
+    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, []);
+  });
+
+  it("removes reactions when remove flag is set", async () => {
+    const setMessageReaction = vi.fn().mockResolvedValue(undefined);
+    const api = { setMessageReaction } as unknown as {
+      setMessageReaction: typeof setMessageReaction;
+    };
+
+    await reactMessageTelegram("123", 456, "✅", {
+      token: "tok",
+      api,
+      remove: true,
+    });
+
+    expect(setMessageReaction).toHaveBeenCalledWith("123", 456, []);
+  });
+});
+
 describe("sendStickerTelegram", () => {
   beforeEach(() => {
     loadConfig.mockReturnValue({});
@@ -683,28 +1060,6 @@ describe("sendStickerTelegram", () => {
     }
   });
 
-  it("includes message_thread_id for forum topic messages", async () => {
-    const chatId = "-1001234567890";
-    const fileId = "CAACAgIAAxkBAAI...sticker_file_id";
-    const sendSticker = vi.fn().mockResolvedValue({
-      message_id: 101,
-      chat: { id: chatId },
-    });
-    const api = { sendSticker } as unknown as {
-      sendSticker: typeof sendSticker;
-    };
-
-    await sendStickerTelegram(chatId, fileId, {
-      token: "tok",
-      api,
-      messageThreadId: 271,
-    });
-
-    expect(sendSticker).toHaveBeenCalledWith(chatId, fileId, {
-      message_thread_id: 271,
-    });
-  });
-
   it("retries sticker sends without message_thread_id when thread is missing", async () => {
     const chatId = "123";
     const threadErr = new Error("400: Bad Request: message thread not found");
@@ -754,67 +1109,6 @@ describe("sendStickerTelegram", () => {
     });
   });
 
-  it("includes both thread and reply params for forum topic replies", async () => {
-    const chatId = "-1001234567890";
-    const fileId = "CAACAgIAAxkBAAI...sticker_file_id";
-    const sendSticker = vi.fn().mockResolvedValue({
-      message_id: 103,
-      chat: { id: chatId },
-    });
-    const api = { sendSticker } as unknown as {
-      sendSticker: typeof sendSticker;
-    };
-
-    await sendStickerTelegram(chatId, fileId, {
-      token: "tok",
-      api,
-      messageThreadId: 271,
-      replyToMessageId: 500,
-    });
-
-    expect(sendSticker).toHaveBeenCalledWith(chatId, fileId, {
-      message_thread_id: 271,
-      reply_to_message_id: 500,
-    });
-  });
-
-  it("normalizes chat ids with internal prefixes", async () => {
-    const sendSticker = vi.fn().mockResolvedValue({
-      message_id: 104,
-      chat: { id: "123" },
-    });
-    const api = { sendSticker } as unknown as {
-      sendSticker: typeof sendSticker;
-    };
-
-    await sendStickerTelegram("telegram:123", "fileId123", {
-      token: "tok",
-      api,
-    });
-
-    expect(sendSticker).toHaveBeenCalledWith("123", "fileId123", undefined);
-  });
-
-  it("parses message_thread_id from recipient string (telegram:group:...:topic:...)", async () => {
-    const chatId = "-1001234567890";
-    const sendSticker = vi.fn().mockResolvedValue({
-      message_id: 105,
-      chat: { id: chatId },
-    });
-    const api = { sendSticker } as unknown as {
-      sendSticker: typeof sendSticker;
-    };
-
-    await sendStickerTelegram(`telegram:group:${chatId}:topic:271`, "fileId123", {
-      token: "tok",
-      api,
-    });
-
-    expect(sendSticker).toHaveBeenCalledWith(chatId, "fileId123", {
-      message_thread_id: 271,
-    });
-  });
-
   it("wraps chat-not-found with actionable context", async () => {
     const chatId = "123";
     const err = new Error("400: Bad Request: chat not found");
@@ -849,3 +1143,172 @@ describe("sendStickerTelegram", () => {
     expect(sendSticker).toHaveBeenCalledWith(chatId, "fileId123", undefined);
   });
 });
+
+describe("editMessageTelegram", () => {
+  beforeEach(() => {
+    botApi.editMessageText.mockReset();
+    botCtorSpy.mockReset();
+  });
+
+  it("keeps existing buttons when buttons is undefined (no reply_markup)", async () => {
+    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
+
+    await editMessageTelegram("123", 1, "hi", {
+      token: "tok",
+      cfg: {},
+    });
+
+    expect(botCtorSpy).toHaveBeenCalledTimes(1);
+    expect(botCtorSpy.mock.calls[0]?.[0]).toBe("tok");
+    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
+    const params = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
+    expect(params).toEqual(expect.objectContaining({ parse_mode: "HTML" }));
+    expect(params).not.toHaveProperty("reply_markup");
+  });
+
+  it("removes buttons when buttons is empty (reply_markup.inline_keyboard = [])", async () => {
+    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
+
+    await editMessageTelegram("123", 1, "hi", {
+      token: "tok",
+      cfg: {},
+      buttons: [],
+    });
+
+    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
+    const params = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
+    expect(params).toEqual(
+      expect.objectContaining({
+        parse_mode: "HTML",
+        reply_markup: { inline_keyboard: [] },
+      }),
+    );
+  });
+
+  it("falls back to plain text when Telegram HTML parse fails (and preserves reply_markup)", async () => {
+    botApi.editMessageText
+      .mockRejectedValueOnce(new Error("400: Bad Request: can't parse entities"))
+      .mockResolvedValueOnce({ message_id: 1, chat: { id: "123" } });
+
+    await editMessageTelegram("123", 1, "<bad> html", {
+      token: "tok",
+      cfg: {},
+      buttons: [],
+    });
+
+    expect(botApi.editMessageText).toHaveBeenCalledTimes(2);
+
+    const firstParams = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
+    expect(firstParams).toEqual(
+      expect.objectContaining({
+        parse_mode: "HTML",
+        reply_markup: { inline_keyboard: [] },
+      }),
+    );
+
+    const secondParams = (botApi.editMessageText.mock.calls[1] ?? [])[3] as Record<string, unknown>;
+    expect(secondParams).toEqual(
+      expect.objectContaining({
+        reply_markup: { inline_keyboard: [] },
+      }),
+    );
+  });
+
+  it("treats 'message is not modified' as success", async () => {
+    botApi.editMessageText.mockRejectedValueOnce(
+      new Error(
+        "400: Bad Request: message is not modified: specified new message content and reply markup are exactly the same as a current content and reply markup of the message",
+      ),
+    );
+
+    await expect(
+      editMessageTelegram("123", 1, "hi", {
+        token: "tok",
+        cfg: {},
+      }),
+    ).resolves.toEqual({ ok: true, messageId: "1", chatId: "123" });
+    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
+  });
+
+  it("disables link previews when linkPreview is false", async () => {
+    botApi.editMessageText.mockResolvedValue({ message_id: 1, chat: { id: "123" } });
+
+    await editMessageTelegram("123", 1, "https://example.com", {
+      token: "tok",
+      cfg: {},
+      linkPreview: false,
+    });
+
+    expect(botApi.editMessageText).toHaveBeenCalledTimes(1);
+    const params = (botApi.editMessageText.mock.calls[0] ?? [])[3] as Record<string, unknown>;
+    expect(params).toEqual(
+      expect.objectContaining({
+        parse_mode: "HTML",
+        link_preview_options: { is_disabled: true },
+      }),
+    );
+  });
+});
+
+describe("sendPollTelegram", () => {
+  it("maps durationSeconds to open_period", async () => {
+    const api = {
+      sendPoll: vi.fn(async () => ({ message_id: 123, chat: { id: 555 }, poll: { id: "p1" } })),
+    };
+
+    const res = await sendPollTelegram(
+      "123",
+      { question: " Q ", options: [" A ", "B "], durationSeconds: 60 },
+      { token: "t", api: api as unknown as Bot["api"] },
+    );
+
+    expect(res).toEqual({ messageId: "123", chatId: "555", pollId: "p1" });
+    expect(api.sendPoll).toHaveBeenCalledTimes(1);
+    expect(api.sendPoll.mock.calls[0]?.[0]).toBe("123");
+    expect(api.sendPoll.mock.calls[0]?.[1]).toBe("Q");
+    expect(api.sendPoll.mock.calls[0]?.[2]).toEqual(["A", "B"]);
+    expect(api.sendPoll.mock.calls[0]?.[3]).toMatchObject({ open_period: 60 });
+  });
+
+  it("retries without message_thread_id on thread-not-found", async () => {
+    const api = {
+      sendPoll: vi.fn(
+        async (_chatId: string, _question: string, _options: string[], params: unknown) => {
+          const p = params as { message_thread_id?: unknown } | undefined;
+          if (p?.message_thread_id) {
+            throw new Error("400: Bad Request: message thread not found");
+          }
+          return { message_id: 1, chat: { id: 2 }, poll: { id: "p2" } };
+        },
+      ),
+    };
+
+    const res = await sendPollTelegram(
+      "123",
+      { question: "Q", options: ["A", "B"] },
+      { token: "t", api: api as unknown as Bot["api"], messageThreadId: 99 },
+    );
+
+    expect(res).toEqual({ messageId: "1", chatId: "2", pollId: "p2" });
+    expect(api.sendPoll).toHaveBeenCalledTimes(2);
+    expect(api.sendPoll.mock.calls[0]?.[3]).toMatchObject({ message_thread_id: 99 });
+    expect(
+      (api.sendPoll.mock.calls[1]?.[3] as { message_thread_id?: unknown } | undefined)
+        ?.message_thread_id,
+    ).toBeUndefined();
+  });
+
+  it("rejects durationHours for Telegram polls", async () => {
+    const api = { sendPoll: vi.fn() };
+
+    await expect(
+      sendPollTelegram(
+        "123",
+        { question: "Q", options: ["A", "B"], durationHours: 1 },
+        { token: "t", api: api as unknown as Bot["api"] },
+      ),
+    ).rejects.toThrow(/durationHours is not supported/i);
+
+    expect(api.sendPoll).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/telegram/send.ts b/src/telegram/send.ts
index d4c4dd0e9b9..72cf2eb5037 100644
--- a/src/telegram/send.ts
+++ b/src/telegram/send.ts
@@ -63,6 +63,11 @@ type TelegramSendResult = {
   chatId: string;
 };
 
+type TelegramMessageLike = {
+  message_id?: number;
+  chat?: { id?: string | number };
+};
+
 type TelegramReactionOpts = {
   token?: string;
   accountId?: string;
@@ -74,6 +79,9 @@ type TelegramReactionOpts = {
 
 const PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;
 const THREAD_NOT_FOUND_RE = /400:\s*Bad Request:\s*message thread not found/i;
+const MESSAGE_NOT_MODIFIED_RE =
+  /400:\s*Bad Request:\s*message is not modified|MESSAGE_NOT_MODIFIED/i;
+const CHAT_NOT_FOUND_RE = /400: Bad Request: chat not found/i;
 const diagLogger = createSubsystemLogger("telegram/diagnostic");
 
 function createTelegramHttpLogger(cfg: ReturnType<typeof loadConfig>) {
@@ -182,6 +190,10 @@ function isTelegramThreadNotFoundError(err: unknown): boolean {
   return THREAD_NOT_FOUND_RE.test(formatErrorMessage(err));
 }
 
+function isTelegramMessageNotModifiedError(err: unknown): boolean {
+  return MESSAGE_NOT_MODIFIED_RE.test(formatErrorMessage(err));
+}
+
 function hasMessageThreadIdParam(params?: Record<string, unknown>): boolean {
   if (!params) {
     return false;
@@ -207,6 +219,177 @@ function removeMessageThreadIdParam(
   return Object.keys(next).length > 0 ? next : undefined;
 }
 
+function isTelegramHtmlParseError(err: unknown): boolean {
+  return PARSE_ERR_RE.test(formatErrorMessage(err));
+}
+
+function buildTelegramThreadReplyParams(params: {
+  targetMessageThreadId?: number;
+  messageThreadId?: number;
+  replyToMessageId?: number;
+  quoteText?: string;
+}): Record<string, unknown> {
+  const messageThreadId =
+    params.messageThreadId != null ? params.messageThreadId : params.targetMessageThreadId;
+  const threadSpec =
+    messageThreadId != null ? { id: messageThreadId, scope: "forum" as const } : undefined;
+  const threadIdParams = buildTelegramThreadParams(threadSpec);
+  const threadParams: Record<string, unknown> = threadIdParams ? { ...threadIdParams } : {};
+
+  if (params.replyToMessageId != null) {
+    const replyToMessageId = Math.trunc(params.replyToMessageId);
+    if (params.quoteText?.trim()) {
+      threadParams.reply_parameters = {
+        message_id: replyToMessageId,
+        quote: params.quoteText.trim(),
+      };
+    } else {
+      threadParams.reply_to_message_id = replyToMessageId;
+    }
+  }
+  return threadParams;
+}
+
+async function withTelegramHtmlParseFallback<T>(params: {
+  label: string;
+  verbose?: boolean;
+  requestHtml: (label: string) => Promise<T>;
+  requestPlain: (label: string) => Promise<T>;
+}): Promise<T> {
+  try {
+    return await params.requestHtml(params.label);
+  } catch (err) {
+    if (!isTelegramHtmlParseError(err)) {
+      throw err;
+    }
+    if (params.verbose) {
+      console.warn(
+        `telegram ${params.label} failed with HTML parse error, retrying as plain text: ${formatErrorMessage(
+          err,
+        )}`,
+      );
+    }
+    return await params.requestPlain(`${params.label}-plain`);
+  }
+}
+
+type TelegramApiContext = {
+  cfg: ReturnType<typeof loadConfig>;
+  account: ResolvedTelegramAccount;
+  api: Bot["api"];
+};
+
+function resolveTelegramApiContext(opts: {
+  token?: string;
+  accountId?: string;
+  api?: Bot["api"];
+  cfg?: ReturnType<typeof loadConfig>;
+}): TelegramApiContext {
+  const cfg = opts.cfg ?? loadConfig();
+  const account = resolveTelegramAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const token = resolveToken(opts.token, account);
+  const client = resolveTelegramClientOptions(account);
+  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
+  return { cfg, account, api };
+}
+
+type TelegramRequestWithDiag = <T>(
+  fn: () => Promise<T>,
+  label?: string,
+  options?: { shouldLog?: (err: unknown) => boolean },
+) => Promise<T>;
+
+function createTelegramRequestWithDiag(params: {
+  cfg: ReturnType<typeof loadConfig>;
+  account: ResolvedTelegramAccount;
+  retry?: RetryConfig;
+  verbose?: boolean;
+  shouldRetry?: (err: unknown) => boolean;
+  useApiErrorLogging?: boolean;
+}): TelegramRequestWithDiag {
+  const request = createTelegramRetryRunner({
+    retry: params.retry,
+    configRetry: params.account.config.retry,
+    verbose: params.verbose,
+    ...(params.shouldRetry ? { shouldRetry: params.shouldRetry } : {}),
+  });
+  const logHttpError = createTelegramHttpLogger(params.cfg);
+  return <T>(
+    fn: () => Promise<T>,
+    label?: string,
+    options?: { shouldLog?: (err: unknown) => boolean },
+  ) => {
+    const runRequest = () => request(fn, label);
+    const call =
+      params.useApiErrorLogging === false
+        ? runRequest()
+        : withTelegramApiErrorLogging({
+            operation: label ?? "request",
+            fn: runRequest,
+            ...(options?.shouldLog ? { shouldLog: options.shouldLog } : {}),
+          });
+    return call.catch((err) => {
+      logHttpError(label ?? "request", err);
+      throw err;
+    });
+  };
+}
+
+function wrapTelegramChatNotFoundError(err: unknown, params: { chatId: string; input: string }) {
+  if (!CHAT_NOT_FOUND_RE.test(formatErrorMessage(err))) {
+    return err;
+  }
+  return new Error(
+    [
+      `Telegram send failed: chat not found (chat_id=${params.chatId}).`,
+      "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
+      `Input was: ${JSON.stringify(params.input)}.`,
+    ].join(" "),
+  );
+}
+
+async function withTelegramThreadFallback<T>(
+  params: Record<string, unknown> | undefined,
+  label: string,
+  verbose: boolean | undefined,
+  attempt: (
+    effectiveParams: Record<string, unknown> | undefined,
+    effectiveLabel: string,
+  ) => Promise<T>,
+): Promise<T> {
+  try {
+    return await attempt(params, label);
+  } catch (err) {
+    if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
+      throw err;
+    }
+    if (verbose) {
+      console.warn(
+        `telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`,
+      );
+    }
+    const retriedParams = removeMessageThreadIdParam(params);
+    return await attempt(retriedParams, `${label}-threadless`);
+  }
+}
+
+function createRequestWithChatNotFound(params: {
+  requestWithDiag: TelegramRequestWithDiag;
+  chatId: string;
+  input: string;
+}) {
+  return async <T>(fn: () => Promise<T>, label: string) =>
+    params.requestWithDiag(fn, label).catch((err) => {
+      throw wrapTelegramChatNotFoundError(err, {
+        chatId: params.chatId,
+        input: params.input,
+      });
+    });
+}
+
 export function buildInlineKeyboard(
   buttons?: TelegramSendOpts["buttons"],
 ): InlineKeyboardMarkup | undefined {
@@ -236,92 +419,31 @@ export async function sendMessageTelegram(
   text: string,
   opts: TelegramSendOpts = {},
 ): Promise<TelegramSendResult> {
-  const cfg = loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const token = resolveToken(opts.token, account);
+  const { cfg, account, api } = resolveTelegramApiContext(opts);
   const target = parseTelegramTarget(to);
   const chatId = normalizeChatId(target.chatId);
-  // Use provided api or create a new Bot instance. The nullish coalescing
-  // operator ensures api is always defined (Bot.api is always non-null).
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
   const mediaUrl = opts.mediaUrl?.trim();
   const replyMarkup = buildInlineKeyboard(opts.buttons);
 
-  // Build optional params for forum topics and reply threading.
-  // Only include these if actually provided to keep API calls clean.
-  const messageThreadId =
-    opts.messageThreadId != null ? opts.messageThreadId : target.messageThreadId;
-  const threadSpec =
-    messageThreadId != null ? { id: messageThreadId, scope: "forum" as const } : undefined;
-  const threadIdParams = buildTelegramThreadParams(threadSpec);
-  const threadParams: Record<string, unknown> = threadIdParams ? { ...threadIdParams } : {};
-  const quoteText = opts.quoteText?.trim();
-  if (opts.replyToMessageId != null) {
-    if (quoteText) {
-      threadParams.reply_parameters = {
-        message_id: Math.trunc(opts.replyToMessageId),
-        quote: quoteText,
-      };
-    } else {
-      threadParams.reply_to_message_id = Math.trunc(opts.replyToMessageId);
-    }
-  }
+  const threadParams = buildTelegramThreadReplyParams({
+    targetMessageThreadId: target.messageThreadId,
+    messageThreadId: opts.messageThreadId,
+    replyToMessageId: opts.replyToMessageId,
+    quoteText: opts.quoteText,
+  });
   const hasThreadParams = Object.keys(threadParams).length > 0;
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
     shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    withTelegramApiErrorLogging({
-      operation: label ?? "request",
-      fn: () => request(fn, label),
-    }).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
-  const wrapChatNotFound = (err: unknown) => {
-    if (!/400: Bad Request: chat not found/i.test(formatErrorMessage(err))) {
-      return err;
-    }
-    return new Error(
-      [
-        `Telegram send failed: chat not found (chat_id=${chatId}).`,
-        "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
-        `Input was: ${JSON.stringify(to)}.`,
-      ].join(" "),
-    );
-  };
-
-  const sendWithThreadFallback = async <T>(
-    params: Record<string, unknown> | undefined,
-    label: string,
-    attempt: (
-      effectiveParams: Record<string, unknown> | undefined,
-      effectiveLabel: string,
-    ) => Promise<T>,
-  ): Promise<T> => {
-    try {
-      return await attempt(params, label);
-    } catch (err) {
-      if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
-        throw err;
-      }
-      if (opts.verbose) {
-        console.warn(
-          `telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`,
-        );
-      }
-      const retriedParams = removeMessageThreadIdParam(params);
-      return await attempt(retriedParams, `${label}-threadless`);
-    }
-  };
+  const requestWithChatNotFound = createRequestWithChatNotFound({
+    requestWithDiag,
+    chatId,
+    input: to,
+  });
 
   const textMode = opts.textMode ?? "markdown";
   const tableMode = resolveMarkdownTableMode({
@@ -340,48 +462,50 @@ export async function sendMessageTelegram(
     params?: Record<string, unknown>,
     fallbackText?: string,
   ) => {
-    return await sendWithThreadFallback(params, "message", async (effectiveParams, label) => {
-      const htmlText = renderHtmlText(rawText);
-      const baseParams = effectiveParams ? { ...effectiveParams } : {};
-      if (linkPreviewOptions) {
-        baseParams.link_preview_options = linkPreviewOptions;
-      }
-      const hasBaseParams = Object.keys(baseParams).length > 0;
-      const sendParams = {
-        parse_mode: "HTML" as const,
-        ...baseParams,
-        ...(opts.silent === true ? { disable_notification: true } : {}),
-      };
-      const res = await requestWithDiag(
-        () =>
-          api.sendMessage(chatId, htmlText, sendParams as Parameters<typeof api.sendMessage>[2]),
-        label,
-      ).catch(async (err) => {
-        // Telegram rejects malformed HTML (e.g., unsupported tags or entities).
-        // When that happens, fall back to plain text so the message still delivers.
-        const errText = formatErrorMessage(err);
-        if (PARSE_ERR_RE.test(errText)) {
-          if (opts.verbose) {
-            console.warn(`telegram HTML parse failed, retrying as plain text: ${errText}`);
-          }
-          const fallback = fallbackText ?? rawText;
-          const plainParams = hasBaseParams
-            ? (baseParams as Parameters<typeof api.sendMessage>[2])
-            : undefined;
-          return await requestWithDiag(
-            () =>
-              plainParams
-                ? api.sendMessage(chatId, fallback, plainParams)
-                : api.sendMessage(chatId, fallback),
-            `${label}-plain`,
-          ).catch((err2) => {
-            throw wrapChatNotFound(err2);
-          });
+    return await withTelegramThreadFallback(
+      params,
+      "message",
+      opts.verbose,
+      async (effectiveParams, label) => {
+        const htmlText = renderHtmlText(rawText);
+        const baseParams = effectiveParams ? { ...effectiveParams } : {};
+        if (linkPreviewOptions) {
+          baseParams.link_preview_options = linkPreviewOptions;
         }
-        throw wrapChatNotFound(err);
-      });
-      return res;
-    });
+        const hasBaseParams = Object.keys(baseParams).length > 0;
+        const sendParams = {
+          parse_mode: "HTML" as const,
+          ...baseParams,
+          ...(opts.silent === true ? { disable_notification: true } : {}),
+        };
+        return await withTelegramHtmlParseFallback({
+          label,
+          verbose: opts.verbose,
+          requestHtml: (retryLabel) =>
+            requestWithChatNotFound(
+              () =>
+                api.sendMessage(
+                  chatId,
+                  htmlText,
+                  sendParams as Parameters<typeof api.sendMessage>[2],
+                ),
+              retryLabel,
+            ),
+          requestPlain: (retryLabel) => {
+            const plainParams = hasBaseParams
+              ? (baseParams as Parameters<typeof api.sendMessage>[2])
+              : undefined;
+            return requestWithChatNotFound(
+              () =>
+                plainParams
+                  ? api.sendMessage(chatId, fallbackText ?? rawText, plainParams)
+                  : api.sendMessage(chatId, fallbackText ?? rawText),
+              retryLabel,
+            );
+          },
+        });
+      },
+    );
   };
 
   if (mediaUrl) {
@@ -423,124 +547,105 @@ export async function sendMessageTelegram(
       ...baseMediaParams,
       ...(opts.silent === true ? { disable_notification: true } : {}),
     };
-    let result:
-      | Awaited<ReturnType<typeof api.sendPhoto>>
-      | Awaited<ReturnType<typeof api.sendVideo>>
-      | Awaited<ReturnType<typeof api.sendVideoNote>>
-      | Awaited<ReturnType<typeof api.sendAudio>>
-      | Awaited<ReturnType<typeof api.sendVoice>>
-      | Awaited<ReturnType<typeof api.sendAnimation>>
-      | Awaited<ReturnType<typeof api.sendDocument>>;
-    if (isGif) {
-      result = await sendWithThreadFallback(
+    const sendMedia = async (
+      label: string,
+      sender: (
+        effectiveParams: Record<string, unknown> | undefined,
+      ) => Promise<TelegramMessageLike>,
+    ) =>
+      await withTelegramThreadFallback(
         mediaParams,
-        "animation",
-        async (effectiveParams, label) =>
-          requestWithDiag(
-            () =>
-              api.sendAnimation(
+        label,
+        opts.verbose,
+        async (effectiveParams, retryLabel) =>
+          requestWithChatNotFound(() => sender(effectiveParams), retryLabel),
+      );
+
+    const mediaSender = (() => {
+      if (isGif) {
+        return {
+          label: "animation",
+          sender: (effectiveParams: Record<string, unknown> | undefined) =>
+            api.sendAnimation(
+              chatId,
+              file,
+              effectiveParams as Parameters<typeof api.sendAnimation>[2],
+            ) as Promise<TelegramMessageLike>,
+        };
+      }
+      if (kind === "image") {
+        return {
+          label: "photo",
+          sender: (effectiveParams: Record<string, unknown> | undefined) =>
+            api.sendPhoto(
+              chatId,
+              file,
+              effectiveParams as Parameters<typeof api.sendPhoto>[2],
+            ) as Promise<TelegramMessageLike>,
+        };
+      }
+      if (kind === "video") {
+        if (isVideoNote) {
+          return {
+            label: "video_note",
+            sender: (effectiveParams: Record<string, unknown> | undefined) =>
+              api.sendVideoNote(
                 chatId,
                 file,
-                effectiveParams as Parameters<typeof api.sendAnimation>[2],
-              ),
-            label,
-          ).catch((err) => {
-            throw wrapChatNotFound(err);
-          }),
-      );
-    } else if (kind === "image") {
-      result = await sendWithThreadFallback(mediaParams, "photo", async (effectiveParams, label) =>
-        requestWithDiag(
-          () => api.sendPhoto(chatId, file, effectiveParams as Parameters<typeof api.sendPhoto>[2]),
-          label,
-        ).catch((err) => {
-          throw wrapChatNotFound(err);
-        }),
-      );
-    } else if (kind === "video") {
-      if (isVideoNote) {
-        result = await sendWithThreadFallback(
-          mediaParams,
-          "video_note",
-          async (effectiveParams, label) =>
-            requestWithDiag(
-              () =>
-                api.sendVideoNote(
-                  chatId,
-                  file,
-                  effectiveParams as Parameters<typeof api.sendVideoNote>[2],
-                ),
-              label,
-            ).catch((err) => {
-              throw wrapChatNotFound(err);
-            }),
-        );
-      } else {
-        result = await sendWithThreadFallback(
-          mediaParams,
-          "video",
-          async (effectiveParams, label) =>
-            requestWithDiag(
-              () =>
-                api.sendVideo(chatId, file, effectiveParams as Parameters<typeof api.sendVideo>[2]),
-              label,
-            ).catch((err) => {
-              throw wrapChatNotFound(err);
-            }),
-        );
+                effectiveParams as Parameters<typeof api.sendVideoNote>[2],
+              ) as Promise<TelegramMessageLike>,
+          };
+        }
+        return {
+          label: "video",
+          sender: (effectiveParams: Record<string, unknown> | undefined) =>
+            api.sendVideo(
+              chatId,
+              file,
+              effectiveParams as Parameters<typeof api.sendVideo>[2],
+            ) as Promise<TelegramMessageLike>,
+        };
       }
-    } else if (kind === "audio") {
-      const { useVoice } = resolveTelegramVoiceSend({
-        wantsVoice: opts.asVoice === true, // default false (backward compatible)
-        contentType: media.contentType,
-        fileName,
-        logFallback: logVerbose,
-      });
-      if (useVoice) {
-        result = await sendWithThreadFallback(
-          mediaParams,
-          "voice",
-          async (effectiveParams, label) =>
-            requestWithDiag(
-              () =>
-                api.sendVoice(chatId, file, effectiveParams as Parameters<typeof api.sendVoice>[2]),
-              label,
-            ).catch((err) => {
-              throw wrapChatNotFound(err);
-            }),
-        );
-      } else {
-        result = await sendWithThreadFallback(
-          mediaParams,
-          "audio",
-          async (effectiveParams, label) =>
-            requestWithDiag(
-              () =>
-                api.sendAudio(chatId, file, effectiveParams as Parameters<typeof api.sendAudio>[2]),
-              label,
-            ).catch((err) => {
-              throw wrapChatNotFound(err);
-            }),
-        );
-      }
-    } else {
-      result = await sendWithThreadFallback(
-        mediaParams,
-        "document",
-        async (effectiveParams, label) =>
-          requestWithDiag(
-            () =>
-              api.sendDocument(
+      if (kind === "audio") {
+        const { useVoice } = resolveTelegramVoiceSend({
+          wantsVoice: opts.asVoice === true, // default false (backward compatible)
+          contentType: media.contentType,
+          fileName,
+          logFallback: logVerbose,
+        });
+        if (useVoice) {
+          return {
+            label: "voice",
+            sender: (effectiveParams: Record<string, unknown> | undefined) =>
+              api.sendVoice(
                 chatId,
                 file,
-                effectiveParams as Parameters<typeof api.sendDocument>[2],
-              ),
-            label,
-          ).catch((err) => {
-            throw wrapChatNotFound(err);
-          }),
-      );
-    }
+                effectiveParams as Parameters<typeof api.sendVoice>[2],
+              ) as Promise<TelegramMessageLike>,
+          };
+        }
+        return {
+          label: "audio",
+          sender: (effectiveParams: Record<string, unknown> | undefined) =>
+            api.sendAudio(
+              chatId,
+              file,
+              effectiveParams as Parameters<typeof api.sendAudio>[2],
+            ) as Promise<TelegramMessageLike>,
+        };
+      }
+      return {
+        label: "document",
+        sender: (effectiveParams: Record<string, unknown> | undefined) =>
+          api.sendDocument(
+            chatId,
+            file,
+            effectiveParams as Parameters<typeof api.sendDocument>[2],
+          ) as Promise<TelegramMessageLike>,
+      };
+    })();
+
+    const result = await sendMedia(mediaSender.label, mediaSender.sender);
     const mediaMessageId = String(result?.message_id ?? "unknown");
     const resolvedChatId = String(result?.chat?.id ?? chatId);
     if (result?.message_id) {
@@ -602,31 +707,16 @@ export async function reactMessageTelegram(
   emoji: string,
   opts: TelegramReactionOpts = {},
 ): Promise<{ ok: true } | { ok: false; warning: string }> {
-  const cfg = loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const token = resolveToken(opts.token, account);
+  const { cfg, account, api } = resolveTelegramApiContext(opts);
   const chatId = normalizeChatId(String(chatIdInput));
   const messageId = normalizeMessageId(messageIdInput);
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
     shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    withTelegramApiErrorLogging({
-      operation: label ?? "request",
-      fn: () => request(fn, label),
-    }).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
   const remove = opts.remove === true;
   const trimmedEmoji = emoji.trim();
   // Build the reaction array. We cast emoji to the grammY union type since
@@ -663,31 +753,16 @@ export async function deleteMessageTelegram(
   messageIdInput: string | number,
   opts: TelegramDeleteOpts = {},
 ): Promise<{ ok: true }> {
-  const cfg = loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const token = resolveToken(opts.token, account);
+  const { cfg, account, api } = resolveTelegramApiContext(opts);
   const chatId = normalizeChatId(String(chatIdInput));
   const messageId = normalizeMessageId(messageIdInput);
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
     shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    withTelegramApiErrorLogging({
-      operation: label ?? "request",
-      fn: () => request(fn, label),
-    }).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
   await requestWithDiag(() => api.deleteMessage(chatId, messageId), "deleteMessage");
   logVerbose(`[telegram] Deleted message ${messageId} from chat ${chatId}`);
   return { ok: true };
@@ -714,30 +789,23 @@ export async function editMessageTelegram(
   text: string,
   opts: TelegramEditOpts = {},
 ): Promise<{ ok: true; messageId: string; chatId: string }> {
-  const cfg = opts.cfg ?? loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
+  const { cfg, account, api } = resolveTelegramApiContext({
+    ...opts,
+    cfg: opts.cfg,
   });
-  const token = resolveToken(opts.token, account);
   const chatId = normalizeChatId(String(chatIdInput));
   const messageId = normalizeMessageId(messageIdInput);
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    withTelegramApiErrorLogging({
-      operation: label ?? "request",
-      fn: () => request(fn, label),
-    }).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
+  const requestWithEditShouldLog = <T>(
+    fn: () => Promise<T>,
+    label?: string,
+    shouldLog?: (err: unknown) => boolean,
+  ) => requestWithDiag(fn, label, shouldLog ? { shouldLog } : undefined);
 
   const textMode = opts.textMode ?? "markdown";
   const tableMode = resolveMarkdownTableMode({
@@ -764,34 +832,41 @@ export async function editMessageTelegram(
   if (replyMarkup !== undefined) {
     editParams.reply_markup = replyMarkup;
   }
+  const plainParams: Record<string, unknown> = {};
+  if (opts.linkPreview === false) {
+    plainParams.link_preview_options = { is_disabled: true };
+  }
+  if (replyMarkup !== undefined) {
+    plainParams.reply_markup = replyMarkup;
+  }
 
-  await requestWithDiag(
-    () => api.editMessageText(chatId, messageId, htmlText, editParams),
-    "editMessage",
-  ).catch(async (err) => {
-    // Telegram rejects malformed HTML. Fall back to plain text.
-    const errText = formatErrorMessage(err);
-    if (PARSE_ERR_RE.test(errText)) {
-      if (opts.verbose) {
-        console.warn(`telegram HTML parse failed, retrying as plain text: ${errText}`);
-      }
-      const plainParams: Record<string, unknown> = {};
-      if (opts.linkPreview === false) {
-        plainParams.link_preview_options = { is_disabled: true };
-      }
-      if (replyMarkup !== undefined) {
-        plainParams.reply_markup = replyMarkup;
-      }
-      return await requestWithDiag(
-        () =>
-          Object.keys(plainParams).length > 0
-            ? api.editMessageText(chatId, messageId, text, plainParams)
-            : api.editMessageText(chatId, messageId, text),
-        "editMessage-plain",
-      );
+  try {
+    await withTelegramHtmlParseFallback({
+      label: "editMessage",
+      verbose: opts.verbose,
+      requestHtml: (retryLabel) =>
+        requestWithEditShouldLog(
+          () => api.editMessageText(chatId, messageId, htmlText, editParams),
+          retryLabel,
+          (err) => !isTelegramMessageNotModifiedError(err),
+        ),
+      requestPlain: (retryLabel) =>
+        requestWithEditShouldLog(
+          () =>
+            Object.keys(plainParams).length > 0
+              ? api.editMessageText(chatId, messageId, text, plainParams)
+              : api.editMessageText(chatId, messageId, text),
+          retryLabel,
+          (plainErr) => !isTelegramMessageNotModifiedError(plainErr),
+        ),
+    });
+  } catch (err) {
+    if (isTelegramMessageNotModifiedError(err)) {
+      // no-op: Telegram reports message content unchanged, treat as success
+    } else {
+      throw err;
     }
-    throw err;
-  });
+  }
 
   logVerbose(`[telegram] Edited message ${messageId} in chat ${chatId}`);
   return { ok: true, messageId: String(messageId), chatId };
@@ -837,90 +912,38 @@ export async function sendStickerTelegram(
     throw new Error("Telegram sticker file_id is required");
   }
 
-  const cfg = loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const token = resolveToken(opts.token, account);
+  const { cfg, account, api } = resolveTelegramApiContext(opts);
   const target = parseTelegramTarget(to);
   const chatId = normalizeChatId(target.chatId);
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
 
-  const messageThreadId =
-    opts.messageThreadId != null ? opts.messageThreadId : target.messageThreadId;
-  const threadSpec =
-    messageThreadId != null ? { id: messageThreadId, scope: "forum" as const } : undefined;
-  const threadIdParams = buildTelegramThreadParams(threadSpec);
-  const threadParams: Record<string, number> = threadIdParams ? { ...threadIdParams } : {};
-  if (opts.replyToMessageId != null) {
-    threadParams.reply_to_message_id = Math.trunc(opts.replyToMessageId);
-  }
+  const threadParams = buildTelegramThreadReplyParams({
+    targetMessageThreadId: target.messageThreadId,
+    messageThreadId: opts.messageThreadId,
+    replyToMessageId: opts.replyToMessageId,
+  });
   const hasThreadParams = Object.keys(threadParams).length > 0;
 
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
+    useApiErrorLogging: false,
+  });
+  const requestWithChatNotFound = createRequestWithChatNotFound({
+    requestWithDiag,
+    chatId,
+    input: to,
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    request(fn, label).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
-
-  const wrapChatNotFound = (err: unknown) => {
-    if (!/400: Bad Request: chat not found/i.test(formatErrorMessage(err))) {
-      return err;
-    }
-    return new Error(
-      [
-        `Telegram send failed: chat not found (chat_id=${chatId}).`,
-        "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
-        `Input was: ${JSON.stringify(to)}.`,
-      ].join(" "),
-    );
-  };
-
-  const sendWithThreadFallback = async <T>(
-    params: Record<string, number> | undefined,
-    label: string,
-    attempt: (
-      effectiveParams: Record<string, number> | undefined,
-      effectiveLabel: string,
-    ) => Promise<T>,
-  ): Promise<T> => {
-    try {
-      return await attempt(params, label);
-    } catch (err) {
-      if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
-        throw err;
-      }
-      if (opts.verbose) {
-        console.warn(
-          `telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`,
-        );
-      }
-      const retriedParams = removeMessageThreadIdParam(params) as
-        | Record<string, number>
-        | undefined;
-      return await attempt(retriedParams, `${label}-threadless`);
-    }
-  };
 
   const stickerParams = hasThreadParams ? threadParams : undefined;
 
-  const result = await sendWithThreadFallback(
+  const result = await withTelegramThreadFallback(
     stickerParams,
     "sticker",
+    opts.verbose,
     async (effectiveParams, label) =>
-      requestWithDiag(() => api.sendSticker(chatId, fileId.trim(), effectiveParams), label).catch(
-        (err) => {
-          throw wrapChatNotFound(err);
-        },
-      ),
+      requestWithChatNotFound(() => api.sendSticker(chatId, fileId.trim(), effectiveParams), label),
   );
 
   const messageId = String(result?.message_id ?? "unknown");
@@ -964,81 +987,34 @@ export async function sendPollTelegram(
   poll: PollInput,
   opts: TelegramPollOpts = {},
 ): Promise<{ messageId: string; chatId: string; pollId?: string }> {
-  const cfg = loadConfig();
-  const account = resolveTelegramAccount({
-    cfg,
-    accountId: opts.accountId,
-  });
-  const token = resolveToken(opts.token, account);
+  const { cfg, account, api } = resolveTelegramApiContext(opts);
   const target = parseTelegramTarget(to);
   const chatId = normalizeChatId(target.chatId);
-  const client = resolveTelegramClientOptions(account);
-  const api = opts.api ?? new Bot(token, client ? { client } : undefined).api;
 
   // Normalize the poll input (validates question, options, maxSelections)
   const normalizedPoll = normalizePollInput(poll, { maxOptions: 10 });
 
-  const messageThreadId =
-    opts.messageThreadId != null ? opts.messageThreadId : target.messageThreadId;
-  const threadSpec =
-    messageThreadId != null ? { id: messageThreadId, scope: "forum" as const } : undefined;
-  const threadIdParams = buildTelegramThreadParams(threadSpec);
+  const threadParams = buildTelegramThreadReplyParams({
+    targetMessageThreadId: target.messageThreadId,
+    messageThreadId: opts.messageThreadId,
+    replyToMessageId: opts.replyToMessageId,
+  });
 
   // Build poll options as simple strings (Grammy accepts string[] or InputPollOption[])
   const pollOptions = normalizedPoll.options;
 
-  const request = createTelegramRetryRunner({
+  const requestWithDiag = createTelegramRequestWithDiag({
+    cfg,
+    account,
     retry: opts.retry,
-    configRetry: account.config.retry,
     verbose: opts.verbose,
     shouldRetry: (err) => isRecoverableTelegramNetworkError(err, { context: "send" }),
   });
-  const logHttpError = createTelegramHttpLogger(cfg);
-  const requestWithDiag = <T>(fn: () => Promise<T>, label?: string) =>
-    withTelegramApiErrorLogging({
-      operation: label ?? "request",
-      fn: () => request(fn, label),
-    }).catch((err) => {
-      logHttpError(label ?? "request", err);
-      throw err;
-    });
-
-  const wrapChatNotFound = (err: unknown) => {
-    if (!/400: Bad Request: chat not found/i.test(formatErrorMessage(err))) {
-      return err;
-    }
-    return new Error(
-      [
-        `Telegram send failed: chat not found (chat_id=${chatId}).`,
-        "Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",
-        `Input was: ${JSON.stringify(to)}.`,
-      ].join(" "),
-    );
-  };
-
-  const sendWithThreadFallback = async <T>(
-    params: Record<string, unknown> | undefined,
-    label: string,
-    attempt: (
-      effectiveParams: Record<string, unknown> | undefined,
-      effectiveLabel: string,
-    ) => Promise<T>,
-  ): Promise<T> => {
-    try {
-      return await attempt(params, label);
-    } catch (err) {
-      if (!hasMessageThreadIdParam(params) || !isTelegramThreadNotFoundError(err)) {
-        throw err;
-      }
-      if (opts.verbose) {
-        console.warn(
-          `telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`,
-        );
-      }
-      const retriedParams = removeMessageThreadIdParam(params);
-      return await attempt(retriedParams, `${label}-threadless`);
-    }
-  };
+  const requestWithChatNotFound = createRequestWithChatNotFound({
+    requestWithDiag,
+    chatId,
+    input: to,
+  });
 
   const durationSeconds = normalizedPoll.durationSeconds;
   if (durationSeconds === undefined && normalizedPoll.durationHours !== undefined) {
@@ -1056,20 +1032,19 @@ export async function sendPollTelegram(
     allows_multiple_answers: normalizedPoll.maxSelections > 1,
     is_anonymous: opts.isAnonymous ?? true,
     ...(durationSeconds !== undefined ? { open_period: durationSeconds } : {}),
-    ...(threadIdParams ? threadIdParams : {}),
-    ...(opts.replyToMessageId != null
-      ? { reply_to_message_id: Math.trunc(opts.replyToMessageId) }
-      : {}),
+    ...(Object.keys(threadParams).length > 0 ? threadParams : {}),
     ...(opts.silent === true ? { disable_notification: true } : {}),
   };
 
-  const result = await sendWithThreadFallback(pollParams, "poll", async (effectiveParams, label) =>
-    requestWithDiag(
-      () => api.sendPoll(chatId, normalizedPoll.question, pollOptions, effectiveParams),
-      label,
-    ).catch((err) => {
-      throw wrapChatNotFound(err);
-    }),
+  const result = await withTelegramThreadFallback(
+    pollParams,
+    "poll",
+    opts.verbose,
+    async (effectiveParams, label) =>
+      requestWithChatNotFound(
+        () => api.sendPoll(chatId, normalizedPoll.question, pollOptions, effectiveParams),
+        label,
+      ),
   );
 
   const messageId = String(result?.message_id ?? "unknown");
diff --git a/src/telegram/send.video-note.test.ts b/src/telegram/send.video-note.test.ts
deleted file mode 100644
index 6924bad2170..00000000000
--- a/src/telegram/send.video-note.test.ts
+++ /dev/null
@@ -1,174 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import {
-  getTelegramSendTestMocks,
-  importTelegramSendModule,
-  installTelegramSendTestHooks,
-} from "./send.test-harness.js";
-
-installTelegramSendTestHooks();
-
-const { loadWebMedia } = getTelegramSendTestMocks();
-const { sendMessageTelegram } = await importTelegramSendModule();
-
-describe("sendMessageTelegram video notes", () => {
-  it("sends video as video note when asVideoNote is true", async () => {
-    const chatId = "123";
-    const text = "ignored caption context"; // Should be sent separately
-
-    const sendVideoNote = vi.fn().mockResolvedValue({
-      message_id: 101,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 102,
-      chat: { id: chatId },
-    });
-    const api = { sendVideoNote, sendMessage } as unknown as {
-      sendVideoNote: typeof sendVideoNote;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-video"),
-      contentType: "video/mp4",
-      fileName: "video.mp4",
-    });
-
-    const res = await sendMessageTelegram(chatId, text, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/video.mp4",
-      asVideoNote: true,
-    });
-
-    // Video note sent WITHOUT caption (video notes cannot have captions)
-    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {});
-
-    // Text sent as separate message
-    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
-      parse_mode: "HTML",
-    });
-
-    // Returns the text message ID as it is the "main" content with text
-    expect(res.messageId).toBe("102");
-  });
-
-  it("sends regular video when asVideoNote is false", async () => {
-    const chatId = "123";
-    const text = "my caption";
-
-    const sendVideo = vi.fn().mockResolvedValue({
-      message_id: 201,
-      chat: { id: chatId },
-    });
-    const api = { sendVideo } as unknown as {
-      sendVideo: typeof sendVideo;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-video"),
-      contentType: "video/mp4",
-      fileName: "video.mp4",
-    });
-
-    const res = await sendMessageTelegram(chatId, text, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/video.mp4",
-      asVideoNote: false,
-    });
-
-    // Regular video sent WITH caption
-    expect(sendVideo).toHaveBeenCalledWith(chatId, expect.anything(), {
-      caption: expect.any(String),
-      parse_mode: "HTML",
-    });
-    expect(res.messageId).toBe("201");
-  });
-
-  it("adds reply_markup to separate text message for video notes", async () => {
-    const chatId = "123";
-    const text = "Check this out";
-
-    const sendVideoNote = vi.fn().mockResolvedValue({
-      message_id: 301,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 302,
-      chat: { id: chatId },
-    });
-    const api = { sendVideoNote, sendMessage } as unknown as {
-      sendVideoNote: typeof sendVideoNote;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-video"),
-      contentType: "video/mp4",
-      fileName: "video.mp4",
-    });
-
-    await sendMessageTelegram(chatId, text, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/video.mp4",
-      asVideoNote: true,
-      buttons: [[{ text: "Btn", callback_data: "dat" }]],
-    });
-
-    // Video note sent WITHOUT reply_markup (it goes to text)
-    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {});
-
-    // Text message gets reply markup
-    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
-      parse_mode: "HTML",
-      reply_markup: {
-        inline_keyboard: [[{ text: "Btn", callback_data: "dat" }]],
-      },
-    });
-  });
-
-  it("threads video note and text message correctly", async () => {
-    const chatId = "123";
-    const text = "Threaded reply";
-
-    const sendVideoNote = vi.fn().mockResolvedValue({
-      message_id: 401,
-      chat: { id: chatId },
-    });
-    const sendMessage = vi.fn().mockResolvedValue({
-      message_id: 402,
-      chat: { id: chatId },
-    });
-    const api = { sendVideoNote, sendMessage } as unknown as {
-      sendVideoNote: typeof sendVideoNote;
-      sendMessage: typeof sendMessage;
-    };
-
-    loadWebMedia.mockResolvedValueOnce({
-      buffer: Buffer.from("fake-video"),
-      contentType: "video/mp4",
-      fileName: "video.mp4",
-    });
-
-    await sendMessageTelegram(chatId, text, {
-      token: "tok",
-      api,
-      mediaUrl: "https://example.com/video.mp4",
-      asVideoNote: true,
-      replyToMessageId: 999,
-    });
-
-    // Video note threaded
-    expect(sendVideoNote).toHaveBeenCalledWith(chatId, expect.anything(), {
-      reply_to_message_id: 999,
-    });
-
-    // Text threaded
-    expect(sendMessage).toHaveBeenCalledWith(chatId, text, {
-      parse_mode: "HTML",
-      reply_to_message_id: 999,
-    });
-  });
-});
diff --git a/src/telegram/sent-message-cache.test.ts b/src/telegram/sent-message-cache.test.ts
deleted file mode 100644
index 054d9b2fc8f..00000000000
--- a/src/telegram/sent-message-cache.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { clearSentMessageCache, recordSentMessage, wasSentByBot } from "./sent-message-cache.js";
-
-describe("sent-message-cache", () => {
-  afterEach(() => {
-    clearSentMessageCache();
-  });
-
-  it("records and retrieves sent messages", () => {
-    recordSentMessage(123, 1);
-    recordSentMessage(123, 2);
-    recordSentMessage(456, 10);
-
-    expect(wasSentByBot(123, 1)).toBe(true);
-    expect(wasSentByBot(123, 2)).toBe(true);
-    expect(wasSentByBot(456, 10)).toBe(true);
-    expect(wasSentByBot(123, 3)).toBe(false);
-    expect(wasSentByBot(789, 1)).toBe(false);
-  });
-
-  it("handles string chat IDs", () => {
-    recordSentMessage("123", 1);
-    expect(wasSentByBot("123", 1)).toBe(true);
-    expect(wasSentByBot(123, 1)).toBe(true);
-  });
-
-  it("clears cache", () => {
-    recordSentMessage(123, 1);
-    expect(wasSentByBot(123, 1)).toBe(true);
-
-    clearSentMessageCache();
-    expect(wasSentByBot(123, 1)).toBe(false);
-  });
-});
diff --git a/src/telegram/targets.test.ts b/src/telegram/targets.test.ts
index e25e38b2c3c..51d34206c6d 100644
--- a/src/telegram/targets.test.ts
+++ b/src/telegram/targets.test.ts
@@ -23,12 +23,14 @@ describe("parseTelegramTarget", () => {
   it("parses plain chatId", () => {
     expect(parseTelegramTarget("-1001234567890")).toEqual({
       chatId: "-1001234567890",
+      chatType: "group",
     });
   });
 
   it("parses @username", () => {
     expect(parseTelegramTarget("@mychannel")).toEqual({
       chatId: "@mychannel",
+      chatType: "unknown",
     });
   });
 
@@ -36,6 +38,7 @@ describe("parseTelegramTarget", () => {
     expect(parseTelegramTarget("-1001234567890:123")).toEqual({
       chatId: "-1001234567890",
       messageThreadId: 123,
+      chatType: "group",
     });
   });
 
@@ -43,6 +46,7 @@ describe("parseTelegramTarget", () => {
     expect(parseTelegramTarget("-1001234567890:topic:456")).toEqual({
       chatId: "-1001234567890",
       messageThreadId: 456,
+      chatType: "group",
     });
   });
 
@@ -50,12 +54,14 @@ describe("parseTelegramTarget", () => {
     expect(parseTelegramTarget("  -1001234567890:99  ")).toEqual({
       chatId: "-1001234567890",
       messageThreadId: 99,
+      chatType: "group",
     });
   });
 
   it("does not treat non-numeric suffix as topicId", () => {
     expect(parseTelegramTarget("-1001234567890:abc")).toEqual({
       chatId: "-1001234567890:abc",
+      chatType: "unknown",
     });
   });
 
@@ -63,6 +69,7 @@ describe("parseTelegramTarget", () => {
     expect(parseTelegramTarget("telegram:group:-1001234567890:topic:456")).toEqual({
       chatId: "-1001234567890",
       messageThreadId: 456,
+      chatType: "group",
     });
   });
 });
diff --git a/src/telegram/targets.ts b/src/telegram/targets.ts
index cb26c0d06b3..346bb3e35c5 100644
--- a/src/telegram/targets.ts
+++ b/src/telegram/targets.ts
@@ -1,6 +1,7 @@
 export type TelegramTarget = {
   chatId: string;
   messageThreadId?: number;
+  chatType: "direct" | "group" | "unknown";
 };
 
 export function stripTelegramInternalPrefixes(to: string): string {
@@ -33,6 +34,17 @@ export function stripTelegramInternalPrefixes(to: string): string {
  * - `chatId:topicId` (numeric topic/thread ID)
  * - `chatId:topic:topicId` (explicit topic marker; preferred)
  */
+function resolveTelegramChatType(chatId: string): "direct" | "group" | "unknown" {
+  const trimmed = chatId.trim();
+  if (!trimmed) {
+    return "unknown";
+  }
+  if (/^-?\d+$/.test(trimmed)) {
+    return trimmed.startsWith("-") ? "group" : "direct";
+  }
+  return "unknown";
+}
+
 export function parseTelegramTarget(to: string): TelegramTarget {
   const normalized = stripTelegramInternalPrefixes(to);
 
@@ -41,6 +53,7 @@ export function parseTelegramTarget(to: string): TelegramTarget {
     return {
       chatId: topicMatch[1],
       messageThreadId: Number.parseInt(topicMatch[2], 10),
+      chatType: resolveTelegramChatType(topicMatch[1]),
     };
   }
 
@@ -49,8 +62,16 @@ export function parseTelegramTarget(to: string): TelegramTarget {
     return {
       chatId: colonMatch[1],
       messageThreadId: Number.parseInt(colonMatch[2], 10),
+      chatType: resolveTelegramChatType(colonMatch[1]),
     };
   }
 
-  return { chatId: normalized };
+  return {
+    chatId: normalized,
+    chatType: resolveTelegramChatType(normalized),
+  };
+}
+
+export function resolveTelegramTargetChatType(target: string): "direct" | "group" | "unknown" {
+  return parseTelegramTarget(target).chatType;
 }
diff --git a/src/telegram/token.test.ts b/src/telegram/token.test.ts
index ad5a389ddcc..34b06ca1d44 100644
--- a/src/telegram/token.test.ts
+++ b/src/telegram/token.test.ts
@@ -1,14 +1,32 @@
 import fs from "node:fs";
+import fsPromises from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveTelegramToken } from "./token.js";
+import { readTelegramUpdateOffset, writeTelegramUpdateOffset } from "./update-offset-store.js";
 
 function withTempDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-telegram-token-"));
 }
 
+async function withTempStateDir<T>(fn: (dir: string) => Promise<T>) {
+  const previous = process.env.OPENCLAW_STATE_DIR;
+  const dir = await fsPromises.mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-"));
+  process.env.OPENCLAW_STATE_DIR = dir;
+  try {
+    return await fn(dir);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previous;
+    }
+    await fsPromises.rm(dir, { recursive: true, force: true });
+  }
+}
+
 describe("resolveTelegramToken", () => {
   afterEach(() => {
     vi.unstubAllEnvs();
@@ -87,3 +105,18 @@ describe("resolveTelegramToken", () => {
     expect(res.source).toBe("config");
   });
 });
+
+describe("telegram update offset store", () => {
+  it("persists and reloads the last update id", async () => {
+    await withTempStateDir(async () => {
+      expect(await readTelegramUpdateOffset({ accountId: "primary" })).toBeNull();
+
+      await writeTelegramUpdateOffset({
+        accountId: "primary",
+        updateId: 421,
+      });
+
+      expect(await readTelegramUpdateOffset({ accountId: "primary" })).toBe(421);
+    });
+  });
+});
diff --git a/src/telegram/token.ts b/src/telegram/token.ts
index ed11d3f7476..461fcf5259c 100644
--- a/src/telegram/token.ts
+++ b/src/telegram/token.ts
@@ -1,12 +1,12 @@
 import fs from "node:fs";
+import type { BaseTokenResolution } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 import type { TelegramAccountConfig } from "../config/types.telegram.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
 
 export type TelegramTokenSource = "env" | "tokenFile" | "config" | "none";
 
-export type TelegramTokenResolution = {
-  token: string;
+export type TelegramTokenResolution = BaseTokenResolution & {
   source: TelegramTokenSource;
 };
 
diff --git a/src/telegram/update-offset-store.test.ts b/src/telegram/update-offset-store.test.ts
deleted file mode 100644
index 4e3f5d9a3b5..00000000000
--- a/src/telegram/update-offset-store.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { readTelegramUpdateOffset, writeTelegramUpdateOffset } from "./update-offset-store.js";
-
-async function withTempStateDir<T>(fn: (dir: string) => Promise<T>) {
-  const previous = process.env.OPENCLAW_STATE_DIR;
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-telegram-"));
-  process.env.OPENCLAW_STATE_DIR = dir;
-  try {
-    return await fn(dir);
-  } finally {
-    if (previous === undefined) {
-      delete process.env.OPENCLAW_STATE_DIR;
-    } else {
-      process.env.OPENCLAW_STATE_DIR = previous;
-    }
-    await fs.rm(dir, { recursive: true, force: true });
-  }
-}
-
-describe("telegram update offset store", () => {
-  it("persists and reloads the last update id", async () => {
-    await withTempStateDir(async () => {
-      expect(await readTelegramUpdateOffset({ accountId: "primary" })).toBeNull();
-
-      await writeTelegramUpdateOffset({
-        accountId: "primary",
-        updateId: 421,
-      });
-
-      expect(await readTelegramUpdateOffset({ accountId: "primary" })).toBe(421);
-    });
-  });
-});
diff --git a/src/telegram/webhook-set.ts b/src/telegram/webhook-set.ts
deleted file mode 100644
index 1bee5248526..00000000000
--- a/src/telegram/webhook-set.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { type ApiClientOptions, Bot } from "grammy";
-import type { TelegramNetworkConfig } from "../config/types.telegram.js";
-import { withTelegramApiErrorLogging } from "./api-logging.js";
-import { resolveTelegramFetch } from "./fetch.js";
-
-export async function setTelegramWebhook(opts: {
-  token: string;
-  url: string;
-  secret?: string;
-  dropPendingUpdates?: boolean;
-  network?: TelegramNetworkConfig;
-}) {
-  const fetchImpl = resolveTelegramFetch(undefined, { network: opts.network });
-  const client: ApiClientOptions | undefined = fetchImpl
-    ? { fetch: fetchImpl as unknown as ApiClientOptions["fetch"] }
-    : undefined;
-  const bot = new Bot(opts.token, client ? { client } : undefined);
-  await withTelegramApiErrorLogging({
-    operation: "setWebhook",
-    fn: () =>
-      bot.api.setWebhook(opts.url, {
-        secret_token: opts.secret,
-        drop_pending_updates: opts.dropPendingUpdates ?? false,
-      }),
-  });
-}
-
-export async function deleteTelegramWebhook(opts: {
-  token: string;
-  network?: TelegramNetworkConfig;
-}) {
-  const fetchImpl = resolveTelegramFetch(undefined, { network: opts.network });
-  const client: ApiClientOptions | undefined = fetchImpl
-    ? { fetch: fetchImpl as unknown as ApiClientOptions["fetch"] }
-    : undefined;
-  const bot = new Bot(opts.token, client ? { client } : undefined);
-  await withTelegramApiErrorLogging({
-    operation: "deleteWebhook",
-    fn: () => bot.api.deleteWebhook(),
-  });
-}
diff --git a/src/terminal/note.ts b/src/terminal/note.ts
index 48bca06fecd..e1dc5717f1a 100644
--- a/src/terminal/note.ts
+++ b/src/terminal/note.ts
@@ -2,6 +2,10 @@ import { note as clackNote } from "@clack/prompts";
 import { visibleWidth } from "./ansi.js";
 import { stylePromptTitle } from "./prompt-style.js";
 
+const URL_PREFIX_RE = /^(https?:\/\/|file:\/\/)/i;
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+const FILE_LIKE_RE = /^[a-zA-Z0-9._-]+$/;
+
 function splitLongWord(word: string, maxLen: number): string[] {
   if (maxLen <= 0) {
     return [word];
@@ -14,6 +18,31 @@ function splitLongWord(word: string, maxLen: number): string[] {
   return parts.length > 0 ? parts : [word];
 }
 
+function isCopySensitiveToken(word: string): boolean {
+  if (!word) {
+    return false;
+  }
+  if (URL_PREFIX_RE.test(word)) {
+    return true;
+  }
+  if (
+    word.startsWith("/") ||
+    word.startsWith("~/") ||
+    word.startsWith("./") ||
+    word.startsWith("../")
+  ) {
+    return true;
+  }
+  if (WINDOWS_DRIVE_RE.test(word) || word.startsWith("\\\\")) {
+    return true;
+  }
+  if (word.includes("/") || word.includes("\\")) {
+    return true;
+  }
+  // Preserve common file-like tokens (for example administrators_authorized_keys).
+  return word.includes("_") && FILE_LIKE_RE.test(word);
+}
+
 function wrapLine(line: string, maxWidth: number): string[] {
   if (line.trim().length === 0) {
     return [line];
@@ -36,6 +65,10 @@ function wrapLine(line: string, maxWidth: number): string[] {
   for (const word of words) {
     if (!current) {
       if (visibleWidth(word) > available) {
+        if (isCopySensitiveToken(word)) {
+          current = word;
+          continue;
+        }
         const parts = splitLongWord(word, available);
         const first = parts.shift() ?? "";
         lines.push(prefix + first);
@@ -61,6 +94,10 @@ function wrapLine(line: string, maxWidth: number): string[] {
     available = nextWidth;
 
     if (visibleWidth(word) > available) {
+      if (isCopySensitiveToken(word)) {
+        current = word;
+        continue;
+      }
       const parts = splitLongWord(word, available);
       const first = parts.shift() ?? "";
       lines.push(prefix + first);
diff --git a/src/terminal/restore.test.ts b/src/terminal/restore.test.ts
index 5f79f2732a7..deaa8e74c0a 100644
--- a/src/terminal/restore.test.ts
+++ b/src/terminal/restore.test.ts
@@ -8,6 +8,20 @@ vi.mock("./progress-line.js", () => ({
 
 import { restoreTerminalState } from "./restore.js";
 
+function configureTerminalIO(params: {
+  stdinIsTTY: boolean;
+  stdoutIsTTY: boolean;
+  setRawMode?: (mode: boolean) => void;
+  resume?: () => void;
+  isPaused?: () => boolean;
+}) {
+  Object.defineProperty(process.stdin, "isTTY", { value: params.stdinIsTTY, configurable: true });
+  Object.defineProperty(process.stdout, "isTTY", { value: params.stdoutIsTTY, configurable: true });
+  (process.stdin as { setRawMode?: (mode: boolean) => void }).setRawMode = params.setRawMode;
+  (process.stdin as { resume?: () => void }).resume = params.resume;
+  (process.stdin as { isPaused?: () => boolean }).isPaused = params.isPaused;
+}
+
 describe("restoreTerminalState", () => {
   const originalStdinIsTTY = process.stdin.isTTY;
   const originalStdoutIsTTY = process.stdout.isTTY;
@@ -35,11 +49,13 @@ describe("restoreTerminalState", () => {
     const resume = vi.fn();
     const isPaused = vi.fn(() => true);
 
-    Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
-    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
-    (process.stdin as { setRawMode?: (mode: boolean) => void }).setRawMode = setRawMode;
-    (process.stdin as { resume?: () => void }).resume = resume;
-    (process.stdin as { isPaused?: () => boolean }).isPaused = isPaused;
+    configureTerminalIO({
+      stdinIsTTY: true,
+      stdoutIsTTY: false,
+      setRawMode,
+      resume,
+      isPaused,
+    });
 
     restoreTerminalState("test");
 
@@ -52,11 +68,13 @@ describe("restoreTerminalState", () => {
     const resume = vi.fn();
     const isPaused = vi.fn(() => true);
 
-    Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
-    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
-    (process.stdin as { setRawMode?: (mode: boolean) => void }).setRawMode = setRawMode;
-    (process.stdin as { resume?: () => void }).resume = resume;
-    (process.stdin as { isPaused?: () => boolean }).isPaused = isPaused;
+    configureTerminalIO({
+      stdinIsTTY: true,
+      stdoutIsTTY: false,
+      setRawMode,
+      resume,
+      isPaused,
+    });
 
     restoreTerminalState("test", { resumeStdinIfPaused: true });
 
@@ -69,11 +87,13 @@ describe("restoreTerminalState", () => {
     const resume = vi.fn();
     const isPaused = vi.fn(() => true);
 
-    Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });
-    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
-    (process.stdin as { setRawMode?: (mode: boolean) => void }).setRawMode = setRawMode;
-    (process.stdin as { resume?: () => void }).resume = resume;
-    (process.stdin as { isPaused?: () => boolean }).isPaused = isPaused;
+    configureTerminalIO({
+      stdinIsTTY: false,
+      stdoutIsTTY: false,
+      setRawMode,
+      resume,
+      isPaused,
+    });
 
     restoreTerminalState("test", { resumeStdinIfPaused: true });
 
diff --git a/src/terminal/table.test.ts b/src/terminal/table.test.ts
index 3c0d22b35db..f8b34516ca9 100644
--- a/src/terminal/table.test.ts
+++ b/src/terminal/table.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { visibleWidth } from "./ansi.js";
+import { wrapNoteMessage } from "./note.js";
 import { renderTable } from "./table.js";
 
 describe("renderTable", () => {
@@ -130,3 +131,58 @@ describe("renderTable", () => {
     expect(line2Index).toBe(line1Index + 1);
   });
 });
+
+describe("wrapNoteMessage", () => {
+  it("preserves long filesystem paths without inserting spaces/newlines", () => {
+    const input =
+      "/Users/user/Documents/Github/impact-signals-pipeline/with/really/long/segments/file.txt";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 22, columns: 80 });
+
+    expect(wrapped).toBe(input);
+  });
+
+  it("preserves long urls without inserting spaces/newlines", () => {
+    const input =
+      "https://example.com/this/is/a/very/long/url/segment/that/should/not/be/split/for-copy";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 24, columns: 80 });
+
+    expect(wrapped).toBe(input);
+  });
+
+  it("preserves long file-like underscore tokens for copy safety", () => {
+    const input = "administrators_authorized_keys_with_extra_suffix";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 14, columns: 80 });
+
+    expect(wrapped).toBe(input);
+  });
+
+  it("still chunks generic long opaque tokens to avoid pathological line width", () => {
+    const input = "x".repeat(70);
+    const wrapped = wrapNoteMessage(input, { maxWidth: 20, columns: 80 });
+
+    expect(wrapped).toContain("\n");
+    expect(wrapped.replace(/\n/g, "")).toBe(input);
+  });
+
+  it("wraps bullet lines while preserving bullet indentation", () => {
+    const input = "- one two three four five six seven eight nine ten";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 18, columns: 80 });
+    const lines = wrapped.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines[0]?.startsWith("- ")).toBe(true);
+    expect(lines.slice(1).every((line) => line.startsWith("  "))).toBe(true);
+  });
+
+  it("preserves long Windows paths without inserting spaces/newlines", () => {
+    // No spaces: wrapNoteMessage splits on whitespace, so a "Program Files" style path would wrap.
+    const input = "C:\\\\State\\\\OpenClaw\\\\bin\\\\openclaw.exe";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 10, columns: 80 });
+    expect(wrapped).toBe(input);
+  });
+
+  it("preserves UNC paths without inserting spaces/newlines", () => {
+    const input = "\\\\\\\\server\\\\share\\\\some\\\\really\\\\long\\\\path\\\\file.txt";
+    const wrapped = wrapNoteMessage(input, { maxWidth: 12, columns: 80 });
+    expect(wrapped).toBe(input);
+  });
+});
diff --git a/src/test-helpers/state-dir-env.ts b/src/test-helpers/state-dir-env.ts
index 3561c27af77..235cbca1c4e 100644
--- a/src/test-helpers/state-dir-env.ts
+++ b/src/test-helpers/state-dir-env.ts
@@ -1,26 +1,11 @@
-type StateDirEnvSnapshot = {
-  openclawStateDir: string | undefined;
-  clawdbotStateDir: string | undefined;
-};
+import { captureEnv } from "../test-utils/env.js";
 
-export function snapshotStateDirEnv(): StateDirEnvSnapshot {
-  return {
-    openclawStateDir: process.env.OPENCLAW_STATE_DIR,
-    clawdbotStateDir: process.env.CLAWDBOT_STATE_DIR,
-  };
+export function snapshotStateDirEnv() {
+  return captureEnv(["OPENCLAW_STATE_DIR", "CLAWDBOT_STATE_DIR"]);
 }
 
-export function restoreStateDirEnv(snapshot: StateDirEnvSnapshot): void {
-  if (snapshot.openclawStateDir === undefined) {
-    delete process.env.OPENCLAW_STATE_DIR;
-  } else {
-    process.env.OPENCLAW_STATE_DIR = snapshot.openclawStateDir;
-  }
-  if (snapshot.clawdbotStateDir === undefined) {
-    delete process.env.CLAWDBOT_STATE_DIR;
-  } else {
-    process.env.CLAWDBOT_STATE_DIR = snapshot.clawdbotStateDir;
-  }
+export function restoreStateDirEnv(snapshot: ReturnType<typeof snapshotStateDirEnv>): void {
+  snapshot.restore();
 }
 
 export function setStateDirEnv(stateDir: string): void {
diff --git a/src/test-utils/env.ts b/src/test-utils/env.ts
new file mode 100644
index 00000000000..36c9b137fc4
--- /dev/null
+++ b/src/test-utils/env.ts
@@ -0,0 +1,74 @@
+export function captureEnv(keys: string[]) {
+  const snapshot = new Map<string, string | undefined>();
+  for (const key of keys) {
+    snapshot.set(key, process.env[key]);
+  }
+
+  return {
+    restore() {
+      for (const [key, value] of snapshot) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    },
+  };
+}
+
+export function captureFullEnv() {
+  const snapshot: Record<string, string | undefined> = { ...process.env };
+
+  return {
+    restore() {
+      for (const key of Object.keys(process.env)) {
+        if (!(key in snapshot)) {
+          delete process.env[key];
+        }
+      }
+      for (const [key, value] of Object.entries(snapshot)) {
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    },
+  };
+}
+
+export function withEnv<T>(env: Record<string, string | undefined>, fn: () => T): T {
+  const snapshot = captureEnv(Object.keys(env));
+  try {
+    for (const [key, value] of Object.entries(env)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    return fn();
+  } finally {
+    snapshot.restore();
+  }
+}
+
+export async function withEnvAsync<T>(
+  env: Record<string, string | undefined>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const snapshot = captureEnv(Object.keys(env));
+  try {
+    for (const [key, value] of Object.entries(env)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    return await fn();
+  } finally {
+    snapshot.restore();
+  }
+}
diff --git a/src/tts/tts.test.ts b/src/tts/tts.test.ts
index a7fc0daec54..2a134b421b5 100644
--- a/src/tts/tts.test.ts
+++ b/src/tts/tts.test.ts
@@ -2,6 +2,7 @@ import { completeSimple } from "@mariozechner/pi-ai";
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { getApiKeyForModel } from "../agents/model-auth.js";
 import { resolveModel } from "../agents/pi-embedded-runner/model.js";
+import { withEnv } from "../test-utils/env.js";
 import * as tts from "./tts.js";
 
 vi.mock("@mariozechner/pi-ai", () => ({
@@ -367,38 +368,6 @@ describe("tts", () => {
       messages: { tts: {} },
     };
 
-    const restoreEnv = (snapshot: Record<string, string | undefined>) => {
-      const keys = ["OPENAI_API_KEY", "ELEVENLABS_API_KEY", "XI_API_KEY"] as const;
-      for (const key of keys) {
-        const value = snapshot[key];
-        if (value === undefined) {
-          delete process.env[key];
-        } else {
-          process.env[key] = value;
-        }
-      }
-    };
-
-    const withEnv = (env: Record<string, string | undefined>, run: () => void) => {
-      const snapshot = {
-        OPENAI_API_KEY: process.env.OPENAI_API_KEY,
-        ELEVENLABS_API_KEY: process.env.ELEVENLABS_API_KEY,
-        XI_API_KEY: process.env.XI_API_KEY,
-      };
-      try {
-        for (const [key, value] of Object.entries(env)) {
-          if (value === undefined) {
-            delete process.env[key];
-          } else {
-            process.env[key] = value;
-          }
-        }
-        run();
-      } finally {
-        restoreEnv(snapshot);
-      }
-    };
-
     it("prefers OpenAI when no provider is configured and API key exists", () => {
       withEnv(
         {
diff --git a/src/tui/commands.test.ts b/src/tui/commands.test.ts
deleted file mode 100644
index 5bd02b87d9c..00000000000
--- a/src/tui/commands.test.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { getSlashCommands, parseCommand } from "./commands.js";
-
-describe("tui slash commands", () => {
-  it("treats /elev as an alias for /elevated", () => {
-    expect(parseCommand("/elev on")).toEqual({ name: "elevated", args: "on" });
-  });
-
-  it("normalizes alias case", () => {
-    expect(parseCommand("/ELEV off")).toEqual({
-      name: "elevated",
-      args: "off",
-    });
-  });
-
-  it("includes gateway text commands", () => {
-    const commands = getSlashCommands({});
-    expect(commands.some((command) => command.name === "context")).toBe(true);
-    expect(commands.some((command) => command.name === "commands")).toBe(true);
-  });
-});
diff --git a/src/tui/tui-formatters.test.ts b/src/tui/tui-formatters.test.ts
index 7e2a0bbf27a..13368748fec 100644
--- a/src/tui/tui-formatters.test.ts
+++ b/src/tui/tui-formatters.test.ts
@@ -160,4 +160,27 @@ describe("sanitizeRenderableText", () => {
 
     expect(longestSegment).toBeLessThanOrEqual(32);
   });
+
+  it("preserves long filesystem paths verbatim for copy safety", () => {
+    const input =
+      "/Users/jasonshawn/PerfectXiao/a_very_long_directory_name_designed_specifically_to_test_the_line_wrapping_issue/file.txt";
+    const sanitized = sanitizeRenderableText(input);
+
+    expect(sanitized).toBe(input);
+  });
+
+  it("preserves long urls verbatim for copy safety", () => {
+    const input =
+      "https://example.com/this/is/a/very/long/url/segment/that/should/remain/contiguous/when/rendered";
+    const sanitized = sanitizeRenderableText(input);
+
+    expect(sanitized).toBe(input);
+  });
+
+  it("preserves long file-like underscore tokens for copy safety", () => {
+    const input = "administrators_authorized_keys_with_extra_suffix".repeat(2);
+    const sanitized = sanitizeRenderableText(input);
+
+    expect(sanitized).toBe(input);
+  });
 });
diff --git a/src/tui/tui-formatters.ts b/src/tui/tui-formatters.ts
index ff7b7d49c6b..804d8ca4a5b 100644
--- a/src/tui/tui-formatters.ts
+++ b/src/tui/tui-formatters.ts
@@ -7,6 +7,9 @@ const MAX_TOKEN_CHARS = 32;
 const LONG_TOKEN_RE = /\S{33,}/g;
 const LONG_TOKEN_TEST_RE = /\S{33,}/;
 const BINARY_LINE_REPLACEMENT_THRESHOLD = 12;
+const URL_PREFIX_RE = /^(https?:\/\/|file:\/\/)/i;
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+const FILE_LIKE_RE = /^[a-zA-Z0-9._-]+$/;
 
 function hasControlChars(text: string): boolean {
   for (const char of text) {
@@ -47,6 +50,35 @@ function chunkToken(token: string, maxChars: number): string[] {
   return chunks;
 }
 
+function isCopySensitiveToken(token: string): boolean {
+  if (URL_PREFIX_RE.test(token)) {
+    return true;
+  }
+  if (
+    token.startsWith("/") ||
+    token.startsWith("~/") ||
+    token.startsWith("./") ||
+    token.startsWith("../")
+  ) {
+    return true;
+  }
+  if (WINDOWS_DRIVE_RE.test(token) || token.startsWith("\\\\")) {
+    return true;
+  }
+  if (token.includes("/") || token.includes("\\")) {
+    return true;
+  }
+  return token.includes("_") && FILE_LIKE_RE.test(token);
+}
+
+function normalizeLongTokenForDisplay(token: string): string {
+  // Preserve copy-sensitive tokens exactly (paths/urls/file-like names).
+  if (isCopySensitiveToken(token)) {
+    return token;
+  }
+  return chunkToken(token, MAX_TOKEN_CHARS).join(" ");
+}
+
 function redactBinaryLikeLine(line: string): string {
   const replacementCount = (line.match(REPLACEMENT_CHAR_RE) || []).length;
   if (
@@ -80,7 +112,7 @@ export function sanitizeRenderableText(text: string): string {
         .join("\n")
     : withoutControlChars;
   return LONG_TOKEN_TEST_RE.test(redacted)
-    ? redacted.replace(LONG_TOKEN_RE, (token) => chunkToken(token, MAX_TOKEN_CHARS).join(" "))
+    ? redacted.replace(LONG_TOKEN_RE, normalizeLongTokenForDisplay)
     : redacted;
 }
 
diff --git a/src/tui/tui.test.ts b/src/tui/tui.test.ts
index 7ef276526bf..aa60f12109b 100644
--- a/src/tui/tui.test.ts
+++ b/src/tui/tui.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { getSlashCommands, parseCommand } from "./commands.js";
 import { resolveFinalAssistantText, resolveTuiSessionKey } from "./tui.js";
 
 describe("resolveFinalAssistantText", () => {
@@ -16,6 +17,25 @@ describe("resolveFinalAssistantText", () => {
   });
 });
 
+describe("tui slash commands", () => {
+  it("treats /elev as an alias for /elevated", () => {
+    expect(parseCommand("/elev on")).toEqual({ name: "elevated", args: "on" });
+  });
+
+  it("normalizes alias case", () => {
+    expect(parseCommand("/ELEV off")).toEqual({
+      name: "elevated",
+      args: "off",
+    });
+  });
+
+  it("includes gateway text commands", () => {
+    const commands = getSlashCommands({});
+    expect(commands.some((command) => command.name === "context")).toBe(true);
+    expect(commands.some((command) => command.name === "commands")).toBe(true);
+  });
+});
+
 describe("resolveTuiSessionKey", () => {
   it("uses global only as the default when scope is global", () => {
     expect(
diff --git a/src/utils.test.ts b/src/utils.test.ts
index 163470090fe..6c4bf3aceb1 100644
--- a/src/utils.test.ts
+++ b/src/utils.test.ts
@@ -60,6 +60,10 @@ describe("sleep", () => {
 });
 
 describe("assertWebChannel", () => {
+  it("accepts valid channel", () => {
+    expect(() => assertWebChannel("web")).not.toThrow();
+  });
+
   it("throws for invalid channel", () => {
     expect(() => assertWebChannel("bad" as string)).toThrow();
   });
diff --git a/src/utils/boolean.test.ts b/src/utils/boolean.test.ts
deleted file mode 100644
index 04c1dd52f5e..00000000000
--- a/src/utils/boolean.test.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseBooleanValue } from "./boolean.js";
-
-describe("parseBooleanValue", () => {
-  it("handles boolean inputs", () => {
-    expect(parseBooleanValue(true)).toBe(true);
-    expect(parseBooleanValue(false)).toBe(false);
-  });
-
-  it("parses default truthy/falsy strings", () => {
-    expect(parseBooleanValue("true")).toBe(true);
-    expect(parseBooleanValue("1")).toBe(true);
-    expect(parseBooleanValue("yes")).toBe(true);
-    expect(parseBooleanValue("on")).toBe(true);
-    expect(parseBooleanValue("false")).toBe(false);
-    expect(parseBooleanValue("0")).toBe(false);
-    expect(parseBooleanValue("no")).toBe(false);
-    expect(parseBooleanValue("off")).toBe(false);
-  });
-
-  it("respects custom truthy/falsy lists", () => {
-    expect(
-      parseBooleanValue("on", {
-        truthy: ["true"],
-        falsy: ["false"],
-      }),
-    ).toBeUndefined();
-    expect(
-      parseBooleanValue("yes", {
-        truthy: ["yes"],
-        falsy: ["no"],
-      }),
-    ).toBe(true);
-  });
-
-  it("returns undefined for unsupported values", () => {
-    expect(parseBooleanValue("")).toBeUndefined();
-    expect(parseBooleanValue("maybe")).toBeUndefined();
-    expect(parseBooleanValue(1)).toBeUndefined();
-  });
-});
diff --git a/src/utils/chunk-items.ts b/src/utils/chunk-items.ts
new file mode 100644
index 00000000000..58ceebff1a4
--- /dev/null
+++ b/src/utils/chunk-items.ts
@@ -0,0 +1,10 @@
+export function chunkItems<T>(items: readonly T[], size: number): T[][] {
+  if (size <= 0) {
+    return [Array.from(items)];
+  }
+  const rows: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    rows.push(items.slice(i, i + size));
+  }
+  return rows;
+}
diff --git a/src/utils/provider-utils.test.ts b/src/utils/provider-utils.test.ts
deleted file mode 100644
index d00324f5903..00000000000
--- a/src/utils/provider-utils.test.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isReasoningTagProvider } from "./provider-utils.js";
-
-describe("isReasoningTagProvider", () => {
-  it("returns false for ollama - native reasoning field, no tags needed (#2279)", () => {
-    expect(isReasoningTagProvider("ollama")).toBe(false);
-    expect(isReasoningTagProvider("Ollama")).toBe(false);
-  });
-
-  it("returns true for google-gemini-cli", () => {
-    expect(isReasoningTagProvider("google-gemini-cli")).toBe(true);
-  });
-
-  it("returns true for google-generative-ai", () => {
-    expect(isReasoningTagProvider("google-generative-ai")).toBe(true);
-  });
-
-  it("returns true for google-antigravity", () => {
-    expect(isReasoningTagProvider("google-antigravity")).toBe(true);
-    expect(isReasoningTagProvider("google-antigravity/gemini-3")).toBe(true);
-  });
-
-  it("returns true for minimax", () => {
-    expect(isReasoningTagProvider("minimax")).toBe(true);
-    expect(isReasoningTagProvider("minimax-cn")).toBe(true);
-  });
-
-  it("returns false for null/undefined/empty", () => {
-    expect(isReasoningTagProvider(null)).toBe(false);
-    expect(isReasoningTagProvider(undefined)).toBe(false);
-    expect(isReasoningTagProvider("")).toBe(false);
-  });
-
-  it("returns false for standard providers", () => {
-    expect(isReasoningTagProvider("anthropic")).toBe(false);
-    expect(isReasoningTagProvider("openai")).toBe(false);
-    expect(isReasoningTagProvider("openrouter")).toBe(false);
-  });
-});
diff --git a/src/utils/shell-argv.test.ts b/src/utils/shell-argv.test.ts
deleted file mode 100644
index 156cf1bfdfd..00000000000
--- a/src/utils/shell-argv.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { splitShellArgs } from "./shell-argv.js";
-
-describe("splitShellArgs", () => {
-  it("splits whitespace and respects quotes", () => {
-    expect(splitShellArgs(`qmd --foo "bar baz"`)).toEqual(["qmd", "--foo", "bar baz"]);
-    expect(splitShellArgs(`qmd --foo 'bar baz'`)).toEqual(["qmd", "--foo", "bar baz"]);
-  });
-
-  it("supports backslash escapes inside double quotes", () => {
-    expect(splitShellArgs(String.raw`echo "a\"b"`)).toEqual(["echo", `a"b`]);
-    expect(splitShellArgs(String.raw`echo "\$HOME"`)).toEqual(["echo", "$HOME"]);
-  });
-
-  it("returns null for unterminated quotes", () => {
-    expect(splitShellArgs(`echo "oops`)).toBeNull();
-    expect(splitShellArgs(`echo 'oops`)).toBeNull();
-  });
-});
diff --git a/src/utils/utils-misc.test.ts b/src/utils/utils-misc.test.ts
new file mode 100644
index 00000000000..1c8a1632285
--- /dev/null
+++ b/src/utils/utils-misc.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { parseBooleanValue } from "./boolean.js";
+import { isReasoningTagProvider } from "./provider-utils.js";
+import { splitShellArgs } from "./shell-argv.js";
+
+describe("parseBooleanValue", () => {
+  it("handles boolean inputs", () => {
+    expect(parseBooleanValue(true)).toBe(true);
+    expect(parseBooleanValue(false)).toBe(false);
+  });
+
+  it("parses default truthy/falsy strings", () => {
+    expect(parseBooleanValue("true")).toBe(true);
+    expect(parseBooleanValue("1")).toBe(true);
+    expect(parseBooleanValue("yes")).toBe(true);
+    expect(parseBooleanValue("on")).toBe(true);
+    expect(parseBooleanValue("false")).toBe(false);
+    expect(parseBooleanValue("0")).toBe(false);
+    expect(parseBooleanValue("no")).toBe(false);
+    expect(parseBooleanValue("off")).toBe(false);
+  });
+
+  it("respects custom truthy/falsy lists", () => {
+    expect(
+      parseBooleanValue("on", {
+        truthy: ["true"],
+        falsy: ["false"],
+      }),
+    ).toBeUndefined();
+    expect(
+      parseBooleanValue("yes", {
+        truthy: ["yes"],
+        falsy: ["no"],
+      }),
+    ).toBe(true);
+  });
+
+  it("returns undefined for unsupported values", () => {
+    expect(parseBooleanValue("")).toBeUndefined();
+    expect(parseBooleanValue("maybe")).toBeUndefined();
+    expect(parseBooleanValue(1)).toBeUndefined();
+  });
+});
+
+describe("isReasoningTagProvider", () => {
+  it("returns false for ollama - native reasoning field, no tags needed (#2279)", () => {
+    expect(isReasoningTagProvider("ollama")).toBe(false);
+    expect(isReasoningTagProvider("Ollama")).toBe(false);
+  });
+
+  it("returns true for google-gemini-cli", () => {
+    expect(isReasoningTagProvider("google-gemini-cli")).toBe(true);
+  });
+
+  it("returns true for google-generative-ai", () => {
+    expect(isReasoningTagProvider("google-generative-ai")).toBe(true);
+  });
+
+  it("returns true for google-antigravity", () => {
+    expect(isReasoningTagProvider("google-antigravity")).toBe(true);
+    expect(isReasoningTagProvider("google-antigravity/gemini-3")).toBe(true);
+  });
+
+  it("returns true for minimax", () => {
+    expect(isReasoningTagProvider("minimax")).toBe(true);
+    expect(isReasoningTagProvider("minimax-cn")).toBe(true);
+  });
+
+  it("returns false for null/undefined/empty", () => {
+    expect(isReasoningTagProvider(null)).toBe(false);
+    expect(isReasoningTagProvider(undefined)).toBe(false);
+    expect(isReasoningTagProvider("")).toBe(false);
+  });
+
+  it("returns false for standard providers", () => {
+    expect(isReasoningTagProvider("anthropic")).toBe(false);
+    expect(isReasoningTagProvider("openai")).toBe(false);
+    expect(isReasoningTagProvider("openrouter")).toBe(false);
+  });
+});
+
+describe("splitShellArgs", () => {
+  it("splits whitespace and respects quotes", () => {
+    expect(splitShellArgs(`qmd --foo "bar baz"`)).toEqual(["qmd", "--foo", "bar baz"]);
+    expect(splitShellArgs(`qmd --foo 'bar baz'`)).toEqual(["qmd", "--foo", "bar baz"]);
+  });
+
+  it("supports backslash escapes inside double quotes", () => {
+    expect(splitShellArgs(String.raw`echo "a\"b"`)).toEqual(["echo", `a"b`]);
+    expect(splitShellArgs(String.raw`echo "\$HOME"`)).toEqual(["echo", "$HOME"]);
+  });
+
+  it("returns null for unterminated quotes", () => {
+    expect(splitShellArgs(`echo "oops`)).toBeNull();
+    expect(splitShellArgs(`echo 'oops`)).toBeNull();
+  });
+});
diff --git a/src/utils/with-timeout.ts b/src/utils/with-timeout.ts
new file mode 100644
index 00000000000..7a2d8361df1
--- /dev/null
+++ b/src/utils/with-timeout.ts
@@ -0,0 +1,14 @@
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return promise;
+  }
+  let timer: NodeJS.Timeout | null = null;
+  const timeout = new Promise<T>((_, reject) => {
+    timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  });
+}
diff --git a/src/web/accounts.whatsapp-auth.test.ts b/src/web/accounts.whatsapp-auth.test.ts
index c63ae12e56a..89dac3977cc 100644
--- a/src/web/accounts.whatsapp-auth.test.ts
+++ b/src/web/accounts.whatsapp-auth.test.ts
@@ -2,10 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { captureEnv } from "../test-utils/env.js";
 import { hasAnyWhatsAppAuth, listWhatsAppAuthDirs } from "./accounts.js";
 
 describe("hasAnyWhatsAppAuth", () => {
-  let previousOauthDir: string | undefined;
+  let envSnapshot: ReturnType<typeof captureEnv>;
   let tempOauthDir: string | undefined;
 
   const writeCreds = (dir: string) => {
@@ -14,17 +15,13 @@ describe("hasAnyWhatsAppAuth", () => {
   };
 
   beforeEach(() => {
-    previousOauthDir = process.env.OPENCLAW_OAUTH_DIR;
+    envSnapshot = captureEnv(["OPENCLAW_OAUTH_DIR"]);
     tempOauthDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-oauth-"));
     process.env.OPENCLAW_OAUTH_DIR = tempOauthDir;
   });
 
   afterEach(() => {
-    if (previousOauthDir === undefined) {
-      delete process.env.OPENCLAW_OAUTH_DIR;
-    } else {
-      process.env.OPENCLAW_OAUTH_DIR = previousOauthDir;
-    }
+    envSnapshot.restore();
     if (tempOauthDir) {
       fs.rmSync(tempOauthDir, { recursive: true, force: true });
       tempOauthDir = undefined;
diff --git a/src/web/auto-reply/monitor/message-line.test.ts b/src/web/auto-reply/monitor/message-line.test.ts
deleted file mode 100644
index 4fad746d407..00000000000
--- a/src/web/auto-reply/monitor/message-line.test.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildInboundLine, formatReplyContext } from "./message-line.js";
-
-describe("buildInboundLine", () => {
-  it("prefixes group messages with sender", () => {
-    const line = buildInboundLine({
-      cfg: {
-        agents: { defaults: { workspace: "/tmp/openclaw" } },
-        channels: { whatsapp: { messagePrefix: "" } },
-      } as never,
-      agentId: "main",
-      msg: {
-        from: "123@g.us",
-        conversationId: "123@g.us",
-        to: "+15550009999",
-        accountId: "default",
-        body: "ping",
-        timestamp: 1700000000000,
-        chatType: "group",
-        chatId: "123@g.us",
-        senderJid: "111@s.whatsapp.net",
-        senderE164: "+15550001111",
-        senderName: "Bob",
-        sendComposing: async () => undefined,
-        reply: async () => undefined,
-        sendMedia: async () => undefined,
-      } as never,
-    });
-
-    expect(line).toContain("Bob (+15550001111):");
-    expect(line).toContain("ping");
-  });
-
-  it("includes reply-to context blocks when replyToBody is present", () => {
-    const line = buildInboundLine({
-      cfg: {
-        agents: { defaults: { workspace: "/tmp/openclaw" } },
-        channels: { whatsapp: { messagePrefix: "" } },
-      } as never,
-      agentId: "main",
-      msg: {
-        from: "+1555",
-        to: "+1555",
-        body: "hello",
-        chatType: "direct",
-        replyToId: "q1",
-        replyToBody: "original",
-        replyToSender: "+1999",
-      } as never,
-      envelope: { includeTimestamp: false },
-    });
-
-    expect(line).toContain("[Replying to +1999 id:q1]");
-    expect(line).toContain("original");
-    expect(line).toContain("[/Replying]");
-  });
-
-  it("applies the WhatsApp messagePrefix when configured", () => {
-    const line = buildInboundLine({
-      cfg: {
-        agents: { defaults: { workspace: "/tmp/openclaw" } },
-        channels: { whatsapp: { messagePrefix: "[PFX]" } },
-      } as never,
-      agentId: "main",
-      msg: {
-        from: "+1555",
-        to: "+2666",
-        body: "ping",
-        chatType: "direct",
-      } as never,
-      envelope: { includeTimestamp: false },
-    });
-
-    expect(line).toContain("[PFX] ping");
-  });
-});
-
-describe("formatReplyContext", () => {
-  it("returns null when replyToBody is missing", () => {
-    expect(formatReplyContext({} as never)).toBeNull();
-  });
-});
diff --git a/src/web/auto-reply/monitor/process-message.ts b/src/web/auto-reply/monitor/process-message.ts
index 90e857474da..ed86bf93098 100644
--- a/src/web/auto-reply/monitor/process-message.ts
+++ b/src/web/auto-reply/monitor/process-message.ts
@@ -88,7 +88,11 @@ async function resolveWhatsAppCommandAuthorized(params: {
     return normalizeAllowFromE164(configuredGroupAllowFrom).includes(senderE164);
   }
 
-  const storeAllowFrom = await readChannelAllowFromStore("whatsapp").catch(() => []);
+  const storeAllowFrom = await readChannelAllowFromStore(
+    "whatsapp",
+    process.env,
+    params.msg.accountId,
+  ).catch(() => []);
   const combinedAllowFrom = Array.from(
     new Set([...(configuredAllowFrom ?? []), ...storeAllowFrom]),
   );
diff --git a/src/web/auto-reply/session-snapshot.test.ts b/src/web/auto-reply/session-snapshot.test.ts
deleted file mode 100644
index 1f9d6dfc9f4..00000000000
--- a/src/web/auto-reply/session-snapshot.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
-import { saveSessionStore } from "../../config/sessions.js";
-import { getSessionSnapshot } from "./session-snapshot.js";
-
-describe("getSessionSnapshot", () => {
-  it("uses channel reset overrides when configured", async () => {
-    vi.useFakeTimers();
-    vi.setSystemTime(new Date(2026, 0, 18, 5, 0, 0));
-    try {
-      const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-snapshot-"));
-      const storePath = path.join(root, "sessions.json");
-      const sessionKey = "agent:main:whatsapp:dm:s1";
-
-      await saveSessionStore(storePath, {
-        [sessionKey]: {
-          sessionId: "snapshot-session",
-          updatedAt: new Date(2026, 0, 18, 3, 30, 0).getTime(),
-          lastChannel: "whatsapp",
-        },
-      });
-
-      const cfg = {
-        session: {
-          store: storePath,
-          reset: { mode: "daily", atHour: 4, idleMinutes: 240 },
-          resetByChannel: {
-            whatsapp: { mode: "idle", idleMinutes: 360 },
-          },
-        },
-      } as Parameters<typeof getSessionSnapshot>[0];
-
-      const snapshot = getSessionSnapshot(cfg, "whatsapp:+15550001111", true, {
-        sessionKey,
-      });
-
-      expect(snapshot.resetPolicy.mode).toBe("idle");
-      expect(snapshot.resetPolicy.idleMinutes).toBe(360);
-      expect(snapshot.fresh).toBe(true);
-      expect(snapshot.dailyResetAt).toBeUndefined();
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});
diff --git a/src/web/auto-reply/util.test.ts b/src/web/auto-reply/util.test.ts
deleted file mode 100644
index a9327657d32..00000000000
--- a/src/web/auto-reply/util.test.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { elide, isLikelyWhatsAppCryptoError } from "./util.js";
-
-describe("web auto-reply util", () => {
-  describe("elide", () => {
-    it("returns undefined for undefined input", () => {
-      expect(elide(undefined)).toBe(undefined);
-    });
-
-    it("returns input when under limit", () => {
-      expect(elide("hi", 10)).toBe("hi");
-    });
-
-    it("returns input when exactly at limit", () => {
-      expect(elide("12345", 5)).toBe("12345");
-    });
-
-    it("truncates and annotates when over limit", () => {
-      expect(elide("abcdef", 3)).toBe("abc… (truncated 3 chars)");
-    });
-  });
-
-  describe("isLikelyWhatsAppCryptoError", () => {
-    it("returns false for non-matching reasons", () => {
-      expect(isLikelyWhatsAppCryptoError(new Error("boom"))).toBe(false);
-      expect(isLikelyWhatsAppCryptoError("boom")).toBe(false);
-      expect(isLikelyWhatsAppCryptoError({ message: "bad mac" })).toBe(false);
-    });
-
-    it("matches known Baileys crypto auth errors (string)", () => {
-      expect(
-        isLikelyWhatsAppCryptoError(
-          "baileys: unsupported state or unable to authenticate data (noise-handler)",
-        ),
-      ).toBe(true);
-      expect(isLikelyWhatsAppCryptoError("bad mac in aesDecryptGCM (baileys)")).toBe(true);
-    });
-
-    it("matches known Baileys crypto auth errors (Error)", () => {
-      const err = new Error("bad mac");
-      err.stack = "at something\nat @whiskeysockets/baileys/noise-handler\n";
-      expect(isLikelyWhatsAppCryptoError(err)).toBe(true);
-    });
-
-    it("does not throw on circular objects", () => {
-      const circular: Record<string, unknown> = {};
-      circular.self = circular;
-      expect(isLikelyWhatsAppCryptoError(circular)).toBe(false);
-    });
-
-    it("handles non-string reasons without throwing", () => {
-      expect(isLikelyWhatsAppCryptoError(null)).toBe(false);
-      expect(isLikelyWhatsAppCryptoError(123)).toBe(false);
-      expect(isLikelyWhatsAppCryptoError(true)).toBe(false);
-      expect(isLikelyWhatsAppCryptoError(123n)).toBe(false);
-      expect(isLikelyWhatsAppCryptoError(Symbol("bad mac"))).toBe(false);
-      expect(isLikelyWhatsAppCryptoError(function namedFn() {})).toBe(false);
-    });
-  });
-});
diff --git a/src/web/auto-reply/monitor/group-gating.test.ts b/src/web/auto-reply/web-auto-reply-monitor.test.ts
similarity index 76%
rename from src/web/auto-reply/monitor/group-gating.test.ts
rename to src/web/auto-reply/web-auto-reply-monitor.test.ts
index 74bce52197a..766bd0f932e 100644
--- a/src/web/auto-reply/monitor/group-gating.test.ts
+++ b/src/web/auto-reply/web-auto-reply-monitor.test.ts
@@ -2,9 +2,10 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { resolveAgentRoute } from "../../../routing/resolve-route.js";
-import { buildMentionConfig } from "../mentions.js";
-import { applyGroupGating } from "./group-gating.js";
+import { resolveAgentRoute } from "../../routing/resolve-route.js";
+import { buildMentionConfig } from "./mentions.js";
+import { applyGroupGating } from "./monitor/group-gating.js";
+import { buildInboundLine, formatReplyContext } from "./monitor/message-line.js";
 
 let sessionDir: string | undefined;
 let sessionStorePath: string;
@@ -32,10 +33,10 @@ const makeConfig = (overrides: Record<string, unknown>) =>
     },
     session: { store: sessionStorePath },
     ...overrides,
-  }) as unknown as ReturnType<typeof import("../../../config/config.js").loadConfig>;
+  }) as unknown as ReturnType<typeof import("../../config/config.js").loadConfig>;
 
 function runGroupGating(params: {
-  cfg: ReturnType<typeof import("../../../config/config.js").loadConfig>;
+  cfg: ReturnType<typeof import("../../config/config.js").loadConfig>;
   msg: Record<string, unknown>;
   conversationId?: string;
   agentId?: string;
@@ -340,3 +341,83 @@ describe("applyGroupGating", () => {
     expect(result.shouldProcess).toBe(false);
   });
 });
+
+describe("buildInboundLine", () => {
+  it("prefixes group messages with sender", () => {
+    const line = buildInboundLine({
+      cfg: {
+        agents: { defaults: { workspace: "/tmp/openclaw" } },
+        channels: { whatsapp: { messagePrefix: "" } },
+      } as never,
+      agentId: "main",
+      msg: {
+        from: "123@g.us",
+        conversationId: "123@g.us",
+        to: "+15550009999",
+        accountId: "default",
+        body: "ping",
+        timestamp: 1700000000000,
+        chatType: "group",
+        chatId: "123@g.us",
+        senderJid: "111@s.whatsapp.net",
+        senderE164: "+15550001111",
+        senderName: "Bob",
+        sendComposing: async () => undefined,
+        reply: async () => undefined,
+        sendMedia: async () => undefined,
+      } as never,
+    });
+
+    expect(line).toContain("Bob (+15550001111):");
+    expect(line).toContain("ping");
+  });
+
+  it("includes reply-to context blocks when replyToBody is present", () => {
+    const line = buildInboundLine({
+      cfg: {
+        agents: { defaults: { workspace: "/tmp/openclaw" } },
+        channels: { whatsapp: { messagePrefix: "" } },
+      } as never,
+      agentId: "main",
+      msg: {
+        from: "+1555",
+        to: "+1555",
+        body: "hello",
+        chatType: "direct",
+        replyToId: "q1",
+        replyToBody: "original",
+        replyToSender: "+1999",
+      } as never,
+      envelope: { includeTimestamp: false },
+    });
+
+    expect(line).toContain("[Replying to +1999 id:q1]");
+    expect(line).toContain("original");
+    expect(line).toContain("[/Replying]");
+  });
+
+  it("applies the WhatsApp messagePrefix when configured", () => {
+    const line = buildInboundLine({
+      cfg: {
+        agents: { defaults: { workspace: "/tmp/openclaw" } },
+        channels: { whatsapp: { messagePrefix: "[PFX]" } },
+      } as never,
+      agentId: "main",
+      msg: {
+        from: "+1555",
+        to: "+2666",
+        body: "ping",
+        chatType: "direct",
+      } as never,
+      envelope: { includeTimestamp: false },
+    });
+
+    expect(line).toContain("[PFX] ping");
+  });
+});
+
+describe("formatReplyContext", () => {
+  it("returns null when replyToBody is missing", () => {
+    expect(formatReplyContext({} as never)).toBeNull();
+  });
+});
diff --git a/src/web/auto-reply/mentions.test.ts b/src/web/auto-reply/web-auto-reply-utils.test.ts
similarity index 52%
rename from src/web/auto-reply/mentions.test.ts
rename to src/web/auto-reply/web-auto-reply-utils.test.ts
index 27e4f426bc3..2308373f4be 100644
--- a/src/web/auto-reply/mentions.test.ts
+++ b/src/web/auto-reply/web-auto-reply-utils.test.ts
@@ -1,9 +1,12 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import type { WebInboundMsg } from "./types.js";
+import { saveSessionStore } from "../../config/sessions.js";
 import { isBotMentionedFromTargets, resolveMentionTargets } from "./mentions.js";
+import { getSessionSnapshot } from "./session-snapshot.js";
+import { elide, isLikelyWhatsAppCryptoError } from "./util.js";
 
 const makeMsg = (overrides: Partial<WebInboundMsg>): WebInboundMsg =>
   ({
@@ -116,3 +119,98 @@ describe("resolveMentionTargets with @lid mapping", () => {
     }
   });
 });
+
+describe("getSessionSnapshot", () => {
+  it("uses channel reset overrides when configured", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(2026, 0, 18, 5, 0, 0));
+    try {
+      const root = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-snapshot-"));
+      const storePath = path.join(root, "sessions.json");
+      const sessionKey = "agent:main:whatsapp:dm:s1";
+
+      await saveSessionStore(storePath, {
+        [sessionKey]: {
+          sessionId: "snapshot-session",
+          updatedAt: new Date(2026, 0, 18, 3, 30, 0).getTime(),
+          lastChannel: "whatsapp",
+        },
+      });
+
+      const cfg = {
+        session: {
+          store: storePath,
+          reset: { mode: "daily", atHour: 4, idleMinutes: 240 },
+          resetByChannel: {
+            whatsapp: { mode: "idle", idleMinutes: 360 },
+          },
+        },
+      } as Parameters<typeof getSessionSnapshot>[0];
+
+      const snapshot = getSessionSnapshot(cfg, "whatsapp:+15550001111", true, {
+        sessionKey,
+      });
+
+      expect(snapshot.resetPolicy.mode).toBe("idle");
+      expect(snapshot.resetPolicy.idleMinutes).toBe(360);
+      expect(snapshot.fresh).toBe(true);
+      expect(snapshot.dailyResetAt).toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("web auto-reply util", () => {
+  describe("elide", () => {
+    it("returns undefined for undefined input", () => {
+      expect(elide(undefined)).toBe(undefined);
+    });
+
+    it("returns input when under limit", () => {
+      expect(elide("hi", 10)).toBe("hi");
+    });
+
+    it("truncates and annotates when over limit", () => {
+      expect(elide("abcdef", 3)).toBe("abc… (truncated 3 chars)");
+    });
+  });
+
+  describe("isLikelyWhatsAppCryptoError", () => {
+    it("returns false for non-matching reasons", () => {
+      expect(isLikelyWhatsAppCryptoError(new Error("boom"))).toBe(false);
+      expect(isLikelyWhatsAppCryptoError("boom")).toBe(false);
+      expect(isLikelyWhatsAppCryptoError({ message: "bad mac" })).toBe(false);
+    });
+
+    it("matches known Baileys crypto auth errors (string)", () => {
+      expect(
+        isLikelyWhatsAppCryptoError(
+          "baileys: unsupported state or unable to authenticate data (noise-handler)",
+        ),
+      ).toBe(true);
+      expect(isLikelyWhatsAppCryptoError("bad mac in aesDecryptGCM (baileys)")).toBe(true);
+    });
+
+    it("matches known Baileys crypto auth errors (Error)", () => {
+      const err = new Error("bad mac");
+      err.stack = "at something\nat @whiskeysockets/baileys/noise-handler\n";
+      expect(isLikelyWhatsAppCryptoError(err)).toBe(true);
+    });
+
+    it("does not throw on circular objects", () => {
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+      expect(isLikelyWhatsAppCryptoError(circular)).toBe(false);
+    });
+
+    it("handles non-string reasons without throwing", () => {
+      expect(isLikelyWhatsAppCryptoError(null)).toBe(false);
+      expect(isLikelyWhatsAppCryptoError(123)).toBe(false);
+      expect(isLikelyWhatsAppCryptoError(true)).toBe(false);
+      expect(isLikelyWhatsAppCryptoError(123n)).toBe(false);
+      expect(isLikelyWhatsAppCryptoError(Symbol("bad mac"))).toBe(false);
+      expect(isLikelyWhatsAppCryptoError(function namedFn() {})).toBe(false);
+    });
+  });
+});
diff --git a/src/web/inbound/access-control.ts b/src/web/inbound/access-control.ts
index 08d97acd584..96671e7bc77 100644
--- a/src/web/inbound/access-control.ts
+++ b/src/web/inbound/access-control.ts
@@ -40,7 +40,11 @@ export async function checkInboundAccessControl(params: {
   });
   const dmPolicy = account.dmPolicy ?? "pairing";
   const configuredAllowFrom = account.allowFrom;
-  const storeAllowFrom = await readChannelAllowFromStore("whatsapp").catch(() => []);
+  const storeAllowFrom = await readChannelAllowFromStore(
+    "whatsapp",
+    process.env,
+    account.accountId,
+  ).catch(() => []);
   // Without user config, default to self-only DM access so the owner can talk to themselves.
   const combinedAllowFrom = Array.from(
     new Set([...(configuredAllowFrom ?? []), ...storeAllowFrom]),
@@ -148,6 +152,7 @@ export async function checkInboundAccessControl(params: {
             const { code, created } = await upsertChannelPairingRequest({
               channel: "whatsapp",
               id: candidate,
+              accountId: account.accountId,
               meta: { name: (params.pushName ?? "").trim() || undefined },
             });
             if (created) {
diff --git a/src/web/login.test.ts b/src/web/login.test.ts
index 5ef6f889bd4..89baa473397 100644
--- a/src/web/login.test.ts
+++ b/src/web/login.test.ts
@@ -1,6 +1,9 @@
 import { EventEmitter } from "node:events";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { resetLogger, setLoggerOverride } from "../logging.js";
+import { renderQrPngBase64 } from "./qr-image.js";
 
 vi.mock("./session.js", () => {
   const ev = new EventEmitter();
@@ -47,3 +50,20 @@ describe("web login", () => {
     expect(close).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("renderQrPngBase64", () => {
+  it("renders a PNG data payload", async () => {
+    const b64 = await renderQrPngBase64("openclaw");
+    const buf = Buffer.from(b64, "base64");
+    expect(buf.subarray(0, 8).toString("hex")).toBe("89504e470d0a1a0a");
+  });
+
+  it("avoids dynamic require of qrcode-terminal vendor modules", async () => {
+    const sourcePath = resolve(process.cwd(), "src/web/qr-image.ts");
+    const source = await readFile(sourcePath, "utf-8");
+    expect(source).not.toContain("createRequire(");
+    expect(source).not.toContain('require("qrcode-terminal/vendor/QRCode")');
+    expect(source).toContain("qrcode-terminal/vendor/QRCode/index.js");
+    expect(source).toContain("qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel.js");
+  });
+});
diff --git a/src/web/media.test.ts b/src/web/media.test.ts
index 86fe6c59c06..298e819d650 100644
--- a/src/web/media.test.ts
+++ b/src/web/media.test.ts
@@ -3,8 +3,10 @@ import os from "node:os";
 import path from "node:path";
 import sharp from "sharp";
 import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { sendVoiceMessageDiscord } from "../discord/send.js";
 import * as ssrf from "../infra/net/ssrf.js";
 import { optimizeImageToPng } from "../media/image-ops.js";
+import { captureEnv } from "../test-utils/env.js";
 import { loadWebMedia, loadWebMediaRaw, optimizeImageToJpeg } from "./media.js";
 
 let fixtureRoot = "";
@@ -19,6 +21,7 @@ let alphaPngFile = "";
 let fallbackPngBuffer: Buffer;
 let fallbackPngFile = "";
 let fallbackPngCap = 0;
+let stateDirSnapshot: ReturnType<typeof captureEnv>;
 
 async function writeTempFile(buffer: Buffer, ext: string): Promise<string> {
   const file = path.join(fixtureRoot, `media-${fixtureFileCount++}${ext}`);
@@ -96,6 +99,22 @@ afterEach(() => {
 });
 
 describe("web media loading", () => {
+  beforeAll(() => {
+    // Ensure state dir is stable and not influenced by other tests that stub OPENCLAW_STATE_DIR.
+    // Also keep it outside os.tmpdir() so tmpdir localRoots doesn't accidentally make all state readable.
+    stateDirSnapshot = captureEnv(["OPENCLAW_STATE_DIR"]);
+    process.env.OPENCLAW_STATE_DIR = path.join(
+      path.parse(os.tmpdir()).root,
+      "var",
+      "lib",
+      "openclaw-media-state-test",
+    );
+  });
+
+  afterAll(() => {
+    stateDirSnapshot.restore();
+  });
+
   beforeAll(() => {
     vi.spyOn(ssrf, "resolvePinnedHostname").mockImplementation(async (hostname) => {
       const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
@@ -109,45 +128,14 @@ describe("web media loading", () => {
   });
 
   it("strips MEDIA: prefix before reading local file", async () => {
-    const buffer = await sharp({
-      create: { width: 2, height: 2, channels: 3, background: "#0000ff" },
-    })
-      .png()
-      .toBuffer();
-
-    const file = await writeTempFile(buffer, ".png");
-
-    const result = await loadWebMedia(`MEDIA:${file}`, 1024 * 1024);
-
-    expect(result.kind).toBe("image");
-    expect(result.buffer.length).toBeGreaterThan(0);
-  });
-
-  it("strips MEDIA: prefix with whitespace after colon", async () => {
-    const buffer = await sharp({
-      create: { width: 2, height: 2, channels: 3, background: "#0000ff" },
-    })
-      .png()
-      .toBuffer();
-
-    const file = await writeTempFile(buffer, ".png");
-
-    const result = await loadWebMedia(`MEDIA: ${file}`, 1024 * 1024);
+    const result = await loadWebMedia(`MEDIA:${tinyPngFile}`, 1024 * 1024);
 
     expect(result.kind).toBe("image");
     expect(result.buffer.length).toBeGreaterThan(0);
   });
 
   it("strips MEDIA: prefix with extra whitespace (LLM-friendly)", async () => {
-    const buffer = await sharp({
-      create: { width: 2, height: 2, channels: 3, background: "#0000ff" },
-    })
-      .png()
-      .toBuffer();
-
-    const file = await writeTempFile(buffer, ".png");
-
-    const result = await loadWebMedia(`  MEDIA :  ${file}`, 1024 * 1024);
+    const result = await loadWebMedia(`  MEDIA :  ${tinyPngFile}`, 1024 * 1024);
 
     expect(result.kind).toBe("image");
     expect(result.buffer.length).toBeGreaterThan(0);
@@ -315,6 +303,27 @@ describe("web media loading", () => {
   });
 });
 
+describe("Discord voice message input hardening", () => {
+  it("rejects local paths outside allowed media roots", async () => {
+    const candidate = path.join(process.cwd(), "package.json");
+    await expect(sendVoiceMessageDiscord("channel:123", candidate)).rejects.toThrow(
+      /Local media path is not under an allowed directory/i,
+    );
+  });
+
+  it("blocks SSRF targets when given a private-network URL", async () => {
+    await expect(
+      sendVoiceMessageDiscord("channel:123", "http://127.0.0.1/voice.ogg"),
+    ).rejects.toThrow(/Failed to fetch media|Blocked|private|internal/i);
+  });
+
+  it("rejects non-http URL schemes", async () => {
+    await expect(
+      sendVoiceMessageDiscord("channel:123", "rtsp://example.com/voice.ogg"),
+    ).rejects.toThrow(/Local media path is not under an allowed directory|ENOENT|no such file/i);
+  });
+});
+
 describe("local media root guard", () => {
   it("rejects local paths outside allowed roots", async () => {
     // Explicit roots that don't contain the temp file.
@@ -346,11 +355,12 @@ describe("local media root guard", () => {
   });
 
   it("allows default OpenClaw state workspace and sandbox roots", async () => {
-    const { STATE_DIR } = await import("../config/paths.js");
+    const { resolveStateDir } = await import("../config/paths.js");
+    const stateDir = resolveStateDir();
     const readFile = vi.fn(async () => Buffer.from("generated-media"));
 
     await expect(
-      loadWebMedia(path.join(STATE_DIR, "workspace", "tmp", "render.bin"), {
+      loadWebMedia(path.join(stateDir, "workspace", "tmp", "render.bin"), {
         maxBytes: 1024 * 1024,
         readFile,
       }),
@@ -361,7 +371,7 @@ describe("local media root guard", () => {
     );
 
     await expect(
-      loadWebMedia(path.join(STATE_DIR, "sandboxes", "session-1", "frame.bin"), {
+      loadWebMedia(path.join(stateDir, "sandboxes", "session-1", "frame.bin"), {
         maxBytes: 1024 * 1024,
         readFile,
       }),
@@ -373,11 +383,12 @@ describe("local media root guard", () => {
   });
 
   it("rejects default OpenClaw state per-agent workspace-* roots without explicit local roots", async () => {
-    const { STATE_DIR } = await import("../config/paths.js");
+    const { resolveStateDir } = await import("../config/paths.js");
+    const stateDir = resolveStateDir();
     const readFile = vi.fn(async () => Buffer.from("generated-media"));
 
     await expect(
-      loadWebMedia(path.join(STATE_DIR, "workspace-clawdy", "tmp", "render.bin"), {
+      loadWebMedia(path.join(stateDir, "workspace-clawdy", "tmp", "render.bin"), {
         maxBytes: 1024 * 1024,
         readFile,
       }),
@@ -385,9 +396,10 @@ describe("local media root guard", () => {
   });
 
   it("allows per-agent workspace-* paths with explicit local roots", async () => {
-    const { STATE_DIR } = await import("../config/paths.js");
+    const { resolveStateDir } = await import("../config/paths.js");
+    const stateDir = resolveStateDir();
     const readFile = vi.fn(async () => Buffer.from("generated-media"));
-    const agentWorkspaceDir = path.join(STATE_DIR, "workspace-clawdy");
+    const agentWorkspaceDir = path.join(stateDir, "workspace-clawdy");
 
     await expect(
       loadWebMedia(path.join(agentWorkspaceDir, "tmp", "render.bin"), {
diff --git a/src/web/media.ts b/src/web/media.ts
index f777dabdbbb..13ed96e492f 100644
--- a/src/web/media.ts
+++ b/src/web/media.ts
@@ -52,6 +52,24 @@ async function assertLocalMediaAllowed(
   } catch {
     resolved = path.resolve(mediaPath);
   }
+
+  // Hardening: the default allowlist includes `os.tmpdir()`, and tests/CI may
+  // override the state dir into tmp. Avoid accidentally allowing per-agent
+  // `workspace-*` state roots via the tmpdir prefix match; require explicit
+  // localRoots for those.
+  if (localRoots === undefined) {
+    const workspaceRoot = roots.find((root) => path.basename(root) === "workspace");
+    if (workspaceRoot) {
+      const stateDir = path.dirname(workspaceRoot);
+      const rel = path.relative(stateDir, resolved);
+      if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+        const firstSegment = rel.split(path.sep)[0] ?? "";
+        if (firstSegment.startsWith("workspace-")) {
+          throw new Error(`Local media path is not under an allowed directory: ${mediaPath}`);
+        }
+      }
+    }
+  }
   for (const root of roots) {
     let resolvedRoot: string;
     try {
diff --git a/src/web/qr-image.test.ts b/src/web/qr-image.test.ts
deleted file mode 100644
index 6fdf25f43ba..00000000000
--- a/src/web/qr-image.test.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { describe, expect, it } from "vitest";
-import { renderQrPngBase64 } from "./qr-image.js";
-
-describe("renderQrPngBase64", () => {
-  it("renders a PNG data payload", async () => {
-    const b64 = await renderQrPngBase64("openclaw");
-    const buf = Buffer.from(b64, "base64");
-    expect(buf.subarray(0, 8).toString("hex")).toBe("89504e470d0a1a0a");
-  });
-
-  it("avoids dynamic require of qrcode-terminal vendor modules", async () => {
-    const sourcePath = resolve(process.cwd(), "src/web/qr-image.ts");
-    const source = await readFile(sourcePath, "utf-8");
-    expect(source).not.toContain("createRequire(");
-    expect(source).not.toContain('require("qrcode-terminal/vendor/QRCode")');
-    expect(source).toContain("qrcode-terminal/vendor/QRCode/index.js");
-    expect(source).toContain("qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel.js");
-  });
-});
diff --git a/src/wizard/onboarding.gateway-config.ts b/src/wizard/onboarding.gateway-config.ts
index dae687d12cf..a874c077b28 100644
--- a/src/wizard/onboarding.gateway-config.ts
+++ b/src/wizard/onboarding.gateway-config.ts
@@ -12,6 +12,11 @@ import {
   randomToken,
   validateGatewayPasswordInput,
 } from "../commands/onboard-helpers.js";
+import {
+  TAILSCALE_DOCS_LINES,
+  TAILSCALE_EXPOSURE_OPTIONS,
+  TAILSCALE_MISSING_BIN_NOTE_LINES,
+} from "../gateway/gateway-config-prompts.shared.js";
 import { findTailscaleBinary } from "../infra/tailscale.js";
 import { validateIPv4AddressInput } from "../shared/net/ipv4.js";
 
@@ -113,46 +118,20 @@ export async function configureGatewayForOnboarding(
       ? quickstartGateway.tailscaleMode
       : await prompter.select<GatewayWizardSettings["tailscaleMode"]>({
           message: "Tailscale exposure",
-          options: [
-            { value: "off", label: "Off", hint: "No Tailscale exposure" },
-            {
-              value: "serve",
-              label: "Serve",
-              hint: "Private HTTPS for your tailnet (devices on Tailscale)",
-            },
-            {
-              value: "funnel",
-              label: "Funnel",
-              hint: "Public HTTPS via Tailscale Funnel (internet)",
-            },
-          ],
+          options: [...TAILSCALE_EXPOSURE_OPTIONS],
         });
 
   // Detect Tailscale binary before proceeding with serve/funnel setup.
   if (tailscaleMode !== "off") {
     const tailscaleBin = await findTailscaleBinary();
     if (!tailscaleBin) {
-      await prompter.note(
-        [
-          "Tailscale binary not found in PATH or /Applications.",
-          "Ensure Tailscale is installed from:",
-          "  https://tailscale.com/download/mac",
-          "",
-          "You can continue setup, but serve/funnel will fail at runtime.",
-        ].join("\n"),
-        "Tailscale Warning",
-      );
+      await prompter.note(TAILSCALE_MISSING_BIN_NOTE_LINES.join("\n"), "Tailscale Warning");
     }
   }
 
   let tailscaleResetOnExit = flow === "quickstart" ? quickstartGateway.tailscaleResetOnExit : false;
   if (tailscaleMode !== "off" && flow !== "quickstart") {
-    await prompter.note(
-      ["Docs:", "https://docs.openclaw.ai/gateway/tailscale", "https://docs.openclaw.ai/web"].join(
-        "\n",
-      ),
-      "Tailscale",
-    );
+    await prompter.note(TAILSCALE_DOCS_LINES.join("\n"), "Tailscale");
     tailscaleResetOnExit = Boolean(
       await prompter.confirm({
         message: "Reset Tailscale serve/funnel on exit?",
diff --git a/src/wizard/onboarding.test.ts b/src/wizard/onboarding.test.ts
index a6911ac48ae..4aed0cd4776 100644
--- a/src/wizard/onboarding.test.ts
+++ b/src/wizard/onboarding.test.ts
@@ -1,12 +1,67 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import type { RuntimeEnv } from "../runtime.js";
 import type { WizardPrompter } from "./prompts.js";
 import { DEFAULT_BOOTSTRAP_FILENAME } from "../agents/workspace.js";
 import { runOnboardingWizard } from "./onboarding.js";
 
+const ensureAuthProfileStore = vi.hoisted(() => vi.fn(() => ({ profiles: {} })));
+const promptAuthChoiceGrouped = vi.hoisted(() => vi.fn(async () => "skip"));
+const applyAuthChoice = vi.hoisted(() => vi.fn(async (args) => ({ config: args.config })));
+const resolvePreferredProviderForAuthChoice = vi.hoisted(() => vi.fn(() => "openai"));
+const warnIfModelConfigLooksOff = vi.hoisted(() => vi.fn(async () => {}));
+const applyPrimaryModel = vi.hoisted(() => vi.fn((cfg) => cfg));
+const promptDefaultModel = vi.hoisted(() => vi.fn(async () => ({ config: null, model: null })));
+const promptCustomApiConfig = vi.hoisted(() => vi.fn(async (args) => ({ config: args.config })));
+const configureGatewayForOnboarding = vi.hoisted(() =>
+  vi.fn(async (args) => ({
+    nextConfig: args.nextConfig,
+    settings: {
+      port: args.localPort ?? 18789,
+      bind: "loopback",
+      authMode: "token",
+      gatewayToken: "test-token",
+      tailscaleMode: "off",
+      tailscaleResetOnExit: false,
+    },
+  })),
+);
+const finalizeOnboardingWizard = vi.hoisted(() =>
+  vi.fn(async (options) => {
+    if (!process.env.BRAVE_API_KEY) {
+      await options.prompter.note("hint", "Web search (optional)");
+    }
+
+    if (options.opts.skipUi) {
+      return { launchedTui: false };
+    }
+
+    const hatch = await options.prompter.select({
+      message: "How do you want to hatch your bot?",
+      options: [],
+    });
+    if (hatch !== "tui") {
+      return { launchedTui: false };
+    }
+
+    let message: string | undefined;
+    try {
+      await fs.stat(path.join(options.workspaceDir, DEFAULT_BOOTSTRAP_FILENAME));
+      message = "Wake up, my friend!";
+    } catch {
+      message = undefined;
+    }
+
+    await runTui({ deliver: false, message });
+    return { launchedTui: true };
+  }),
+);
+const listChannelPlugins = vi.hoisted(() => vi.fn(() => []));
+const logConfigUpdated = vi.hoisted(() => vi.fn(() => {}));
+const setupInternalHooks = vi.hoisted(() => vi.fn(async (cfg) => cfg));
+
 const setupChannels = vi.hoisted(() => vi.fn(async (cfg) => cfg));
 const setupSkills = vi.hoisted(() => vi.fn(async (cfg) => cfg));
 const healthCommand = vi.hoisted(() => vi.fn(async () => {}));
@@ -29,34 +84,68 @@ vi.mock("../commands/onboard-skills.js", () => ({
   setupSkills,
 }));
 
+vi.mock("../agents/auth-profiles.js", () => ({
+  ensureAuthProfileStore,
+}));
+
+vi.mock("../commands/auth-choice-prompt.js", () => ({
+  promptAuthChoiceGrouped,
+}));
+
+vi.mock("../commands/auth-choice.js", () => ({
+  applyAuthChoice,
+  resolvePreferredProviderForAuthChoice,
+  warnIfModelConfigLooksOff,
+}));
+
+vi.mock("../commands/model-picker.js", () => ({
+  applyPrimaryModel,
+  promptDefaultModel,
+}));
+
+vi.mock("../commands/onboard-custom.js", () => ({
+  promptCustomApiConfig,
+}));
+
 vi.mock("../commands/health.js", () => ({
   healthCommand,
 }));
 
-vi.mock("../config/config.js", async (importActual) => {
-  const actual = await importActual<typeof import("../config/config.js")>();
-  return {
-    ...actual,
-    readConfigFileSnapshot,
-    writeConfigFile,
-  };
-});
+vi.mock("../commands/onboard-hooks.js", () => ({
+  setupInternalHooks,
+}));
 
-vi.mock("../commands/onboard-helpers.js", async (importActual) => {
-  const actual = await importActual<typeof import("../commands/onboard-helpers.js")>();
-  return {
-    ...actual,
-    ensureWorkspaceAndSessions,
-    detectBrowserOpenSupport: vi.fn(async () => ({ ok: false })),
-    openUrl: vi.fn(async () => true),
-    printWizardHeader: vi.fn(),
-    probeGatewayReachable: vi.fn(async () => ({ ok: true })),
-    resolveControlUiLinks: vi.fn(() => ({
-      httpUrl: "http://127.0.0.1:18789",
-      wsUrl: "ws://127.0.0.1:18789",
-    })),
-  };
-});
+vi.mock("../config/config.js", () => ({
+  DEFAULT_GATEWAY_PORT: 18789,
+  resolveGatewayPort: () => 18789,
+  readConfigFileSnapshot,
+  writeConfigFile,
+}));
+
+vi.mock("../commands/onboard-helpers.js", () => ({
+  DEFAULT_WORKSPACE: "/tmp/openclaw-workspace",
+  applyWizardMetadata: (cfg: unknown) => cfg,
+  summarizeExistingConfig: () => "summary",
+  handleReset: async () => {},
+  randomToken: () => "test-token",
+  normalizeGatewayTokenInput: (value: unknown) => ({
+    ok: true,
+    token: typeof value === "string" ? value.trim() : "",
+    error: null,
+  }),
+  validateGatewayPasswordInput: () => ({ ok: true, error: null }),
+  ensureWorkspaceAndSessions,
+  detectBrowserOpenSupport: vi.fn(async () => ({ ok: false })),
+  openUrl: vi.fn(async () => true),
+  printWizardHeader: vi.fn(),
+  probeGatewayReachable: vi.fn(async () => ({ ok: true })),
+  waitForGatewayReachable: vi.fn(async () => {}),
+  formatControlUiSshHint: vi.fn(() => "ssh hint"),
+  resolveControlUiLinks: vi.fn(() => ({
+    httpUrl: "http://127.0.0.1:18789",
+    wsUrl: "ws://127.0.0.1:18789",
+  })),
+}));
 
 vi.mock("../commands/systemd-linger.js", () => ({
   ensureSystemdUserLingerInteractive,
@@ -70,10 +159,26 @@ vi.mock("../infra/control-ui-assets.js", () => ({
   ensureControlUiAssetsBuilt,
 }));
 
+vi.mock("../channels/plugins/index.js", () => ({
+  listChannelPlugins,
+}));
+
+vi.mock("../config/logging.js", () => ({
+  logConfigUpdated,
+}));
+
 vi.mock("../tui/tui.js", () => ({
   runTui,
 }));
 
+vi.mock("./onboarding.gateway-config.js", () => ({
+  configureGatewayForOnboarding,
+}));
+
+vi.mock("./onboarding.finalize.js", () => ({
+  finalizeOnboardingWizard,
+}));
+
 vi.mock("./onboarding.completion.js", () => ({
   setupOnboardingShellCompletion,
 }));
@@ -111,6 +216,25 @@ function createRuntime(opts?: { throwsOnExit?: boolean }): RuntimeEnv {
 }
 
 describe("runOnboardingWizard", () => {
+  let suiteRoot = "";
+  let suiteCase = 0;
+
+  beforeAll(async () => {
+    suiteRoot = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-onboard-suite-"));
+  });
+
+  afterAll(async () => {
+    await fs.rm(suiteRoot, { recursive: true, force: true });
+    suiteRoot = "";
+    suiteCase = 0;
+  });
+
+  async function makeCaseDir(prefix: string): Promise<string> {
+    const dir = path.join(suiteRoot, `${prefix}${++suiteCase}`);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+  }
+
   it("exits when config is invalid", async () => {
     readConfigFileSnapshot.mockResolvedValueOnce({
       path: "/tmp/.openclaw/openclaw.json",
@@ -182,47 +306,43 @@ describe("runOnboardingWizard", () => {
   }) {
     runTui.mockClear();
 
-    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-onboard-"));
-    try {
-      if (params.writeBootstrapFile) {
-        await fs.writeFile(path.join(workspaceDir, DEFAULT_BOOTSTRAP_FILENAME), "{}");
-      }
-
-      const select: WizardPrompter["select"] = vi.fn(async (opts) => {
-        if (opts.message === "How do you want to hatch your bot?") {
-          return "tui";
-        }
-        return "quickstart";
-      });
-
-      const prompter = createWizardPrompter({ select });
-      const runtime = createRuntime({ throwsOnExit: true });
-
-      await runOnboardingWizard(
-        {
-          acceptRisk: true,
-          flow: "quickstart",
-          mode: "local",
-          workspace: workspaceDir,
-          authChoice: "skip",
-          skipProviders: true,
-          skipSkills: true,
-          skipHealth: true,
-          installDaemon: false,
-        },
-        runtime,
-        prompter,
-      );
-
-      expect(runTui).toHaveBeenCalledWith(
-        expect.objectContaining({
-          deliver: false,
-          message: params.expectedMessage,
-        }),
-      );
-    } finally {
-      await fs.rm(workspaceDir, { recursive: true, force: true });
+    const workspaceDir = await makeCaseDir("workspace-");
+    if (params.writeBootstrapFile) {
+      await fs.writeFile(path.join(workspaceDir, DEFAULT_BOOTSTRAP_FILENAME), "{}");
     }
+
+    const select: WizardPrompter["select"] = vi.fn(async (opts) => {
+      if (opts.message === "How do you want to hatch your bot?") {
+        return "tui";
+      }
+      return "quickstart";
+    });
+
+    const prompter = createWizardPrompter({ select });
+    const runtime = createRuntime({ throwsOnExit: true });
+
+    await runOnboardingWizard(
+      {
+        acceptRisk: true,
+        flow: "quickstart",
+        mode: "local",
+        workspace: workspaceDir,
+        authChoice: "skip",
+        skipProviders: true,
+        skipSkills: true,
+        skipHealth: true,
+        installDaemon: false,
+      },
+      runtime,
+      prompter,
+    );
+
+    expect(runTui).toHaveBeenCalledWith(
+      expect.objectContaining({
+        deliver: false,
+        message: params.expectedMessage,
+      }),
+    );
   }
 
   it("launches TUI without auto-delivery when hatching", async () => {
diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts
index ae15e406e72..a5bff274ce8 100644
--- a/src/wizard/onboarding.ts
+++ b/src/wizard/onboarding.ts
@@ -7,42 +7,15 @@ import type {
 import type { OpenClawConfig } from "../config/config.js";
 import type { RuntimeEnv } from "../runtime.js";
 import type { QuickstartGatewayDefaults, WizardFlow } from "./onboarding.types.js";
-import { ensureAuthProfileStore } from "../agents/auth-profiles.js";
-import { listChannelPlugins } from "../channels/plugins/index.js";
 import { formatCliCommand } from "../cli/command-format.js";
-import { promptAuthChoiceGrouped } from "../commands/auth-choice-prompt.js";
-import {
-  applyAuthChoice,
-  resolvePreferredProviderForAuthChoice,
-  warnIfModelConfigLooksOff,
-} from "../commands/auth-choice.js";
-import { applyPrimaryModel, promptDefaultModel } from "../commands/model-picker.js";
-import { setupChannels } from "../commands/onboard-channels.js";
-import { applyOnboardingLocalWorkspaceConfig } from "../commands/onboard-config.js";
-import { promptCustomApiConfig } from "../commands/onboard-custom.js";
-import {
-  applyWizardMetadata,
-  DEFAULT_WORKSPACE,
-  ensureWorkspaceAndSessions,
-  handleReset,
-  printWizardHeader,
-  probeGatewayReachable,
-  summarizeExistingConfig,
-} from "../commands/onboard-helpers.js";
-import { setupInternalHooks } from "../commands/onboard-hooks.js";
-import { promptRemoteGatewayConfig } from "../commands/onboard-remote.js";
-import { setupSkills } from "../commands/onboard-skills.js";
 import {
   DEFAULT_GATEWAY_PORT,
   readConfigFileSnapshot,
   resolveGatewayPort,
   writeConfigFile,
 } from "../config/config.js";
-import { logConfigUpdated } from "../config/logging.js";
 import { defaultRuntime } from "../runtime.js";
 import { resolveUserPath } from "../utils.js";
-import { finalizeOnboardingWizard } from "./onboarding.finalize.js";
-import { configureGatewayForOnboarding } from "./onboarding.gateway-config.js";
 import { WizardCancelledError, type WizardPrompter } from "./prompts.js";
 
 async function requireRiskAcknowledgement(params: {
@@ -93,7 +66,8 @@ export async function runOnboardingWizard(
   runtime: RuntimeEnv = defaultRuntime,
   prompter: WizardPrompter,
 ) {
-  printWizardHeader(runtime);
+  const onboardHelpers = await import("../commands/onboard-helpers.js");
+  onboardHelpers.printWizardHeader(runtime);
   await prompter.intro("OpenClaw onboarding");
   await requireRiskAcknowledgement({ opts, prompter });
 
@@ -101,7 +75,7 @@ export async function runOnboardingWizard(
   let baseConfig: OpenClawConfig = snapshot.valid ? snapshot.config : {};
 
   if (snapshot.exists && !snapshot.valid) {
-    await prompter.note(summarizeExistingConfig(baseConfig), "Invalid config");
+    await prompter.note(onboardHelpers.summarizeExistingConfig(baseConfig), "Invalid config");
     if (snapshot.issues.length > 0) {
       await prompter.note(
         [
@@ -156,7 +130,10 @@ export async function runOnboardingWizard(
   }
 
   if (snapshot.exists) {
-    await prompter.note(summarizeExistingConfig(baseConfig), "Existing config detected");
+    await prompter.note(
+      onboardHelpers.summarizeExistingConfig(baseConfig),
+      "Existing config detected",
+    );
 
     const action = await prompter.select({
       message: "Config handling",
@@ -168,7 +145,8 @@ export async function runOnboardingWizard(
     });
 
     if (action === "reset") {
-      const workspaceDefault = baseConfig.agents?.defaults?.workspace ?? DEFAULT_WORKSPACE;
+      const workspaceDefault =
+        baseConfig.agents?.defaults?.workspace ?? onboardHelpers.DEFAULT_WORKSPACE;
       const resetScope = (await prompter.select({
         message: "Reset scope",
         options: [
@@ -183,7 +161,7 @@ export async function runOnboardingWizard(
           },
         ],
       })) as ResetScope;
-      await handleReset(resetScope, resolveUserPath(workspaceDefault), runtime);
+      await onboardHelpers.handleReset(resetScope, resolveUserPath(workspaceDefault), runtime);
       baseConfig = {};
     }
   }
@@ -294,14 +272,14 @@ export async function runOnboardingWizard(
 
   const localPort = resolveGatewayPort(baseConfig);
   const localUrl = `ws://127.0.0.1:${localPort}`;
-  const localProbe = await probeGatewayReachable({
+  const localProbe = await onboardHelpers.probeGatewayReachable({
     url: localUrl,
     token: baseConfig.gateway?.auth?.token ?? process.env.OPENCLAW_GATEWAY_TOKEN,
     password: baseConfig.gateway?.auth?.password ?? process.env.OPENCLAW_GATEWAY_PASSWORD,
   });
   const remoteUrl = baseConfig.gateway?.remote?.url?.trim() ?? "";
   const remoteProbe = remoteUrl
-    ? await probeGatewayReachable({
+    ? await onboardHelpers.probeGatewayReachable({
         url: remoteUrl,
         token: baseConfig.gateway?.remote?.token,
       })
@@ -334,8 +312,10 @@ export async function runOnboardingWizard(
         })) as OnboardMode));
 
   if (mode === "remote") {
+    const { promptRemoteGatewayConfig } = await import("../commands/onboard-remote.js");
+    const { logConfigUpdated } = await import("../config/logging.js");
     let nextConfig = await promptRemoteGatewayConfig(baseConfig, prompter);
-    nextConfig = applyWizardMetadata(nextConfig, { command: "onboard", mode });
+    nextConfig = onboardHelpers.applyWizardMetadata(nextConfig, { command: "onboard", mode });
     await writeConfigFile(nextConfig);
     logConfigUpdated(runtime);
     await prompter.outro("Remote gateway configured.");
@@ -345,16 +325,24 @@ export async function runOnboardingWizard(
   const workspaceInput =
     opts.workspace ??
     (flow === "quickstart"
-      ? (baseConfig.agents?.defaults?.workspace ?? DEFAULT_WORKSPACE)
+      ? (baseConfig.agents?.defaults?.workspace ?? onboardHelpers.DEFAULT_WORKSPACE)
       : await prompter.text({
           message: "Workspace directory",
-          initialValue: baseConfig.agents?.defaults?.workspace ?? DEFAULT_WORKSPACE,
+          initialValue: baseConfig.agents?.defaults?.workspace ?? onboardHelpers.DEFAULT_WORKSPACE,
         }));
 
-  const workspaceDir = resolveUserPath(workspaceInput.trim() || DEFAULT_WORKSPACE);
+  const workspaceDir = resolveUserPath(workspaceInput.trim() || onboardHelpers.DEFAULT_WORKSPACE);
 
+  const { applyOnboardingLocalWorkspaceConfig } = await import("../commands/onboard-config.js");
   let nextConfig: OpenClawConfig = applyOnboardingLocalWorkspaceConfig(baseConfig, workspaceDir);
 
+  const { ensureAuthProfileStore } = await import("../agents/auth-profiles.js");
+  const { promptAuthChoiceGrouped } = await import("../commands/auth-choice-prompt.js");
+  const { promptCustomApiConfig } = await import("../commands/onboard-custom.js");
+  const { applyAuthChoice, resolvePreferredProviderForAuthChoice, warnIfModelConfigLooksOff } =
+    await import("../commands/auth-choice.js");
+  const { applyPrimaryModel, promptDefaultModel } = await import("../commands/model-picker.js");
+
   const authStore = ensureAuthProfileStore(undefined, {
     allowKeychainPrompt: false,
   });
@@ -408,6 +396,7 @@ export async function runOnboardingWizard(
 
   await warnIfModelConfigLooksOff(nextConfig, prompter);
 
+  const { configureGatewayForOnboarding } = await import("./onboarding.gateway-config.js");
   const gateway = await configureGatewayForOnboarding({
     flow,
     baseConfig,
@@ -423,6 +412,8 @@ export async function runOnboardingWizard(
   if (opts.skipChannels ?? opts.skipProviders) {
     await prompter.note("Skipping channel setup.", "Channels");
   } else {
+    const { listChannelPlugins } = await import("../channels/plugins/index.js");
+    const { setupChannels } = await import("../commands/onboard-channels.js");
     const quickstartAllowFromChannels =
       flow === "quickstart"
         ? listChannelPlugins()
@@ -439,23 +430,27 @@ export async function runOnboardingWizard(
   }
 
   await writeConfigFile(nextConfig);
+  const { logConfigUpdated } = await import("../config/logging.js");
   logConfigUpdated(runtime);
-  await ensureWorkspaceAndSessions(workspaceDir, runtime, {
+  await onboardHelpers.ensureWorkspaceAndSessions(workspaceDir, runtime, {
     skipBootstrap: Boolean(nextConfig.agents?.defaults?.skipBootstrap),
   });
 
   if (opts.skipSkills) {
     await prompter.note("Skipping skills setup.", "Skills");
   } else {
+    const { setupSkills } = await import("../commands/onboard-skills.js");
     nextConfig = await setupSkills(nextConfig, workspaceDir, runtime, prompter);
   }
 
   // Setup hooks (session memory on /new)
+  const { setupInternalHooks } = await import("../commands/onboard-hooks.js");
   nextConfig = await setupInternalHooks(nextConfig, runtime, prompter);
 
-  nextConfig = applyWizardMetadata(nextConfig, { command: "onboard", mode });
+  nextConfig = onboardHelpers.applyWizardMetadata(nextConfig, { command: "onboard", mode });
   await writeConfigFile(nextConfig);
 
+  const { finalizeOnboardingWizard } = await import("./onboarding.finalize.js");
   const { launchedTui } = await finalizeOnboardingWizard({
     flow,
     opts,
diff --git a/test/fixtures/child-process-bridge/child.js b/test/fixtures/child-process-bridge/child.js
index 9ef083e42b3..57c7d703e38 100644
--- a/test/fixtures/child-process-bridge/child.js
+++ b/test/fixtures/child-process-bridge/child.js
@@ -1,20 +1,10 @@
-import http from "node:http";
+process.stdout.write("ready\n");
 
-const server = http.createServer((_, res) => {
-  res.writeHead(200, { "content-type": "text/plain" });
-  res.end("ok");
-});
-
-server.listen(0, "127.0.0.1", () => {
-  const addr = server.address();
-  if (!addr || typeof addr === "string") {
-    throw new Error("unexpected address");
-  }
-  process.stdout.write(`${addr.port}\n`);
-});
+const keepAlive = setInterval(() => {}, 1000);
 
 const shutdown = () => {
-  server.close(() => process.exit(0));
+  clearInterval(keepAlive);
+  process.exit(0);
 };
 
 process.on("SIGTERM", shutdown);
diff --git a/test/git-hooks-pre-commit.e2e.test.ts b/test/git-hooks-pre-commit.e2e.test.ts
new file mode 100644
index 00000000000..f2f6d208804
--- /dev/null
+++ b/test/git-hooks-pre-commit.e2e.test.ts
@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync } from "node:fs";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const run = (cwd: string, cmd: string, args: string[] = []) => {
+  return execFileSync(cmd, args, { cwd, encoding: "utf8" }).trim();
+};
+
+describe("git-hooks/pre-commit (integration)", () => {
+  it("does not treat staged filenames as git-add flags (e.g. --all)", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-pre-commit-"));
+    run(dir, "git", ["init", "-q"]);
+
+    // Copy the hook + helpers so the test exercises real on-disk wiring.
+    await mkdir(path.join(dir, "git-hooks"), { recursive: true });
+    await mkdir(path.join(dir, "scripts", "pre-commit"), { recursive: true });
+    copyFileSync(
+      path.join(process.cwd(), "git-hooks", "pre-commit"),
+      path.join(dir, "git-hooks", "pre-commit"),
+    );
+    copyFileSync(
+      path.join(process.cwd(), "scripts", "pre-commit", "run-node-tool.sh"),
+      path.join(dir, "scripts", "pre-commit", "run-node-tool.sh"),
+    );
+    copyFileSync(
+      path.join(process.cwd(), "scripts", "pre-commit", "filter-staged-files.mjs"),
+      path.join(dir, "scripts", "pre-commit", "filter-staged-files.mjs"),
+    );
+    chmodSync(path.join(dir, "git-hooks", "pre-commit"), 0o755);
+    chmodSync(path.join(dir, "scripts", "pre-commit", "run-node-tool.sh"), 0o755);
+
+    // Create an untracked file that should NOT be staged by the hook.
+    await writeFile(path.join(dir, "secret.txt"), "do-not-stage\n");
+
+    // Stage a maliciously-named file. Older hooks using `xargs git add` could run `git add --all`.
+    await writeFile(path.join(dir, "--all"), "flag\n");
+    run(dir, "git", ["add", "--", "--all"]);
+
+    // Run the hook directly (same logic as when installed via core.hooksPath).
+    run(dir, "bash", ["git-hooks/pre-commit"]);
+
+    const staged = run(dir, "git", ["diff", "--cached", "--name-only"]).split("\n").filter(Boolean);
+    expect(staged).toEqual(["--all"]);
+  });
+});
diff --git a/ui/src/styles/chat/layout.css b/ui/src/styles/chat/layout.css
index 821ecbd3abc..3b330cacef9 100644
--- a/ui/src/styles/chat/layout.css
+++ b/ui/src/styles/chat/layout.css
@@ -333,7 +333,7 @@
 
 .chat-controls__session {
   min-width: 140px;
-  max-width: 420px;
+  max-width: 300px;
 }
 
 .chat-controls__thinking {
@@ -400,7 +400,7 @@
 .chat-controls__session select {
   padding: 6px 10px;
   font-size: 13px;
-  max-width: 420px;
+  max-width: 300px;
   overflow: hidden;
   text-overflow: ellipsis;
 }
diff --git a/ui/src/ui/app-lifecycle.ts b/ui/src/ui/app-lifecycle.ts
index 9a9826103a8..a40f5d5ee28 100644
--- a/ui/src/ui/app-lifecycle.ts
+++ b/ui/src/ui/app-lifecycle.ts
@@ -17,10 +17,14 @@ import {
   syncTabWithLocation,
   syncThemeWithSettings,
 } from "./app-settings.ts";
+import { loadControlUiBootstrapConfig } from "./controllers/control-ui-bootstrap.ts";
 
 type LifecycleHost = {
   basePath: string;
   tab: Tab;
+  assistantName: string;
+  assistantAvatar: string | null;
+  assistantAgentId: string | null;
   chatHasAutoScrolled: boolean;
   chatManualRefreshInFlight: boolean;
   chatLoading: boolean;
@@ -36,6 +40,7 @@ type LifecycleHost = {
 
 export function handleConnected(host: LifecycleHost) {
   host.basePath = inferBasePath();
+  void loadControlUiBootstrapConfig(host);
   applySettingsFromUrl(host as unknown as Parameters<typeof applySettingsFromUrl>[0]);
   syncTabWithLocation(host as unknown as Parameters<typeof syncTabWithLocation>[0], true);
   syncThemeWithSettings(host as unknown as Parameters<typeof syncThemeWithSettings>[0]);
diff --git a/ui/src/ui/app-render.helpers.node.test.ts b/ui/src/ui/app-render.helpers.node.test.ts
index c386ccc0f71..ab6ba84396d 100644
--- a/ui/src/ui/app-render.helpers.node.test.ts
+++ b/ui/src/ui/app-render.helpers.node.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { SessionsListResult } from "./types.ts";
-import { resolveSessionDisplayName } from "./app-render.helpers.ts";
+import { parseSessionKey, resolveSessionDisplayName } from "./app-render.helpers.ts";
 
 type SessionRow = SessionsListResult["sessions"][number];
 
@@ -8,72 +8,238 @@ function row(overrides: Partial<SessionRow> & { key: string }): SessionRow {
   return { kind: "direct", updatedAt: 0, ...overrides };
 }
 
-describe("resolveSessionDisplayName", () => {
-  it("returns key when no row is provided", () => {
-    expect(resolveSessionDisplayName("agent:main:main")).toBe("agent:main:main");
+/* ================================================================
+ *  parseSessionKey – low-level key → type / fallback mapping
+ * ================================================================ */
+
+describe("parseSessionKey", () => {
+  it("identifies main session (bare 'main')", () => {
+    expect(parseSessionKey("main")).toEqual({ prefix: "", fallbackName: "Main Session" });
   });
 
-  it("returns key when row has no label or displayName", () => {
-    expect(resolveSessionDisplayName("agent:main:main", row({ key: "agent:main:main" }))).toBe(
-      "agent:main:main",
+  it("identifies main session (agent:main:main)", () => {
+    expect(parseSessionKey("agent:main:main")).toEqual({
+      prefix: "",
+      fallbackName: "Main Session",
+    });
+  });
+
+  it("identifies subagent sessions", () => {
+    expect(parseSessionKey("agent:main:subagent:18abfefe-1fa6-43cb-8ba8-ebdc9b43e253")).toEqual({
+      prefix: "Subagent:",
+      fallbackName: "Subagent:",
+    });
+  });
+
+  it("identifies cron sessions", () => {
+    expect(parseSessionKey("agent:main:cron:daily-briefing-uuid")).toEqual({
+      prefix: "Cron:",
+      fallbackName: "Cron Job:",
+    });
+  });
+
+  it("identifies direct chat with known channel", () => {
+    expect(parseSessionKey("agent:main:bluebubbles:direct:+19257864429")).toEqual({
+      prefix: "",
+      fallbackName: "iMessage · +19257864429",
+    });
+  });
+
+  it("identifies direct chat with telegram", () => {
+    expect(parseSessionKey("agent:main:telegram:direct:user123")).toEqual({
+      prefix: "",
+      fallbackName: "Telegram · user123",
+    });
+  });
+
+  it("identifies group chat with known channel", () => {
+    expect(parseSessionKey("agent:main:discord:group:guild-chan")).toEqual({
+      prefix: "",
+      fallbackName: "Discord Group",
+    });
+  });
+
+  it("capitalises unknown channels in direct/group patterns", () => {
+    expect(parseSessionKey("agent:main:mychannel:direct:user1")).toEqual({
+      prefix: "",
+      fallbackName: "Mychannel · user1",
+    });
+  });
+
+  it("identifies channel-prefixed legacy keys", () => {
+    expect(parseSessionKey("bluebubbles:g-agent-main-bluebubbles-direct-+19257864429")).toEqual({
+      prefix: "",
+      fallbackName: "iMessage Session",
+    });
+    expect(parseSessionKey("discord:123:456")).toEqual({
+      prefix: "",
+      fallbackName: "Discord Session",
+    });
+  });
+
+  it("handles bare channel name as key", () => {
+    expect(parseSessionKey("telegram")).toEqual({
+      prefix: "",
+      fallbackName: "Telegram Session",
+    });
+  });
+
+  it("returns raw key for unknown patterns", () => {
+    expect(parseSessionKey("something-unknown")).toEqual({
+      prefix: "",
+      fallbackName: "something-unknown",
+    });
+  });
+});
+
+/* ================================================================
+ *  resolveSessionDisplayName – full resolution with row data
+ * ================================================================ */
+
+describe("resolveSessionDisplayName", () => {
+  // ── Key-only fallbacks (no row) ──────────────────
+
+  it("returns 'Main Session' for agent:main:main key", () => {
+    expect(resolveSessionDisplayName("agent:main:main")).toBe("Main Session");
+  });
+
+  it("returns 'Main Session' for bare 'main' key", () => {
+    expect(resolveSessionDisplayName("main")).toBe("Main Session");
+  });
+
+  it("returns 'Subagent:' for subagent key without row", () => {
+    expect(resolveSessionDisplayName("agent:main:subagent:abc-123")).toBe("Subagent:");
+  });
+
+  it("returns 'Cron Job:' for cron key without row", () => {
+    expect(resolveSessionDisplayName("agent:main:cron:abc-123")).toBe("Cron Job:");
+  });
+
+  it("parses direct chat key with channel", () => {
+    expect(resolveSessionDisplayName("agent:main:bluebubbles:direct:+19257864429")).toBe(
+      "iMessage · +19257864429",
     );
   });
 
-  it("returns key when displayName matches key", () => {
+  it("parses channel-prefixed legacy key", () => {
+    expect(resolveSessionDisplayName("discord:123:456")).toBe("Discord Session");
+  });
+
+  it("returns raw key for unknown patterns", () => {
+    expect(resolveSessionDisplayName("something-custom")).toBe("something-custom");
+  });
+
+  // ── With row data (label / displayName) ──────────
+
+  it("returns parsed fallback when row has no label or displayName", () => {
+    expect(resolveSessionDisplayName("agent:main:main", row({ key: "agent:main:main" }))).toBe(
+      "Main Session",
+    );
+  });
+
+  it("returns parsed fallback when displayName matches key", () => {
     expect(resolveSessionDisplayName("mykey", row({ key: "mykey", displayName: "mykey" }))).toBe(
       "mykey",
     );
   });
 
-  it("returns key when label matches key", () => {
+  it("returns parsed fallback when label matches key", () => {
     expect(resolveSessionDisplayName("mykey", row({ key: "mykey", label: "mykey" }))).toBe("mykey");
   });
 
-  it("uses displayName prominently when available", () => {
-    expect(
-      resolveSessionDisplayName(
-        "discord:123:456",
-        row({ key: "discord:123:456", displayName: "My Chat" }),
-      ),
-    ).toBe("My Chat (discord:123:456)");
-  });
-
-  it("falls back to label when displayName is absent", () => {
+  it("uses label alone when available", () => {
     expect(
       resolveSessionDisplayName(
         "discord:123:456",
         row({ key: "discord:123:456", label: "General" }),
       ),
-    ).toBe("General (discord:123:456)");
+    ).toBe("General");
   });
 
-  it("prefers displayName over label when both are present", () => {
+  it("falls back to displayName when label is absent", () => {
+    expect(
+      resolveSessionDisplayName(
+        "discord:123:456",
+        row({ key: "discord:123:456", displayName: "My Chat" }),
+      ),
+    ).toBe("My Chat");
+  });
+
+  it("prefers label over displayName when both are present", () => {
     expect(
       resolveSessionDisplayName(
         "discord:123:456",
         row({ key: "discord:123:456", displayName: "My Chat", label: "General" }),
       ),
-    ).toBe("My Chat (discord:123:456)");
+    ).toBe("General");
   });
 
-  it("ignores whitespace-only displayName", () => {
+  it("ignores whitespace-only label and falls back to displayName", () => {
     expect(
       resolveSessionDisplayName(
         "discord:123:456",
-        row({ key: "discord:123:456", displayName: "   ", label: "General" }),
+        row({ key: "discord:123:456", displayName: "My Chat", label: "   " }),
       ),
-    ).toBe("General (discord:123:456)");
+    ).toBe("My Chat");
   });
 
-  it("ignores whitespace-only label", () => {
+  it("uses parsed fallback when whitespace-only label and no displayName", () => {
     expect(
       resolveSessionDisplayName("discord:123:456", row({ key: "discord:123:456", label: "   " })),
-    ).toBe("discord:123:456");
+    ).toBe("Discord Session");
   });
 
-  it("trims displayName and label", () => {
+  it("trims label and displayName", () => {
+    expect(resolveSessionDisplayName("k", row({ key: "k", label: "  General  " }))).toBe("General");
     expect(resolveSessionDisplayName("k", row({ key: "k", displayName: "  My Chat  " }))).toBe(
-      "My Chat (k)",
+      "My Chat",
     );
   });
+
+  // ── Type prefixes applied to labels / displayNames ──
+
+  it("prefixes subagent label with Subagent:", () => {
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:subagent:abc-123",
+        row({ key: "agent:main:subagent:abc-123", label: "maintainer-v2" }),
+      ),
+    ).toBe("Subagent: maintainer-v2");
+  });
+
+  it("prefixes subagent displayName with Subagent:", () => {
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:subagent:abc-123",
+        row({ key: "agent:main:subagent:abc-123", displayName: "Task Runner" }),
+      ),
+    ).toBe("Subagent: Task Runner");
+  });
+
+  it("prefixes cron label with Cron:", () => {
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:cron:abc-123",
+        row({ key: "agent:main:cron:abc-123", label: "daily-briefing" }),
+      ),
+    ).toBe("Cron: daily-briefing");
+  });
+
+  it("prefixes cron displayName with Cron:", () => {
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:cron:abc-123",
+        row({ key: "agent:main:cron:abc-123", displayName: "Nightly Sync" }),
+      ),
+    ).toBe("Cron: Nightly Sync");
+  });
+
+  it("does not prefix non-typed sessions with labels", () => {
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:bluebubbles:direct:+19257864429",
+        row({ key: "agent:main:bluebubbles:direct:+19257864429", label: "Tyler" }),
+      ),
+    ).toBe("Tyler");
+  });
 });
diff --git a/ui/src/ui/app-render.helpers.ts b/ui/src/ui/app-render.helpers.ts
index a7e0b9aa2b3..dcc8843bae2 100644
--- a/ui/src/ui/app-render.helpers.ts
+++ b/ui/src/ui/app-render.helpers.ts
@@ -159,7 +159,7 @@ export function renderChatControls(state: AppViewState) {
             sessionOptions,
             (entry) => entry.key,
             (entry) =>
-              html`<option value=${entry.key}>
+              html`<option value=${entry.key} title=${entry.key}>
                 ${entry.displayName ?? entry.key}
               </option>`,
           )}
@@ -256,19 +256,96 @@ function resolveMainSessionKey(
   return null;
 }
 
+/* ── Channel display labels ────────────────────────────── */
+const CHANNEL_LABELS: Record<string, string> = {
+  bluebubbles: "iMessage",
+  telegram: "Telegram",
+  discord: "Discord",
+  signal: "Signal",
+  slack: "Slack",
+  whatsapp: "WhatsApp",
+  matrix: "Matrix",
+  email: "Email",
+  sms: "SMS",
+};
+
+const KNOWN_CHANNEL_KEYS = Object.keys(CHANNEL_LABELS);
+
+/** Parsed type / context extracted from a session key. */
+export type SessionKeyInfo = {
+  /** Prefix for typed sessions (Subagent:/Cron:). Empty for others. */
+  prefix: string;
+  /** Human-readable fallback when no label / displayName is available. */
+  fallbackName: string;
+};
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Parse a session key to extract type information and a human-readable
+ * fallback display name.  Exported for testing.
+ */
+export function parseSessionKey(key: string): SessionKeyInfo {
+  // ── Main session ─────────────────────────────────
+  if (key === "main" || key === "agent:main:main") {
+    return { prefix: "", fallbackName: "Main Session" };
+  }
+
+  // ── Subagent ─────────────────────────────────────
+  if (key.includes(":subagent:")) {
+    return { prefix: "Subagent:", fallbackName: "Subagent:" };
+  }
+
+  // ── Cron job ─────────────────────────────────────
+  if (key.includes(":cron:")) {
+    return { prefix: "Cron:", fallbackName: "Cron Job:" };
+  }
+
+  // ── Direct chat  (agent:<x>:<channel>:direct:<id>) ──
+  const directMatch = key.match(/^agent:[^:]+:([^:]+):direct:(.+)$/);
+  if (directMatch) {
+    const channel = directMatch[1];
+    const identifier = directMatch[2];
+    const channelLabel = CHANNEL_LABELS[channel] ?? capitalize(channel);
+    return { prefix: "", fallbackName: `${channelLabel} · ${identifier}` };
+  }
+
+  // ── Group chat  (agent:<x>:<channel>:group:<id>) ────
+  const groupMatch = key.match(/^agent:[^:]+:([^:]+):group:(.+)$/);
+  if (groupMatch) {
+    const channel = groupMatch[1];
+    const channelLabel = CHANNEL_LABELS[channel] ?? capitalize(channel);
+    return { prefix: "", fallbackName: `${channelLabel} Group` };
+  }
+
+  // ── Channel-prefixed legacy keys (e.g. "bluebubbles:g-…") ──
+  for (const ch of KNOWN_CHANNEL_KEYS) {
+    if (key === ch || key.startsWith(`${ch}:`)) {
+      return { prefix: "", fallbackName: `${CHANNEL_LABELS[ch]} Session` };
+    }
+  }
+
+  // ── Unknown — return key as-is ───────────────────
+  return { prefix: "", fallbackName: key };
+}
+
 export function resolveSessionDisplayName(
   key: string,
   row?: SessionsListResult["sessions"][number],
-) {
-  const displayName = row?.displayName?.trim() || "";
+): string {
   const label = row?.label?.trim() || "";
-  if (displayName && displayName !== key) {
-    return `${displayName} (${key})`;
-  }
+  const displayName = row?.displayName?.trim() || "";
+  const { prefix, fallbackName } = parseSessionKey(key);
+
   if (label && label !== key) {
-    return `${label} (${key})`;
+    return prefix ? `${prefix} ${label}` : label;
   }
-  return key;
+  if (displayName && displayName !== key) {
+    return prefix ? `${prefix} ${displayName}` : displayName;
+  }
+  return fallbackName;
 }
 
 function resolveSessionOptions(
diff --git a/ui/src/ui/app-render.ts b/ui/src/ui/app-render.ts
index 3e9662b6214..c48282461eb 100644
--- a/ui/src/ui/app-render.ts
+++ b/ui/src/ui/app-render.ts
@@ -24,6 +24,7 @@ import {
   runCronJob,
   removeCronJob,
   addCronJob,
+  normalizeCronFormState,
 } from "./controllers/cron.ts";
 import { loadDebug, callDebugMethod } from "./controllers/debug.ts";
 import {
@@ -323,7 +324,8 @@ export function renderApp(state: AppViewState) {
                 channelMeta: state.channelsSnapshot?.channelMeta ?? [],
                 runsJobId: state.cronRunsJobId,
                 runs: state.cronRuns,
-                onFormChange: (patch) => (state.cronForm = { ...state.cronForm, ...patch }),
+                onFormChange: (patch) =>
+                  (state.cronForm = normalizeCronFormState({ ...state.cronForm, ...patch })),
                 onRefresh: () => state.loadCron(),
                 onAdd: () => addCronJob(state),
                 onToggle: (job, enabled) => toggleCronJob(state, job, enabled),
diff --git a/ui/src/ui/app.ts b/ui/src/ui/app.ts
index bb2c9f1540f..8709cbd32d0 100644
--- a/ui/src/ui/app.ts
+++ b/ui/src/ui/app.ts
@@ -76,7 +76,7 @@ import {
   type ToolStreamEntry,
   type CompactionStatus,
 } from "./app-tool-stream.ts";
-import { resolveInjectedAssistantIdentity } from "./assistant-identity.ts";
+import { normalizeAssistantIdentity } from "./assistant-identity.ts";
 import { loadAssistantIdentity as loadAssistantIdentityInternal } from "./controllers/assistant-identity.ts";
 import { loadSettings, type UiSettings } from "./storage.ts";
 import { type ChatAttachment, type ChatQueueItem, type CronFormState } from "./ui-types.ts";
@@ -87,7 +87,7 @@ declare global {
   }
 }
 
-const injectedAssistantIdentity = resolveInjectedAssistantIdentity();
+const bootAssistantIdentity = normalizeAssistantIdentity({});
 
 function resolveOnboardingMode(): boolean {
   if (!window.location.search) {
@@ -118,9 +118,9 @@ export class OpenClawApp extends LitElement {
   private toolStreamSyncTimer: number | null = null;
   private sidebarCloseTimer: number | null = null;
 
-  @state() assistantName = injectedAssistantIdentity.name;
-  @state() assistantAvatar = injectedAssistantIdentity.avatar;
-  @state() assistantAgentId = injectedAssistantIdentity.agentId ?? null;
+  @state() assistantName = bootAssistantIdentity.name;
+  @state() assistantAvatar = bootAssistantIdentity.avatar;
+  @state() assistantAgentId = bootAssistantIdentity.agentId ?? null;
 
   @state() sessionKey = this.settings.sessionKey;
   @state() chatLoading = false;
diff --git a/ui/src/ui/assistant-identity.ts b/ui/src/ui/assistant-identity.ts
index 4b9fef54e10..3f6e14fa925 100644
--- a/ui/src/ui/assistant-identity.ts
+++ b/ui/src/ui/assistant-identity.ts
@@ -10,13 +10,6 @@ export type AssistantIdentity = {
   avatar: string | null;
 };
 
-declare global {
-  interface Window {
-    __OPENCLAW_ASSISTANT_NAME__?: string;
-    __OPENCLAW_ASSISTANT_AVATAR__?: string;
-  }
-}
-
 function coerceIdentityValue(value: string | undefined, maxLength: number): string | undefined {
   if (typeof value !== "string") {
     return undefined;
@@ -40,13 +33,3 @@ export function normalizeAssistantIdentity(
     typeof input?.agentId === "string" && input.agentId.trim() ? input.agentId.trim() : null;
   return { agentId, name, avatar };
 }
-
-export function resolveInjectedAssistantIdentity(): AssistantIdentity {
-  if (typeof window === "undefined") {
-    return normalizeAssistantIdentity({});
-  }
-  return normalizeAssistantIdentity({
-    name: window.__OPENCLAW_ASSISTANT_NAME__,
-    avatar: window.__OPENCLAW_ASSISTANT_AVATAR__,
-  });
-}
diff --git a/ui/src/ui/chat-markdown.browser.test.ts b/ui/src/ui/chat-markdown.browser.test.ts
index c0e692b0732..17a898bac4c 100644
--- a/ui/src/ui/chat-markdown.browser.test.ts
+++ b/ui/src/ui/chat-markdown.browser.test.ts
@@ -1,31 +1,7 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { OpenClawApp } from "./app.ts";
+import { describe, expect, it } from "vitest";
+import { mountApp, registerAppMountHooks } from "./test-helpers/app-mount.ts";
 
-// oxlint-disable-next-line typescript/unbound-method
-const originalConnect = OpenClawApp.prototype.connect;
-
-function mountApp(pathname: string) {
-  window.history.replaceState({}, "", pathname);
-  const app = document.createElement("openclaw-app") as OpenClawApp;
-  document.body.append(app);
-  return app;
-}
-
-beforeEach(() => {
-  OpenClawApp.prototype.connect = () => {
-    // no-op: avoid real gateway WS connections in browser tests
-  };
-  window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
-  localStorage.clear();
-  document.body.innerHTML = "";
-});
-
-afterEach(() => {
-  OpenClawApp.prototype.connect = originalConnect;
-  window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
-  localStorage.clear();
-  document.body.innerHTML = "";
-});
+registerAppMountHooks();
 
 describe("chat markdown rendering", () => {
   it("renders markdown inside tool output sidebar", async () => {
diff --git a/ui/src/ui/controllers/chat.test.ts b/ui/src/ui/controllers/chat.test.ts
index b99c38cae1d..2989092ae3b 100644
--- a/ui/src/ui/controllers/chat.test.ts
+++ b/ui/src/ui/controllers/chat.test.ts
@@ -92,4 +92,125 @@ describe("handleChatEvent", () => {
     expect(state.chatStream).toBe(null);
     expect(state.chatStreamStartedAt).toBe(null);
   });
+
+  it("processes aborted from own run and keeps partial assistant message", () => {
+    const existingMessage = {
+      role: "user",
+      content: [{ type: "text", text: "Hi" }],
+      timestamp: 1,
+    };
+    const partialMessage = {
+      role: "assistant",
+      content: [{ type: "text", text: "Partial reply" }],
+      timestamp: 2,
+    };
+    const state = createState({
+      sessionKey: "main",
+      chatRunId: "run-1",
+      chatStream: "Partial reply",
+      chatStreamStartedAt: 100,
+      chatMessages: [existingMessage],
+    });
+    const payload: ChatEventPayload = {
+      runId: "run-1",
+      sessionKey: "main",
+      state: "aborted",
+      message: partialMessage,
+    };
+
+    expect(handleChatEvent(state, payload)).toBe("aborted");
+    expect(state.chatRunId).toBe(null);
+    expect(state.chatStream).toBe(null);
+    expect(state.chatStreamStartedAt).toBe(null);
+    expect(state.chatMessages).toEqual([existingMessage, partialMessage]);
+  });
+
+  it("falls back to streamed partial when aborted payload message is invalid", () => {
+    const existingMessage = {
+      role: "user",
+      content: [{ type: "text", text: "Hi" }],
+      timestamp: 1,
+    };
+    const state = createState({
+      sessionKey: "main",
+      chatRunId: "run-1",
+      chatStream: "Partial reply",
+      chatStreamStartedAt: 100,
+      chatMessages: [existingMessage],
+    });
+    const payload = {
+      runId: "run-1",
+      sessionKey: "main",
+      state: "aborted",
+      message: "not-an-assistant-message",
+    } as unknown as ChatEventPayload;
+
+    expect(handleChatEvent(state, payload)).toBe("aborted");
+    expect(state.chatRunId).toBe(null);
+    expect(state.chatStream).toBe(null);
+    expect(state.chatStreamStartedAt).toBe(null);
+    expect(state.chatMessages).toHaveLength(2);
+    expect(state.chatMessages[0]).toEqual(existingMessage);
+    expect(state.chatMessages[1]).toMatchObject({
+      role: "assistant",
+      content: [{ type: "text", text: "Partial reply" }],
+    });
+  });
+
+  it("falls back to streamed partial when aborted payload has non-assistant role", () => {
+    const existingMessage = {
+      role: "user",
+      content: [{ type: "text", text: "Hi" }],
+      timestamp: 1,
+    };
+    const state = createState({
+      sessionKey: "main",
+      chatRunId: "run-1",
+      chatStream: "Partial reply",
+      chatStreamStartedAt: 100,
+      chatMessages: [existingMessage],
+    });
+    const payload: ChatEventPayload = {
+      runId: "run-1",
+      sessionKey: "main",
+      state: "aborted",
+      message: {
+        role: "user",
+        content: [{ type: "text", text: "unexpected" }],
+      },
+    };
+
+    expect(handleChatEvent(state, payload)).toBe("aborted");
+    expect(state.chatMessages).toHaveLength(2);
+    expect(state.chatMessages[1]).toMatchObject({
+      role: "assistant",
+      content: [{ type: "text", text: "Partial reply" }],
+    });
+  });
+
+  it("processes aborted from own run without message and empty stream", () => {
+    const existingMessage = {
+      role: "user",
+      content: [{ type: "text", text: "Hi" }],
+      timestamp: 1,
+    };
+    const state = createState({
+      sessionKey: "main",
+      chatRunId: "run-1",
+      chatStream: "",
+      chatStreamStartedAt: 100,
+      chatMessages: [existingMessage],
+    });
+    const payload: ChatEventPayload = {
+      runId: "run-1",
+      sessionKey: "main",
+      state: "aborted",
+    };
+
+    expect(handleChatEvent(state, payload)).toBe("aborted");
+    expect(state.chatRunId).toBe(null);
+    expect(state.chatStream).toBe(null);
+    expect(state.chatStreamStartedAt).toBe(null);
+    expect(state.chatMessages).toEqual([existingMessage]);
+  });
 });
diff --git a/ui/src/ui/controllers/chat.ts b/ui/src/ui/controllers/chat.ts
index 127e03dd4d2..4990b6a7aa3 100644
--- a/ui/src/ui/controllers/chat.ts
+++ b/ui/src/ui/controllers/chat.ts
@@ -58,6 +58,20 @@ function dataUrlToBase64(dataUrl: string): { content: string; mimeType: string }
   return { mimeType: match[1], content: match[2] };
 }
 
+function normalizeAbortedAssistantMessage(message: unknown): Record<string, unknown> | null {
+  if (!message || typeof message !== "object") {
+    return null;
+  }
+  const candidate = message as Record<string, unknown>;
+  if (candidate.role !== "assistant") {
+    return null;
+  }
+  if (!("content" in candidate) || !Array.isArray(candidate.content)) {
+    return null;
+  }
+  return candidate;
+}
+
 export async function sendChatMessage(
   state: ChatState,
   message: string,
@@ -198,6 +212,22 @@ export function handleChatEvent(state: ChatState, payload?: ChatEventPayload) {
     state.chatRunId = null;
     state.chatStreamStartedAt = null;
   } else if (payload.state === "aborted") {
+    const normalizedMessage = normalizeAbortedAssistantMessage(payload.message);
+    if (normalizedMessage) {
+      state.chatMessages = [...state.chatMessages, normalizedMessage];
+    } else {
+      const streamedText = state.chatStream ?? "";
+      if (streamedText.trim()) {
+        state.chatMessages = [
+          ...state.chatMessages,
+          {
+            role: "assistant",
+            content: [{ type: "text", text: streamedText }],
+            timestamp: Date.now(),
+          },
+        ];
+      }
+    }
     state.chatStream = null;
     state.chatRunId = null;
     state.chatStreamStartedAt = null;
diff --git a/ui/src/ui/controllers/control-ui-bootstrap.test.ts b/ui/src/ui/controllers/control-ui-bootstrap.test.ts
new file mode 100644
index 00000000000..29e66fab854
--- /dev/null
+++ b/ui/src/ui/controllers/control-ui-bootstrap.test.ts
@@ -0,0 +1,82 @@
+/* @vitest-environment jsdom */
+
+import { describe, expect, it, vi } from "vitest";
+import { CONTROL_UI_BOOTSTRAP_CONFIG_PATH } from "../../../../src/gateway/control-ui-contract.js";
+import { loadControlUiBootstrapConfig } from "./control-ui-bootstrap.ts";
+
+describe("loadControlUiBootstrapConfig", () => {
+  it("loads assistant identity from the bootstrap endpoint", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        basePath: "/openclaw",
+        assistantName: "Ops",
+        assistantAvatar: "O",
+        assistantAgentId: "main",
+      }),
+    });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const state = {
+      basePath: "/openclaw",
+      assistantName: "Assistant",
+      assistantAvatar: null,
+      assistantAgentId: null,
+    };
+
+    await loadControlUiBootstrapConfig(state);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      `/openclaw${CONTROL_UI_BOOTSTRAP_CONFIG_PATH}`,
+      expect.objectContaining({ method: "GET" }),
+    );
+    expect(state.assistantName).toBe("Ops");
+    expect(state.assistantAvatar).toBe("O");
+    expect(state.assistantAgentId).toBe("main");
+
+    vi.unstubAllGlobals();
+  });
+
+  it("ignores failures", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: false });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const state = {
+      basePath: "",
+      assistantName: "Assistant",
+      assistantAvatar: null,
+      assistantAgentId: null,
+    };
+
+    await loadControlUiBootstrapConfig(state);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      CONTROL_UI_BOOTSTRAP_CONFIG_PATH,
+      expect.objectContaining({ method: "GET" }),
+    );
+    expect(state.assistantName).toBe("Assistant");
+
+    vi.unstubAllGlobals();
+  });
+
+  it("normalizes trailing slash basePath for bootstrap fetch path", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({ ok: false });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const state = {
+      basePath: "/openclaw/",
+      assistantName: "Assistant",
+      assistantAvatar: null,
+      assistantAgentId: null,
+    };
+
+    await loadControlUiBootstrapConfig(state);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      `/openclaw${CONTROL_UI_BOOTSTRAP_CONFIG_PATH}`,
+      expect.objectContaining({ method: "GET" }),
+    );
+
+    vi.unstubAllGlobals();
+  });
+});
diff --git a/ui/src/ui/controllers/control-ui-bootstrap.ts b/ui/src/ui/controllers/control-ui-bootstrap.ts
new file mode 100644
index 00000000000..a996e1265d3
--- /dev/null
+++ b/ui/src/ui/controllers/control-ui-bootstrap.ts
@@ -0,0 +1,49 @@
+import {
+  CONTROL_UI_BOOTSTRAP_CONFIG_PATH,
+  type ControlUiBootstrapConfig,
+} from "../../../../src/gateway/control-ui-contract.js";
+import { normalizeAssistantIdentity } from "../assistant-identity.ts";
+import { normalizeBasePath } from "../navigation.ts";
+
+export type ControlUiBootstrapState = {
+  basePath: string;
+  assistantName: string;
+  assistantAvatar: string | null;
+  assistantAgentId: string | null;
+};
+
+export async function loadControlUiBootstrapConfig(state: ControlUiBootstrapState) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  if (typeof fetch !== "function") {
+    return;
+  }
+
+  const basePath = normalizeBasePath(state.basePath ?? "");
+  const url = basePath
+    ? `${basePath}${CONTROL_UI_BOOTSTRAP_CONFIG_PATH}`
+    : CONTROL_UI_BOOTSTRAP_CONFIG_PATH;
+
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      credentials: "same-origin",
+    });
+    if (!res.ok) {
+      return;
+    }
+    const parsed = (await res.json()) as ControlUiBootstrapConfig;
+    const normalized = normalizeAssistantIdentity({
+      agentId: parsed.assistantAgentId ?? null,
+      name: parsed.assistantName,
+      avatar: parsed.assistantAvatar ?? null,
+    });
+    state.assistantName = normalized.name;
+    state.assistantAvatar = normalized.avatar;
+    state.assistantAgentId = normalized.agentId ?? null;
+  } catch {
+    // Ignore bootstrap failures; UI will update identity after connecting.
+  }
+}
diff --git a/ui/src/ui/controllers/cron.test.ts b/ui/src/ui/controllers/cron.test.ts
new file mode 100644
index 00000000000..66d05286a3b
--- /dev/null
+++ b/ui/src/ui/controllers/cron.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it, vi } from "vitest";
+import { DEFAULT_CRON_FORM } from "../app-defaults.ts";
+import { addCronJob, normalizeCronFormState, type CronState } from "./cron.ts";
+
+function createState(overrides: Partial<CronState> = {}): CronState {
+  return {
+    client: null,
+    connected: true,
+    cronLoading: false,
+    cronJobs: [],
+    cronStatus: null,
+    cronError: null,
+    cronForm: { ...DEFAULT_CRON_FORM },
+    cronRunsJobId: null,
+    cronRuns: [],
+    cronBusy: false,
+    ...overrides,
+  };
+}
+
+describe("cron controller", () => {
+  it("normalizes stale announce mode when session/payload no longer support announce", () => {
+    const normalized = normalizeCronFormState({
+      ...DEFAULT_CRON_FORM,
+      sessionTarget: "main",
+      payloadKind: "systemEvent",
+      deliveryMode: "announce",
+    });
+
+    expect(normalized.deliveryMode).toBe("none");
+  });
+
+  it("keeps announce mode when isolated agentTurn supports announce", () => {
+    const normalized = normalizeCronFormState({
+      ...DEFAULT_CRON_FORM,
+      sessionTarget: "isolated",
+      payloadKind: "agentTurn",
+      deliveryMode: "announce",
+    });
+
+    expect(normalized.deliveryMode).toBe("announce");
+  });
+
+  it("forwards webhook delivery in cron.add payload", async () => {
+    const request = vi.fn(async (method: string, _payload?: unknown) => {
+      if (method === "cron.add") {
+        return { id: "job-1" };
+      }
+      if (method === "cron.list") {
+        return { jobs: [] };
+      }
+      if (method === "cron.status") {
+        return { enabled: true, jobs: 0, nextWakeAtMs: null };
+      }
+      return {};
+    });
+
+    const state = createState({
+      client: {
+        request,
+      } as unknown as CronState["client"],
+      cronForm: {
+        ...DEFAULT_CRON_FORM,
+        name: "webhook job",
+        scheduleKind: "every",
+        everyAmount: "1",
+        everyUnit: "minutes",
+        sessionTarget: "isolated",
+        wakeMode: "next-heartbeat",
+        payloadKind: "agentTurn",
+        payloadText: "run this",
+        deliveryMode: "webhook",
+        deliveryTo: "https://example.invalid/cron",
+      },
+    });
+
+    await addCronJob(state);
+
+    const addCall = request.mock.calls.find(([method]) => method === "cron.add");
+    expect(addCall).toBeDefined();
+    expect(addCall?.[1]).toMatchObject({
+      name: "webhook job",
+      delivery: { mode: "webhook", to: "https://example.invalid/cron" },
+    });
+  });
+
+  it("does not submit stale announce delivery when unsupported", async () => {
+    const request = vi.fn(async (method: string, _payload?: unknown) => {
+      if (method === "cron.add") {
+        return { id: "job-2" };
+      }
+      if (method === "cron.list") {
+        return { jobs: [] };
+      }
+      if (method === "cron.status") {
+        return { enabled: true, jobs: 0, nextWakeAtMs: null };
+      }
+      return {};
+    });
+
+    const state = createState({
+      client: {
+        request,
+      } as unknown as CronState["client"],
+      cronForm: {
+        ...DEFAULT_CRON_FORM,
+        name: "main job",
+        scheduleKind: "every",
+        everyAmount: "1",
+        everyUnit: "minutes",
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payloadKind: "systemEvent",
+        payloadText: "run this",
+        deliveryMode: "announce",
+        deliveryTo: "buddy",
+      },
+    });
+
+    await addCronJob(state);
+
+    const addCall = request.mock.calls.find(([method]) => method === "cron.add");
+    expect(addCall).toBeDefined();
+    expect(addCall?.[1]).toMatchObject({
+      name: "main job",
+    });
+    expect((addCall?.[1] as { delivery?: unknown } | undefined)?.delivery).toBeUndefined();
+    expect(state.cronForm.deliveryMode).toBe("none");
+  });
+});
diff --git a/ui/src/ui/controllers/cron.ts b/ui/src/ui/controllers/cron.ts
index 190311bca6c..fbb7d65dbc9 100644
--- a/ui/src/ui/controllers/cron.ts
+++ b/ui/src/ui/controllers/cron.ts
@@ -16,6 +16,25 @@ export type CronState = {
   cronBusy: boolean;
 };
 
+export function supportsAnnounceDelivery(
+  form: Pick<CronFormState, "sessionTarget" | "payloadKind">,
+) {
+  return form.sessionTarget === "isolated" && form.payloadKind === "agentTurn";
+}
+
+export function normalizeCronFormState(form: CronFormState): CronFormState {
+  if (form.deliveryMode !== "announce") {
+    return form;
+  }
+  if (supportsAnnounceDelivery(form)) {
+    return form;
+  }
+  return {
+    ...form,
+    deliveryMode: "none",
+  };
+}
+
 export async function loadCronStatus(state: CronState) {
   if (!state.client || !state.connected) {
     return;
@@ -104,27 +123,34 @@ export async function addCronJob(state: CronState) {
   state.cronBusy = true;
   state.cronError = null;
   try {
-    const schedule = buildCronSchedule(state.cronForm);
-    const payload = buildCronPayload(state.cronForm);
+    const form = normalizeCronFormState(state.cronForm);
+    if (form !== state.cronForm) {
+      state.cronForm = form;
+    }
+
+    const schedule = buildCronSchedule(form);
+    const payload = buildCronPayload(form);
+    const selectedDeliveryMode = form.deliveryMode;
     const delivery =
-      state.cronForm.sessionTarget === "isolated" &&
-      state.cronForm.payloadKind === "agentTurn" &&
-      state.cronForm.deliveryMode
+      selectedDeliveryMode && selectedDeliveryMode !== "none"
         ? {
-            mode: state.cronForm.deliveryMode === "announce" ? "announce" : "none",
-            channel: state.cronForm.deliveryChannel.trim() || "last",
-            to: state.cronForm.deliveryTo.trim() || undefined,
+            mode: selectedDeliveryMode,
+            channel:
+              selectedDeliveryMode === "announce"
+                ? form.deliveryChannel.trim() || "last"
+                : undefined,
+            to: form.deliveryTo.trim() || undefined,
           }
         : undefined;
-    const agentId = state.cronForm.agentId.trim();
+    const agentId = form.agentId.trim();
     const job = {
-      name: state.cronForm.name.trim(),
-      description: state.cronForm.description.trim() || undefined,
+      name: form.name.trim(),
+      description: form.description.trim() || undefined,
       agentId: agentId || undefined,
-      enabled: state.cronForm.enabled,
+      enabled: form.enabled,
       schedule,
-      sessionTarget: state.cronForm.sessionTarget,
-      wakeMode: state.cronForm.wakeMode,
+      sessionTarget: form.sessionTarget,
+      wakeMode: form.wakeMode,
       payload,
       delivery,
     };
diff --git a/ui/src/ui/focus-mode.browser.test.ts b/ui/src/ui/focus-mode.browser.test.ts
index 9576100d1e9..c134ecb5bf5 100644
--- a/ui/src/ui/focus-mode.browser.test.ts
+++ b/ui/src/ui/focus-mode.browser.test.ts
@@ -1,31 +1,7 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { OpenClawApp } from "./app.ts";
+import { describe, expect, it } from "vitest";
+import { mountApp, registerAppMountHooks } from "./test-helpers/app-mount.ts";
 
-// oxlint-disable-next-line typescript/unbound-method
-const originalConnect = OpenClawApp.prototype.connect;
-
-function mountApp(pathname: string) {
-  window.history.replaceState({}, "", pathname);
-  const app = document.createElement("openclaw-app") as OpenClawApp;
-  document.body.append(app);
-  return app;
-}
-
-beforeEach(() => {
-  OpenClawApp.prototype.connect = () => {
-    // no-op: avoid real gateway WS connections in browser tests
-  };
-  window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
-  localStorage.clear();
-  document.body.innerHTML = "";
-});
-
-afterEach(() => {
-  OpenClawApp.prototype.connect = originalConnect;
-  window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
-  localStorage.clear();
-  document.body.innerHTML = "";
-});
+registerAppMountHooks();
 
 describe("chat focus mode", () => {
   it("collapses header + sidebar on chat tab only", async () => {
diff --git a/ui/src/ui/presenter.ts b/ui/src/ui/presenter.ts
index 13fa32722cc..009b886ba98 100644
--- a/ui/src/ui/presenter.ts
+++ b/ui/src/ui/presenter.ts
@@ -71,9 +71,13 @@ export function formatCronPayload(job: CronJob) {
   const delivery = job.delivery;
   if (delivery && delivery.mode !== "none") {
     const target =
-      delivery.channel || delivery.to
-        ? ` (${delivery.channel ?? "last"}${delivery.to ? ` -> ${delivery.to}` : ""})`
-        : "";
+      delivery.mode === "webhook"
+        ? delivery.to
+          ? ` (${delivery.to})`
+          : ""
+        : delivery.channel || delivery.to
+          ? ` (${delivery.channel ?? "last"}${delivery.to ? ` -> ${delivery.to}` : ""})`
+          : "";
     return `${base} · ${delivery.mode}${target}`;
   }
   return base;
diff --git a/ui/src/ui/test-helpers/app-mount.ts b/ui/src/ui/test-helpers/app-mount.ts
new file mode 100644
index 00000000000..d21e453c44c
--- /dev/null
+++ b/ui/src/ui/test-helpers/app-mount.ts
@@ -0,0 +1,30 @@
+import { afterEach, beforeEach } from "vitest";
+import { OpenClawApp } from "../app.ts";
+
+// oxlint-disable-next-line typescript/unbound-method
+const originalConnect = OpenClawApp.prototype.connect;
+
+export function mountApp(pathname: string) {
+  window.history.replaceState({}, "", pathname);
+  const app = document.createElement("openclaw-app") as OpenClawApp;
+  document.body.append(app);
+  return app;
+}
+
+export function registerAppMountHooks() {
+  beforeEach(() => {
+    OpenClawApp.prototype.connect = () => {
+      // no-op: avoid real gateway WS connections in browser tests
+    };
+    window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
+    localStorage.clear();
+    document.body.innerHTML = "";
+  });
+
+  afterEach(() => {
+    OpenClawApp.prototype.connect = originalConnect;
+    window.__OPENCLAW_CONTROL_UI_BASE_PATH__ = undefined;
+    localStorage.clear();
+    document.body.innerHTML = "";
+  });
+}
diff --git a/ui/src/ui/types.ts b/ui/src/ui/types.ts
index 2d53a9ccbb5..f985774bc30 100644
--- a/ui/src/ui/types.ts
+++ b/ui/src/ui/types.ts
@@ -452,7 +452,7 @@ export type CronPayload =
     };
 
 export type CronDelivery = {
-  mode: "none" | "announce";
+  mode: "none" | "announce" | "webhook";
   channel?: string;
   to?: string;
   bestEffort?: boolean;
diff --git a/ui/src/ui/ui-types.ts b/ui/src/ui/ui-types.ts
index 7ce3c73998e..724f2a92009 100644
--- a/ui/src/ui/ui-types.ts
+++ b/ui/src/ui/ui-types.ts
@@ -29,7 +29,7 @@ export type CronFormState = {
   wakeMode: "next-heartbeat" | "now";
   payloadKind: "systemEvent" | "agentTurn";
   payloadText: string;
-  deliveryMode: "none" | "announce";
+  deliveryMode: "none" | "announce" | "webhook";
   deliveryChannel: string;
   deliveryTo: string;
   timeoutSeconds: string;
diff --git a/ui/src/ui/views/config-form.node.ts b/ui/src/ui/views/config-form.node.ts
index f57fb834e14..cd567d5e662 100644
--- a/ui/src/ui/views/config-form.node.ts
+++ b/ui/src/ui/views/config-form.node.ts
@@ -500,35 +500,39 @@ function renderObject(params: {
   const additional = schema.additionalProperties;
   const allowExtra = Boolean(additional) && typeof additional === "object";
 
+  const fields = html`
+    ${sorted.map(([propKey, node]) =>
+      renderNode({
+        schema: node,
+        value: obj[propKey],
+        path: [...path, propKey],
+        hints,
+        unsupported,
+        disabled,
+        onPatch,
+      }),
+    )}
+    ${
+      allowExtra
+        ? renderMapField({
+            schema: additional,
+            value: obj,
+            path,
+            hints,
+            unsupported,
+            disabled,
+            reservedKeys: reserved,
+            onPatch,
+          })
+        : nothing
+    }
+  `;
+
   // For top-level, don't wrap in collapsible
   if (path.length === 1) {
     return html`
       <div class="cfg-fields">
-        ${sorted.map(([propKey, node]) =>
-          renderNode({
-            schema: node,
-            value: obj[propKey],
-            path: [...path, propKey],
-            hints,
-            unsupported,
-            disabled,
-            onPatch,
-          }),
-        )}
-        ${
-          allowExtra
-            ? renderMapField({
-                schema: additional,
-                value: obj,
-                path,
-                hints,
-                unsupported,
-                disabled,
-                reservedKeys: reserved,
-                onPatch,
-              })
-            : nothing
-        }
+        ${fields}
       </div>
     `;
   }
@@ -542,31 +546,7 @@ function renderObject(params: {
       </summary>
       ${help ? html`<div class="cfg-object__help">${help}</div>` : nothing}
       <div class="cfg-object__content">
-        ${sorted.map(([propKey, node]) =>
-          renderNode({
-            schema: node,
-            value: obj[propKey],
-            path: [...path, propKey],
-            hints,
-            unsupported,
-            disabled,
-            onPatch,
-          }),
-        )}
-        ${
-          allowExtra
-            ? renderMapField({
-                schema: additional,
-                value: obj,
-                path,
-                hints,
-                unsupported,
-                disabled,
-                reservedKeys: reserved,
-                onPatch,
-              })
-            : nothing
-        }
+        ${fields}
       </div>
     </details>
   `;
diff --git a/ui/src/ui/views/cron.test.ts b/ui/src/ui/views/cron.test.ts
index ea74093afec..e53509f0dff 100644
--- a/ui/src/ui/views/cron.test.ts
+++ b/ui/src/ui/views/cron.test.ts
@@ -158,4 +158,68 @@ describe("cron view", () => {
     expect(summaries[0]).toBe("newer run");
     expect(summaries[1]).toBe("older run");
   });
+
+  it("shows webhook delivery option in the form", () => {
+    const container = document.createElement("div");
+    render(
+      renderCron(
+        createProps({
+          form: { ...DEFAULT_CRON_FORM, payloadKind: "agentTurn" },
+        }),
+      ),
+      container,
+    );
+
+    const options = Array.from(container.querySelectorAll("option")).map((opt) =>
+      (opt.textContent ?? "").trim(),
+    );
+    expect(options).toContain("Webhook POST");
+  });
+
+  it("normalizes stale announce selection in the form when unsupported", () => {
+    const container = document.createElement("div");
+    render(
+      renderCron(
+        createProps({
+          form: {
+            ...DEFAULT_CRON_FORM,
+            sessionTarget: "main",
+            payloadKind: "systemEvent",
+            deliveryMode: "announce",
+          },
+        }),
+      ),
+      container,
+    );
+
+    const options = Array.from(container.querySelectorAll("option")).map((opt) =>
+      (opt.textContent ?? "").trim(),
+    );
+    expect(options).not.toContain("Announce summary (default)");
+    expect(options).toContain("Webhook POST");
+    expect(options).toContain("None (internal)");
+    expect(container.querySelector('input[placeholder="https://example.invalid/cron"]')).toBeNull();
+  });
+
+  it("shows webhook delivery details for jobs", () => {
+    const container = document.createElement("div");
+    const job = {
+      ...createJob("job-2"),
+      sessionTarget: "isolated" as const,
+      payload: { kind: "agentTurn" as const, message: "do it" },
+      delivery: { mode: "webhook" as const, to: "https://example.invalid/cron" },
+    };
+    render(
+      renderCron(
+        createProps({
+          jobs: [job],
+        }),
+      ),
+      container,
+    );
+
+    expect(container.textContent).toContain("Delivery");
+    expect(container.textContent).toContain("webhook");
+    expect(container.textContent).toContain("https://example.invalid/cron");
+  });
 });
diff --git a/ui/src/ui/views/cron.ts b/ui/src/ui/views/cron.ts
index a51cbfbbd3b..11b5477c31b 100644
--- a/ui/src/ui/views/cron.ts
+++ b/ui/src/ui/views/cron.ts
@@ -60,6 +60,10 @@ export function renderCron(props: CronProps) {
     props.runsJobId == null ? undefined : props.jobs.find((job) => job.id === props.runsJobId);
   const selectedRunTitle = selectedJob?.name ?? props.runsJobId ?? "(select a job)";
   const orderedRuns = props.runs.toSorted((a, b) => b.ts - a.ts);
+  const supportsAnnounce =
+    props.form.sessionTarget === "isolated" && props.form.payloadKind === "agentTurn";
+  const selectedDeliveryMode =
+    props.form.deliveryMode === "announce" && !supportsAnnounce ? "none" : props.form.deliveryMode;
   return html`
     <section class="grid grid-cols-2">
       <div class="card">
@@ -198,24 +202,31 @@ export function renderCron(props: CronProps) {
             rows="4"
           ></textarea>
         </label>
-        ${
-          props.form.payloadKind === "agentTurn"
-            ? html`
-                <div class="form-grid" style="margin-top: 12px;">
-                  <label class="field">
-                    <span>Delivery</span>
-                    <select
-                      .value=${props.form.deliveryMode}
-                      @change=${(e: Event) =>
-                        props.onFormChange({
-                          deliveryMode: (e.target as HTMLSelectElement)
-                            .value as CronFormState["deliveryMode"],
-                        })}
-                    >
+        <div class="form-grid" style="margin-top: 12px;">
+          <label class="field">
+            <span>Delivery</span>
+            <select
+              .value=${selectedDeliveryMode}
+              @change=${(e: Event) =>
+                props.onFormChange({
+                  deliveryMode: (e.target as HTMLSelectElement)
+                    .value as CronFormState["deliveryMode"],
+                })}
+            >
+              ${
+                supportsAnnounce
+                  ? html`
                       <option value="announce">Announce summary (default)</option>
-                      <option value="none">None (internal)</option>
-                    </select>
-                  </label>
+                    `
+                  : nothing
+              }
+              <option value="webhook">Webhook POST</option>
+              <option value="none">None (internal)</option>
+            </select>
+          </label>
+          ${
+            props.form.payloadKind === "agentTurn"
+              ? html`
                   <label class="field">
                     <span>Timeout (seconds)</span>
                     <input
@@ -226,11 +237,27 @@ export function renderCron(props: CronProps) {
                         })}
                     />
                   </label>
-                  ${
-                    props.form.deliveryMode === "announce"
-                      ? html`
-                          <label class="field">
-                            <span>Channel</span>
+                `
+              : nothing
+          }
+          ${
+            selectedDeliveryMode !== "none"
+              ? html`
+                  <label class="field">
+                    <span>${selectedDeliveryMode === "webhook" ? "Webhook URL" : "Channel"}</span>
+                    ${
+                      selectedDeliveryMode === "webhook"
+                        ? html`
+                            <input
+                              .value=${props.form.deliveryTo}
+                              @input=${(e: Event) =>
+                                props.onFormChange({
+                                  deliveryTo: (e.target as HTMLInputElement).value,
+                                })}
+                              placeholder="https://example.invalid/cron"
+                            />
+                          `
+                        : html`
                             <select
                               .value=${props.form.deliveryChannel || "last"}
                               @change=${(e: Event) =>
@@ -245,7 +272,12 @@ export function renderCron(props: CronProps) {
                                   </option>`,
                               )}
                             </select>
-                          </label>
+                          `
+                    }
+                  </label>
+                  ${
+                    selectedDeliveryMode === "announce"
+                      ? html`
                           <label class="field">
                             <span>To</span>
                             <input
@@ -260,10 +292,10 @@ export function renderCron(props: CronProps) {
                         `
                       : nothing
                   }
-                </div>
-              `
-            : nothing
-        }
+                `
+              : nothing
+          }
+        </div>
         <div class="row" style="margin-top: 14px;">
           <button class="btn primary" ?disabled=${props.busy} @click=${props.onAdd}>
             ${props.busy ? "Saving…" : "Add job"}
@@ -458,9 +490,13 @@ function renderJobPayload(job: CronJob) {
 
   const delivery = job.delivery;
   const deliveryTarget =
-    delivery?.channel || delivery?.to
-      ? ` (${delivery.channel ?? "last"}${delivery.to ? ` -> ${delivery.to}` : ""})`
-      : "";
+    delivery?.mode === "webhook"
+      ? delivery.to
+        ? ` (${delivery.to})`
+        : ""
+      : delivery?.channel || delivery?.to
+        ? ` (${delivery.channel ?? "last"}${delivery.to ? ` -> ${delivery.to}` : ""})`
+        : "";
 
   return html`
     <div class="cron-job-detail">
diff --git a/ui/src/ui/views/usage-render-overview.ts b/ui/src/ui/views/usage-render-overview.ts
index 8a65216e7bb..41ed8413492 100644
--- a/ui/src/ui/views/usage-render-overview.ts
+++ b/ui/src/ui/views/usage-render-overview.ts
@@ -649,6 +649,38 @@ function renderSessionsCard(
     0,
   );
 
+  const renderSessionBarRow = (s: UsageSessionEntry, isSelected: boolean) => {
+    const value = getSessionValue(s);
+    const displayLabel = formatSessionListLabel(s);
+    const meta = buildSessionMeta(s);
+    return html`
+      <div
+        class="session-bar-row ${isSelected ? "selected" : ""}"
+        @click=${(e: MouseEvent) => onSelectSession(s.key, e.shiftKey)}
+        title="${s.key}"
+      >
+        <div class="session-bar-label">
+          <div class="session-bar-title">${displayLabel}</div>
+          ${meta.length > 0 ? html`<div class="session-bar-meta">${meta.join(" · ")}</div>` : nothing}
+        </div>
+        <div class="session-bar-track" style="display: none;"></div>
+        <div class="session-bar-actions">
+          <button
+            class="session-copy-btn"
+            title="Copy session name"
+            @click=${(e: MouseEvent) => {
+              e.stopPropagation();
+              void copySessionName(s);
+            }}
+          >
+            Copy
+          </button>
+          <div class="session-bar-value">${isTokenMode ? formatTokens(value) : formatCost(value)}</div>
+        </div>
+      </div>
+    `;
+  };
+
   const selectedSet = new Set(selectedSessions);
   const selectedEntries = sortedWithDir.filter((s) => selectedSet.has(s.key));
   const selectedCount = selectedEntries.length;
@@ -720,83 +752,22 @@ function renderSessionsCard(
                 <div class="muted" style="padding: 20px; text-align: center">No recent sessions</div>
               `
             : html`
-                <div class="session-bars" style="max-height: 220px; margin-top: 6px;">
-                  ${recentEntries.map((s) => {
-                    const value = getSessionValue(s);
-                    const isSelected = selectedSet.has(s.key);
-                    const displayLabel = formatSessionListLabel(s);
-                    const meta = buildSessionMeta(s);
-                    return html`
-                      <div
-                        class="session-bar-row ${isSelected ? "selected" : ""}"
-                        @click=${(e: MouseEvent) => onSelectSession(s.key, e.shiftKey)}
-                        title="${s.key}"
-                      >
-                        <div class="session-bar-label">
-                          <div class="session-bar-title">${displayLabel}</div>
-                          ${meta.length > 0 ? html`<div class="session-bar-meta">${meta.join(" · ")}</div>` : nothing}
-                        </div>
-                        <div class="session-bar-track" style="display: none;"></div>
-                        <div class="session-bar-actions">
-                          <button
-                            class="session-copy-btn"
-                            title="Copy session name"
-                            @click=${(e: MouseEvent) => {
-                              e.stopPropagation();
-                              void copySessionName(s);
-                            }}
-                          >
-                            Copy
-                          </button>
-                          <div class="session-bar-value">${isTokenMode ? formatTokens(value) : formatCost(value)}</div>
-                        </div>
-                      </div>
-                    `;
-                  })}
-                </div>
-              `
+	                <div class="session-bars" style="max-height: 220px; margin-top: 6px;">
+	                  ${recentEntries.map((s) => renderSessionBarRow(s, selectedSet.has(s.key)))}
+	                </div>
+	              `
           : sessions.length === 0
             ? html`
                 <div class="muted" style="padding: 20px; text-align: center">No sessions in range</div>
               `
             : html`
-                <div class="session-bars">
-                  ${sortedWithDir.slice(0, 50).map((s) => {
-                    const value = getSessionValue(s);
-                    const isSelected = selectedSessions.includes(s.key);
-                    const displayLabel = formatSessionListLabel(s);
-                    const meta = buildSessionMeta(s);
-
-                    return html`
-                      <div
-                        class="session-bar-row ${isSelected ? "selected" : ""}"
-                        @click=${(e: MouseEvent) => onSelectSession(s.key, e.shiftKey)}
-                        title="${s.key}"
-                      >
-                        <div class="session-bar-label">
-                          <div class="session-bar-title">${displayLabel}</div>
-                          ${meta.length > 0 ? html`<div class="session-bar-meta">${meta.join(" · ")}</div>` : nothing}
-                        </div>
-                        <div class="session-bar-track" style="display: none;"></div>
-                        <div class="session-bar-actions">
-                          <button
-                            class="session-copy-btn"
-                            title="Copy session name"
-                            @click=${(e: MouseEvent) => {
-                              e.stopPropagation();
-                              void copySessionName(s);
-                            }}
-                          >
-                            Copy
-                          </button>
-                          <div class="session-bar-value">${isTokenMode ? formatTokens(value) : formatCost(value)}</div>
-                        </div>
-                      </div>
-                    `;
-                  })}
-                  ${sessions.length > 50 ? html`<div class="muted" style="padding: 8px; text-align: center; font-size: 11px;">+${sessions.length - 50} more</div>` : nothing}
-                </div>
-              `
+	                <div class="session-bars">
+	                  ${sortedWithDir
+                      .slice(0, 50)
+                      .map((s) => renderSessionBarRow(s, selectedSet.has(s.key)))}
+	                  ${sessions.length > 50 ? html`<div class="muted" style="padding: 8px; text-align: center; font-size: 11px;">+${sessions.length - 50} more</div>` : nothing}
+	                </div>
+	              `
       }
       ${
         selectedCount > 1
@@ -804,37 +775,7 @@ function renderSessionsCard(
               <div style="margin-top: 10px;">
                 <div class="sessions-card-count">Selected (${selectedCount})</div>
                 <div class="session-bars" style="max-height: 160px; margin-top: 6px;">
-                  ${selectedEntries.map((s) => {
-                    const value = getSessionValue(s);
-                    const displayLabel = formatSessionListLabel(s);
-                    const meta = buildSessionMeta(s);
-                    return html`
-                      <div
-                        class="session-bar-row selected"
-                        @click=${(e: MouseEvent) => onSelectSession(s.key, e.shiftKey)}
-                        title="${s.key}"
-                      >
-                        <div class="session-bar-label">
-                          <div class="session-bar-title">${displayLabel}</div>
-                          ${meta.length > 0 ? html`<div class="session-bar-meta">${meta.join(" · ")}</div>` : nothing}
-                        </div>
-                  <div class="session-bar-track" style="display: none;"></div>
-                        <div class="session-bar-actions">
-                          <button
-                            class="session-copy-btn"
-                            title="Copy session name"
-                            @click=${(e: MouseEvent) => {
-                              e.stopPropagation();
-                              void copySessionName(s);
-                            }}
-                          >
-                            Copy
-                          </button>
-                          <div class="session-bar-value">${isTokenMode ? formatTokens(value) : formatCost(value)}</div>
-                        </div>
-                      </div>
-                    `;
-                  })}
+                  ${selectedEntries.map((s) => renderSessionBarRow(s, true))}
                 </div>
               </div>
             `
diff --git a/vitest.config.ts b/vitest.config.ts
index 71a92990525..c3a042499ed 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -33,7 +33,7 @@ export default defineConfig({
     unstubGlobals: true,
     pool: "forks",
     maxWorkers: isCI ? ciWorkers : localWorkers,
-    include: ["src/**/*.test.ts", "extensions/**/*.test.ts", "test/format-error.test.ts"],
+    include: ["src/**/*.test.ts", "extensions/**/*.test.ts", "test/**/*.test.ts"],
     setupFiles: ["test/setup.ts"],
     exclude: [
       "dist/**",