fix(discord): propagate timeout through channel capabilities diagnostics (#93716)

* fix(discord): propagate timeout through channel capabilities diagnostics

* fix(discord): fix type error in capabilities timeout test

* fix(discord): cancel timed-out capability diagnostics

* fix(discord): abort in-flight capability requests

---------

Co-authored-by: Vincent Koc <25068+vincentkoc@users.noreply.github.com>

.agents/skills/autoreview/SKILL.md

@@ -24,7 +24,7 @@ Use when:
 - Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class.
 - When an accepted finding shows a bug class or repeated pattern, inspect the current PR scope for sibling instances before fixing.
 - Fix the scoped bug class at once when practical; stop at touched surfaces, owner boundaries, and clear follow-up territory.
-- Keep going until structured review returns no accepted/actionable findings.
+- Keep going until structured review returns no accepted/actionable findings only while the work remains inside the original task scope.
 - If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper.
 - For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
 - Never switch or override the requested review engine/model. If the review hits model capacity, retry the same command a few times with the same engine/model.
@@ -43,6 +43,42 @@ Use when:
 - If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run `gitcrawl doctor --json` and inspect `source_db_health`, `runtime_db_health`, and `portable_store_status` before falling back to live GitHub.
 - Do not push just to review. Push only when the user requested push/ship/PR update.
 
+## Scope Governor
+
+Autoreview is a closeout gate, not permission to rewrite the task.
+
+Before the first review, freeze a scope baseline: original request or issue, target branch, intended behavior, owner boundary, changed files, and non-test LOC. For inherited or already-bloated branches, use the intended PR diff as the baseline rather than accepting all existing branch drift.
+
+Before patching a finding, classify it:
+
+- **In-scope blocker**: the finding is introduced by the current diff, affects the same owner boundary, and can be fixed without changing the task's contract.
+- **Follow-up**: the finding is real but belongs to an adjacent bug class, sibling surface, cleanup, or broader hardening track.
+- **Stop-and-escalate**: the finding requires a new protocol/config/storage/public API contract, a different owner boundary, a release-process change, or a design choice outside the original request.
+
+Stop patching and report the scope break instead of continuing when:
+
+- a narrow PR turns into an architecture change, protocol change, migration, or release-process change;
+- the diff grows past 2x the original files or non-test LOC without explicit approval to expand scope;
+- two review-triggered patch cycles have not converged; pause and reclassify every remaining finding before another edit;
+- the best fix is "define the canonical contract first" rather than another local inference layer;
+- fixing the accepted finding would make the PR no longer describe the same behavior, issue, or owner boundary.
+
+After the two-cycle pause, continue only when every remaining accepted finding is still an in-scope blocker. Otherwise preserve the useful analysis, identify the smallest safe landed subset if one exists, and open or request a follow-up for the larger fix. Do not keep committing speculative fixes just to satisfy the reviewer.
+
+Do not stack or push review-triggered fix commits while scope classification or focused proof is unresolved. Keep exploratory edits local until the cycle is proven in scope; if scope breaks, remove them from the landing lane instead of preserving them as branch history.
+
+Critical exceptions must be explicit: active data loss, crash, broken install/upgrade, release blocker, or concrete security exposure. If the exception is not one of those, it is not critical enough to blow up scope.
+
+## Release Branches And Release Process
+
+On release, beta, stable, hotfix, signing, notarization, appcast, package-publish, or release-check work, use freeze discipline even when the branch name is not release-like:
+
+- Fix only release blockers, failed release infrastructure, exact backports, install/upgrade breakage, data loss, crashes, or concrete security exposure.
+- Treat non-blocking autoreview findings as follow-ups for `main`, not reasons to broaden the release branch.
+- Do not introduce new product behavior, config surface, protocol shape, migration, plugin ownership, docs narrative, or process policy unless it directly unblocks the release.
+- Keep proof tied to the release target: exact branch/ref, failing check or shipped-risk reason, smallest command/proof, and whether the fix must also forward-port to `main`.
+- If review discovers a real but non-critical design problem during release closeout, stop with a follow-up issue/PR plan; do not use the release branch as the refactor lane.
+
 ## Pick Target
 
 Dirty local work:

.agents/skills/autoreview/scripts/autoreview

@@ -440,8 +440,36 @@ def load_datasets(args: argparse.Namespace) -> str:
     return "\n\n".join(chunks)
 
 
+def review_scope_policy() -> str:
+    return textwrap.dedent(
+        """
+        Review scope discipline:
+        - This helper is a closeout gate. Do not turn a narrow patch into a broad
+          redesign request.
+        - Report a finding only when this diff introduces or exposes a concrete
+          defect that must be fixed before this target can land.
+        - If the best fix requires a new protocol, config, storage, public API,
+          release process, migration, owner-boundary move, or canonical contract,
+          say that directly in the finding and keep the finding tied to the
+          smallest changed line that proves the current patch is not landable.
+        - Do not ask for sibling-surface hardening, cleanup, refactors, or
+          follow-up architecture work unless the current diff is incorrect
+          without that work.
+        - Prefer the smallest correct pre-merge fix. A broader ideal design is
+          not an actionable finding unless the current patch cannot safely land.
+        - If this is release-branch or release-process work, apply freeze
+          discipline. Report only release blockers, exact backport regressions,
+          install/upgrade breakage, crashes, data loss, concrete security
+          exposure, or release-infrastructure failures. Non-blocking design,
+          cleanup, and hardening concerns belong on main as follow-ups.
+        """
+    ).strip()
+
+
 def build_prompt(repo: Path, target: str, target_ref: str | None, bundle: str, extra_prompt: str, datasets: str) -> str:
     target_line = f"{target} {target_ref}" if target_ref else target
+    branch = current_branch(repo)
+    scope_policy = review_scope_policy()
     return textwrap.dedent(
         f"""
         You are a senior code reviewer. Review the provided git change bundle only.
@@ -463,8 +491,11 @@ def build_prompt(repo: Path, target: str, target_ref: str | None, bundle: str, e
         - If there are no actionable findings, return an empty findings array and mark the patch correct.
 
         Review target: {target_line}
+        Current branch: {branch}
         Repository: {repo}
 
+        {scope_policy}
+
         {extra_prompt}
 
         {datasets}

.agents/skills/autoreview/scripts/test-review-harness.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import argparse
 import os
+import runpy
 import shutil
 import stat
 import subprocess
@@ -145,8 +146,23 @@ def create_fixture_repo(repo: Path, fixture: str) -> None:
     write_fixture_file(repo, MALICIOUS_CHANGED if fixture == "malicious" else BENIGN_CHANGED)
 
 
+def validate_prompt_policy(repo: Path, autoreview: Path) -> None:
+    namespace = runpy.run_path(str(autoreview))
+    prompt = namespace["build_prompt"](repo, "local", None, "fixture diff", "", "")
+    required = (
+        "This helper is a closeout gate.",
+        "Do not turn a narrow patch into a broad",
+        "If this is release-branch or release-process work",
+        "Non-blocking design,",
+    )
+    missing = [needle for needle in required if needle not in prompt]
+    if missing:
+        raise RuntimeError(f"autoreview prompt missing scope policy: {missing}")
+
+
 def run_reviews(repo: Path, script_dir: Path, fixture: str, engines: list[str]) -> None:
     autoreview = script_dir / "autoreview"
+    validate_prompt_policy(repo, autoreview)
     for engine in engines:
         print(f"== {engine} ==", flush=True)
         command = [

.agents/skills/openclaw-pr-maintainer/SKILL.md

@@ -284,7 +284,7 @@ gh search issues --repo openclaw/openclaw --match title,body --limit 50 \
 - If bot review conversations exist on your PR, address them and resolve them yourself once fixed.
 - Leave a review conversation unresolved only when reviewer or maintainer judgment is still needed.
 - Before landing any PR with non-trivial code changes, run `$autoreview` until no accepted/actionable findings remain, unless equivalent manual review already covered it, the change is trivial/docs-only, or the user opts out.
-- When landing or merging any PR, follow the global `/landpr` process.
+- When an agent is landing or merging a PR targeting `main`, use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`.
 - Use `scripts/committer "<msg>" <file...>` for scoped commits instead of manual `git add` and `git commit`.
 - Keep commit messages concise and action-oriented.
 - Group related changes; avoid bundling unrelated refactors.

.agents/skills/release-openclaw-ci/SKILL.md

@@ -16,6 +16,10 @@ Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a rele
 - Watch one parent run plus compact child summaries. Avoid broad `gh run view` polling loops; REST quota is easy to burn.
 - Fetch logs only for failed or currently-blocking jobs. If quota is low, stop polling and wait for reset.
 - Treat live-provider flakes separately from code failures: prove key validity, provider HTTP status, retry evidence, and exact failing lane before editing code.
+- A model-list response proves authentication, not billing or inference
+  entitlement. Mandatory live providers must pass a real completion probe
+  before release dispatch. Fix the credential first; do not add an alternate
+  auth path merely to bypass a failed release credential.
 - Full Release Validation parent monitors fail fast: once a required child job
   fails, the parent cancels the remaining child matrix and prints the failed
   job summary. Inspect that first red job instead of waiting for unrelated
@@ -36,6 +40,8 @@ git rev-parse HEAD
 preflight. Inject those exact targeted keys first, then run the verifier; use
 ambient env only when it was already intentionally injected for this release.
 The script prints only provider status and HTTP class, never tokens.
+The Anthropic check performs a tiny message completion so exhausted or
+non-billable credentials fail before the expensive release matrix.
 
 ## Dispatch
 
@@ -65,6 +71,13 @@ gh workflow run openclaw-performance.yml \
 
 Prefer the trusted workflow on `main`, target the exact release SHA:
 
+- Keep trusted-workflow checks compatible with frozen release targets. If
+  `main` adds a target-owned guard script or package command after the release
+  branch cut, make the trusted workflow skip only when that target surface is
+  absent. Heal the trusted workflow before rerunning validation; do not port an
+  unrelated runtime refactor or mutate the release candidate just to satisfy a
+  newer `main`-only check.
+
 ```bash
 gh workflow run full-release-validation.yml \
   --repo openclaw/openclaw \
@@ -106,7 +119,10 @@ Stop watchers before ending the turn or switching strategy.
      --jq '.jobs[] | select(.conclusion=="failure" or .conclusion=="timed_out" or .conclusion=="cancelled") | [.databaseId,.name,.conclusion,.url] | @tsv'
    ```
 3. Fetch one failed job log. If rate-limited, note reset time and avoid more REST calls.
-4. For secret-looking failures, validate the provider endpoint from the same secret source before editing code.
+4. For secret-looking failures, validate a real completion from the same secret source before editing code. A successful model-list request is insufficient.
+   Claude CLI subscription credentials are a separate native auth path; prove
+   them in a clean-home CLI probe, never as a substitute for a required
+   Anthropic API-key lane.
 5. For live-cache failures, inspect whether it is missing/invalid key, empty text, provider refusal, timeout, or baseline miss. Do not weaken release gates without clear provider evidence.
 6. Fix narrowly, run local/changed proof, commit, push, rerun the smallest matching group.
 

.agents/skills/release-openclaw-ci/scripts/verify-provider-secrets.mjs

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 /**
- * Release preflight helper that verifies required provider API keys can reach
- * their model-list endpoints without printing secret values.
+ * Release preflight helper that verifies required provider API keys without
+ * printing secret values. Anthropic must complete a prompt because model-list
+ * access does not prove billing or inference entitlement.
  */
 import process from "node:process";
 
 const args = new Map();
 for (let index = 2; index < process.argv.length; index += 1) {
   const arg = process.argv[index];
-  if (!arg.startsWith("--")) continue;
+  if (!arg.startsWith("--")) {
+    continue;
+  }
   const [key, inlineValue] = arg.slice(2).split("=", 2);
   const value = inlineValue ?? process.argv[index + 1];
-  if (inlineValue === undefined) index += 1;
+  if (inlineValue === undefined) {
+    index += 1;
+  }
   args.set(key, value);
 }
 
@@ -28,7 +33,9 @@ const timeoutMs = Number(args.get("timeout-ms") ?? 10_000);
 function envFirst(names) {
   for (const name of names) {
     const value = process.env[name]?.trim();
-    if (value) return { name, value };
+    if (value) {
+      return { name, value };
+    }
   }
   return undefined;
 }
@@ -44,13 +51,19 @@ async function checkProvider(id, config) {
   try {
     const headers = config.headers(secret.value);
     const response = await fetch(config.url, {
+      body: config.body,
       headers,
+      method: config.method,
       signal: controller.signal,
     });
+    const responseBody = config.validateResponse
+      ? await response.json().catch(() => undefined)
+      : undefined;
+    const ok = response.ok && (!config.validateResponse || config.validateResponse(responseBody));
     return {
       id,
-      ok: response.ok,
-      status: response.ok ? "ok" : `http_${response.status}`,
+      ok,
+      status: response.ok ? (ok ? "ok" : "invalid_response") : `http_${response.status}`,
       env: secret.name,
     };
   } catch (error) {
@@ -73,11 +86,21 @@ const providers = {
   },
   anthropic: {
     env: ["ANTHROPIC_API_KEY", "ANTHROPIC_API_TOKEN"],
-    url: "https://api.anthropic.com/v1/models",
+    url: "https://api.anthropic.com/v1/messages",
+    method: "POST",
+    body: JSON.stringify({
+      max_tokens: 8,
+      messages: [{ role: "user", content: "Reply with OK." }],
+      model: "claude-haiku-4-5",
+    }),
     headers: (token) => ({
       "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
       "x-api-key": token,
     }),
+    validateResponse: (body) =>
+      Array.isArray(body?.content) &&
+      body.content.some((part) => typeof part?.text === "string" && part.text.trim()),
   },
   fireworks: {
     env: ["FIREWORKS_API_KEY"],
@@ -108,7 +131,9 @@ let failed = false;
 for (const result of results) {
   const requiredLabel = required.has(result.id) ? "required" : "optional";
   console.log(`${result.id}: ${result.status} env=${result.env} ${requiredLabel}`);
-  if (required.has(result.id) && !result.ok) failed = true;
+  if (required.has(result.id) && !result.ok) {
+    failed = true;
+  }
 }
 
 if (failed) {

.agents/skills/release-openclaw-maintainer/SKILL.md

@@ -552,6 +552,16 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
 - `preflight_only=true` on the npm workflow is also the right way to validate an
   existing tag after publish; it should keep running the build checks even when
   the npm version is already published.
+- npm registry metadata is eventually consistent immediately after trusted
+  publishing. Keep postpublish `npm view` checks on bounded `--prefer-online`
+  retries, and carry that verified tarball/integrity metadata into later proof
+  steps instead of reading the registry again. If the OpenClaw npm child
+  succeeded but the parent publish workflow failed on an immediate exact-version
+  `E404`, verify the exact version with a cache-bypassed registry read, run the
+  standalone postpublish verifier and the full beta verifier with the original
+  successful child run IDs, then finalize the draft, dependency evidence asset,
+  and release proof manually. Never rerun the publish workflow for that
+  already-published version.
 - npm validation-only preflight may still be dispatched from ordinary branches
   when testing workflow changes before merge. Release checks and real publish
   use only `main` or `release/YYYY.M.PATCH`.
@@ -720,8 +730,13 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
     waited plugin publish or Windows Hub promotion fails after OpenClaw npm
     succeeds, the workflow keeps the release draft with OpenClaw npm evidence
     and exits red; do not undraft until the gap is repaired. The standalone
-    verifier command remains the recovery probe:
+    verifier command remains the first recovery probe:
     `node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>`.
+    For a failed postpublish parent after successful publish children, also run
+    `pnpm release:verify-beta -- <published-version> ... --skip-github-release`
+    with the original child run IDs and an evidence output path before manually
+    recreating the workflow's draft, dependency evidence asset, proof section,
+    and publish step.
 25. Run the post-published beta verification roster. First scan current `main`
     for critical fixes that landed after the release branch cut; backport only
     important low-risk fixes before starting expensive lanes, or increment to

.github/workflows/ci-build-artifacts-testbox.yml

@@ -61,7 +61,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
@@ -188,7 +188,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          timeout --signal=TERM --kill-after=10s 30s git \
+          timeout --signal=TERM --kill-after=10s 120s git \
             -c protocol.version=2 \
             fetch --no-tags --prune --no-recurse-submodules --depth=50 origin \
             "+refs/heads/main:refs/remotes/origin/main"

.github/workflows/ci-check-arm-testbox.yml

@@ -76,7 +76,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
@@ -106,7 +106,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          timeout --signal=TERM --kill-after=10s 30s git \
+          timeout --signal=TERM --kill-after=10s 120s git \
             -c protocol.version=2 \
             fetch --no-tags --prune --no-recurse-submodules --depth=50 origin \
             "+refs/heads/main:refs/remotes/origin/main"

.github/workflows/ci-check-testbox.yml

@@ -61,7 +61,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
@@ -91,7 +91,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          timeout --signal=TERM --kill-after=10s 30s git \
+          timeout --signal=TERM --kill-after=10s 120s git \
             -c protocol.version=2 \
             fetch --no-tags --prune --no-recurse-submodules --depth=50 origin \
             "+refs/heads/main:refs/remotes/origin/main"

.github/workflows/ci.yml

@@ -90,7 +90,7 @@ jobs:
             local ref="$1"
             local fetch_status
             for attempt in 1 2 3; do
-              timeout --signal=TERM --kill-after=10s 30s git -C "$GITHUB_WORKSPACE" \
+              timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
                 fetch --no-tags --prune --no-recurse-submodules --depth=2 origin \
                 "+${ref}:refs/remotes/origin/checkout" && return 0
@@ -351,7 +351,7 @@ jobs:
             local ref="$1"
             local fetch_status
             for attempt in 1 2 3; do
-              timeout --signal=TERM --kill-after=10s 30s git -C "$GITHUB_WORKSPACE" \
+              timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
                 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
                 "+${ref}:refs/remotes/origin/checkout" && return 0
@@ -499,7 +499,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -564,7 +564,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -810,7 +810,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -850,10 +850,10 @@ jobs:
               ;;
             contracts-plugins-ci-routing)
               pnpm test:contracts:plugins
-              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/changed-lanes.test.ts test/scripts/run-vitest.test.ts test/scripts/test-projects.test.ts
+              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/changed-lanes.test.ts test/scripts/ci-workflow-guards.test.ts test/scripts/run-vitest.test.ts test/scripts/test-projects.test.ts
               ;;
             ci-routing)
-              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/changed-lanes.test.ts test/scripts/run-vitest.test.ts test/scripts/test-projects.test.ts
+              pnpm test src/commands/status.scan-result.test.ts src/scripts/ci-changed-scope.test.ts test/scripts/changed-lanes.test.ts test/scripts/ci-workflow-guards.test.ts test/scripts/run-vitest.test.ts test/scripts/test-projects.test.ts
               ;;
             bun-launcher)
               OPENCLAW_TEST_BUN_LAUNCHER=1 pnpm test test/openclaw-launcher.e2e.test.ts
@@ -899,7 +899,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -979,7 +979,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1056,7 +1056,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1131,7 +1131,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1258,7 +1258,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1399,7 +1399,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1523,7 +1523,13 @@ jobs:
               fi
               ;;
             session-transcript-reader-boundary)
-              run_check "lint:tmp:session-transcript-reader-boundary" pnpm run lint:tmp:session-transcript-reader-boundary
+              if [ ! -f scripts/check-session-transcript-reader-boundary.mjs ]; then
+                echo "[skip] session transcript reader boundary check is not present in this checkout"
+              elif ! node -e 'const pkg = require("./package.json"); process.exit(pkg.scripts?.["lint:tmp:session-transcript-reader-boundary"] ? 0 : 1);'; then
+                echo "[skip] session transcript reader boundary script is not present in package.json"
+              else
+                run_check "lint:tmp:session-transcript-reader-boundary" pnpm run lint:tmp:session-transcript-reader-boundary
+              fi
               ;;
             extension-channels)
               run_check "lint:extensions:channels" pnpm run lint:extensions:channels
@@ -1578,7 +1584,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
@@ -1624,7 +1630,7 @@ jobs:
             git -C "$workdir" config gc.auto 0
             git -C "$workdir" remote add origin "https://github.com/openclaw/clawhub.git"
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+refs/heads/main:refs/remotes/origin/checkout" || return 1
@@ -1671,7 +1677,7 @@ jobs:
           fetch_checkout_ref() {
             local fetch_status
             for attempt in 1 2 3; do
-              timeout --signal=TERM --kill-after=10s 30s git -C "$GITHUB_WORKSPACE" \
+              timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
                 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
                 "+${CHECKOUT_SHA}:refs/remotes/origin/checkout" && return 0
@@ -2077,7 +2083,7 @@ jobs:
             git -C "$workdir" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
             git -C "$workdir" config gc.auto 0
 
-            timeout --signal=TERM --kill-after=10s 30s git -C "$workdir" \
+            timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1

.github/workflows/full-release-validation.yml

@@ -275,7 +275,7 @@ jobs:
             local workflow="$1"
             shift
 
-            local before_json dispatch_output run_id status conclusion url poll_count
+            local dispatch_output run_id status conclusion url poll_count
             gh_with_retry() {
               local output status attempt
               for attempt in 1 2 3 4 5 6; do
@@ -298,8 +298,6 @@ jobs:
               printf '%s\n' "$output" >&2
               return "$status"
             }
-            before_json="$(gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 100 --json databaseId --jq '[.[].databaseId]')"
-
             dispatch_output="$(gh_with_retry workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@")"
             printf '%s\n' "$dispatch_output"
             run_id="$(
@@ -309,20 +307,7 @@ jobs:
             )"
 
             if [[ -z "$run_id" ]]; then
-              for _ in $(seq 1 60); do
-                run_id="$(
-                  BEFORE_IDS="$before_json" gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 50 --json databaseId,createdAt \
-                    --jq 'map(select(.databaseId as $id | (env.BEFORE_IDS | fromjson | index($id) | not))) | sort_by(.createdAt) | reverse | .[0].databaseId // empty'
-                )"
-                if [[ -n "$run_id" ]]; then
-                  break
-                fi
-                sleep 5
-              done
-            fi
-
-            if [[ -z "${run_id:-}" ]]; then
-              echo "Could not find dispatched run for ${workflow}." >&2
+              echo "::error::gh workflow run ${workflow} did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs." >&2
               exit 1
             fi
 
@@ -423,7 +408,7 @@ jobs:
             local workflow="$1"
             shift
 
-            local before_json dispatch_output run_id status conclusion url poll_count
+            local dispatch_output run_id status conclusion url poll_count
             gh_with_retry() {
               local output status attempt
               for attempt in 1 2 3 4 5 6; do
@@ -446,8 +431,6 @@ jobs:
               printf '%s\n' "$output" >&2
               return "$status"
             }
-            before_json="$(gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 100 --json databaseId --jq '[.[].databaseId]')"
-
             dispatch_output="$(gh_with_retry workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@")"
             printf '%s\n' "$dispatch_output"
             run_id="$(
@@ -457,20 +440,7 @@ jobs:
             )"
 
             if [[ -z "$run_id" ]]; then
-              for _ in $(seq 1 60); do
-                run_id="$(
-                  BEFORE_IDS="$before_json" gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 50 --json databaseId,createdAt \
-                    --jq 'map(select(.databaseId as $id | (env.BEFORE_IDS | fromjson | index($id) | not))) | sort_by(.createdAt) | reverse | .[0].databaseId // empty'
-                )"
-                if [[ -n "$run_id" ]]; then
-                  break
-                fi
-                sleep 5
-              done
-            fi
-
-            if [[ -z "${run_id:-}" ]]; then
-              echo "Could not find dispatched run for ${workflow}." >&2
+              echo "::error::gh workflow run ${workflow} did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs." >&2
               exit 1
             fi
 
@@ -581,7 +551,7 @@ jobs:
             local workflow="$1"
             shift
 
-            local before_json dispatch_output run_id status conclusion url poll_count run_json
+            local dispatch_output run_id status conclusion url poll_count run_json
             gh_with_retry() {
               local output status attempt
               for attempt in 1 2 3 4 5 6; do
@@ -604,8 +574,6 @@ jobs:
               printf '%s\n' "$output" >&2
               return "$status"
             }
-            before_json="$(gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 100 --json databaseId --jq '[.[].databaseId]')"
-
             dispatch_output="$(gh_with_retry workflow run "$workflow" --ref "$CHILD_WORKFLOW_REF" "$@")"
             printf '%s\n' "$dispatch_output"
             run_id="$(
@@ -615,20 +583,7 @@ jobs:
             )"
 
             if [[ -z "$run_id" ]]; then
-              for _ in $(seq 1 60); do
-                run_id="$(
-                  BEFORE_IDS="$before_json" gh_with_retry run list --workflow "$workflow" --event workflow_dispatch --limit 50 --json databaseId,createdAt \
-                    --jq 'map(select(.databaseId as $id | (env.BEFORE_IDS | fromjson | index($id) | not))) | sort_by(.createdAt) | reverse | .[0].databaseId // empty'
-                )"
-                if [[ -n "$run_id" ]]; then
-                  break
-                fi
-                sleep 5
-              done
-            fi
-
-            if [[ -z "${run_id:-}" ]]; then
-              echo "Could not find dispatched run for ${workflow}." >&2
+              echo "::error::gh workflow run ${workflow} did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs." >&2
               exit 1
             fi
 
@@ -928,8 +883,6 @@ jobs:
             return "$status"
           }
 
-          before_json="$(gh_with_retry run list --workflow npm-telegram-beta-e2e.yml --event workflow_dispatch --limit 100 --json databaseId --jq '[.[].databaseId]')"
-
           args=(-f package_spec="${PACKAGE_SPEC:-openclaw@beta}" -f harness_ref="$TARGET_SHA" -f provider_mode="$PROVIDER_MODE")
           if [[ -z "${PACKAGE_SPEC// }" ]]; then
             if [[ "$PREPARE_PACKAGE_RESULT" != "success" || -z "${PACKAGE_ARTIFACT_NAME// }" ]]; then
@@ -946,22 +899,16 @@ jobs:
             args+=(-f scenario="$SCENARIO")
           fi
 
-          gh_with_retry workflow run npm-telegram-beta-e2e.yml --ref "$CHILD_WORKFLOW_REF" "${args[@]}"
-
-          run_id=""
-          for _ in $(seq 1 60); do
-            run_id="$(
-              BEFORE_IDS="$before_json" gh_with_retry run list --workflow npm-telegram-beta-e2e.yml --event workflow_dispatch --limit 50 --json databaseId,createdAt \
-                --jq 'map(select(.databaseId as $id | (env.BEFORE_IDS | fromjson | index($id) | not))) | sort_by(.createdAt) | reverse | .[0].databaseId // empty'
-            )"
-            if [[ -n "$run_id" ]]; then
-              break
-            fi
-            sleep 5
-          done
+          dispatch_output="$(gh_with_retry workflow run npm-telegram-beta-e2e.yml --ref "$CHILD_WORKFLOW_REF" "${args[@]}")"
+          printf '%s\n' "$dispatch_output"
+          run_id="$(
+            printf '%s\n' "$dispatch_output" |
+              sed -nE 's#.*actions/runs/([0-9]+).*#\1#p' |
+              tail -n 1
+          )"
 
           if [[ -z "$run_id" ]]; then
-            echo "Could not find dispatched run for npm-telegram-beta-e2e.yml." >&2
+            echo "::error::gh workflow run npm-telegram-beta-e2e.yml did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs." >&2
             exit 1
           fi
 
@@ -1073,31 +1020,23 @@ jobs:
             echo "- Release impact: advisory"
           } >> "$GITHUB_STEP_SUMMARY"
 
-          before_json="$(gh_with_retry run list --workflow openclaw-performance.yml --event workflow_dispatch --limit 100 --json databaseId --jq '[.[].databaseId]')"
-
-          gh_with_retry workflow run openclaw-performance.yml \
+          dispatch_output="$(gh_with_retry workflow run openclaw-performance.yml \
             --ref "$CHILD_WORKFLOW_REF" \
             -f target_ref="$TARGET_SHA" \
             -f profile=release \
             -f repeat=3 \
             -f deep_profile=false \
             -f live_openai_candidate=false \
-            -f fail_on_regression=false
-
-          run_id=""
-          for _ in $(seq 1 60); do
-            run_id="$(
-              BEFORE_IDS="$before_json" gh_with_retry run list --workflow openclaw-performance.yml --event workflow_dispatch --limit 50 --json databaseId,createdAt \
-                --jq 'map(select(.databaseId as $id | (env.BEFORE_IDS | fromjson | index($id) | not))) | sort_by(.createdAt) | reverse | .[0].databaseId // empty'
-            )"
-            if [[ -n "$run_id" ]]; then
-              break
-            fi
-            sleep 5
-          done
+            -f fail_on_regression=false)"
+          printf '%s\n' "$dispatch_output"
+          run_id="$(
+            printf '%s\n' "$dispatch_output" |
+              sed -nE 's#.*actions/runs/([0-9]+).*#\1#p' |
+              tail -n 1
+          )"
 
           if [[ -z "$run_id" ]]; then
-            echo "::warning::Could not find dispatched run for openclaw-performance.yml."
+            echo "::warning::gh workflow run openclaw-performance.yml did not return an Actions run URL; refusing to guess from recent workflow_dispatch runs."
             exit 0
           fi
 

.github/workflows/install-smoke.yml

@@ -476,19 +476,21 @@ jobs:
       - name: Run Rocky Linux installer smoke
         run: |
           timeout --kill-after=30s 20m docker run --rm \
+            --platform linux/amd64 \
             -e OPENCLAW_NO_ONBOARD=1 \
             -e OPENCLAW_NO_PROMPT=1 \
             -v "$PWD/scripts/install.sh:/tmp/install.sh:ro" \
-            rockylinux:9@sha256:d7be1c094cc5845ee815d4632fe377514ee6ebcf8efaed6892889657e5ddaaa6 \
+            rockylinux:9@sha256:d644d203142cd5b54ad2a83a203e1dee68af2229f8fe32f52a30c6e1d3c3a9e0 \
             bash -lc 'dnf install -y -q ca-certificates tar gzip xz findutils which sudo >/dev/null && bash /tmp/install.sh --install-method npm --version latest --no-onboard --no-prompt --verify && openclaw --version'
 
       - name: Run Rocky Linux CLI installer smoke
         run: |
           timeout --kill-after=30s 20m docker run --rm \
+            --platform linux/amd64 \
             -e OPENCLAW_NO_ONBOARD=1 \
             -e OPENCLAW_NO_PROMPT=1 \
             -v "$PWD/scripts/install-cli.sh:/tmp/install-cli.sh:ro" \
-            rockylinux:9@sha256:d7be1c094cc5845ee815d4632fe377514ee6ebcf8efaed6892889657e5ddaaa6 \
+            rockylinux:9@sha256:d644d203142cd5b54ad2a83a203e1dee68af2229f8fe32f52a30c6e1d3c3a9e0 \
             bash -lc 'dnf install -y -q ca-certificates tar gzip xz findutils which sudo >/dev/null && bash /tmp/install-cli.sh --prefix /tmp/openclaw-cli --version latest --no-onboard && /tmp/openclaw-cli/bin/openclaw --version'
 
   bun_global_install_smoke:

.github/workflows/openclaw-live-and-e2e-checks-reusable.yml

@@ -2222,7 +2222,11 @@ jobs:
           case "${{ matrix.suite_id }}" in
             live-cli-backend-docker)
               echo "OPENCLAW_LIVE_CLI_BACKEND_MODEL=claude-cli/claude-sonnet-4-6" >> "$GITHUB_ENV"
-              echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=api-key" >> "$GITHUB_ENV"
+              if [[ -n "${OPENCLAW_CLAUDE_CREDENTIALS_JSON:-}" || -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]]; then
+                echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=subscription" >> "$GITHUB_ENV"
+              else
+                echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=api-key" >> "$GITHUB_ENV"
+              fi
               echo "OPENCLAW_LIVE_CLI_BACKEND_DEBUG=1" >> "$GITHUB_ENV"
               echo "OPENCLAW_CLI_BACKEND_LOG_OUTPUT=1" >> "$GITHUB_ENV"
               echo "OPENCLAW_TEST_CONSOLE=1" >> "$GITHUB_ENV"
@@ -2447,7 +2451,11 @@ jobs:
           case "${{ matrix.suite_id }}" in
             live-cli-backend-docker)
               echo "OPENCLAW_LIVE_CLI_BACKEND_MODEL=claude-cli/claude-sonnet-4-6" >> "$GITHUB_ENV"
-              echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=api-key" >> "$GITHUB_ENV"
+              if [[ -n "${OPENCLAW_CLAUDE_CREDENTIALS_JSON:-}" || -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]]; then
+                echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=subscription" >> "$GITHUB_ENV"
+              else
+                echo "OPENCLAW_LIVE_CLI_BACKEND_AUTH=api-key" >> "$GITHUB_ENV"
+              fi
               echo "OPENCLAW_LIVE_CLI_BACKEND_DEBUG=1" >> "$GITHUB_ENV"
               echo "OPENCLAW_CLI_BACKEND_LOG_OUTPUT=1" >> "$GITHUB_ENV"
               echo "OPENCLAW_TEST_CONSOLE=1" >> "$GITHUB_ENV"

.github/workflows/openclaw-release-publish.yml

@@ -1112,13 +1112,14 @@ jobs:
           }
 
           append_release_proof_to_github_release() {
-            local release_version body_file notes_file tarball integrity telegram_line clawhub_line clawhub_bootstrap_line clawhub_runtime_state_path windows_line
+            local release_version body_file notes_file evidence_path tarball integrity telegram_line clawhub_line clawhub_bootstrap_line clawhub_runtime_state_path windows_line
 
             release_version="${RELEASE_TAG#v}"
             body_file="${RUNNER_TEMP}/release-body.md"
             notes_file="${RUNNER_TEMP}/release-notes-with-proof.md"
-            tarball="$(npm view "openclaw@${release_version}" dist.tarball --json | jq -r '.')"
-            integrity="$(npm view "openclaw@${release_version}" dist.integrity --json | jq -r '.')"
+            evidence_path="${POSTPUBLISH_EVIDENCE_DIR}/release-postpublish-evidence.json"
+            tarball="$(jq -er '.openclawNpmTarball | select(type == "string" and length > 0)' "${evidence_path}")"
+            integrity="$(jq -er '.openclawNpmIntegrity | select(type == "string" and length > 0)' "${evidence_path}")"
             gh release view "${RELEASE_TAG}" --repo "$GITHUB_REPOSITORY" --json body --jq .body > "${body_file}"
 
             if [[ -n "${NPM_TELEGRAM_RUN_ID// }" ]]; then

.github/workflows/windows-blacksmith-testbox.yml

@@ -65,7 +65,9 @@ jobs:
           fi
           runner_ssh_port="${BLACKSMITH_SSH_PORT:-22}"
 
-          response="$(curl -s -f -L --post302 --post303 -X POST "${api_url}/api/testbox/phone-home" \
+          hydrating_response="$RUNNER_TEMP/testbox-hydrating.response"
+          hydrating_http_code="$(curl -sS -L --post302 --post303 -o "$hydrating_response" -w '%{http_code}' \
+            -X POST "${api_url}/api/testbox/phone-home" \
             -H "Content-Type: application/json" \
             -H "Authorization: Bearer ${auth_token}" \
             -d "{
@@ -77,7 +79,15 @@ jobs:
               \"working_directory\": \"${GITHUB_WORKSPACE}\",
               \"adopted_run_id\": \"${GITHUB_RUN_ID}\",
               \"metadata\": {}
-            }" 2>/dev/null || true)"
+            }" || true)"
+
+          echo "phone_home_hydrating_http=${hydrating_http_code}"
+          if [[ ! "$hydrating_http_code" =~ ^2 ]]; then
+            echo "Blacksmith phone-home hydrating failed; response body:" >&2
+            cat "$hydrating_response" >&2 || true
+            exit 1
+          fi
+          response="$(cat "$hydrating_response")"
 
           echo "$TESTBOX_ID" > "$state/testbox_id"
           echo "$installation_model_id" > "$state/installation_model_id"
@@ -100,12 +110,14 @@ jobs:
           fi
 
           ssh_public_key="$(cat "$state/ssh_public_key" 2>/dev/null || true)"
-          if [ -n "$ssh_public_key" ]; then
-            mkdir -p ~/.ssh
-            printf '%s\n' "$ssh_public_key" >> ~/.ssh/authorized_keys
-            chmod 700 ~/.ssh
-            chmod 600 ~/.ssh/authorized_keys
+          if [ -z "$ssh_public_key" ]; then
+            echo "Blacksmith phone-home did not return an SSH public key; testbox cannot accept CLI connections." >&2
+            exit 1
           fi
+          mkdir -p ~/.ssh
+          printf '%s\n' "$ssh_public_key" >> ~/.ssh/authorized_keys
+          chmod 700 ~/.ssh
+          chmod 600 ~/.ssh/authorized_keys
 
       - name: Checkout
         uses: actions/checkout@v6
@@ -161,6 +173,11 @@ jobs:
             -H "Authorization: Bearer ${auth_token}" \
             --data-binary @"$ready_body" || true)"
           echo "phone_home_ready_http=${http_code}"
+          if [[ ! "$http_code" =~ ^2 ]]; then
+            echo "Blacksmith phone-home ready failed; response body:" >&2
+            cat "$RUNNER_TEMP/testbox-ready.response" >&2 || true
+            exit 1
+          fi
 
           echo "============================================"
           echo "Testbox ready!"

.github/workflows/windows-testbox-probe.yml

@@ -133,8 +133,9 @@ jobs:
               $rootfs = "C:\wsl\ubuntu-noble-wsl.rootfs.tar.gz"
               New-Item -ItemType Directory -Force -Path @((Split-Path -Parent $rootfs), $wslRoot) | Out-Null
               Invoke-WebRequest -Uri $env:UBUNTU_WSL_ROOTFS_URL -OutFile $rootfs -UseBasicParsing
-              wsl.exe --import UbuntuProbe $wslRoot $rootfs --version 2
-              Write-Host "wsl_import_exit=$LASTEXITCODE"
+              $import = Invoke-WslText -Arguments @("--import", "UbuntuProbe", $wslRoot, $rootfs, "--version", "2")
+              Write-Host $import.Text
+              Write-Host "wsl_import_exit=$($import.Code)"
               $list = Invoke-WslText -Arguments @("--list", "--verbose")
               Write-Host $list.Text
               Write-Host "wsl_list_after_import_exit=$($list.Code)"
@@ -144,14 +145,15 @@ jobs:
             if ($distros.Count -gt 0) {
               $distro = $distros[0]
               Write-Host "wsl_probe_distro=$distro"
-              wsl.exe -d $distro --exec bash -lc 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi'
+              $exec = Invoke-WslText -Arguments @("-d", $distro, "--exec", "bash", "-lc", 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi')
             } else {
-              wsl.exe --exec bash -lc 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi'
+              $exec = Invoke-WslText -Arguments @("--exec", "bash", "-lc", 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi')
             }
-            if ($LASTEXITCODE -eq 0) {
+            Write-Host $exec.Text
+            if ($exec.Code -eq 0) {
               $ok = $true
             }
-            Write-Host "wsl_exec_exit=$LASTEXITCODE"
+            Write-Host "wsl_exec_exit=$($exec.Code)"
           }
 
           if ($ok) {

.github/workflows/workflow-sanity.yml

@@ -251,3 +251,6 @@ jobs:
 
       - name: Check plugin SDK API baseline drift
         run: pnpm plugin-sdk:api:check
+
+      - name: Check plugin SDK surface budget
+        run: pnpm plugin-sdk:surface:check

.gitignore

@@ -83,6 +83,12 @@ apps/ios/fastlane/screenshots/
 apps/ios/fastlane/test_output/
 apps/ios/fastlane/logs/
 apps/ios/fastlane/.env
+apps/android/fastlane/report.xml
+apps/android/fastlane/Preview.html
+apps/android/fastlane/test_output/
+apps/android/fastlane/logs/
+apps/android/fastlane/.env
+apps/android/fastlane/metadata/android/**/images/
 
 # fastlane build artifacts (local)
 apps/ios/*.ipa

AGENTS.md

@@ -172,7 +172,7 @@ Skills own workflows; root owns hard policy and routing.
 - PR artifacts/screenshots: attach to PR/comment/external artifact store. Never push screenshots, videos, proof images, or proof assets to OpenClaw or any product repo branch, including temp artifact branches. Use Crabbox artifact publishing plus the manifest URL. Do not commit `.github/pr-assets`.
 - CI polling: exact SHA, relevant checks only, minimal fields. Skip routine noise (`Auto response`, `Labeler`, docs agents, performance/stale). Logs only after failure/completion or concrete need.
 - OpenClaw write-access maintainers may skip `Real behavior proof` when local tests or Crabbox verified behavior; record proof in PR verification.
-- `/landpr`: use `~/.codex/prompts/landpr.md`; do not idle on `auto-response` or `check-docs`.
+- Agent PR landing to `main`: use only the repo-native `scripts/pr` wrapper: run `scripts/pr review-init <PR>`, follow its emitted checkout/guard guidance, initialize and complete review artifacts with `scripts/pr review-artifacts-init <PR>`, validate them with `scripts/pr review-validate-artifacts <PR>`, then run `scripts/pr prepare-run <PR>` and `scripts/pr merge-run <PR>`; do not idle on `auto-response` or `check-docs`.
 
 ## Code
 

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Docs: https://docs.openclaw.ai
 
+## 2026.6.9
+
+### Highlights
+
+- Channel delivery is steadier across WhatsApp GIF/media placeholders, Telegram rich progress and media directives, QQBot cron voice sends, Feishu card replies, Discord ingress/search, Matrix mentions, Mattermost mentions, and generated reply preservation. (#93679, #93698, #93690, #92947, #93618, #93449, #93407, #88796, #83156, #93242, #93629) Thanks @liuhao1024, @obviyus, @ZengWen-DT, @mgunnin, @SebTardif, @wdx-agent-io, @iloveleon19, and @lzyyzznl.
+- Agent, Gateway, and session recovery paths now surface Codex app-server failures, route approval notices with write scope, bootstrap plugin session targets, preserve prompt-released and failed-turn history, recover stale transcripts on reset, and keep assistant string content readable. (#93665, #93656, #93630, #93646, #89483, #93194, #93496) Thanks @litang9, @mushuiyu886, @ZengWen-DT, @Alix-007, @IWhatsskill, @snowzlm, and @harjothkhara.
+- Provider and plugin surfaces gained Codex hosted web search, remote-node Codex dynamic tools, Google Meet realtime provider secret inputs, Qwen image prompt placement, Bedrock embedding model normalization, key-free web-search opt-in behavior, and externally installed channel plugin startup loading. (#93446, #93654, #93677, #93649, #93452, #93616, #93470) Thanks @fuller-stack-dev, @goutamadwant, @LiuwqGit, @davemorin, and @sunlit-deng.
+- UI, onboarding, update, and setup flows preserve default models during auth setup, copy Control UI code blocks over plain HTTP, clear stale Talk errors, keep WebChat replies from double-rendering, preserve CJK IME composition, skip unsupported Homebrew prompts, and avoid per-Node npm prefixes during self-update. (#93658, #93666, #93606, #93298, #93498, #93521, #93650) Thanks @ml12580, @Pick-cat, @liuhao1024, @zhangguiping-xydt, and @Zhaoqj2016.
+
+### Changes
+
+- Add compact cron list responses and isolated model-usage diagnostics for scheduled runs. (#93395, #93398) Thanks @yu-xin-c and @849261680.
+- Add Codex hosted web search and expose remote-node execution as a Codex dynamic tool while keeping key-free web-search providers opt-in. (#93446, #93654, #93616) Thanks @fuller-stack-dev and @davemorin.
+- Add iOS watch action surfaces and refresh Android/iOS release upload metadata paths for mobile release preparation. (#93387) Thanks @Solvely-Colin and @joshavant.
+
+### Fixes
+
+- Channels: preserve unsent text-only finals after streamed partial content, recover lone Telegram spool handlers on timeout, bind Telegram bot mentions to assistant identity, hydrate Telegram group reply-chain media, preserve Mattermost Codex progress previews, bound WhatsApp read-receipt stalls, and distinguish WhatsApp GIF playback placeholders. (#93629, #93615, #93088, #93575, #93476, #93303, #93679) Thanks @liuhao1024, @0xghost42, @kesslerio, @eldar702, @goutamadwant, and @Alix-007.
+- Gateway, agents, and CLI: surface Codex app-server failures, compute usage totals across all sessions, accept `--log-level` after subcommands, skip compile cache on early Node 24.x, honor embedded-run default models, and preserve aborted isolated-run failures. (#93665, #93612, #93455, #89799, #93439, #93471) Thanks @litang9, @liuhao1024, @ooiuuii, @zhangguiping-xydt, @harjothkhara, and @BhargavSatya.
+- Providers and plugins: keep Google Meet realtime secret inputs declared, place DashScope image prompts in user content, strip Bedrock inference profile prefixes for embeddings, resolve provider policy for plugin-owned CLI backends, and allow Dreaming sidecars through restrictive memory allowlists. (#93677, #93649, #93452, #93261, #93678) Thanks @goutamadwant, @LiuwqGit, and @BitmapAsset.
+- Skills, memory, and doctor: preserve ClawHub origin provenance on readback, clear corrupt skill idempotency pointers, report skipped QMD embedding probes, archive superseded plugin install index conflicts, and repair null `agents.list[].workspace` values. (#93314, #93509, #93473, #93648, #93105) Thanks @Alix-007, @TurboTheTurtle, and @xydigit-sj.
+- Security and policy: audit open-DM tool exposure, redact secrets in `/debug` output, avoid parent group allowlist false positives, and keep externally installed channel plugins loaded at Gateway startup. (#92883, #93333, #93434, #93470) Thanks @yu-xin-c, @Alix-007, @kingrubic, and @sunlit-deng.
+- Runtime and tooling: rewrite pnpm versioned entry paths to stable wrappers, summarize cleanup dry-runs by label, route text decoding through the shared Windows codepage fallback, and keep root-owned service commands out of stale sudo scope. (#93671, #93565, #93555, #93693) Thanks @liuhao1024, @AgentArcLab, and @zhanxingxin1998.
+
 ## 2026.6.8
 
 ### Highlights
@@ -23,15 +47,26 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Onboarding/skills: show the Homebrew install recommendation only on macOS and Linux, so FreeBSD and other unsupported platforms no longer get a misleading brew prompt. Fixes #68893; carries forward #68894, #68910, #68941, #68943, #69002, and #69545. Thanks @yurivict, @Sanjays2402, @Eruditi, @JustInCache, @nnish16, and @Mlightsnow.
 - Channels and delivery: preserve account-scoped DM channel send policy, rich Telegram final replies, rich Telegram tables and lists, Telegram thread-create CLI remapping, Slack outbound `message_sent` hooks, contributed message-tool schema optionality, same-channel generated media completions, and channel chunking around surrogate pairs and Infinity limits. (#92788, #92679, #89421, #89943, #91137, #91246, #92735) Thanks @yetval, @obviyus, @spacegeologist, @rishitamrakar, @lundog, @TurboTheTurtle, and @yhterrance.
+- Auto-reply/groups: keep ordinary group text replies on automatic final-reply delivery while allowing `message(action=send)` for files, images, and other attachments to the same group or topic. Carries forward #43276; refs #48004. Thanks @NayukiChiba and @ShakaRover.
+- Auto-reply/skills: preserve multiline payloads for `/skill` and direct skill slash commands while keeping command-head normalization for aliases, colon syntax, and bot mentions. Fixes #79155; carries forward #81305. Thanks @web3blind.
+- iMessage: normalize leading NUL sent-message echo prefixes while preserving interior NUL bytes and the leading attributedBody marker handling from #73942. Carries forward #63581. Thanks @drvoss.
 - Discord: give generated auto-thread titles a 60-second timeout and 4,096-token reasoning-model output budget, clamped to the selected model output cap. (#64734) Thanks @hanamizuki.
 - Agent, cron, and Gateway runtime: mark active main sessions before restart shutdown aborts, pause yielded subagent runs whose terminal also signals abort, preserve yielded media completions, de-duplicate main-session heartbeat events, expose session identity in runtime prompts, reject unknown OpenAI agent selectors, keep generated media completions and slash-command block replies in WebChat, preserve fresh post-compaction usage while clearing stale usage snapshots, and require admin privileges for HTTP session/model override surfaces. (#91357, #92631, #92146, #91287, #92468, #92510, #91246, #50795, #50845, #82874, #92651, #92646) Thanks @ooiuuii, @openperf, @IWhatsskill, @ZengWen-DT, @zhangguiping-xydt, @Hollychou924, @leno23, and @TurboTheTurtle.
+- Agents/exec: default empty-success background completion notices on only for real chat channels, preserving explicit opt-outs and keeping generic providers silent while carrying forward the narrow UX intent from #39726 and #46926. Thanks @Sapientropic and @wenkang-xie.
 - Providers and model replay: preserve storeless OpenAI Responses replay compatibility, avoid eager tool streaming for Claude 4.5 in Copilot, honor profile auth for SecretRef model entries, bound model browsing, strip provider prefixes where runtimes need bare IDs, and surface nested embedding fetch failures. (#90706, #75393, #90686, #92247, #92627, #91218, #92628) Thanks @snowzlm, @Kailigithub, @rohitjavvadi, @samson910022, @liuhao1024, @bymle, and @mushuiyu886.
 - Memory, state, diagnostics, and config: split header-too-large embedding batches, keep QMD memory search enabled in transient mode, avoid SQLite WAL on NFS volumes, preserve recovery scheduling outside stuck-session warning backoff, and keep shell environment fallbacks contained in config write tests. (#92650, #92618, #92639, #91247, #92752) Thanks @mushuiyu886, @TurboTheTurtle, @849261680, and @gnanam1990.
+- Workspace setup state: store setup completion outside the workspace dot directory using an OpenClaw-named root file, migrate valid legacy state forward, and avoid clobbering generic root `workspace-state.json` files for TigerFS-style dot-path compatibility. This Clownfish replacement carries forward the focused #53326 fix idea because the original branch was closed and uneditable. (#53326, #44783, #39446) Thanks @1qh.
 - UI/mobile/TUI: preserve dashboard session parent lineage, WebChat backscroll, reset soft command args, sidebar session picker interactivity, collapsed workspace files, resolved `/model` confirmation refs, and stale foreground iOS Gateway reconnects. (#90658, #92622, #91353, #92705, #92779, #92773, #92552) Thanks @luoyanglang, @TurboTheTurtle, @zhouhe-xydt, @NianJiuZst, @shakkernerd, @NarahariRaghava, and @Solvely-Colin.
+- TUI: reload the active session after external `/new` or `/reset` session-change events so stale transcript and stream state clear promptly. Fixes #38966; carries forward #40472. Thanks @yizhanzjz and @wsyjh8.
+- Control UI: preserve Gateway Access tokens during same-normalized WebSocket URL edits and reload gateway-scoped tokens when switching endpoints. Fixes #41545; repairs #42001 with additional source PRs #41546, #41552, and #41718. Thanks @wsyjh8, @llagy0020, @llagy007, @pingfanfan, and @zheliu2.
+- Gateway CLI: tolerate a single transient clean WebSocket close before `hello-ok` so one-shot RPC calls reconnect instead of failing noisily, while repeated clean pre-hello closes still surface. Carries forward source PRs #54475 and #54774; #85253 covered adjacent connect assembly diagnostics. Thanks @ruanrrn.
+- Gateway/Linux: keep root-owned systemd user service lifecycle commands on root's user manager when a stale `SUDO_USER` remains in a root shell with root's user bus environment. Fixes #81410. Thanks @Ericksza and @ChuckClose-tech.
 - Release and test reliability: extend slow Gateway/full-suite watchdogs, split local full-suite shards when throttled, stabilize plugin auth marker fixtures, avoid brittle provider-ref error text, and keep QA Lab bootstrap selection assertions aligned with flow-only scenarios. (#92652)
 - macOS Peekaboo bridge: update the embedded Peekaboo package to 3.5.2 and route bundled-skill CLI commands through the OpenClaw app bridge so they inherit its Screen Recording and Accessibility grants.
 - Agent routing: route subagent RPC callbacks addressed to an agent-shaped `--to` target to the correct session key instead of falling back to the main session, so WeChat (and other channel) session-key callbacks reach the intended subagent session. (#90231) Thanks @zhangguiping-xydt.
+- Cron: preserve model, fallback, thinking, timeout, light-context, unsafe-content, and tool allow-list overrides on implicit text payloads by promoting them to agent turns, while explicit system events still prune those fields. Fixes #28905; carries forward #64060 and #73946. Thanks @liaoandi.
 - QQBot delivery: keep markdown table chunks self-contained across message boundaries by preserving table state across block deliveries, flushing unfinished table-row fragments as plain text, and detecting short pipe-terminated rows by column count so split rows are not sent as malformed markdown. (#92428) Thanks @sliverp.
 
 ## 2026.6.6

appcast.xml

@@ -2,6 +2,48 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>OpenClaw</title>
+        <item>
+            <title>2026.6.8</title>
+            <pubDate>Tue, 16 Jun 2026 17:17:20 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
+            <sparkle:version>2606000890</sparkle:version>
+            <sparkle:shortVersionString>2026.6.8</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>OpenClaw 2026.6.8</h2>
+<h3>Highlights</h3>
+<ul>
+<li>Telegram and WhatsApp channel delivery are richer and less brittle: Telegram can send structured rich text with tables, lists, expandable blockquotes, preserved intentional line breaks, prompt-preserving CLI backend delivery, retired native draft migration, and safer rich-media boundaries, while WhatsApp now honors configured ACP bindings. (#92679, #93164, #84082, #89421, #92513) Thanks @obviyus, @jzakirov, @spacegeologist, and @TurboTheTurtle.</li>
+<li>Agent and Gateway recovery is sharper across account-scoped DM sends, generated media completions, auto-reply message-tool final replies, reset archive fallback reads, restart shutdown aborts, yielded subagent pauses, trusted subagent thinking override fallback, yielded cron media, heartbeat dedupe, session identity prompts, and unknown OpenAI agent selector rejection. (#92788, #91246, #92879, #91357, #92631, #92412, #92146, #91287, #92468, #92510) Thanks @yetval, @TurboTheTurtle, @masatohoshino, @CadanHu, @ooiuuii, @openperf, @IWhatsskill, @ZengWen-DT, and @zhangguiping-xydt.</li>
+<li>Provider/model handling expands and tightens with GLM-5.2, Claude Haiku 4.5 catalog rows, OpenRouter and Google Vertex provider-prefix normalization, managed SecretRef auth, OAuth image-default routing through Codex, bounded model browse discovery, LM Studio binary thinking-off delivery, storeless OpenAI Responses replay gating, invalid OpenAI reasoning-signature and genericized Anthropic thinking-signature recovery, Claude 4.5 Copilot tool-streaming safety, and OpenAI/Anthropic-family payload quarantine for unreadable or post-hook tool schemas. (#92796, #90116, #92627, #91218, #90686, #92824, #92247, #92002, #90706, #92941, #92201, #92916, #75393, #92908, #92921, #92928) Thanks @arkyu2077, @liuhao1024, @bymle, @rohitjavvadi, @nxmxbbd, @bek91, @samson910022, @mmyzwl, @CarlCapital, @snowzlm, @Kailigithub, and @vincentkoc.</li>
+<li><code>/usage</code> and reply payload hooks now have a native full footer renderer, default template, fixed-decimal formatting, credential-aware limits, better partial-count handling, and warnings for broken templates instead of silent bad output. (#92657, #89835, #89629) Thanks @Marvinthebored.</li>
+<li>UI and mobile flows are steadier: workspace files can collapse and start collapsed, WebChat backscroll survives streaming, the sidebar session picker remains interactive above the desktop workbench, reset soft args survive UI dispatch, stale dashboard session parent lineage is preserved, and iOS reconnects stale foreground gateways. (#92779, #92622, #92705, #91353, #90658, #92552) Thanks @shakkernerd, @TurboTheTurtle, @NianJiuZst, @zhouhe-xydt, @luoyanglang, and @Solvely-Colin.</li>
+<li>Memory, state, and diagnostics recover cleaner: oversized OpenAI embedding batches split before 431s, QMD memory search stays available in transient mode, SQLite avoids WAL on NFS state volumes, stuck-session recovery scheduling no longer resets warning backoff, full memory reindexes preserve rollback/cache recovery, raw Memory Wiki source pages stop looking malformed, and Infinity chunk limits stay genuinely unbounded. (#92650, #92618, #92639, #91247, #92752, #92881, #59137, #92876, #69700, #92735) Thanks @mushuiyu886, @TurboTheTurtle, @849261680, @gnanam1990, @TSHOGX, @arlen8411, and @yhterrance.</li>
+</ul>
+<h3>Changes</h3>
+<ul>
+<li>Providers/models: add GLM-5.2 support and Claude Haiku 4.5 catalog entries while keeping provider-qualified model IDs normalized across OpenRouter and Google Vertex paths. (#92796, #90116, #92627, #91218) Thanks @arkyu2077, @liuhao1024, and @bymle.</li>
+<li>Web search: keep key-free providers such as Parallel Free, DuckDuckGo, Ollama, and Codex Hosted Search as explicit opt-ins instead of selecting them automatically when no API-backed provider is configured. (#93616) Thanks @davemorin and @vincentkoc.</li>
+<li>Channel plugins: ship Telegram rich-message delivery and WhatsApp ACP binding support, including preserved intentional line breaks, rich prompt handoff to CLI backends, and transport fixtures for richer drafts. (#92679, #93164, #92513) Thanks @obviyus and @TurboTheTurtle.</li>
+<li>Agent commands: support <code>/btw</code> in CLI-backed sessions and keep CLI usage-error exits classified as usage failures instead of successful runs. (#92669, #92162) Thanks @joshavant and @Pandah97.</li>
+<li>Usage hooks: add built-in full footer rendering, default footer templates, per-turn usage state, credential-aware limits, and fixed-decimal formatting for usage-bar templates. (#92657, #89835, #89629) Thanks @Marvinthebored.</li>
+<li>Docs and operator guidance: document node config examples, clarify before-install hook scope, correct agent default concurrency comments, refresh ZAI provider docs, and update channel/group docs for current Telegram and WhatsApp behavior. (#92677, #92766, #92695) Thanks @liuhao1024, @sallyom, and @ArielSmoliar.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Channels and delivery: preserve account-scoped DM channel send policy, intentional rich-message line breaks in Telegram and status output, rich Telegram final replies, rich Telegram tables and lists, Telegram thread-create CLI remapping, Feishu dynamic-agent routes after persisted binding reuse, Slack outbound <code>message_sent</code> hooks, contributed message-tool schema optionality, same-channel generated media completions, and channel chunking around surrogate pairs and Infinity limits. (#92788, #93164, #92679, #89421, #89943, #42837, #92814, #91137, #91246, #92735) Thanks @yetval, @obviyus, @spacegeologist, @rishitamrakar, @liuhao1024, @lundog, @TurboTheTurtle, and @yhterrance.</li>
+<li>Discord: give generated auto-thread titles a 60-second timeout and 4,096-token reasoning-model output budget, clamped to the selected model output cap. (#64734) Thanks @hanamizuki.</li>
+<li>Agent, cron, and Gateway runtime: mark active main sessions before restart shutdown aborts, pause yielded subagent runs whose terminal also signals abort, clamp trusted subagent thinking overrides through provider/model fallback, preserve yielded media completions, deliver channel message-tool final replies through auto-reply while hiding internal delivery hints, restore reset archive fallback reads when active async transcripts are missing, de-duplicate main-session heartbeat events, expose session identity in runtime prompts, reject unknown OpenAI agent selectors, keep generated media completions, slash-command block replies, and trajectory export commands in WebChat, and require admin privileges for HTTP session/model override surfaces. (#91357, #92631, #92412, #92146, #92879, #91287, #92468, #92510, #91246, #92651, #92646) Thanks @ooiuuii, @openperf, @IWhatsskill, @masatohoshino, @CadanHu, @ZengWen-DT, @zhangguiping-xydt, and @TurboTheTurtle.</li>
+<li>Providers and model replay: preserve storeless OpenAI Responses replay compatibility, recover invalid OpenAI reasoning signatures and genericized Anthropic thinking-signature replay errors, route OAuth image defaults through Codex for eligible OpenAI profiles, avoid eager tool streaming for Claude 4.5 in Copilot, quarantine unreadable and post-hook OpenAI/Anthropic-family tool schemas without broadening allowed tool choices, deliver explicit thinking-off requests to LM Studio binary-thinking models, honor profile auth for SecretRef model entries, bound model browsing, strip provider prefixes where runtimes need bare IDs, and surface nested embedding fetch failures. (#90706, #92941, #92201, #92916, #92824, #75393, #92908, #92921, #92928, #92002, #90686, #92247, #92627, #91218, #92628) Thanks @snowzlm, @mmyzwl, @CarlCapital, @bek91, @Kailigithub, @vincentkoc, @rohitjavvadi, @samson910022, @nxmxbbd, @liuhao1024, @bymle, and @mushuiyu886.</li>
+<li>Memory, state, diagnostics, and config: split header-too-large embedding batches, keep QMD memory search enabled in transient mode, avoid SQLite WAL on NFS volumes, preserve recovery scheduling outside stuck-session warning backoff, preserve full-reindex rollback/cache recovery, treat raw Memory Wiki source pages as source evidence, and keep shell environment fallbacks contained in config write tests. (#92650, #92618, #92639, #91247, #92752, #92881, #59137, #92876, #69700) Thanks @mushuiyu886, @TurboTheTurtle, @849261680, @gnanam1990, @TSHOGX, and @arlen8411.</li>
+<li>UI/mobile/TUI: preserve dashboard session parent lineage, WebChat backscroll, reset soft command args, sidebar session picker interactivity, collapsed workspace files, resolved <code>/model</code> confirmation refs, stale foreground iOS Gateway reconnects, and paused setup-parent stdin after inherited-stdio child exit. (#90658, #92622, #91353, #92705, #92779, #92773, #92552, #93159) Thanks @luoyanglang, @TurboTheTurtle, @zhouhe-xydt, @NianJiuZst, @shakkernerd, @NarahariRaghava, @Solvely-Colin, and @fuller-stack-dev.</li>
+<li>Plugins and updates: repair missing required platform packages during managed plugin installs and updates, including omitted Codex platform binaries.</li>
+<li>Dependencies: update Hono to 4.12.25 so published OpenClaw and ACPX packages use the patched runtime.</li>
+<li>Release and test reliability: extend slow Gateway/full-suite watchdogs, split local full-suite shards when throttled, stabilize plugin auth marker fixtures, avoid brittle provider-ref error text, fold Telegram RTT sampling into live QA evidence, simplify QA scorecard mappings around canonical coverage IDs, keep QA Lab bootstrap selection assertions aligned with flow-only scenarios, skip QA coverage artifact consumers when runtime parity producer status is not green, keep Feishu lifecycle release checks pointed at the active fixture config, isolate trajectory-export live seed turns from Codex-native shell approvals, preserve release-check child refs while pinning expected SHAs, widen live OpenAI TTS budgets for slower provider responses, and avoid false downgrade prompts for unresolved latest-tag updates. (#92652, #92550, #92558, #92911) Thanks @RomneyDa and @Andy312432.</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.6.8/OpenClaw-2026.6.8.zip" length="55815364" type="application/octet-stream" sparkle:edSignature="hLJ14xg6+DMFrXViIW3Njs++OPIGO+RWH9h+mPCSzXPAkKyYUGvtOLu1qEKvvfC8rs5FGgW/w4zDLfD2azqiBA=="/>
+        </item>
         <item>
             <title>2026.6.5</title>
             <pubDate>Tue, 09 Jun 2026 19:06:49 +0000</pubDate>
@@ -209,69 +251,5 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.6.1/OpenClaw-2026.6.1.zip" length="55062100" type="application/octet-stream" sparkle:edSignature="PVp8E2HBCvikB/0LCr36lFEyHPAzoFA2ScT6LW27FlzvP+m4r1AEuVN2UrtgWlpkGSsn4Eav0kPJe32u4ObNBw=="/>
         </item>
-        <item>
-            <title>2026.5.28</title>
-            <pubDate>Sat, 30 May 2026 21:21:09 +0000</pubDate>
-            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>2026052890</sparkle:version>
-            <sparkle:shortVersionString>2026.5.28</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>OpenClaw 2026.5.28</h2>
-<h3>Highlights</h3>
-<ul>
-<li>Agent and Codex runtime recovery is steadier: subagents keep cwd/workspace separation, hook context stays prompt-local, session locks release on timeout abort while live OpenClaw locks survive cleanup, stale restart continuations are avoided, and Codex app-server/helper failures no longer tear down shared runtime state. (#87218, #86875, #87409, #87399, #87375, #88129)</li>
-<li>Channel delivery and session identity got safer across outbound plugin hooks, Matrix room ids, iMessage reactions/approvals, Slack final replies, Discord recovered tool warnings, runtime-config message actions, WhatsApp profile auth roots, Telegram polling, and Microsoft Teams service URL trust checks. (#73706, #75670, #87366, #87451, #87334, #84535, #82492, #83304, #87160)</li>
-<li>Mobile and chat surfaces got a broader refresh: the iOS Pro UI, hosted push relay default, realtime Talk tab playback, Gateway chat transport, onboarding, Talk permissions, WebChat reconnect delivery, and session picker behavior now preserve more state across reconnects and empty searches. (#87367, #87531, #87682, #88096, #88105) Thanks @ngutman.</li>
-<li>Browser, channel, and automation inputs are stricter: Browser tool timeouts, viewport/tab indices, Gateway ports, cron retry handling, Discord component ids, schema array refs, Telegram callback pages, and channel progress callbacks now reject malformed values earlier and preserve the intended delivery context. (#82887)</li>
-<li>Provider, media, and document coverage expands with Claude Opus 4.8, Fal Krea image schemas, NVIDIA featured models, MiniMax streaming music responses, encrypted PDF extraction, voice model catalogs, GitHub Copilot agent runtime support, and a Codex Supervisor plugin path for delegated Codex workflows. (#87845, #87890, #80775, #84764, #87751, #87794)</li>
-<li>CLI, auth, doctor, and provider paths fail faster and recover more clearly: malformed numeric/version options are rejected, workspace dotenv provider credentials are ignored, heartbeat defaults, OAuth/token lifetimes, and local service startup requests are bounded, agent auth health labels are clearer, legacy <code>api_key</code> auth profiles migrate to canonical form, and restart guidance is actionable. (#87398, #86281, #87361, #88133, #83655, #87559, #88088, #85924) Thanks @vincentkoc and @giodl73-repo.</li>
-<li>Plugin and Gateway hot paths do less repeated work while preserving cache correctness for install records, config JSON parsing, tool search catalogs, session stores, manifest model rows, auto-enabled plugin config, browser tokens, viewer assets, and release-split external plugin packages. (#86699)</li>
-<li>Release, QA, and E2E validation now bound more log, artifact, harness, and cross-OS waits so failing lanes produce proof instead of hanging or false-greening.</li>
-</ul>
-<h3>Changes</h3>
-<ul>
-<li>Status: show active subagent details in status output.</li>
-<li>Diffs: split the default language pack and expand default Diffs language coverage while keeping the host floor aligned. (#87370, #87372) Thanks @RomneyDa.</li>
-<li>ClawHub: add plugin display names plus skill verification and trust surfaces. (#87354, #86699) Thanks @thewilloftheshadow and @Patrick-Erichsen.</li>
-<li>iOS: refresh the dev app with Pro Command, Chat, Agents, Settings, hosted push relay defaults, and realtime Talk playback wired to gateway sessions, diagnostics, chat, and realtime Talk. (#87367, #88096, #88105) Thanks @Solvely-Colin and @ngutman.</li>
-<li>Docs: clarify Codex computer-use setup, paste-token stdin auth setup, macOS gateway sleep troubleshooting, native Codex hook relay recovery, container model auth, install deployment cards, device-token admin gating, CLI setup flow compatibility, Notte cloud browser CDP setup, and backport targets. (#87313, #63050, #87685) Thanks @bdjben, @liaoandi, and @thewilloftheshadow.</li>
-<li>PDF/tools: use ClawPDF for PDF extraction, support encrypted PDF extraction, and surface MCP structured content in agent tool results. (#87670, #87751)</li>
-<li>Providers: add Claude Opus 4.8 support, Fal Krea image model schemas, NVIDIA featured model catalogs, MiniMax streaming music responses, and provider-backed voice model catalogs. (#87845, #87890, #80775, #84764, #87794) Thanks @eleqtrizit and @vincentkoc.</li>
-<li>Codex/GitHub: add the GitHub Copilot agent runtime and the Codex Supervisor plugin package.</li>
-<li>Plugins: externalize GitHub Copilot and Tokenjuice as official install-on-demand plugins with npm and ClawHub publish metadata.</li>
-<li>Workboard: add agent coordination tools for tracking and handing off active agent work.</li>
-<li>Discord: show commentary in progress drafts so live Discord runs expose useful in-progress context. (#85200)</li>
-<li>Plugin SDK: add a reply payload sending hook for plugins that need to deliver channel-owned replies and flatten package types for SDK declarations. (#82823, #87165) Thanks @RomneyDa.</li>
-<li>Policy: add policy comparison, ingress-channel conformance, and sandbox-posture conformance checks. (#85572, #85744, #86768)</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Agents: fall back to local config pruning when the optional <code>agents delete</code> Gateway probe cannot authenticate, so offline installs can still delete agents without removing shared workspaces.</li>
-<li>Tighten phone-control mutation authorization [AI]. (#87150) Thanks @pgondhi987.</li>
-<li>Clarify directive persistence authorization policy [AI]. (#86369) Thanks @pgondhi987.</li>
-<li>Agents/Codex: keep spawned agent cwd/workspace state separated, forward ACP spawn attachments, keep hook context prompt-local, release session locks on timeout abort and runtime teardown without deleting live OpenClaw-owned locks during cleanup, avoid session event queue self-wait, clean up exec abort listeners, stream assistant deltas incrementally, recover raw missing-thread compaction failures, preserve rotated compaction session identity, keep compaction-timeout snapshots continuable, preserve shared app-server state across startup or helper failures, keep native hook relay alive across restarts and prune stale bridge files, close native hook relay replacement races, keep Claude live tool progress visible for watchdog recovery, suppress abandoned requester completion handoff, route workspace memory through tools, resolve Codex runtime models first, report quarantined dynamic tools, format <code>skills</code> command output, bind node auto-review to prepared plans, retry Claude CLI transcript probes, and bound compaction/steering retries. (#87218, #86875, #86123, #88129, #87399, #87375, #72574, #87383, #87400, #83022, #87671, #87738, #87747, #87706, #87546, #87541, #81048) Thanks @mbelinky, @Alix-007, @luoyanglang, @yetval, @sjf, @joshavant, and @benjamin1492.</li>
-<li>Codex Supervisor: keep real-home app-server MCP session listing on the loaded state path, bound stored history scans, and close WebSocket probes cleanly.</li>
-<li>Channels: thread canonical session keys into outbound hooks, preserve Matrix room-id case, keep fallback tool warnings mention-inert, retain delivered Slack final replies during late cleanup, continue iMessage polling after denied reactions, suppress duplicate native exec approvals, resolve Gateway message actions against the active runtime config, preserve Telegram SecretRef prompt config and polling keepalives, preserve WhatsApp profile auth roots, QR display, document filenames, and plugin hook config, suppress Discord recovered tool warnings, preserve the Discord voice outbound helper, cap Discord/Signal/Zalo channel request and container timeouts, and block untrusted Teams service URLs while keeping TeamsSDK patterns aligned. (#73706, #75670, #87366, #87451, #87465, #87334, #84535, #76262, #83304, #82492, #87581, #77114, #86426, #85529, #87160) Thanks @zeroaltitude, @lukeboyett, @xiaotian, @funmerlin, @joshavant, @eleqtrizit, @heyitsaamir, @amittell, @liorb-mountapps, @masatohoshino, @bladin, and @giodl73-repo.</li>
-<li>CLI/auth/doctor/providers: reject malformed numeric/timeout/subcommand-version inputs, ignore workspace dotenv provider credentials, wait for respawn child shutdown, bound heartbeat defaults plus Codex, GitHub Copilot, OpenAI, Anthropic, Google, Feishu, LM Studio, MiniMax, Xiaomi TTS, and local-provider OAuth/token/model requests, harden Codex auth probes, label auth health by agent, preserve explicit agentRuntime pins during Codex model migration, warm provider auth off the main thread, honor Codex response timeouts, stop migrating current Claude Haiku 4.5 profiles to Sonnet, bound local service startup, resolve GPT-5.5 without cached catalog, migrate legacy memory auto-provider config, rewrite non-canonical <code>api_key</code> auth profiles, and make doctor restart follow-ups actionable. (#87398, #86281, #87361, #88133, #83655, #87559, #87719, #88088, #85924, #84362) Thanks @Patrick-Erichsen, @samzong, @giodl73-repo, @alkor2000, @mmaps, @nxmxbbd, and @vincentkoc.</li>
-<li>Gateway/security/session state: expire browser tokens after auth rotation, scope assistant idempotency dedupe, drain probe client closes, avoid stale restart continuation reuse, preserve retry-after fallbacks and stale rate-limit cooldown probes, bound webchat image and artifact transcript scans, include seconds in inbound metadata timestamps, clear completed session active runs, clear stale chat stream buffers, and evict current plugin-state namespaces at row caps. (#87810, #87833, #75089) Thanks @joshavant and @litang9.</li>
-<li>Config/parsing/network: reject partial numeric parsing, parse provider/Discord retry headers and dates strictly, honor IPv6 and bare IPv6 <code>no_proxy</code> entries, preserve empty plugin allowlists, canonicalize secret target array indexes, and reject malformed media content lengths, inspected TCP ports, marketplace content lengths, cron epochs, sandbox stat fields, unsafe duration values, empty config path segments, noncanonical schema array refs, unsafe Telegram callback pages, and invalid Teams attachment-fetch DNS targets. (#87883) Thanks @zhangguiping-xydt.</li>
-<li>Browser/input hardening: reject invalid tab indexes, excessive viewport resizes, explicit zero CDP ports, malformed geolocation options, unsafe screenshot or permission-grant timeouts, loose response-body limits, invalid cookie expiries, and non-finite Browser tool delays/timeouts.</li>
-<li>Cron/automation: retry recurring jobs after transient model rate limits before waiting for the next scheduled slot, and preflight model fallbacks before skipping scheduled work. (#82887)</li>
-<li>Auto-reply/directives: respect provider and relayed channel metadata during directive persistence so channel-originated decisions keep their intended context. (#87683)</li>
-<li>WhatsApp: resolve the auth directory from the active profile so profile-scoped WhatsApp installs do not drift to the wrong credential root. (#82492)</li>
-<li>Gateway/session state: clear completed session active runs, avoid cold-loading providers for MCP inventory, cache single-session child indexes, cap handshake timers, and bound preauth, auth-guard, media, transcript, readiness, and port options.</li>
-<li>Channels/replies: preserve channel-owned progress callbacks when verbose output is off, keep group-room progress suppression intact, prefer external session delivery context, escape Discord component id delimiters, force final TUI chat repaints, show Slack reasoning previews, and normalize Discord/Matrix/Mattermost channel numeric options. (#87476, #87423)</li>
-<li>Agents/tool args: harden smart-quoted argument repair for edit arrays and exact escaped arguments so model-produced tool calls recover without corrupting valid input. (#86611)</li>
-<li>Providers/agents: preserve seeded Anthropic signatures, preserve signed thinking payloads, concatenate signature-delta chunks, preserve DeepSeek <code>reasoning_content</code> replay across tier suffixes, apply OpenRouter strict9 ids to Mistral routes, promote Ollama plain-text tool calls, load NVIDIA featured model catalogs, stream MiniMax music generation responses, and recover empty preflight compaction. (#87593, #87493, #80775, #84764) Thanks @eleqtrizit.</li>
-<li>Media/images: skip CLI image cache refs when resolving generated images, allow trusted generated HTML attachments, and bound generated video downloads so stale refs and slow providers fail cleanly. (#87523, #87982)</li>
-<li>File transfer: handle late tar stdin pipe errors after archive validation or unpacking has already settled.</li>
-<li>Performance: trust install-record caches between reloads, prefer native JSON parsing, reuse unchanged tool-search catalogs, reuse gateway session and plugin metadata paths, skip unchanged store serialization, patch single-entry session writes, add precomputed session patch writers, reduce store clone allocations, cache manifest model catalog rows and auto-enabled plugin config, avoid full session snapshots for entry reads, defer configured Slack full startup, prefer bundled plugin dist entries, and slim current metadata identity caches. (#87760)</li>
-<li>Docker/release/QA: package runtime workspace templates, stream cross-OS served artifacts, preserve sparse Crabbox run artifacts, isolate npm plugin installs per package, reject incompatible package plugin API installs, drop the leftover root Sharp dependency from package manifests after the Rastermill migration, bound OpenClaw instance logs, plugin gauntlet relay logs, MCP channel buffers, kitchen-sink scans, agent-turn assertions, QA-Lab credential broker calls, QA Matrix substrate requests, and release scenario logs, and keep release/google live guards current. (#87647, #87477) Thanks @rohitjavvadi and @vincentkoc.</li>
-<li>Release/CI: bound manual git fetches, ClawHub verifier responses, ClawHub owner metadata, dependency-guard error bodies, Parallels limits, startup/test/memory budget parsing, and diffs viewer build warnings so release lanes fail with useful proof instead of hanging. (#87839)</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.5.28/OpenClaw-2026.5.28.zip" length="54750142" type="application/octet-stream" sparkle:edSignature="U4O55uMdPU+OqSx9QR1ApUJ8wg65wxTydzD7iyCn1GHtm1MBK9noEeiA/yoUKkqb/bx0hzi1gNhn+ye19RXnCA=="/>
-        </item>
     </channel>
 </rss>

apps/android/Config/Version.properties

@@ -0,0 +1,6 @@
+# Shared Android version defaults.
+# Source of truth: apps/android/version.json
+# Generated by scripts/android-sync-versioning.ts.
+
+OPENCLAW_ANDROID_VERSION_NAME=2026.6.2
+OPENCLAW_ANDROID_VERSION_CODE=2026060201

apps/android/README.md

@@ -32,7 +32,7 @@ cd apps/android
 ./gradlew :app:installPlayDebug
 ./gradlew :app:testPlayDebugUnitTest
 cd ../..
-bun run android:bundle:release
+pnpm android:release:archive
 ```
 
 Third-party debug flavor:
@@ -44,10 +44,29 @@ cd apps/android
 ./gradlew :app:testThirdPartyDebugUnitTest
 ```
 
-`bun run android:bundle:release` auto-bumps Android `versionName`/`versionCode` in `apps/android/app/build.gradle.kts`, then builds two signed release bundles:
+Android release archives use the pinned version in `apps/android/version.json`. Update it with:
 
-- Play build: `apps/android/build/release-bundles/openclaw-<version>-play-release.aab`
-- Third-party build: `apps/android/build/release-bundles/openclaw-<version>-third-party-release.aab`
+```bash
+pnpm android:version
+pnpm android:version:check
+pnpm android:version:pin -- --from-gateway
+pnpm android:version:pin -- --version 2026.6.5 --version-code 2026060501
+```
+
+Generate raw Google Play screenshots:
+
+```bash
+pnpm android:screenshots
+```
+
+`pnpm android:release:archive` builds signed release artifacts into `apps/android/build/release-artifacts/` and writes `.sha256` checksum files:
+
+- Play build: `openclaw-<version>-play-release.aab`
+- Third-party build: `openclaw-<version>-third-party-release.apk`
+
+`pnpm android:bundle:release` is an alias for the same archive helper.
+
+See `apps/android/VERSIONING.md` and `apps/android/fastlane/SETUP.md` for the release workflow.
 
 Flavor-specific direct Gradle tasks:
 

apps/android/VERSIONING.md

@@ -0,0 +1,38 @@
+# OpenClaw Android Versioning
+
+Android release builds use pinned app metadata instead of auto-bumping `build.gradle.kts`.
+
+## Version model
+
+- `apps/android/version.json` is the source of truth.
+- `version` is the Play `versionName` and uses CalVer: `YYYY.M.D`.
+- `versionCode` uses `YYYYMMDDNN`, where `NN` is a two-digit build number for that pinned app version.
+- `apps/android/Config/Version.properties` is generated from `version.json` and read by Gradle.
+
+Examples:
+
+- `version = 2026.6.2`
+- `versionCode = 2026060201`
+- another upload on the same release train: `versionCode = 2026060202`
+
+## Commands
+
+```bash
+pnpm android:version
+pnpm android:version:check
+pnpm android:version:sync
+pnpm android:version:pin -- --from-gateway
+pnpm android:version:pin -- --version 2026.6.5 --version-code 2026060501
+```
+
+## Release Workflow
+
+1. Pin Android to the intended release version.
+2. Run `pnpm android:version:sync`.
+3. Update `apps/android/fastlane/metadata/android/en-US/release_notes.txt`.
+4. Run `pnpm android:screenshots` to refresh raw Google Play screenshots.
+5. Run `pnpm android:release:archive` to produce the signed Play AAB and third-party APK.
+6. Run `pnpm android:release:upload` to upload metadata, screenshots, and the Play AAB to Google Play internal testing.
+7. Promote to production manually in Google Play Console.
+
+The third-party flavor is archived as a signed APK for non-Play distribution. It is not uploaded by the Play release lane.

apps/android/app/build.gradle.kts

@@ -1,6 +1,24 @@
 import com.android.build.api.variant.impl.VariantOutputImpl
+import java.util.Properties
 
 val dnsjavaInetAddressResolverService = "META-INF/services/java.net.spi.InetAddressResolverProvider"
+val openClawAndroidVersionFile = rootProject.file("Config/Version.properties")
+val openClawAndroidVersionProperties =
+  Properties().apply {
+    if (!openClawAndroidVersionFile.isFile) {
+      error("Missing Android version properties. Run `pnpm android:version:sync`.")
+    }
+    openClawAndroidVersionFile.inputStream().use(::load)
+  }
+
+fun requireOpenClawAndroidVersionProperty(name: String): String =
+  openClawAndroidVersionProperties.getProperty(name)?.trim()?.takeIf { it.isNotEmpty() }
+    ?: error("Missing $name in Config/Version.properties. Run `pnpm android:version:sync`.")
+
+val openClawAndroidVersionName = requireOpenClawAndroidVersionProperty("OPENCLAW_ANDROID_VERSION_NAME")
+val openClawAndroidVersionCode =
+  requireOpenClawAndroidVersionProperty("OPENCLAW_ANDROID_VERSION_CODE").toIntOrNull()
+    ?: error("OPENCLAW_ANDROID_VERSION_CODE must be an integer in Config/Version.properties.")
 
 val androidStoreFile = providers.gradleProperty("OPENCLAW_ANDROID_STORE_FILE").orNull?.takeIf { it.isNotBlank() }
 val androidStorePassword = providers.gradleProperty("OPENCLAW_ANDROID_STORE_PASSWORD").orNull?.takeIf { it.isNotBlank() }
@@ -65,8 +83,8 @@ android {
     applicationId = "ai.openclaw.app"
     minSdk = 31
     targetSdk = 36
-    versionCode = 2026060201
-    versionName = "2026.6.2"
+    versionCode = openClawAndroidVersionCode
+    versionName = openClawAndroidVersionName
     ndk {
       // Support all major ABIs — native libs are tiny (~47 KB per ABI)
       abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")

apps/android/app/src/main/java/ai/openclaw/app/AndroidScreenshotMode.kt

@@ -0,0 +1,28 @@
+package ai.openclaw.app
+
+import android.content.Intent
+
+const val extraAndroidScreenshotMode = "openclaw.screenshotMode"
+const val extraAndroidScreenshotScene = "openclaw.screenshotScene"
+
+enum class AndroidScreenshotScene(
+  val rawValue: String,
+) {
+  Connect("connect"),
+  Chat("chat"),
+  Voice("voice"),
+  Screen("screen"),
+  Settings("settings"),
+  ;
+
+  companion object {
+    fun fromRawValue(raw: String?): AndroidScreenshotScene = entries.firstOrNull { it.rawValue == raw?.trim()?.lowercase() } ?: Connect
+  }
+}
+
+fun parseAndroidScreenshotModeIntent(intent: Intent?): AndroidScreenshotScene? {
+  if (intent?.getBooleanExtra(extraAndroidScreenshotMode, false) != true) {
+    return null
+  }
+  return AndroidScreenshotScene.fromRawValue(intent.getStringExtra(extraAndroidScreenshotScene))
+}

apps/android/app/src/main/java/ai/openclaw/app/MainActivity.kt

@@ -1,5 +1,6 @@
 package ai.openclaw.app
 
+import ai.openclaw.app.ui.AndroidScreenshotModeScreen
 import ai.openclaw.app.ui.OpenClawTheme
 import ai.openclaw.app.ui.RootScreen
 import android.content.Intent
@@ -51,6 +52,12 @@ class MainActivity : ComponentActivity() {
     pendingIntent = intent
     WindowCompat.setDecorFitsSystemWindows(window, false)
     permissionRequester = PermissionRequester(this)
+    if (BuildConfig.DEBUG) {
+      parseAndroidScreenshotModeIntent(intent)?.let { scene ->
+        enterScreenshotMode(scene)
+        return
+      }
+    }
 
     setContent {
       var activeViewModel by remember { mutableStateOf<MainViewModel?>(null) }
@@ -79,6 +86,12 @@ class MainActivity : ComponentActivity() {
     }
   }
 
+  private fun enterScreenshotMode(scene: AndroidScreenshotScene) {
+    setContent {
+      AndroidScreenshotModeScreen(scene = scene)
+    }
+  }
+
   override fun onStart() {
     super.onStart()
     foreground = true

apps/android/app/src/main/java/ai/openclaw/app/ui/AndroidScreenshotModeScreen.kt

@@ -0,0 +1,394 @@
+package ai.openclaw.app.ui
+
+import ai.openclaw.app.AndroidScreenshotScene
+import ai.openclaw.app.ui.design.ClawDesignTheme
+import ai.openclaw.app.ui.design.ClawTheme
+import androidx.compose.foundation.BorderStroke
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ScreenShare
+import androidx.compose.material.icons.filled.ChatBubble
+import androidx.compose.material.icons.filled.CheckCircle
+import androidx.compose.material.icons.filled.Mic
+import androidx.compose.material.icons.filled.Settings
+import androidx.compose.material.icons.filled.WifiTethering
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun AndroidScreenshotModeScreen(scene: AndroidScreenshotScene) {
+  ClawDesignTheme(dark = true) {
+    Column(
+      modifier =
+        Modifier
+          .fillMaxSize()
+          .background(ClawTheme.colors.canvas)
+          .padding(horizontal = 20.dp, vertical = 26.dp),
+      verticalArrangement = Arrangement.SpaceBetween,
+    ) {
+      ScreenshotHeader(scene)
+      ScreenshotSceneBody(scene = scene, modifier = Modifier.weight(1f))
+      ScreenshotTabBar(activeScene = scene)
+    }
+  }
+}
+
+@Composable
+private fun ScreenshotHeader(scene: AndroidScreenshotScene) {
+  Row(
+    modifier = Modifier.fillMaxWidth(),
+    horizontalArrangement = Arrangement.SpaceBetween,
+    verticalAlignment = Alignment.CenterVertically,
+  ) {
+    Column {
+      Text(text = "OpenClaw", style = ClawTheme.type.title, color = ClawTheme.colors.text)
+      Text(
+        text = sceneTitle(scene),
+        style = ClawTheme.type.caption,
+        color = ClawTheme.colors.textMuted,
+      )
+    }
+    StatusPill(label = "Connected", color = ClawTheme.colors.success)
+  }
+}
+
+@Composable
+private fun ScreenshotSceneBody(
+  scene: AndroidScreenshotScene,
+  modifier: Modifier = Modifier,
+) {
+  Column(
+    modifier = modifier.fillMaxWidth().padding(vertical = 20.dp),
+    verticalArrangement = Arrangement.spacedBy(14.dp),
+  ) {
+    when (scene) {
+      AndroidScreenshotScene.Connect -> ConnectScene()
+      AndroidScreenshotScene.Chat -> ChatScene()
+      AndroidScreenshotScene.Voice -> VoiceScene()
+      AndroidScreenshotScene.Screen -> ScreenScene()
+      AndroidScreenshotScene.Settings -> SettingsScene()
+    }
+  }
+}
+
+@Composable
+private fun ConnectScene() {
+  FeaturePanel(icon = Icons.Default.WifiTethering, title = "Gateway paired", subtitle = "Mac Studio - Tailnet") {
+    MetricRow(label = "Node", value = "Android Pixel 9")
+    MetricRow(label = "Transport", value = "Secure WebSocket")
+    MetricRow(label = "Capabilities", value = "Chat, Talk, Camera, Screen")
+  }
+  CompactList(
+    title = "Ready",
+    rows =
+      listOf(
+        "Push wakes active",
+        "Approvals synced",
+        "Device tools available",
+      ),
+  )
+}
+
+@Composable
+private fun ChatScene() {
+  ChatBubble(label = "You", text = "Summarize the launch checklist before I start the release.")
+  ChatBubble(
+    label = "OpenClaw",
+    text = "Android archive, Play metadata, and internal testing upload are ready. Screenshots are being refreshed now.",
+    raised = true,
+  )
+  CompactList(
+    title = "Working set",
+    rows = listOf("Release notes", "Play bundle", "Device screenshots"),
+  )
+}
+
+@Composable
+private fun VoiceScene() {
+  Box(modifier = Modifier.fillMaxWidth().padding(vertical = 20.dp), contentAlignment = Alignment.Center) {
+    Surface(
+      modifier = Modifier.size(196.dp),
+      shape = CircleShape,
+      color = ClawTheme.colors.surfaceRaised,
+      border = BorderStroke(1.dp, ClawTheme.colors.borderStrong),
+    ) {
+      Box(contentAlignment = Alignment.Center) {
+        Icon(
+          imageVector = Icons.Default.Mic,
+          contentDescription = null,
+          tint = ClawTheme.colors.primary,
+          modifier = Modifier.size(72.dp),
+        )
+      }
+    }
+  }
+  FeaturePanel(icon = Icons.Default.Mic, title = "Talk mode", subtitle = "Listening on device") {
+    MetricRow(label = "Wake phrase", value = "OpenClaw")
+    MetricRow(label = "Latency", value = "Realtime")
+  }
+}
+
+@Composable
+private fun ScreenScene() {
+  FeaturePanel(icon = Icons.AutoMirrored.Filled.ScreenShare, title = "Screen tools", subtitle = "Shared with your gateway") {
+    MetricRow(label = "Canvas", value = "Available")
+    MetricRow(label = "Camera", value = "Permission granted")
+    MetricRow(label = "Location", value = "On request")
+  }
+  Surface(
+    modifier = Modifier.fillMaxWidth().height(168.dp),
+    shape = RoundedCornerShape(8.dp),
+    color = ClawTheme.colors.surfaceRaised,
+    border = BorderStroke(1.dp, ClawTheme.colors.border),
+  ) {
+    Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(10.dp)) {
+      Text(text = "Live context", style = ClawTheme.type.section, color = ClawTheme.colors.text)
+      ContextBar(label = "Camera", fraction = 0.74f)
+      ContextBar(label = "Screen", fraction = 0.58f)
+      ContextBar(label = "Location", fraction = 0.38f)
+    }
+  }
+}
+
+@Composable
+private fun SettingsScene() {
+  CompactList(
+    title = "Security",
+    rows = listOf("Biometric lock enabled", "Gateway token encrypted", "Tool approvals required"),
+  )
+  CompactList(
+    title = "Notifications",
+    rows = listOf("Gateway status", "Approval requests", "Background presence"),
+  )
+}
+
+@Composable
+private fun FeaturePanel(
+  icon: ImageVector,
+  title: String,
+  subtitle: String,
+  content: @Composable () -> Unit,
+) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(8.dp),
+    color = ClawTheme.colors.surface,
+    border = BorderStroke(1.dp, ClawTheme.colors.border),
+  ) {
+    Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(14.dp)) {
+      Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+        IconBox(icon = icon)
+        Column {
+          Text(text = title, style = ClawTheme.type.section, color = ClawTheme.colors.text)
+          Text(text = subtitle, style = ClawTheme.type.caption, color = ClawTheme.colors.textMuted)
+        }
+      }
+      content()
+    }
+  }
+}
+
+@Composable
+private fun CompactList(
+  title: String,
+  rows: List<String>,
+) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(8.dp),
+    color = ClawTheme.colors.surfaceRaised,
+    border = BorderStroke(1.dp, ClawTheme.colors.border),
+  ) {
+    Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
+      Text(text = title, style = ClawTheme.type.section, color = ClawTheme.colors.text)
+      rows.forEach { row ->
+        Row(verticalAlignment = Alignment.CenterVertically) {
+          Box(modifier = Modifier.size(7.dp).clip(CircleShape).background(ClawTheme.colors.success))
+          Spacer(modifier = Modifier.width(10.dp))
+          Text(text = row, style = ClawTheme.type.body, color = ClawTheme.colors.textMuted)
+        }
+      }
+    }
+  }
+}
+
+@Composable
+private fun ChatBubble(
+  label: String,
+  text: String,
+  raised: Boolean = false,
+) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(8.dp),
+    color = if (raised) ClawTheme.colors.surfaceRaised else ClawTheme.colors.surface,
+    border = BorderStroke(1.dp, if (raised) ClawTheme.colors.borderStrong else ClawTheme.colors.border),
+  ) {
+    Column(modifier = Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(8.dp)) {
+      Text(text = label, style = ClawTheme.type.caption, color = ClawTheme.colors.textSubtle)
+      Text(text = text, style = ClawTheme.type.body, color = ClawTheme.colors.text)
+    }
+  }
+}
+
+@Composable
+private fun MetricRow(
+  label: String,
+  value: String,
+) {
+  Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+    Text(text = label, style = ClawTheme.type.body, color = ClawTheme.colors.textMuted)
+    Text(
+      text = value,
+      style = ClawTheme.type.label,
+      color = ClawTheme.colors.text,
+      maxLines = 1,
+      overflow = TextOverflow.Ellipsis,
+    )
+  }
+}
+
+@Composable
+private fun ContextBar(
+  label: String,
+  fraction: Float,
+) {
+  Column(verticalArrangement = Arrangement.spacedBy(5.dp)) {
+    Text(text = label, style = ClawTheme.type.caption, color = ClawTheme.colors.textMuted)
+    Box(
+      modifier =
+        Modifier
+          .fillMaxWidth()
+          .height(7.dp)
+          .clip(RoundedCornerShape(4.dp))
+          .background(ClawTheme.colors.surfacePressed),
+    ) {
+      Box(
+        modifier =
+          Modifier
+            .fillMaxWidth(fraction)
+            .height(7.dp)
+            .background(ClawTheme.colors.primary),
+      )
+    }
+  }
+}
+
+@Composable
+private fun ScreenshotTabBar(activeScene: AndroidScreenshotScene) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(8.dp),
+    color = ClawTheme.colors.surface,
+    border = BorderStroke(1.dp, ClawTheme.colors.border),
+  ) {
+    Row(
+      modifier = Modifier.padding(horizontal = 10.dp, vertical = 8.dp),
+      horizontalArrangement = Arrangement.SpaceBetween,
+    ) {
+      TabIcon(icon = Icons.Default.CheckCircle, active = activeScene == AndroidScreenshotScene.Connect)
+      TabIcon(icon = Icons.Default.ChatBubble, active = activeScene == AndroidScreenshotScene.Chat)
+      TabIcon(icon = Icons.Default.Mic, active = activeScene == AndroidScreenshotScene.Voice)
+      TabIcon(icon = Icons.AutoMirrored.Filled.ScreenShare, active = activeScene == AndroidScreenshotScene.Screen)
+      TabIcon(icon = Icons.Default.Settings, active = activeScene == AndroidScreenshotScene.Settings)
+    }
+  }
+}
+
+@Composable
+private fun TabIcon(
+  icon: ImageVector,
+  active: Boolean,
+) {
+  Box(
+    modifier =
+      Modifier
+        .size(42.dp)
+        .clip(RoundedCornerShape(6.dp))
+        .background(if (active) ClawTheme.colors.surfacePressed else Color.Transparent),
+    contentAlignment = Alignment.Center,
+  ) {
+    Icon(
+      imageVector = icon,
+      contentDescription = null,
+      tint = if (active) ClawTheme.colors.text else ClawTheme.colors.textSubtle,
+      modifier = Modifier.size(20.dp),
+    )
+  }
+}
+
+@Composable
+private fun IconBox(icon: ImageVector) {
+  Box(
+    modifier =
+      Modifier
+        .size(42.dp)
+        .clip(RoundedCornerShape(8.dp))
+        .background(ClawTheme.colors.surfacePressed),
+    contentAlignment = Alignment.Center,
+  ) {
+    Icon(
+      imageVector = icon,
+      contentDescription = null,
+      tint = ClawTheme.colors.primary,
+      modifier = Modifier.size(22.dp),
+    )
+  }
+}
+
+@Composable
+private fun StatusPill(
+  label: String,
+  color: Color,
+) {
+  Surface(
+    shape = RoundedCornerShape(8.dp),
+    color = ClawTheme.colors.surfaceRaised,
+    border = BorderStroke(1.dp, ClawTheme.colors.border),
+  ) {
+    Row(
+      modifier = Modifier.padding(horizontal = 10.dp, vertical = 7.dp),
+      verticalAlignment = Alignment.CenterVertically,
+    ) {
+      Box(modifier = Modifier.size(7.dp).clip(CircleShape).background(color))
+      Spacer(modifier = Modifier.width(7.dp))
+      Text(
+        text = label,
+        style = ClawTheme.type.caption.copy(fontWeight = FontWeight.SemiBold),
+        color = color,
+      )
+    }
+  }
+}
+
+private fun sceneTitle(scene: AndroidScreenshotScene): String =
+  when (scene) {
+    AndroidScreenshotScene.Connect -> "Connect"
+    AndroidScreenshotScene.Chat -> "Chat"
+    AndroidScreenshotScene.Voice -> "Talk"
+    AndroidScreenshotScene.Screen -> "Device tools"
+    AndroidScreenshotScene.Settings -> "Settings"
+  }

apps/android/app/src/test/java/ai/openclaw/app/AndroidScreenshotModeTest.kt

@@ -0,0 +1,42 @@
+package ai.openclaw.app
+
+import android.content.Intent
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class AndroidScreenshotModeTest {
+  @Test
+  fun ignoresNormalLaunches() {
+    assertNull(parseAndroidScreenshotModeIntent(Intent(Intent.ACTION_MAIN)))
+  }
+
+  @Test
+  fun parsesRequestedScene() {
+    val parsed =
+      parseAndroidScreenshotModeIntent(
+        Intent(Intent.ACTION_MAIN)
+          .putExtra(extraAndroidScreenshotMode, true)
+          .putExtra(extraAndroidScreenshotScene, "voice"),
+      )
+
+    assertEquals(AndroidScreenshotScene.Voice, parsed)
+  }
+
+  @Test
+  fun defaultsUnknownScenesToConnect() {
+    val parsed =
+      parseAndroidScreenshotModeIntent(
+        Intent(Intent.ACTION_MAIN)
+          .putExtra(extraAndroidScreenshotMode, true)
+          .putExtra(extraAndroidScreenshotScene, "unknown"),
+      )
+
+    assertEquals(AndroidScreenshotScene.Connect, parsed)
+  }
+}

apps/android/fastlane/.env.example

@@ -0,0 +1,20 @@
+# Google Play API key (pick one approach)
+#
+# Recommended local path:
+# GOOGLE_PLAY_JSON_KEY=/absolute/path/to/google-play-service-account.json
+#
+# Or raw JSON content for CI:
+# GOOGLE_PLAY_JSON_KEY_DATA={"type":"service_account",...}
+
+# Optional app targeting
+# GOOGLE_PLAY_PACKAGE_NAME=ai.openclaw.app
+
+# Release target
+# GOOGLE_PLAY_TRACK=internal
+# GOOGLE_PLAY_RELEASE_STATUS=completed
+# GOOGLE_PLAY_VALIDATE_ONLY=1
+
+# Metadata toggles
+# SUPPLY_UPLOAD_METADATA=1
+# SUPPLY_UPLOAD_IMAGES=1
+# SUPPLY_UPLOAD_SCREENSHOTS=1

apps/android/fastlane/Appfile

@@ -0,0 +1,3 @@
+package_name(ENV["GOOGLE_PLAY_PACKAGE_NAME"] || "ai.openclaw.app")
+
+json_key_file(ENV["GOOGLE_PLAY_JSON_KEY"]) if ENV["GOOGLE_PLAY_JSON_KEY"]

apps/android/fastlane/Fastfile

@@ -0,0 +1,274 @@
+require "fileutils"
+require "json"
+require "open3"
+require "shellwords"
+require "supply/client"
+
+default_platform(:android)
+
+DEFAULT_PLAY_PACKAGE_NAME = "ai.openclaw.app"
+DEFAULT_PLAY_TRACK = "internal"
+DEFAULT_PLAY_RELEASE_STATUS = "completed"
+
+def load_env_file(path)
+  return unless File.exist?(path)
+
+  File.foreach(path) do |line|
+    stripped = line.strip
+    next if stripped.empty? || stripped.start_with?("#")
+
+    key, value = stripped.split("=", 2)
+    next if key.nil? || key.empty? || value.nil?
+
+    ENV[key] = value if ENV[key].nil? || ENV[key].strip.empty?
+  end
+end
+
+def env_present?(value)
+  !value.nil? && !value.strip.empty?
+end
+
+def android_root
+  File.expand_path("..", __dir__)
+end
+
+def repo_root
+  File.expand_path("../..", android_root)
+end
+
+def shell_join(args)
+  args.shelljoin
+end
+
+def play_package_name
+  raw = ENV["GOOGLE_PLAY_PACKAGE_NAME"].to_s.strip
+  raw.empty? ? DEFAULT_PLAY_PACKAGE_NAME : raw
+end
+
+def play_track
+  raw = ENV["GOOGLE_PLAY_TRACK"].to_s.strip
+  raw.empty? ? DEFAULT_PLAY_TRACK : raw
+end
+
+def play_release_status
+  raw = ENV["GOOGLE_PLAY_RELEASE_STATUS"].to_s.strip
+  raw.empty? ? DEFAULT_PLAY_RELEASE_STATUS : raw
+end
+
+def play_validate_only?
+  ENV["GOOGLE_PLAY_VALIDATE_ONLY"] == "1"
+end
+
+def play_metadata_upload_requested?
+  ENV["SUPPLY_UPLOAD_METADATA"] == "1"
+end
+
+def play_screenshot_upload_requested?
+  ENV["SUPPLY_UPLOAD_SCREENSHOTS"] == "1"
+end
+
+def play_image_upload_requested?
+  ENV["SUPPLY_UPLOAD_IMAGES"] == "1"
+end
+
+def play_auth_options
+  json_key = ENV["GOOGLE_PLAY_JSON_KEY"].to_s.strip
+  json_key = ENV["SUPPLY_JSON_KEY"].to_s.strip if json_key.empty?
+  json_key = ENV["GOOGLE_PLAY_JSON_KEY_PATH"].to_s.strip if json_key.empty?
+  return { json_key: json_key } unless json_key.empty?
+
+  json_key_data = ENV["GOOGLE_PLAY_JSON_KEY_DATA"].to_s.strip
+  json_key_data = ENV["SUPPLY_JSON_KEY_DATA"].to_s.strip if json_key_data.empty?
+  return { json_key_data: json_key_data } unless json_key_data.empty?
+
+  UI.user_error!("Missing Google Play API credentials. Set GOOGLE_PLAY_JSON_KEY or GOOGLE_PLAY_JSON_KEY_DATA.")
+end
+
+def validate_play_auth!
+  client = nil
+  begin
+    client = Supply::Client.make_from_config(params: play_auth_options)
+    client.begin_edit(package_name: play_package_name)
+  rescue => e
+    UI.user_error!("Google Play API credentials are invalid for #{play_package_name}: #{e.message}")
+  ensure
+    if client&.current_edit
+      begin
+        client.abort_current_edit
+      rescue => e
+        UI.user_error!("Google Play API credentials opened a validation edit but could not close it: #{e.message}")
+      end
+    end
+  end
+end
+
+def read_android_version_metadata
+  stdout, stderr, status = Open3.capture3(
+    "node",
+    "--import",
+    "tsx",
+    File.join(repo_root, "scripts", "android-version.ts"),
+    "--json",
+    "--root",
+    repo_root
+  )
+  unless status.success?
+    detail = stderr.to_s.strip
+    detail = stdout.to_s.strip if detail.empty?
+    UI.user_error!("Failed to read Android version metadata: #{detail}")
+  end
+
+  parsed = JSON.parse(stdout)
+  version = parsed.fetch("canonicalVersion").to_s
+  version_code = parsed.fetch("versionCode").to_i
+  UI.user_error!("Android version helper returned incomplete metadata.") if version.empty? || version_code <= 0
+
+  { version: version, version_code: version_code }
+rescue JSON::ParserError => e
+  UI.user_error!("Invalid JSON from Android version helper: #{e.message}")
+end
+
+def sync_android_versioning!
+  sh(shell_join(["node", "--import", "tsx", File.join(repo_root, "scripts", "android-sync-versioning.ts"), "--check", "--root", repo_root]))
+end
+
+def android_release_notes_path
+  File.join(__dir__, "metadata", "android", "en-US", "release_notes.txt")
+end
+
+def android_changelog_path(version_code)
+  File.join(__dir__, "metadata", "android", "en-US", "changelogs", "#{version_code}.txt")
+end
+
+def sync_android_changelog!(version_code)
+  release_notes_path = android_release_notes_path
+  UI.user_error!("Missing Android release notes at #{release_notes_path}.") unless File.exist?(release_notes_path)
+
+  changelog_path = android_changelog_path(version_code)
+  FileUtils.mkdir_p(File.dirname(changelog_path))
+  File.write(changelog_path, File.read(release_notes_path))
+  changelog_path
+end
+
+def play_metadata_path
+  File.join(__dir__, "metadata", "android")
+end
+
+def play_screenshot_paths
+  Dir[File.join(play_metadata_path, "**", "images", "**", "*.png")]
+end
+
+def validate_android_screenshots!
+  return unless play_screenshot_upload_requested?
+
+  if play_screenshot_paths.empty?
+    UI.user_error!("SUPPLY_UPLOAD_SCREENSHOTS=1 but no PNG screenshots were found under apps/android/fastlane/metadata/android/*/images.")
+  end
+end
+
+def release_artifact_path(version)
+  File.join(android_root, "build", "release-artifacts", "openclaw-#{version}-play-release.aab")
+end
+
+def build_release_artifacts!
+  sh(shell_join(["bun", File.join(android_root, "scripts", "build-release-artifacts.ts")]))
+end
+
+def capture_android_screenshots!
+  sh(shell_join(["bash", File.join(repo_root, "scripts", "android-screenshots.sh")]))
+end
+
+def upload_play_store_metadata!(version_metadata)
+  validate_android_screenshots!
+  sync_android_changelog!(version_metadata.fetch(:version_code))
+
+  upload_to_play_store(
+    **play_auth_options,
+    package_name: play_package_name,
+    track: play_track,
+    version_code: version_metadata.fetch(:version_code),
+    metadata_path: play_metadata_path,
+    skip_upload_apk: true,
+    skip_upload_aab: true,
+    skip_upload_metadata: !play_metadata_upload_requested?,
+    skip_upload_changelogs: false,
+    skip_upload_images: !play_image_upload_requested?,
+    skip_upload_screenshots: !play_screenshot_upload_requested?,
+    validate_only: play_validate_only?
+  )
+end
+
+def upload_play_store_build!(version_metadata, upload_metadata: false, upload_images: false, upload_screenshots: false)
+  ENV["SUPPLY_UPLOAD_SCREENSHOTS"] = "1" if upload_screenshots
+  validate_android_screenshots!
+  sync_android_changelog!(version_metadata.fetch(:version_code))
+  artifact_path = release_artifact_path(version_metadata.fetch(:version))
+  UI.user_error!("Missing Play release artifact at #{artifact_path}. Run pnpm android:release:archive first.") unless File.exist?(artifact_path)
+
+  upload_to_play_store(
+    **play_auth_options,
+    package_name: play_package_name,
+    aab: artifact_path,
+    track: play_track,
+    release_status: play_release_status,
+    metadata_path: play_metadata_path,
+    skip_upload_apk: true,
+    skip_upload_metadata: !upload_metadata,
+    skip_upload_changelogs: false,
+    skip_upload_images: !upload_images,
+    skip_upload_screenshots: !upload_screenshots,
+    validate_only: play_validate_only?
+  )
+end
+
+load_env_file(File.join(__dir__, ".env"))
+
+platform :android do
+  desc "Validate Google Play API credentials"
+  lane :auth_check do
+    validate_play_auth!
+    UI.success("Google Play API credentials are valid.")
+  end
+
+  desc "Upload Google Play metadata, changelog, and optional screenshots"
+  lane :metadata do
+    sync_android_versioning!
+    version_metadata = read_android_version_metadata
+    ENV["SUPPLY_UPLOAD_METADATA"] = "1" unless ENV.key?("SUPPLY_UPLOAD_METADATA")
+    upload_play_store_metadata!(version_metadata)
+    UI.success("Uploaded Android Play metadata for #{version_metadata[:version]} (#{version_metadata[:version_code]}).")
+  end
+
+  desc "Build signed Android release artifacts locally without uploading"
+  lane :play_store_archive do
+    sync_android_versioning!
+    build_release_artifacts!
+  end
+
+  desc "Generate deterministic Android screenshots for Google Play metadata"
+  lane :screenshots do
+    capture_android_screenshots!
+  end
+
+  desc "Upload the signed Play AAB to Google Play"
+  lane :play_store do
+    sync_android_versioning!
+    version_metadata = read_android_version_metadata
+    upload_play_store_build!(version_metadata)
+    UI.success("Uploaded Android Play build to #{play_track}: version=#{version_metadata[:version]} code=#{version_metadata[:version_code]}")
+  end
+
+  desc "Upload Android metadata, archive release artifacts, then upload the Play AAB"
+  lane :release_upload do
+    auth_check
+    sync_android_versioning!
+    version_metadata = read_android_version_metadata
+    screenshots
+    ENV["SUPPLY_UPLOAD_METADATA"] = "1"
+    ENV["SUPPLY_UPLOAD_SCREENSHOTS"] = "1"
+    build_release_artifacts!
+    upload_play_store_build!(version_metadata, upload_metadata: true, upload_screenshots: true)
+    UI.success("Uploaded Android Play build to #{play_track}: version=#{version_metadata[:version]} code=#{version_metadata[:version_code]}")
+    UI.important("Production promotion remains manual in Google Play Console.")
+  end
+end

apps/android/fastlane/SETUP.md

@@ -0,0 +1,74 @@
+# fastlane setup (OpenClaw Android)
+
+Install:
+
+```bash
+brew install fastlane
+```
+
+Create a Google Play service account JSON key with Google Play Developer API access, then grant that service account access to the OpenClaw app in Play Console.
+
+Recommended local auth:
+
+```bash
+GOOGLE_PLAY_JSON_KEY=/absolute/path/to/google-play-service-account.json
+```
+
+Optional app targeting:
+
+```bash
+GOOGLE_PLAY_PACKAGE_NAME=ai.openclaw.app
+```
+
+Validate auth:
+
+```bash
+cd apps/android
+fastlane android auth_check
+```
+
+Archive locally without upload:
+
+```bash
+pnpm android:release:archive
+```
+
+Generate deterministic Google Play screenshots:
+
+```bash
+pnpm android:screenshots
+```
+
+Upload metadata, release notes, and the Play AAB to the internal testing track:
+
+```bash
+pnpm android:release:upload
+```
+
+Direct Fastlane entry point:
+
+```bash
+cd apps/android
+fastlane android release_upload
+```
+
+Release rules:
+
+- `apps/android/version.json` is the pinned Android release version source.
+- `apps/android/Config/Version.properties` is generated from that source and read by Gradle.
+- Supported pinned Android versions use CalVer: `YYYY.M.D`.
+- `versionCode` uses `YYYYMMDDNN`, where `NN` is a two-digit build number for the pinned version.
+- `pnpm android:version:pin -- --from-gateway` promotes the current root gateway version into the pinned Android release version.
+- `pnpm android:version:pin -- --version 2026.6.5 --version-code 2026060502` increments another build on the same Android release train.
+- `pnpm android:version:sync` updates generated version artifacts.
+- `pnpm android:version:check` validates checked-in Android version artifacts.
+- `pnpm android:screenshots` builds and installs the Play debug app, launches deterministic screenshot scenes, and captures raw PNGs.
+- `pnpm android:release:archive` builds the signed Play AAB and third-party APK into `apps/android/build/release-artifacts/`.
+- `pnpm android:release:upload` uploads the Play AAB to the configured Google Play track. The default track is `internal`.
+- Production promotion remains manual in Google Play Console.
+
+Screenshots:
+
+- Android screenshot capture writes raw Play screenshots under `apps/android/fastlane/metadata/android/<locale>/images/phoneScreenshots/`.
+- Set `SUPPLY_UPLOAD_SCREENSHOTS=1` to include those screenshots in `fastlane android metadata`.
+- Do not commit generated screenshot captures unless they become intentional store metadata assets.

apps/android/fastlane/metadata/android/en-US/changelogs/2026060201.txt

@@ -0,0 +1,3 @@
+OpenClaw is now available on Android.
+
+Connect to your OpenClaw Gateway to chat with your assistant, use realtime Talk mode, review approvals, and bring Android device capabilities like camera, location, screen, and notifications into your private automation workflows.

apps/android/fastlane/metadata/android/en-US/full_description.txt

@@ -0,0 +1,18 @@
+OpenClaw is a personal AI assistant you run on your own devices.
+
+Pair this Android app with your OpenClaw Gateway to use your phone as a secure node for chat, voice, approvals, and device-aware automation.
+
+What you can do:
+- Pair with your private OpenClaw Gateway by QR code or setup code
+- Chat with your assistant from Android
+- Use realtime Talk mode and push-to-talk
+- Review Gateway action approvals from your phone
+- Enable device capabilities such as camera, screen, location, and notifications when you choose
+- Receive push wakes and node status updates for connected workflows
+
+OpenClaw is local-first: you control your gateway, keys, configuration, and permissions. Device access is managed by Android permissions and can be enabled only for the capabilities you want to use.
+
+Getting started:
+1) Set up your OpenClaw Gateway
+2) Open the Android app and pair with your gateway
+3) Start using chat, Talk mode, approvals, and automations from your phone

apps/android/fastlane/metadata/android/en-US/release_notes.txt

@@ -0,0 +1,3 @@
+OpenClaw is now available on Android.
+
+Connect to your OpenClaw Gateway to chat with your assistant, use realtime Talk mode, review approvals, and bring Android device capabilities like camera, location, screen, and notifications into your private automation workflows.

apps/android/fastlane/metadata/android/en-US/short_description.txt

@@ -0,0 +1 @@
+Personal AI on your Android devices

apps/android/scripts/build-release-aab.ts

@@ -1,163 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Android release helper that bumps version fields, builds release AAB variants,
- * verifies signatures, and prints SHA-256 checksums.
- */
-
-import { $ } from "bun";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const scriptDir = dirname(fileURLToPath(import.meta.url));
-const androidDir = join(scriptDir, "..");
-const buildGradlePath = join(androidDir, "app", "build.gradle.kts");
-const releaseOutputDir = join(androidDir, "build", "release-bundles");
-
-const releaseVariants = [
-  {
-    flavorName: "play",
-    gradleTask: ":app:bundlePlayRelease",
-    bundlePath: join(androidDir, "app", "build", "outputs", "bundle", "playRelease", "app-play-release.aab"),
-  },
-  {
-    flavorName: "third-party",
-    gradleTask: ":app:bundleThirdPartyRelease",
-    bundlePath: join(
-      androidDir,
-      "app",
-      "build",
-      "outputs",
-      "bundle",
-      "thirdPartyRelease",
-      "app-thirdParty-release.aab",
-    ),
-  },
-] as const;
-
-type VersionState = {
-  versionName: string;
-  versionCode: number;
-};
-
-type ParsedVersionMatches = {
-  versionNameMatch: RegExpMatchArray;
-  versionCodeMatch: RegExpMatchArray;
-};
-
-function formatVersionName(date: Date): string {
-  const year = date.getFullYear();
-  const month = date.getMonth() + 1;
-  const day = date.getDate();
-  return `${year}.${month}.${day}`;
-}
-
-function formatVersionCodePrefix(date: Date): string {
-  const year = date.getFullYear().toString();
-  const month = (date.getMonth() + 1).toString().padStart(2, "0");
-  const day = date.getDate().toString().padStart(2, "0");
-  return `${year}${month}${day}`;
-}
-
-function parseVersionMatches(buildGradleText: string): ParsedVersionMatches {
-  const versionCodeMatch = buildGradleText.match(/versionCode = (\d+)/);
-  const versionNameMatch = buildGradleText.match(/versionName = "([^"]+)"/);
-  if (!versionCodeMatch || !versionNameMatch) {
-    throw new Error(`Couldn't parse versionName/versionCode from ${buildGradlePath}`);
-  }
-  return { versionCodeMatch, versionNameMatch };
-}
-
-function resolveNextVersionCode(currentVersionCode: number, todayPrefix: string): number {
-  const currentRaw = currentVersionCode.toString();
-  let nextSuffix = 0;
-
-  if (currentRaw.startsWith(todayPrefix)) {
-    const suffixRaw = currentRaw.slice(todayPrefix.length);
-    nextSuffix = (suffixRaw ? Number.parseInt(suffixRaw, 10) : 0) + 1;
-  }
-
-  if (!Number.isInteger(nextSuffix) || nextSuffix < 0 || nextSuffix > 99) {
-    throw new Error(
-      `Can't auto-bump Android versionCode for ${todayPrefix}: next suffix ${nextSuffix} is invalid`,
-    );
-  }
-
-  return Number.parseInt(`${todayPrefix}${nextSuffix.toString().padStart(2, "0")}`, 10);
-}
-
-function resolveNextVersion(buildGradleText: string, date: Date): VersionState {
-  const { versionCodeMatch } = parseVersionMatches(buildGradleText);
-  const currentVersionCode = Number.parseInt(versionCodeMatch[1] ?? "", 10);
-  if (!Number.isInteger(currentVersionCode)) {
-    throw new Error(`Invalid Android versionCode in ${buildGradlePath}`);
-  }
-
-  const versionName = formatVersionName(date);
-  const versionCode = resolveNextVersionCode(currentVersionCode, formatVersionCodePrefix(date));
-  return { versionName, versionCode };
-}
-
-function updateBuildGradleVersions(buildGradleText: string, nextVersion: VersionState): string {
-  return buildGradleText
-    .replace(/versionCode = \d+/, `versionCode = ${nextVersion.versionCode}`)
-    .replace(/versionName = "[^"]+"/, `versionName = "${nextVersion.versionName}"`);
-}
-
-async function sha256Hex(path: string): Promise<string> {
-  const buffer = await Bun.file(path).arrayBuffer();
-  const digest = await crypto.subtle.digest("SHA-256", buffer);
-  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-
-async function verifyBundleSignature(path: string): Promise<void> {
-  await $`jarsigner -verify ${path}`.quiet();
-}
-
-async function copyBundle(sourcePath: string, destinationPath: string): Promise<void> {
-  const sourceFile = Bun.file(sourcePath);
-  if (!(await sourceFile.exists())) {
-    throw new Error(`Signed bundle missing at ${sourcePath}`);
-  }
-
-  await Bun.write(destinationPath, sourceFile);
-}
-
-async function main() {
-  const buildGradleFile = Bun.file(buildGradlePath);
-  const originalText = await buildGradleFile.text();
-  const nextVersion = resolveNextVersion(originalText, new Date());
-  const updatedText = updateBuildGradleVersions(originalText, nextVersion);
-
-  if (updatedText === originalText) {
-    throw new Error("Android version bump produced no change");
-  }
-
-  console.log(`Android versionName -> ${nextVersion.versionName}`);
-  console.log(`Android versionCode -> ${nextVersion.versionCode}`);
-
-  await Bun.write(buildGradlePath, updatedText);
-  await $`mkdir -p ${releaseOutputDir}`;
-
-  try {
-    await $`./gradlew ${releaseVariants[0].gradleTask} ${releaseVariants[1].gradleTask}`.cwd(androidDir);
-  } catch (error) {
-    await Bun.write(buildGradlePath, originalText);
-    throw error;
-  }
-
-  for (const variant of releaseVariants) {
-    const outputPath = join(
-      releaseOutputDir,
-      `openclaw-${nextVersion.versionName}-${variant.flavorName}-release.aab`,
-    );
-
-    await copyBundle(variant.bundlePath, outputPath);
-    await verifyBundleSignature(outputPath);
-    const hash = await sha256Hex(outputPath);
-
-    console.log(`Signed AAB (${variant.flavorName}): ${outputPath}`);
-    console.log(`SHA-256 (${variant.flavorName}): ${hash}`);
-  }
-}
-
-await main();

apps/android/scripts/build-release-artifacts.ts

@@ -0,0 +1,209 @@
+#!/usr/bin/env bun
+/**
+ * Android release helper that builds signed release artifacts from the pinned
+ * version metadata, verifies signatures, and writes SHA-256 checksum files.
+ */
+
+import { $ } from "bun";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAndroidVersion, syncAndroidVersioning } from "../../../scripts/lib/android-version.ts";
+
+type ReleaseArtifact = {
+  flavorName: "play" | "third-party";
+  kind: "aab" | "apk";
+  gradleTask: string;
+  sourcePath: string;
+};
+
+type CliOptions = {
+  dryRun: boolean;
+};
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const androidDir = join(scriptDir, "..");
+const rootDir = join(androidDir, "..", "..");
+const releaseOutputDir = join(androidDir, "build", "release-artifacts");
+
+function parseArgs(argv: string[]): CliOptions {
+  let dryRun = false;
+
+  for (const arg of argv) {
+    switch (arg) {
+      case "--dry-run": {
+        dryRun = true;
+        break;
+      }
+      case "-h":
+      case "--help": {
+        console.log(
+          [
+            "Usage: bun apps/android/scripts/build-release-artifacts.ts [--dry-run]",
+            "",
+            "Builds the signed Play AAB and third-party APK from apps/android/version.json.",
+          ].join("\n"),
+        );
+        process.exit(0);
+      }
+      default: {
+        throw new Error(`Unknown argument: ${arg}`);
+      }
+    }
+  }
+
+  return { dryRun };
+}
+
+function releaseArtifacts(versionName: string): ReleaseArtifact[] {
+  return [
+    {
+      flavorName: "play",
+      kind: "aab",
+      gradleTask: ":app:bundlePlayRelease",
+      sourcePath: join(
+        androidDir,
+        "app",
+        "build",
+        "outputs",
+        "bundle",
+        "playRelease",
+        "app-play-release.aab",
+      ),
+    },
+    {
+      flavorName: "third-party",
+      kind: "apk",
+      gradleTask: ":app:assembleThirdPartyRelease",
+      sourcePath: join(
+        androidDir,
+        "app",
+        "build",
+        "outputs",
+        "apk",
+        "thirdParty",
+        "release",
+        `openclaw-${versionName}-thirdParty-release.apk`,
+      ),
+    },
+  ];
+}
+
+async function sha256Hex(path: string): Promise<string> {
+  const buffer = await Bun.file(path).arrayBuffer();
+  const digest = await crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function writeSha256File(path: string): Promise<string> {
+  const hash = await sha256Hex(path);
+  const checksumPath = `${path}.sha256`;
+  await Bun.write(checksumPath, `${hash}  ${basename(path)}\n`);
+  return hash;
+}
+
+async function verifyAabSignature(path: string): Promise<void> {
+  await $`jarsigner -verify ${path}`.quiet();
+}
+
+function resolveApkSignerFromSdk(sdkRoot: string | undefined): string | null {
+  if (!sdkRoot) {
+    return null;
+  }
+
+  const buildToolsDir = join(sdkRoot, "build-tools");
+  if (!existsSync(buildToolsDir)) {
+    return null;
+  }
+
+  const candidates = readdirSync(buildToolsDir)
+    .toSorted((left, right) => right.localeCompare(left))
+    .map((version) => join(buildToolsDir, version, "apksigner"))
+    .filter((candidate) => existsSync(candidate));
+
+  return candidates[0] ?? null;
+}
+
+async function resolveApkSigner(): Promise<string> {
+  const sdkApkSigner =
+    resolveApkSignerFromSdk(Bun.env.ANDROID_HOME) ??
+    resolveApkSignerFromSdk(Bun.env.ANDROID_SDK_ROOT);
+  if (sdkApkSigner) {
+    return sdkApkSigner;
+  }
+
+  try {
+    return (await $`command -v apksigner`.text()).trim();
+  } catch {
+    throw new Error(
+      "Missing apksigner. Install Android SDK build-tools or put apksigner on PATH.",
+    );
+  }
+}
+
+async function verifyApkSignature(path: string): Promise<void> {
+  const apkSigner = await resolveApkSigner();
+  const apkSignerProcess = Bun.spawn([apkSigner, "verify", path], {
+    stdout: "ignore",
+    stderr: "inherit",
+  });
+  const exitCode = await apkSignerProcess.exited;
+  if (exitCode !== 0) {
+    throw new Error(`apksigner verification failed for ${path}`);
+  }
+}
+
+async function copyArtifact(sourcePath: string, destinationPath: string): Promise<void> {
+  const sourceFile = Bun.file(sourcePath);
+  if (!(await sourceFile.exists())) {
+    throw new Error(`Signed release artifact missing at ${sourcePath}`);
+  }
+
+  await Bun.write(destinationPath, sourceFile);
+}
+
+async function verifyArtifactSignature(artifact: ReleaseArtifact, outputPath: string): Promise<void> {
+  if (artifact.kind === "aab") {
+    await verifyAabSignature(outputPath);
+  } else {
+    await verifyApkSignature(outputPath);
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  syncAndroidVersioning({ mode: "check", rootDir });
+  const version = resolveAndroidVersion(rootDir);
+  const artifacts = releaseArtifacts(version.canonicalVersion);
+
+  console.log(`Android versionName: ${version.canonicalVersion}`);
+  console.log(`Android versionCode: ${version.versionCode}`);
+  for (const artifact of artifacts) {
+    console.log(`Release artifact: ${artifact.flavorName} ${artifact.kind}`);
+    console.log(`Gradle task: ${artifact.gradleTask}`);
+  }
+
+  if (options.dryRun) {
+    console.log("Dry run complete. No Gradle tasks were executed.");
+    return;
+  }
+
+  await $`mkdir -p ${releaseOutputDir}`;
+  await $`./gradlew ${artifacts.map((artifact) => artifact.gradleTask)}`.cwd(androidDir);
+
+  for (const artifact of artifacts) {
+    const outputPath = join(
+      releaseOutputDir,
+      `openclaw-${version.canonicalVersion}-${artifact.flavorName}-release.${artifact.kind}`,
+    );
+
+    await copyArtifact(artifact.sourcePath, outputPath);
+    await verifyArtifactSignature(artifact, outputPath);
+    const hash = await writeSha256File(outputPath);
+
+    console.log(`Signed ${artifact.kind.toUpperCase()} (${artifact.flavorName}): ${outputPath}`);
+    console.log(`SHA-256 (${artifact.flavorName}): ${hash}`);
+  }
+}
+
+await main();

apps/android/version.json

@@ -0,0 +1,4 @@
+{
+  "version": "2026.6.2",
+  "versionCode": 2026060201
+}

apps/ios/Config/AppStoreSigning.json

@@ -1,8 +1,8 @@
 {
   "teamId": "FWJYW4S8P8",
-  "signingRepo": "git@github.com:openclaw/ios-signing.git",
-  "certificateType": "IOS_DISTRIBUTION",
-  "profileType": "IOS_APP_STORE",
+  "signingRepo": "git@github.com:openclaw/apps-signing.git",
+  "signingBranch": "main",
+  "profileType": "appstore",
   "targets": [
     {
       "target": "OpenClaw",

apps/ios/README.md

@@ -56,17 +56,17 @@ Prereqs:
 - `xcodegen`
 - `fastlane`
 - Apple account signed into Xcode for the canonical OpenClaw team (`FWJYW4S8P8`)
-- `asc` CLI authenticated for the canonical OpenClaw team
-- Release-owner access to the encrypted signing repo password (`ASC_MATCH_PASSWORD`)
+- Fastlane Apple Developer Portal session for the canonical OpenClaw team when creating bundle IDs or enabling services
+- Release-owner access to the encrypted signing repo password (`MATCH_PASSWORD`)
 - App Store Connect app already created for `ai.openclawfoundation.app`
-- App Store Connect API key set up in Keychain via `scripts/ios-asc-keychain-setup.sh` when auto-resolving a build number or uploading to App Store Connect
+- App Store Connect API key set up in Keychain via `scripts/ios-app-store-connect-keychain-setup.sh` when auto-resolving a build number or uploading to App Store Connect
 
 Release behavior:
 
 - Local development uses the canonical `ai.openclawfoundation.app*` bundle IDs when the OpenClaw team is available, and unique `ai.openclawfoundation.app.test.*` bundle IDs only for non-canonical fallback teams.
 - App Store release uses canonical `ai.openclawfoundation.app*` bundle IDs through a temporary generated xcconfig in `apps/ios/build/AppStoreRelease.xcconfig`.
 - App Store release uses manual `Apple Distribution` signing with profile names pinned in `apps/ios/Config/AppStoreSigning.json`.
-- `asc` owns one-time Developer Portal setup and encrypted signing sync. Fastlane owns release handling after those assets exist.
+- Fastlane owns one-time Developer Portal setup, encrypted `match` signing sync to the repo/branch pinned in `apps/ios/Config/AppStoreSigning.json`, and release handling.
 - App Store release also switches the app to `OpenClawPushTransport=relay`, `OpenClawPushDistribution=official`, `OpenClawPushAPNsEnvironment=production`, and a production `aps-environment` entitlement.
 - `pnpm ios:release:upload` generates App Store screenshots and uploads release notes before archiving and uploading the IPA.
 - `pnpm ios:release` remains a compatibility alias for `pnpm ios:release:upload`; prefer the explicit upload command in new release docs and automation.
@@ -93,16 +93,16 @@ Signing setup commands:
 pnpm ios:release:signing:plan
 pnpm ios:release:signing:check
 pnpm ios:release:signing:setup
-ASC_MATCH_PASSWORD=... pnpm ios:release:signing:sync:push
-ASC_MATCH_PASSWORD=... pnpm ios:release:signing:sync:pull
+MATCH_PASSWORD=... pnpm ios:release:signing:sync:push
+MATCH_PASSWORD=... pnpm ios:release:signing:sync:pull
 ```
 
 Release-owner secrets:
 
 - App Store Connect API auth uses Keychain for private key material plus non-secret `apps/ios/fastlane/.env` variables.
-- The encrypted signing repo password lives outside this repo in the release-owner vault and is exposed locally as `ASC_MATCH_PASSWORD`.
+- The encrypted signing repo password lives outside this repo in the release-owner vault and is exposed locally as `MATCH_PASSWORD`.
 - Apple Distribution private keys, certificates, provisioning profiles, and decrypted signing sync output stay under `apps/ios/build/` or Keychain and are gitignored.
-- Rotating release signing means revoking/replacing the Developer Portal certificate or profile with `asc`, then pushing a fresh encrypted sync state.
+- Rotating release signing means refreshing Fastlane `match` assets and pushing a fresh encrypted sync state.
 
 Prepare the generated release xcconfig/project without archiving:
 
@@ -142,13 +142,13 @@ fastlane ios auth_check
 2. If auth is missing, bootstrap it once on this Mac:
 
 ```bash
-scripts/ios-asc-keychain-setup.sh \
+scripts/ios-app-store-connect-keychain-setup.sh \
   --key-path /absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
   --issuer-id YOUR_ISSUER_ID \
   --write-env
 ```
 
-This should create `apps/ios/fastlane/.env` with the non-secret ASC variables while the private key stays in Keychain.
+This should create `apps/ios/fastlane/.env` with non-secret App Store Connect variables while the private key stays in Keychain.
 
 3. Confirm the App Store Connect app and Apple Developer identifiers/capabilities exist for:
    - `ai.openclawfoundation.app`
@@ -157,7 +157,7 @@ This should create `apps/ios/fastlane/.env` with the non-secret ASC variables wh
    - `ai.openclawfoundation.app.watchkitapp`
    - `ai.openclawfoundation.app.watchkitapp.extension`
 
-   Use `pnpm ios:release:signing:setup` for the initial portal setup, then `ASC_MATCH_PASSWORD=... pnpm ios:release:signing:sync:push` to publish encrypted signing assets to the shared private repo.
+   Use `pnpm ios:release:signing:setup` for the initial portal setup, then `MATCH_PASSWORD=... pnpm ios:release:signing:sync:push` to publish encrypted Fastlane match assets to the shared private repo.
 
 4. Optional: set a custom official relay URL for the build. If unset, the release flow uses `https://ios-push-relay.openclaw.ai`.
 

apps/ios/Sources/Model/NodeAppModel.swift

@@ -18,6 +18,11 @@ private struct GatewayRelayIdentityResponse: Decodable {
     let publicKey: String
 }
 
+private struct WatchChatPreview {
+    var items: [OpenClawWatchChatItem]
+    var statusText: String?
+}
+
 /// Ensures notification requests return promptly even if the system prompt blocks.
 private final class NotificationInvokeLatch<T: Sendable>: @unchecked Sendable {
     private let lock = NSLock()
@@ -54,6 +59,8 @@ private enum IOSDeepLinkAgentPolicy {
 @Observable
 // swiftlint:disable type_body_length file_length
 final class NodeAppModel {
+    private nonisolated static let watchChatPreviewItemLimit = 5
+
     struct AgentDeepLinkPrompt: Identifiable, Equatable {
         let id: String
         let messagePreview: String
@@ -191,6 +198,8 @@ final class NodeAppModel {
     @ObservationIgnored private var foregroundGatewayResumeCheckInFlight = false
     private var lastSignificantLocationWakeAt: Date?
     @ObservationIgnored private let watchReplyCoordinator = WatchReplyCoordinator()
+    @ObservationIgnored private let watchChatCoordinator = WatchChatCoordinator()
+    @ObservationIgnored private let appleReviewDemoChatTransport = AppleReviewDemoChatTransport()
     private var watchExecApprovalPromptsByID: [String: ExecApprovalPrompt] = [:]
     private var pendingWatchExecApprovalRecoveryIDs: [String] = []
     private var pendingForegroundActionDrainInFlight = false
@@ -243,6 +252,7 @@ final class NodeAppModel {
     private static let backgroundAliveLastSuccessAtMsKey = "gateway.backgroundAlive.lastSuccessAtMs"
     private static let backgroundAliveLastTriggerKey = "gateway.backgroundAlive.lastTrigger"
     private static let foregroundResumeHealthTimeoutSeconds = 1
+    private static let watchChatCompletionWaitMs = 45000
 
     var cameraHUDText: String?
     var cameraHUDKind: CameraHUDKind?
@@ -314,6 +324,19 @@ final class NodeAppModel {
                 await self.refreshWatchExecApprovalSnapshotOnDemand(reason: "watch_request")
             }
         }
+        self.watchMessagingService.setAppSnapshotRequestHandler { [weak self] event in
+            Task { @MainActor in
+                guard let self else { return }
+                GatewayDiagnostics.log(
+                    "node app model: watch app snapshot request id=\(event.requestId)")
+                await self.syncWatchAppSnapshot(reason: "watch_app_request", includeChat: true)
+            }
+        }
+        self.watchMessagingService.setAppCommandHandler { [weak self] event in
+            Task { @MainActor in
+                await self?.handleWatchAppCommand(event)
+            }
+        }
 
         self.voiceWake.configure { [weak self] cmd in
             guard let self else { return }
@@ -1910,6 +1933,14 @@ extension NodeAppModel {
         self.agentDisplayName(for: self.chatAgentId, fallback: "Main")
     }
 
+    var chatAgentAvatarURL: String? {
+        self.agentIdentityValue(for: self.chatAgentId, key: "avatarUrl")
+    }
+
+    var chatAgentAvatarText: String? {
+        self.agentIdentityValue(for: self.chatAgentId, key: "emoji")
+    }
+
     var activeAgentName: String {
         self.agentDisplayName(for: self.selectedOrDefaultAgentId, fallback: "Main")
     }
@@ -1930,6 +1961,18 @@ extension NodeAppModel {
         return resolvedId
     }
 
+    private func agentIdentityValue(for agentId: String, key: String) -> String? {
+        let resolvedId = agentId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !resolvedId.isEmpty,
+              let match = self.gatewayAgents.first(where: { $0.id == resolvedId }),
+              let rawValue = match.identity?[key]?.value as? String
+        else {
+            return nil
+        }
+        let trimmed = rawValue.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
     func connectToGateway(
         url: URL,
         gatewayStableID: String,
@@ -2802,9 +2845,22 @@ extension NodeAppModel {
     }
 
     private func setOperatorConnected(_ connected: Bool) {
+        let changed = self.operatorConnected != connected
         self.operatorConnected = connected
         self.operatorStatusText = connected ? "Connected" : "Offline"
         self.refreshOperatorAdminScopeFromStore()
+        guard connected else {
+            guard changed else { return }
+            Task { [weak self] in
+                await self?.syncWatchAppSnapshot(reason: "operator_offline")
+            }
+            return
+        }
+        Task { [weak self] in
+            await self?.flushQueuedWatchChatsIfAvailable()
+            guard changed else { return }
+            await self?.syncWatchAppSnapshot(reason: "operator_online")
+        }
     }
 
     private func refreshOperatorAdminScopeFromStore() {
@@ -3011,6 +3067,7 @@ extension NodeAppModel {
     func onNodeGatewayConnected() async {
         await self.registerAPNsTokenIfNeeded()
         await self.flushQueuedWatchRepliesIfConnected()
+        await self.syncWatchAppSnapshot(reason: "node_connected", includeChat: true)
         await self.syncWatchExecApprovalSnapshot(reason: "node_connected")
         await self.resumePendingForegroundNodeActionsIfNeeded(trigger: "node_connected")
     }
@@ -3215,10 +3272,11 @@ extension NodeAppModel {
             "watch exec approval: status changed "
                 + "reachable=\(status.reachable) activation=\(status.activationState) "
                 + "backgrounded=\(self.isBackgrounded)")
-        guard self.isBackgrounded else { return }
         guard status.supported, status.paired, status.appInstalled else { return }
         guard status.reachable || status.activationState == "activated" else { return }
         let reason = status.reachable ? "watch_reachable" : "watch_activated"
+        await self.syncWatchAppSnapshot(reason: reason, includeChat: status.reachable)
+        guard self.isBackgrounded else { return }
         await self.syncWatchExecApprovalSnapshot(reason: reason)
     }
 
@@ -3303,6 +3361,7 @@ extension NodeAppModel {
             self.watchExecApprovalLogger.error(
                 "watch approval prompt error=\(error.localizedDescription, privacy: .public)")
         }
+        await self.syncWatchAppSnapshot(reason: "\(reason)_app")
         await self.syncWatchExecApprovalSnapshot(reason: "\(reason)_snapshot")
     }
 
@@ -3328,6 +3387,7 @@ extension NodeAppModel {
             self.watchExecApprovalLogger.error(
                 "watch approval resolve error=\(error.localizedDescription, privacy: .public)")
         }
+        await self.syncWatchAppSnapshot(reason: "resolved_app")
         await self.syncWatchExecApprovalSnapshot(reason: "resolved_snapshot")
     }
 
@@ -3351,6 +3411,7 @@ extension NodeAppModel {
             self.watchExecApprovalLogger.error(
                 "watch approval expiry error=\(error.localizedDescription, privacy: .public)")
         }
+        await self.syncWatchAppSnapshot(reason: "expired_\(reason.rawValue)_app")
         await self.syncWatchExecApprovalSnapshot(reason: "expired_\(reason.rawValue)")
     }
 
@@ -3393,10 +3454,311 @@ extension NodeAppModel {
         }
     }
 
+    private func makeWatchChatPreview() async -> WatchChatPreview {
+        do {
+            let payload: OpenClawChatHistoryPayload
+            if self.isAppleReviewDemoModeEnabled {
+                payload = try await self.appleReviewDemoChatTransport.requestHistory(sessionKey: self.chatSessionKey)
+            } else {
+                guard self.isOperatorGatewayConnected else {
+                    return WatchChatPreview(
+                        items: [],
+                        statusText: "Connect iPhone chat to read messages")
+                }
+                payload = try await IOSGatewayChatTransport(gateway: self.operatorSession)
+                    .requestHistory(sessionKey: self.chatSessionKey)
+            }
+
+            let items = Self.makeWatchChatItems(from: payload.messages ?? [])
+            return WatchChatPreview(
+                items: items,
+                statusText: items.isEmpty ? "No chat messages yet" : nil)
+        } catch {
+            GatewayDiagnostics.log("watch app snapshot: chat preview failed error=\(error.localizedDescription)")
+            return WatchChatPreview(items: [], statusText: "Chat unavailable")
+        }
+    }
+
+    private nonisolated static func decodeWatchChatMessage(
+        _ raw: OpenClawKit.AnyCodable) -> OpenClawChatMessage?
+    {
+        guard let data = try? JSONEncoder().encode(raw) else { return nil }
+        return try? JSONDecoder().decode(OpenClawChatMessage.self, from: data)
+    }
+
+    private nonisolated static func makeWatchChatItems(
+        from raw: [OpenClawKit.AnyCodable]) -> [OpenClawWatchChatItem]
+    {
+        var readableMessages: [(OpenClawChatMessage, String)] = []
+        for item in raw.reversed() {
+            guard let message = self.decodeWatchChatMessage(item) else { continue }
+            let text = self.watchChatText(from: message)
+            guard !text.isEmpty else { continue }
+            readableMessages.append((message, text))
+            if readableMessages.count == self.watchChatPreviewItemLimit {
+                break
+            }
+        }
+        return Array(readableMessages.reversed()).enumerated().map { index, entry in
+            let timestampMs = self.watchTimestampMs(entry.0.timestamp)
+            let stableTime = timestampMs.map(String.init) ?? entry.0.id.uuidString
+            return OpenClawWatchChatItem(
+                id: "\(entry.0.role)-\(stableTime)-\(index)",
+                role: entry.0.role,
+                text: self.truncatedWatchChatText(entry.1),
+                timestampMs: timestampMs)
+        }
+    }
+
+    private nonisolated static func watchChatText(from message: OpenClawChatMessage) -> String {
+        let parts = message.content.compactMap { content -> String? in
+            let kind = (content.type ?? "text").lowercased()
+            guard kind.isEmpty || kind == "text" else { return nil }
+            if let text = self.nonEmptyWatchChatText(content.text) {
+                return text
+            }
+            if let text = self.nonEmptyWatchChatText(content.content?.value as? String) {
+                return text
+            }
+            if let dict = content.content?.value as? [String: OpenClawKit.AnyCodable],
+               let text = self.nonEmptyWatchChatText(dict["text"]?.value as? String)
+            {
+                return text
+            }
+            return nil
+        }
+        let contentText = parts.joined(separator: "\n").trimmingCharacters(in: .whitespacesAndNewlines)
+        if !contentText.isEmpty {
+            return contentText
+        }
+        return message.errorMessage?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    }
+
+    private nonisolated static func nonEmptyWatchChatText(_ text: String?) -> String? {
+        let trimmed = text?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private nonisolated static func truncatedWatchChatText(_ text: String) -> String {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard trimmed.count > 240 else { return trimmed }
+        return "\(trimmed.prefix(237))..."
+    }
+
+    private nonisolated static func watchTimestampMs(_ timestamp: Double?) -> Int? {
+        guard let timestamp, timestamp.isFinite, timestamp >= 0 else { return nil }
+        let milliseconds = timestamp > 100_000_000_000 ? timestamp : timestamp * 1000
+        let maxReasonableEpochMs: Double = 32_503_680_000_000
+        guard milliseconds.isFinite,
+              milliseconds >= 0,
+              milliseconds <= maxReasonableEpochMs
+        else {
+            return nil
+        }
+        return Int(milliseconds)
+    }
+
+    private func makeWatchAppSnapshot(
+        chatPreview: WatchChatPreview? = nil) -> OpenClawWatchAppSnapshotMessage
+    {
+        self.pruneExpiredWatchExecApprovalPrompts()
+        let watchGatewayConnected = self.isAppleReviewDemoModeEnabled
+            || (self.gatewayConnected && self.operatorConnected)
+        let displayStatusText = self.gatewayDisplayStatusText
+        let watchGatewayStatusText = watchGatewayConnected || displayStatusText != "Connected"
+            ? displayStatusText
+            : self.operatorStatusText
+        return OpenClawWatchAppSnapshotMessage(
+            gatewayStatusText: watchGatewayStatusText,
+            gatewayConnected: watchGatewayConnected,
+            agentName: self.chatAgentName,
+            agentAvatarURL: self.chatAgentAvatarURL,
+            agentAvatarText: self.chatAgentAvatarText,
+            sessionKey: self.chatSessionKey,
+            gatewayStableID: self.currentWatchChatGatewayStableID(),
+            talkStatusText: self.talkMode.statusText,
+            talkEnabled: self.talkMode.isEnabled,
+            talkListening: self.talkMode.isListening,
+            talkSpeaking: self.talkMode.isSpeaking,
+            pendingApprovalCount: self.watchExecApprovalPromptsByID.count,
+            chatItems: chatPreview?.items,
+            chatStatusText: chatPreview?.statusText,
+            sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
+            snapshotId: UUID().uuidString)
+    }
+
+    private func handleWatchAppCommand(_ event: WatchAppCommandEvent) async {
+        GatewayDiagnostics.log(
+            "watch app command: handle id=\(event.commandId) command=\(event.command.rawValue)")
+        switch event.command {
+        case .refresh:
+            break
+        case .openChat:
+            self.openChat(sessionKey: event.sessionKey ?? self.chatSessionKey)
+        case .sendChat:
+            await self.handleWatchChatCommand(event)
+            return
+        case .startTalk:
+            guard !self.isAppleReviewDemoModeEnabled else { break }
+            self.talkMode.updateMainSessionKey(event.sessionKey ?? self.chatSessionKey)
+            self.setTalkEnabled(true)
+        case .stopTalk:
+            self.setTalkEnabled(false)
+        }
+        await self.syncWatchAppSnapshot(
+            reason: "watch_command_\(event.command.rawValue)",
+            includeChat: true)
+    }
+
+    private func handleWatchChatCommand(_ event: WatchAppCommandEvent) async {
+        guard self.watchChatCommandTargetsCurrentGateway(event) else {
+            GatewayDiagnostics.log("watch chat send skipped: stale gateway target")
+            await self.syncWatchAppSnapshot(reason: "watch_chat_stale_gateway", includeChat: true)
+            return
+        }
+        let eventGatewayID = self.normalizedWatchChatGatewayStableID(event)
+        switch self.watchChatCoordinator.ingest(
+            event,
+            isChatAvailable: self.isWatchChatAvailableForSend(),
+            gatewayStableID: eventGatewayID)
+        {
+        case .dropMissingFields:
+            GatewayDiagnostics.log("watch chat send skipped: missing commandId/text")
+        case .dropMissingTarget:
+            GatewayDiagnostics.log("watch chat send skipped: missing gateway target")
+        case let .deduped(commandId):
+            GatewayDiagnostics.log("watch chat send deduped commandId=\(commandId)")
+        case let .queue(commandId):
+            GatewayDiagnostics.log("watch chat send queued commandId=\(commandId)")
+            await self.syncWatchAppSnapshot(reason: "watch_chat_queued", includeChat: true)
+        case .forward:
+            _ = await self.forwardWatchChatMessage(event, requeueOnFailure: true)
+        }
+    }
+
+    private func flushQueuedWatchChatsIfAvailable() async {
+        let gatewayStableID = self.currentWatchChatGatewayStableID()
+        while let event = self.watchChatCoordinator.nextQueuedCommand(
+            isChatAvailable: self.isWatchChatAvailableForSend(),
+            gatewayStableID: gatewayStableID)
+        {
+            guard self.watchChatCommandTargetsCurrentGateway(event) else {
+                GatewayDiagnostics.log("watch chat send skipped: stale queued gateway target")
+                self.watchChatCoordinator.removeQueuedCommand(
+                    commandId: event.commandId,
+                    gatewayStableID: gatewayStableID)
+                continue
+            }
+            let sent = await self.forwardWatchChatMessage(event, requeueOnFailure: false)
+            guard sent else { return }
+            self.watchChatCoordinator.removeQueuedCommand(
+                commandId: event.commandId,
+                gatewayStableID: gatewayStableID)
+        }
+    }
+
+    private func isWatchChatAvailableForSend() -> Bool {
+        self.isAppleReviewDemoModeEnabled || self.isOperatorGatewayConnected
+    }
+
+    private func currentWatchChatGatewayStableID() -> String? {
+        self.connectedGatewayID?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private func normalizedWatchChatGatewayStableID(_ event: WatchAppCommandEvent) -> String? {
+        let gatewayStableID = event.gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return gatewayStableID.isEmpty ? nil : gatewayStableID
+    }
+
+    private func watchChatCommandTargetsCurrentGateway(_ event: WatchAppCommandEvent) -> Bool {
+        let eventGatewayID = self.normalizedWatchChatGatewayStableID(event) ?? ""
+        let currentGatewayID = self.currentWatchChatGatewayStableID() ?? ""
+        guard !eventGatewayID.isEmpty, !currentGatewayID.isEmpty else { return false }
+        return eventGatewayID == currentGatewayID
+    }
+
+    private func forwardWatchChatMessage(
+        _ event: WatchAppCommandEvent,
+        requeueOnFailure: Bool) async -> Bool
+    {
+        let text = event.text?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !text.isEmpty else {
+            GatewayDiagnostics.log("watch chat send skipped: empty text")
+            return true
+        }
+
+        let sessionKey = (event.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
+            ? event.sessionKey!
+            : self.chatSessionKey
+        self.focusChatSession(sessionKey)
+
+        do {
+            if self.isAppleReviewDemoModeEnabled {
+                _ = try await self.appleReviewDemoChatTransport.sendMessage(
+                    sessionKey: sessionKey,
+                    message: text,
+                    thinking: "auto",
+                    idempotencyKey: event.commandId,
+                    attachments: [])
+                await self.syncWatchAppSnapshot(reason: "watch_chat_sent", includeChat: true)
+                return true
+            }
+
+            guard self.isOperatorGatewayConnected else {
+                GatewayDiagnostics.log("watch chat send skipped: operator gateway disconnected")
+                if requeueOnFailure {
+                    self.watchChatCoordinator.requeueFront(
+                        event,
+                        gatewayStableID: self.normalizedWatchChatGatewayStableID(event))
+                }
+                return false
+            }
+
+            let transport = IOSGatewayChatTransport(gateway: self.operatorSession)
+            let response = try await transport.sendMessage(
+                sessionKey: sessionKey,
+                message: text,
+                thinking: "auto",
+                idempotencyKey: event.commandId,
+                attachments: [])
+            await self.syncWatchAppSnapshot(reason: "watch_chat_sent", includeChat: true)
+            let completed = await transport.waitForRunCompletion(
+                runId: response.runId,
+                timeoutMs: Self.watchChatCompletionWaitMs)
+            guard completed else { return true }
+            await self.syncWatchAppSnapshot(reason: "watch_chat_completed", includeChat: true)
+            return true
+        } catch {
+            GatewayDiagnostics.log("watch chat send failed error=\(error.localizedDescription)")
+            if requeueOnFailure {
+                self.watchChatCoordinator.requeueFront(
+                    event,
+                    gatewayStableID: self.normalizedWatchChatGatewayStableID(event))
+            }
+            return false
+        }
+    }
+
+    private func syncWatchAppSnapshot(reason: String, includeChat: Bool = false) async {
+        let chatPreview = includeChat ? await self.makeWatchChatPreview() : nil
+        let message = self.makeWatchAppSnapshot(chatPreview: chatPreview)
+        do {
+            _ = try await self.watchMessagingService.syncAppSnapshot(message)
+            GatewayDiagnostics.log(
+                "watch app snapshot: sent reason=\(reason) "
+                    + "connected=\(message.gatewayConnected) approvals=\(message.pendingApprovalCount) "
+                    + "chatItems=\(message.chatItems?.count ?? -1)")
+        } catch {
+            GatewayDiagnostics.log(
+                "watch app snapshot: failed reason=\(reason) error=\(error.localizedDescription)")
+        }
+    }
+
     private func refreshWatchExecApprovalSnapshotOnDemand(reason: String) async {
         GatewayDiagnostics.log("watch exec approval: refresh on demand start reason=\(reason)")
         await self.hydrateWatchExecApprovalCacheIfNeeded(reason: reason)
         await self.syncWatchExecApprovalSnapshot(reason: reason)
+        await self.syncWatchAppSnapshot(reason: "\(reason)_app", includeChat: true)
         GatewayDiagnostics.log("watch exec approval: refresh on demand end reason=\(reason)")
     }
 
@@ -4660,10 +5022,34 @@ extension NodeAppModel {
         self.watchReplyCoordinator.queuedCount
     }
 
+    func _test_queuedWatchChatCommandCount() -> Int {
+        self.watchChatCoordinator.queuedCount
+    }
+
+    func _test_queuedWatchChatCommandIds() -> [String] {
+        self.watchChatCoordinator.queuedCommandIds
+    }
+
+    func _test_setConnectedGatewayID(_ gatewayID: String?) {
+        self.connectedGatewayID = gatewayID
+    }
+
+    static func _test_resetPersistedWatchChatQueueState() {
+        WatchChatCoordinator.resetPersistedQueue()
+    }
+
     func _test_setGatewayConnected(_ connected: Bool) {
         self.gatewayConnected = connected
     }
 
+    func _test_setOperatorConnected(_ connected: Bool) {
+        self.setOperatorConnected(connected)
+    }
+
+    nonisolated static func _test_makeWatchChatItems(from raw: [OpenClawKit.AnyCodable]) -> [OpenClawWatchChatItem] {
+        self.makeWatchChatItems(from: raw)
+    }
+
     func _test_isGatewayConnected() -> Bool {
         self.gatewayConnected
     }

apps/ios/Sources/Model/WatchReplyCoordinator.swift

@@ -44,3 +44,160 @@ final class WatchReplyCoordinator {
         self.queuedReplies.count
     }
 }
+
+@MainActor
+final class WatchChatCoordinator {
+    enum Decision {
+        case dropMissingFields
+        case dropMissingTarget
+        case deduped(commandId: String)
+        case queue(commandId: String)
+        case forward
+    }
+
+    private static let persistedQueueKey = "watch.chat.command.queue.v1"
+    private static let maxRecentCommandIds = 128
+
+    private struct QueuedCommand: Codable, Equatable {
+        var gatewayStableID: String
+        var event: WatchAppCommandEvent
+    }
+
+    private let defaults: UserDefaults
+    private var queuedCommands: [QueuedCommand] = []
+    private var recentCommandIds: [String] = []
+    private var seenCommandIds = Set<String>()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+        self.restoreQueue()
+    }
+
+    func ingest(
+        _ event: WatchAppCommandEvent,
+        isChatAvailable: Bool,
+        gatewayStableID: String?) -> Decision
+    {
+        let commandId = event.commandId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let text = event.text?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if commandId.isEmpty || text.isEmpty {
+            return .dropMissingFields
+        }
+        if self.seenCommandIds.contains(commandId) {
+            return .deduped(commandId: commandId)
+        }
+        self.rememberRecentCommandId(commandId)
+        if !isChatAvailable {
+            let owner = gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !owner.isEmpty else { return .dropMissingTarget }
+            self.queuedCommands.append(
+                QueuedCommand(gatewayStableID: owner, event: self.command(event, taggedFor: owner)))
+            self.rebuildSeenCommandIds()
+            self.persistQueue()
+            return .queue(commandId: commandId)
+        }
+        return .forward
+    }
+
+    func nextQueuedCommand(isChatAvailable: Bool, gatewayStableID: String?) -> WatchAppCommandEvent? {
+        let owner = gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard isChatAvailable, !owner.isEmpty else { return nil }
+        return self.queuedCommands.first { $0.gatewayStableID == owner }?.event
+    }
+
+    func removeQueuedCommand(commandId: String, gatewayStableID: String?) {
+        let commandId = commandId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let owner = gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !commandId.isEmpty, !owner.isEmpty else { return }
+        guard let index = self.queuedCommands.firstIndex(where: {
+            $0.gatewayStableID == owner && $0.event.commandId == commandId
+        }) else { return }
+        self.queuedCommands.remove(at: index)
+        self.rememberRecentCommandId(commandId)
+        self.persistQueue()
+    }
+
+    func requeueFront(_ event: WatchAppCommandEvent, gatewayStableID: String?) {
+        let commandId = event.commandId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let owner = gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !owner.isEmpty else { return }
+        if !commandId.isEmpty {
+            self.rememberRecentCommandId(commandId)
+            self.queuedCommands.removeAll { $0.event.commandId == commandId }
+        }
+        self.queuedCommands.insert(
+            QueuedCommand(gatewayStableID: owner, event: self.command(event, taggedFor: owner)),
+            at: 0)
+        self.rebuildSeenCommandIds()
+        self.persistQueue()
+    }
+
+    var queuedCount: Int {
+        self.queuedCommands.count
+    }
+
+    var queuedCommandIds: [String] {
+        self.queuedCommands.map(\.event.commandId)
+    }
+
+    private func restoreQueue() {
+        guard let data = defaults.data(forKey: Self.persistedQueueKey),
+              let persisted = try? JSONDecoder().decode([QueuedCommand].self, from: data)
+        else {
+            return
+        }
+
+        var seen: [String] = []
+        var seenSet = Set<String>()
+        self.queuedCommands = persisted.compactMap { queued in
+            let owner = queued.gatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+            let commandId = queued.event.commandId.trimmingCharacters(in: .whitespacesAndNewlines)
+            let text = queued.event.text?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            guard !owner.isEmpty, !commandId.isEmpty, !text.isEmpty, seenSet.insert(commandId).inserted else {
+                return nil
+            }
+            seen.append(commandId)
+            return QueuedCommand(gatewayStableID: owner, event: self.command(queued.event, taggedFor: owner))
+        }
+        self.recentCommandIds = Array(seen.suffix(Self.maxRecentCommandIds))
+        self.rebuildSeenCommandIds()
+        if self.queuedCommands.count != persisted.count {
+            self.persistQueue()
+        }
+    }
+
+    private func rememberRecentCommandId(_ commandId: String) {
+        guard !commandId.isEmpty else { return }
+        self.recentCommandIds.removeAll { $0 == commandId }
+        self.recentCommandIds.append(commandId)
+        if self.recentCommandIds.count > Self.maxRecentCommandIds {
+            self.recentCommandIds.removeFirst(self.recentCommandIds.count - Self.maxRecentCommandIds)
+        }
+        self.rebuildSeenCommandIds()
+    }
+
+    private func rebuildSeenCommandIds() {
+        var ids = Set(self.recentCommandIds)
+        ids.formUnion(self.queuedCommands.map(\.event.commandId))
+        self.seenCommandIds = ids
+    }
+
+    private func persistQueue() {
+        if self.queuedCommands.isEmpty {
+            self.defaults.removeObject(forKey: Self.persistedQueueKey)
+            return
+        }
+        guard let data = try? JSONEncoder().encode(queuedCommands) else { return }
+        self.defaults.set(data, forKey: Self.persistedQueueKey)
+    }
+
+    private func command(_ event: WatchAppCommandEvent, taggedFor gatewayStableID: String) -> WatchAppCommandEvent {
+        var tagged = event
+        tagged.gatewayStableID = gatewayStableID
+        return tagged
+    }
+
+    static func resetPersistedQueue(defaults: UserDefaults = .standard) {
+        defaults.removeObject(forKey: self.persistedQueueKey)
+    }
+}

apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -97,6 +97,22 @@ struct WatchExecApprovalSnapshotRequestEvent: Equatable {
     var transport: String
 }
 
+struct WatchAppSnapshotRequestEvent: Equatable {
+    var requestId: String
+    var sentAtMs: Int?
+    var transport: String
+}
+
+struct WatchAppCommandEvent: Codable, Equatable {
+    var commandId: String
+    var command: OpenClawWatchAppCommand
+    var sessionKey: String?
+    var gatewayStableID: String?
+    var text: String?
+    var sentAtMs: Int?
+    var transport: String
+}
+
 struct WatchNotificationSendResult: Equatable {
     var deliveredImmediately: Bool
     var queuedForDelivery: Bool
@@ -110,6 +126,8 @@ protocol WatchMessagingServicing: AnyObject, Sendable {
     func setExecApprovalResolveHandler(_ handler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?)
     func setExecApprovalSnapshotRequestHandler(
         _ handler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?)
+    func setAppSnapshotRequestHandler(_ handler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?)
+    func setAppCommandHandler(_ handler: (@Sendable (WatchAppCommandEvent) -> Void)?)
     func sendNotification(
         id: String,
         params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
@@ -121,6 +139,8 @@ protocol WatchMessagingServicing: AnyObject, Sendable {
         _ message: OpenClawWatchExecApprovalExpiredMessage) async throws -> WatchNotificationSendResult
     func syncExecApprovalSnapshot(
         _ message: OpenClawWatchExecApprovalSnapshotMessage) async throws -> WatchNotificationSendResult
+    func syncAppSnapshot(
+        _ message: OpenClawWatchAppSnapshotMessage) async throws -> WatchNotificationSendResult
 }
 
 extension CameraController: CameraServicing {}

apps/ios/Sources/Services/WatchConnectivityTransport.swift

@@ -7,6 +7,8 @@ private struct WatchConnectivityTransportCallbacks {
     var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
     var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
     var execApprovalSnapshotRequestHandler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
+    var appSnapshotRequestHandler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?
+    var appCommandHandler: (@Sendable (WatchAppCommandEvent) -> Void)?
 }
 
 private func sendReachableWatchMessage(_ payload: [String: Any], with session: WCSession) async throws {
@@ -96,6 +98,14 @@ final class WatchConnectivityTransport: NSObject, @unchecked Sendable {
         self.updateCallbacks { $0.execApprovalSnapshotRequestHandler = handler }
     }
 
+    func setAppSnapshotRequestHandler(_ handler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?) {
+        self.updateCallbacks { $0.appSnapshotRequestHandler = handler }
+    }
+
+    func setAppCommandHandler(_ handler: (@Sendable (WatchAppCommandEvent) -> Void)?) {
+        self.updateCallbacks { $0.appCommandHandler = handler }
+    }
+
     func sendPayload(_ payload: [String: Any]) async throws -> WatchNotificationSendResult {
         await self.ensureActivated()
         let session = try self.requireReadySession()
@@ -227,6 +237,24 @@ final class WatchConnectivityTransport: NSObject, @unchecked Sendable {
         }
     }
 
+    private func emitAppSnapshotRequest(_ event: WatchAppSnapshotRequestEvent) {
+        guard let handler = self.callbacksSnapshot().appSnapshotRequestHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
+    private func emitAppCommand(_ event: WatchAppCommandEvent) {
+        guard let handler = self.callbacksSnapshot().appCommandHandler else {
+            return
+        }
+        Task { @MainActor in
+            handler(event)
+        }
+    }
+
     private nonisolated static func status(for session: WCSession) -> WatchMessagingStatus {
         WatchMessagingStatus(
             supported: true,
@@ -296,6 +324,20 @@ extension WatchConnectivityTransport: WCSessionDelegate {
             transport: "sendMessage")
         {
             self.emitExecApprovalSnapshotRequest(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseAppSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitAppSnapshotRequest(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseAppCommandPayload(
+            message,
+            transport: "sendMessage")
+        {
+            self.emitAppCommand(event)
         }
     }
 
@@ -327,6 +369,22 @@ extension WatchConnectivityTransport: WCSessionDelegate {
             self.emitExecApprovalSnapshotRequest(event)
             return
         }
+        if let event = WatchMessagingPayloadCodec.parseAppSnapshotRequestPayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitAppSnapshotRequest(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseAppCommandPayload(
+            message,
+            transport: "sendMessage")
+        {
+            replyHandler(["ok": true])
+            self.emitAppCommand(event)
+            return
+        }
         replyHandler(["ok": false, "error": "unsupported_payload"])
     }
 
@@ -352,6 +410,20 @@ extension WatchConnectivityTransport: WCSessionDelegate {
             transport: "transferUserInfo")
         {
             self.emitExecApprovalSnapshotRequest(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseAppSnapshotRequestPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitAppSnapshotRequest(event)
+            return
+        }
+        if let event = WatchMessagingPayloadCodec.parseAppCommandPayload(
+            userInfo,
+            transport: "transferUserInfo")
+        {
+            self.emitAppCommand(event)
         }
     }
 

apps/ios/Sources/Services/WatchMessagingPayloadCodec.swift

@@ -151,6 +151,55 @@ enum WatchMessagingPayloadCodec {
         return payload
     }
 
+    static func encodeAppSnapshotPayload(
+        _ message: OpenClawWatchAppSnapshotMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": OpenClawWatchPayloadType.appSnapshot.rawValue,
+            "gatewayStatusText": message.gatewayStatusText,
+            "gatewayConnected": message.gatewayConnected,
+            "agentName": message.agentName,
+            "sessionKey": message.sessionKey,
+            "talkStatusText": message.talkStatusText,
+            "talkEnabled": message.talkEnabled,
+            "talkListening": message.talkListening,
+            "talkSpeaking": message.talkSpeaking,
+            "pendingApprovalCount": message.pendingApprovalCount,
+        ]
+        if let agentAvatarURL = nonEmpty(message.agentAvatarURL) {
+            payload["agentAvatarUrl"] = agentAvatarURL
+        }
+        if let agentAvatarText = nonEmpty(message.agentAvatarText) {
+            payload["agentAvatarText"] = agentAvatarText
+        }
+        if let gatewayStableID = nonEmpty(message.gatewayStableID) {
+            payload["gatewayStableID"] = gatewayStableID
+        }
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        if let chatItems = message.chatItems {
+            payload["chatItems"] = chatItems.map { item in
+                var encoded: [String: Any] = [
+                    "id": item.id,
+                    "role": item.role,
+                    "text": item.text,
+                ]
+                if let timestampMs = item.timestampMs {
+                    encoded["timestampMs"] = timestampMs
+                }
+                return encoded
+            }
+        }
+        if let chatStatusText = nonEmpty(message.chatStatusText) {
+            payload["chatStatusText"] = chatStatusText
+        }
+        if let snapshotId = nonEmpty(message.snapshotId) {
+            payload["snapshotId"] = snapshotId
+        }
+        return payload
+    }
+
     static func parseQuickReplyPayload(
         _ payload: [String: Any],
         transport: String) -> WatchQuickReplyEvent?
@@ -216,4 +265,46 @@ enum WatchMessagingPayloadCodec {
             sentAtMs: sentAtMs,
             transport: transport)
     }
+
+    static func parseAppSnapshotRequestPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchAppSnapshotRequestEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.appSnapshotRequest.rawValue else {
+            return nil
+        }
+        let requestId = self.nonEmpty(payload["requestId"] as? String) ?? UUID().uuidString
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchAppSnapshotRequestEvent(
+            requestId: requestId,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
+
+    static func parseAppCommandPayload(
+        _ payload: [String: Any],
+        transport: String) -> WatchAppCommandEvent?
+    {
+        guard (payload["type"] as? String) == OpenClawWatchPayloadType.appCommand.rawValue else {
+            return nil
+        }
+        guard let rawCommand = nonEmpty(payload["command"] as? String),
+              let command = OpenClawWatchAppCommand(rawValue: rawCommand)
+        else {
+            return nil
+        }
+        let commandId = self.nonEmpty(payload["commandId"] as? String) ?? UUID().uuidString
+        let sessionKey = self.nonEmpty(payload["sessionKey"] as? String)
+        let gatewayStableID = self.nonEmpty(payload["gatewayStableID"] as? String)
+        let text = self.nonEmpty(payload["text"] as? String)
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        return WatchAppCommandEvent(
+            commandId: commandId,
+            command: command,
+            sessionKey: sessionKey,
+            gatewayStableID: gatewayStableID,
+            text: text,
+            sentAtMs: sentAtMs,
+            transport: transport)
+    }
 }

apps/ios/Sources/Services/WatchMessagingService.swift

@@ -27,6 +27,8 @@ final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
     private var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
     private var execApprovalSnapshotRequestHandler: (
         @Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
+    private var appSnapshotRequestHandler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?
+    private var appCommandHandler: (@Sendable (WatchAppCommandEvent) -> Void)?
 
     init(transport: WatchConnectivityTransport = WatchConnectivityTransport()) {
         self.transport = transport
@@ -50,6 +52,16 @@ final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
                 self?.emitExecApprovalSnapshotRequest(event)
             }
         }
+        self.transport.setAppSnapshotRequestHandler { [weak self] event in
+            Task { @MainActor [weak self] in
+                self?.emitAppSnapshotRequest(event)
+            }
+        }
+        self.transport.setAppCommandHandler { [weak self] event in
+            Task { @MainActor [weak self] in
+                self?.emitAppCommand(event)
+            }
+        }
     }
 
     nonisolated static func isSupportedOnDevice() -> Bool {
@@ -95,6 +107,14 @@ final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
         self.execApprovalSnapshotRequestHandler = handler
     }
 
+    func setAppSnapshotRequestHandler(_ handler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?) {
+        self.appSnapshotRequestHandler = handler
+    }
+
+    func setAppCommandHandler(_ handler: (@Sendable (WatchAppCommandEvent) -> Void)?) {
+        self.appCommandHandler = handler
+    }
+
     func sendNotification(
         id: String,
         params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult
@@ -131,6 +151,13 @@ final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
             WatchMessagingPayloadCodec.encodeExecApprovalSnapshotPayload(message))
     }
 
+    func syncAppSnapshot(
+        _ message: OpenClawWatchAppSnapshotMessage) async throws -> WatchNotificationSendResult
+    {
+        try await self.transport.sendSnapshotPayload(
+            WatchMessagingPayloadCodec.encodeAppSnapshotPayload(message))
+    }
+
     private func emitStatusIfChanged(_ snapshot: WatchMessagingStatus) {
         guard snapshot != self.lastEmittedStatus else {
             return
@@ -159,4 +186,20 @@ final class WatchMessagingService: @preconcurrency WatchMessagingServicing {
                 + "sentAtMs=\(event.sentAtMs ?? -1)")
         self.execApprovalSnapshotRequestHandler?(event)
     }
+
+    private func emitAppSnapshotRequest(_ event: WatchAppSnapshotRequestEvent) {
+        GatewayDiagnostics.log(
+            "watch messaging: app snapshot request "
+                + "id=\(event.requestId) transport=\(event.transport) "
+                + "sentAtMs=\(event.sentAtMs ?? -1)")
+        self.appSnapshotRequestHandler?(event)
+    }
+
+    private func emitAppCommand(_ event: WatchAppCommandEvent) {
+        GatewayDiagnostics.log(
+            "watch messaging: app command "
+                + "id=\(event.commandId) command=\(event.command.rawValue) "
+                + "transport=\(event.transport)")
+        self.appCommandHandler?(event)
+    }
 }

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -1,4 +1,5 @@
 import Foundation
+import OpenClawChatUI
 import OpenClawKit
 import OpenClawProtocol
 import Testing
@@ -33,6 +34,27 @@ private func makeAgentDeepLinkURL(
     return components.url!
 }
 
+private func makeWatchChatRawMessage(
+    role: String,
+    text: String?,
+    type: String = "text",
+    timestamp: Double) throws -> AnyCodable
+{
+    let message = OpenClawChatMessage(
+        role: role,
+        content: [
+            OpenClawChatMessageContent(
+                type: type,
+                text: text,
+                mimeType: nil,
+                fileName: nil,
+                content: nil),
+        ],
+        timestamp: timestamp)
+    let data = try JSONEncoder().encode(message)
+    return try JSONDecoder().decode(AnyCodable.self, from: data)
+}
+
 @MainActor
 private func mountScreen(_ screen: ScreenController) throws -> ScreenWebViewCoordinator {
     let coordinator = ScreenWebViewCoordinator(controller: screen)
@@ -59,10 +81,13 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
     var lastSentExecApprovalResolved: OpenClawWatchExecApprovalResolvedMessage?
     var lastSentExecApprovalExpired: OpenClawWatchExecApprovalExpiredMessage?
     var lastSentExecApprovalSnapshot: OpenClawWatchExecApprovalSnapshotMessage?
+    var lastSentAppSnapshot: OpenClawWatchAppSnapshotMessage?
     private var statusHandler: (@Sendable (WatchMessagingStatus) -> Void)?
     private var replyHandler: (@Sendable (WatchQuickReplyEvent) -> Void)?
     private var execApprovalResolveHandler: (@Sendable (WatchExecApprovalResolveEvent) -> Void)?
     private var execApprovalSnapshotRequestHandler: (@Sendable (WatchExecApprovalSnapshotRequestEvent) -> Void)?
+    private var appSnapshotRequestHandler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?
+    private var appCommandHandler: (@Sendable (WatchAppCommandEvent) -> Void)?
 
     func status() async -> WatchMessagingStatus {
         self.currentStatus
@@ -86,6 +111,14 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         self.execApprovalSnapshotRequestHandler = handler
     }
 
+    func setAppSnapshotRequestHandler(_ handler: (@Sendable (WatchAppSnapshotRequestEvent) -> Void)?) {
+        self.appSnapshotRequestHandler = handler
+    }
+
+    func setAppCommandHandler(_ handler: (@Sendable (WatchAppCommandEvent) -> Void)?) {
+        self.appCommandHandler = handler
+    }
+
     func sendNotification(id: String, params: OpenClawWatchNotifyParams) async throws -> WatchNotificationSendResult {
         self.lastSent = (id: id, params: params)
         if let sendError {
@@ -134,6 +167,16 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
         return self.nextSendResult
     }
 
+    func syncAppSnapshot(
+        _ message: OpenClawWatchAppSnapshotMessage) async throws -> WatchNotificationSendResult
+    {
+        self.lastSentAppSnapshot = message
+        if let sendError {
+            throw sendError
+        }
+        return self.nextSendResult
+    }
+
     func emitReply(_ event: WatchQuickReplyEvent) {
         self.replyHandler?(event)
     }
@@ -145,6 +188,14 @@ private final class MockWatchMessagingService: @preconcurrency WatchMessagingSer
     func emitExecApprovalSnapshotRequest(_ event: WatchExecApprovalSnapshotRequestEvent) {
         self.execApprovalSnapshotRequestHandler?(event)
     }
+
+    func emitAppSnapshotRequest(_ event: WatchAppSnapshotRequestEvent) {
+        self.appSnapshotRequestHandler?(event)
+    }
+
+    func emitAppCommand(_ event: WatchAppCommandEvent) {
+        self.appCommandHandler?(event)
+    }
 }
 
 private final class MockBootstrapNotificationCenter: NotificationCentering, @unchecked Sendable {
@@ -462,6 +513,581 @@ private final class MockBootstrapNotificationCenter: NotificationCentering, @unc
         #expect(watchService.lastSentExecApprovalSnapshot == nil)
     }
 
+    @Test @MainActor func watchAppSnapshotRequestPublishesCurrentDashboardState() async throws {
+        NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState()
+        defer { NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState() }
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel._test_setGatewayConnected(true)
+        appModel._test_setOperatorConnected(true)
+        appModel._test_setConnectedGatewayID("gateway-watch-snapshot")
+        appModel.gatewayStatusText = "Connected"
+        appModel.talkMode.setEnabled(true)
+        appModel.talkMode.statusText = "Listening"
+
+        watchService.emitAppSnapshotRequest(
+            WatchAppSnapshotRequestEvent(
+                requestId: "app-snapshot-1",
+                sentAtMs: 123,
+                transport: "sendMessage"))
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot != nil {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+
+        let snapshot = try #require(watchService.lastSentAppSnapshot)
+        #expect(snapshot.gatewayConnected == true)
+        #expect(snapshot.gatewayStatusText == "Connected")
+        #expect(snapshot.agentName == "Main")
+        #expect(snapshot.sessionKey == "main")
+        #expect(snapshot.gatewayStableID == "gateway-watch-snapshot")
+        #expect(!snapshot.talkStatusText.isEmpty)
+        #expect(snapshot.talkEnabled == true)
+        #expect(snapshot.pendingApprovalCount == 0)
+    }
+
+    @Test @MainActor func watchAppSnapshotPublishesOfflineWhenOperatorDisconnects() async {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel._test_setGatewayConnected(true)
+        appModel._test_setOperatorConnected(true)
+        appModel.gatewayStatusText = "Connected"
+
+        watchService.emitAppSnapshotRequest(
+            WatchAppSnapshotRequestEvent(
+                requestId: "app-snapshot-before-disconnect",
+                sentAtMs: 123,
+                transport: "sendMessage"))
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot?.gatewayConnected == true {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+        #expect(watchService.lastSentAppSnapshot?.gatewayConnected == true)
+
+        appModel.disconnectGateway()
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot?.gatewayConnected == false {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+
+        #expect(watchService.lastSentAppSnapshot?.gatewayConnected == false)
+        #expect(watchService.lastSentAppSnapshot?.gatewayStatusText == "Offline")
+    }
+
+    @Test @MainActor func watchAppSnapshotPublishesOnlineWhenOperatorReconnects() async {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel._test_setGatewayConnected(true)
+        appModel.gatewayStatusText = "Connected"
+
+        watchService.emitAppSnapshotRequest(
+            WatchAppSnapshotRequestEvent(
+                requestId: "app-snapshot-before-reconnect",
+                sentAtMs: 124,
+                transport: "sendMessage"))
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot?.gatewayConnected == false {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+        #expect(watchService.lastSentAppSnapshot?.gatewayConnected == false)
+
+        appModel._test_setOperatorConnected(true)
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot?.gatewayConnected == true {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+
+        #expect(watchService.lastSentAppSnapshot?.gatewayConnected == true)
+        #expect(watchService.lastSentAppSnapshot?.gatewayStatusText == "Connected")
+    }
+
+    @Test @MainActor func watchAppSnapshotUsesConfiguredAgentAvatar() async throws {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel.gatewayDefaultAgentId = "main"
+        appModel.gatewayAgents = [
+            AgentSummary(
+                id: "main",
+                name: "Main",
+                identity: [
+                    "avatarUrl": AnyCodable("https://example.com/openclaw.png"),
+                    "emoji": AnyCodable("OC"),
+                ],
+                workspace: nil,
+                model: nil,
+                agentruntime: nil),
+        ]
+
+        watchService.emitAppSnapshotRequest(
+            WatchAppSnapshotRequestEvent(
+                requestId: "app-snapshot-avatar",
+                sentAtMs: 124,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        let snapshot = try #require(watchService.lastSentAppSnapshot)
+        #expect(snapshot.agentAvatarURL == "https://example.com/openclaw.png")
+        #expect(snapshot.agentAvatarText == "OC")
+    }
+
+    @Test @MainActor func watchAppSnapshotIncludesPendingApprovalCount() async throws {
+        NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState()
+        defer { NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState() }
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+
+        try appModel._test_presentExecApprovalPrompt(
+            #require(
+                NodeAppModel._test_makeExecApprovalPrompt(
+                    id: "approval-watch-app-count",
+                    commandText: "rm -rf build",
+                    allowedDecisions: ["allow-once", "deny"],
+                    host: "Mac",
+                    nodeId: "node-1",
+                    agentId: "agent-1",
+                    expiresAtMs: nil)))
+        await Task.yield()
+
+        let snapshot = try #require(watchService.lastSentAppSnapshot)
+        #expect(snapshot.pendingApprovalCount == 1)
+    }
+
+    @Test @MainActor func watchAppCommandControlsTalkThroughPhoneModel() async {
+        let watchService = MockWatchMessagingService()
+        let talkMode = TalkModeManager(allowSimulatorCapture: true)
+        let appModel = NodeAppModel(watchMessagingService: watchService, talkMode: talkMode)
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-start-talk",
+                command: .startTalk,
+                sessionKey: "main",
+                gatewayStableID: nil,
+                text: nil,
+                sentAtMs: 123,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(appModel.talkMode.isEnabled == true)
+        #expect(watchService.lastSentAppSnapshot?.talkEnabled == true)
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-stop-talk",
+                command: .stopTalk,
+                sessionKey: "main",
+                gatewayStableID: nil,
+                text: nil,
+                sentAtMs: 124,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(appModel.talkMode.isEnabled == false)
+        #expect(watchService.lastSentAppSnapshot?.talkEnabled == false)
+    }
+
+    @Test @MainActor func watchAppCommandOpensChatSessionOnPhoneModel() async {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-open-chat",
+                command: .openChat,
+                sessionKey: "incident-42",
+                gatewayStableID: nil,
+                text: nil,
+                sentAtMs: 125,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(appModel.chatSessionKey == "incident-42")
+        #expect(watchService.lastSentAppSnapshot?.sessionKey == "incident-42")
+    }
+
+    @Test @MainActor func watchAppCommandSendsChatMessageThroughPhoneModel() async {
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel.enterAppleReviewDemoMode()
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: AppleReviewDemoMode.gatewayID,
+                text: "Watch says hello",
+                sentAtMs: 126,
+                transport: "sendMessage"))
+        for _ in 0..<20 {
+            if watchService.lastSentAppSnapshot?.chatItems?.contains(where: { item in
+                item.role == "user" && item.text.contains("Watch says hello")
+            }) == true {
+                break
+            }
+            try? await Task.sleep(nanoseconds: 50_000_000)
+        }
+
+        #expect(watchService.lastSentAppSnapshot?.chatItems?.contains { item in
+            item.role == "user" && item.text.contains("Watch says hello")
+        } == true)
+    }
+
+    @Test func watchChatPreviewKeepsOlderReadableMessagesAfterInternalEvents() throws {
+        var rawMessages = try [
+            makeWatchChatRawMessage(
+                role: "assistant",
+                text: "Still worth reading",
+                timestamp: 1000),
+        ]
+        for index in 0..<30 {
+            try rawMessages.append(
+                makeWatchChatRawMessage(
+                    role: "assistant",
+                    text: nil,
+                    type: "toolCall",
+                    timestamp: 2000 + Double(index)))
+        }
+
+        let items = NodeAppModel._test_makeWatchChatItems(from: rawMessages)
+
+        #expect(items.map(\.text) == ["Still worth reading"])
+    }
+
+    @Test @MainActor func watchAppCommandQueuesChatMessageWhenOperatorOffline() async {
+        NodeAppModel._test_resetPersistedWatchChatQueueState()
+        defer { NodeAppModel._test_resetPersistedWatchChatQueueState() }
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        let gatewayID = "gateway-watch-chat-offline"
+        appModel._test_setConnectedGatewayID(gatewayID)
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat-offline",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: gatewayID,
+                text: "Queue this from watch",
+                sentAtMs: 127,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(appModel._test_queuedWatchChatCommandCount() == 1)
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat-offline",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: gatewayID,
+                text: "Queue this from watch",
+                sentAtMs: 128,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(appModel._test_queuedWatchChatCommandCount() == 1)
+    }
+
+    @Test @MainActor func watchAppCommandDropsChatMessageForStaleGatewaySnapshot() async {
+        NodeAppModel._test_resetPersistedWatchChatQueueState()
+        defer { NodeAppModel._test_resetPersistedWatchChatQueueState() }
+        let watchService = MockWatchMessagingService()
+        let appModel = NodeAppModel(watchMessagingService: watchService)
+        appModel._test_setConnectedGatewayID("gateway-current")
+
+        watchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat-stale-gateway",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: "gateway-from-old-snapshot",
+                text: "Do not send to the new gateway",
+                sentAtMs: 128,
+                transport: "transferUserInfo"))
+        await Task.yield()
+
+        #expect(appModel._test_queuedWatchChatCommandCount() == 0)
+    }
+
+    @Test @MainActor func watchAppCommandRestoresQueuedChatMessageAfterModelRestart() async {
+        NodeAppModel._test_resetPersistedWatchChatQueueState()
+        defer { NodeAppModel._test_resetPersistedWatchChatQueueState() }
+
+        let gatewayID = "gateway-watch-chat-restore"
+        let firstWatchService = MockWatchMessagingService()
+        let firstAppModel = NodeAppModel(watchMessagingService: firstWatchService)
+        firstAppModel._test_setConnectedGatewayID(gatewayID)
+        firstWatchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat-restore",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: gatewayID,
+                text: "Keep this through restart",
+                sentAtMs: 129,
+                transport: "sendMessage"))
+        await Task.yield()
+
+        #expect(firstAppModel._test_queuedWatchChatCommandIds() == ["watch-send-chat-restore"])
+
+        let secondWatchService = MockWatchMessagingService()
+        let secondAppModel = NodeAppModel(watchMessagingService: secondWatchService)
+        secondAppModel._test_setConnectedGatewayID(gatewayID)
+
+        #expect(secondAppModel._test_queuedWatchChatCommandIds() == ["watch-send-chat-restore"])
+
+        secondWatchService.emitAppCommand(
+            WatchAppCommandEvent(
+                commandId: "watch-send-chat-restore",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: gatewayID,
+                text: "Keep this through restart",
+                sentAtMs: 130,
+                transport: "transferUserInfo"))
+        await Task.yield()
+
+        #expect(secondAppModel._test_queuedWatchChatCommandIds() == ["watch-send-chat-restore"])
+    }
+
+    @Test @MainActor func watchChatQueueScopesAndOrdersCommandsByGateway() throws {
+        let suiteName = "watch-chat-queue-\(UUID().uuidString)"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer {
+            defaults.removePersistentDomain(forName: suiteName)
+        }
+
+        let coordinator = WatchChatCoordinator(defaults: defaults)
+        let first = WatchAppCommandEvent(
+            commandId: "watch-send-chat-gateway-a-1",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: "gateway-a",
+            text: "First for gateway A",
+            sentAtMs: 131,
+            transport: "sendMessage")
+        let second = WatchAppCommandEvent(
+            commandId: "watch-send-chat-gateway-a-2",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: "gateway-a",
+            text: "Second for gateway A",
+            sentAtMs: 132,
+            transport: "sendMessage")
+
+        if case .queue = coordinator.ingest(first, isChatAvailable: false, gatewayStableID: "gateway-a") {
+        } else {
+            Issue.record("expected first gateway A command to queue")
+        }
+        if case .queue = coordinator.ingest(second, isChatAvailable: false, gatewayStableID: "gateway-a") {
+        } else {
+            Issue.record("expected second gateway A command to queue")
+        }
+
+        #expect(coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-b") == nil)
+        coordinator.removeQueuedCommand(
+            commandId: "watch-send-chat-gateway-a-1",
+            gatewayStableID: "gateway-b")
+
+        #expect(
+            coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-a")?.commandId ==
+                "watch-send-chat-gateway-a-1")
+        #expect(
+            coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-a")?.commandId ==
+                "watch-send-chat-gateway-a-1")
+
+        coordinator.removeQueuedCommand(
+            commandId: "watch-send-chat-gateway-a-1",
+            gatewayStableID: "gateway-a")
+        #expect(
+            coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-a")?.commandId ==
+                "watch-send-chat-gateway-a-2")
+    }
+
+    @Test @MainActor func watchChatRequeueKeepsOriginalGatewayOwner() throws {
+        let suiteName = "watch-chat-requeue-\(UUID().uuidString)"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer {
+            defaults.removePersistentDomain(forName: suiteName)
+        }
+
+        let coordinator = WatchChatCoordinator(defaults: defaults)
+        let event = WatchAppCommandEvent(
+            commandId: "watch-send-chat-retry-gateway-a",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: "gateway-a",
+            text: "Retry for gateway A",
+            sentAtMs: 133,
+            transport: "sendMessage")
+
+        coordinator.requeueFront(event, gatewayStableID: event.gatewayStableID)
+
+        #expect(coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-b") == nil)
+        #expect(
+            coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-a")?.commandId ==
+                "watch-send-chat-retry-gateway-a")
+    }
+
+    @Test @MainActor func watchChatRestoreBackfillsGatewayOwnerIntoLegacyQueuedEvent() throws {
+        let suiteName = "watch-chat-restore-legacy-\(UUID().uuidString)"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer {
+            defaults.removePersistentDomain(forName: suiteName)
+        }
+        let legacyQueueJSON = """
+            [
+              {
+                "gatewayStableID": "gateway-a",
+                "event": {
+                  "commandId": "watch-send-chat-legacy",
+                  "command": "send-chat",
+                  "sessionKey": "main",
+                  "text": "Legacy queued text",
+                  "sentAtMs": 134,
+                  "transport": "transferUserInfo"
+                }
+              }
+            ]
+            """
+        defaults.set(
+            Data(legacyQueueJSON.utf8),
+            forKey: "watch.chat.command.queue.v1")
+
+        let coordinator = WatchChatCoordinator(defaults: defaults)
+        let restored = coordinator.nextQueuedCommand(isChatAvailable: true, gatewayStableID: "gateway-a")
+
+        #expect(restored?.commandId == "watch-send-chat-legacy")
+        #expect(restored?.gatewayStableID == "gateway-a")
+    }
+
+    @Test @MainActor func watchChatCommandDedupingKeepsOnlyRecentForwardedCommands() throws {
+        let suiteName = "watch-chat-recent-\(UUID().uuidString)"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer {
+            defaults.removePersistentDomain(forName: suiteName)
+        }
+
+        let coordinator = WatchChatCoordinator(defaults: defaults)
+        for index in 0..<140 {
+            let event = WatchAppCommandEvent(
+                commandId: "watch-forward-\(index)",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: nil,
+                text: "Message \(index)",
+                sentAtMs: index,
+                transport: "sendMessage")
+            if case .forward = coordinator.ingest(
+                event,
+                isChatAvailable: true,
+                gatewayStableID: "gateway-a")
+            {
+            } else {
+                Issue.record("expected forwarded command \(index)")
+            }
+        }
+
+        let oldestEvent = WatchAppCommandEvent(
+            commandId: "watch-forward-0",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: nil,
+            text: "Message 0 again",
+            sentAtMs: 999,
+            transport: "sendMessage")
+        if case .forward = coordinator.ingest(
+            oldestEvent,
+            isChatAvailable: true,
+            gatewayStableID: "gateway-a")
+        {
+        } else {
+            Issue.record("expected oldest forwarded command to age out of dedupe")
+        }
+
+        let recentEvent = WatchAppCommandEvent(
+            commandId: "watch-forward-139",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: nil,
+            text: "Message 139 again",
+            sentAtMs: 1000,
+            transport: "sendMessage")
+        if case .deduped = coordinator.ingest(
+            recentEvent,
+            isChatAvailable: true,
+            gatewayStableID: "gateway-a")
+        {
+        } else {
+            Issue.record("expected recent forwarded command to stay deduped")
+        }
+    }
+
+    @Test @MainActor func watchChatCommandDedupingKeepsDeliveredQueuedCommandsRecent() throws {
+        let suiteName = "watch-chat-delivered-\(UUID().uuidString)"
+        let defaults = try #require(UserDefaults(suiteName: suiteName))
+        defaults.removePersistentDomain(forName: suiteName)
+        defer {
+            defaults.removePersistentDomain(forName: suiteName)
+        }
+
+        let coordinator = WatchChatCoordinator(defaults: defaults)
+        for index in 0..<140 {
+            let event = WatchAppCommandEvent(
+                commandId: "watch-queued-\(index)",
+                command: .sendChat,
+                sessionKey: "main",
+                gatewayStableID: nil,
+                text: "Queued \(index)",
+                sentAtMs: index,
+                transport: "transferUserInfo")
+            if case .queue = coordinator.ingest(
+                event,
+                isChatAvailable: false,
+                gatewayStableID: "gateway-a")
+            {
+            } else {
+                Issue.record("expected queued command \(index)")
+            }
+        }
+
+        coordinator.removeQueuedCommand(
+            commandId: "watch-queued-0",
+            gatewayStableID: "gateway-a")
+
+        let duplicateDeliveredEvent = WatchAppCommandEvent(
+            commandId: "watch-queued-0",
+            command: .sendChat,
+            sessionKey: "main",
+            gatewayStableID: nil,
+            text: "Duplicate after delivery",
+            sentAtMs: 999,
+            transport: "transferUserInfo")
+        if case .deduped = coordinator.ingest(
+            duplicateDeliveredEvent,
+            isChatAvailable: true,
+            gatewayStableID: "gateway-a")
+        {
+        } else {
+            Issue.record("expected delivered queued command to stay deduped")
+        }
+    }
+
     @Test @MainActor func pendingWatchRecoveryIDsAreIncludedWithoutDeliveredNotifications() async {
         NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState()
         defer { NodeAppModel._test_resetPersistedWatchExecApprovalBridgeState() }

apps/ios/VERSIONING.md

@@ -90,10 +90,11 @@ Pinned iOS version `2026.4.10` maps to:
   - prepares App Store distribution signing and bundle settings against the pinned iOS version
 - `scripts/ios-release-signing.mjs`
   - validates the checked-in App Store signing manifest
-  - creates or verifies Developer Portal bundle IDs, capabilities, certificates, and profiles through `asc`
-  - syncs encrypted signing assets with the private shared signing repo
+  - renders the temporary release xcconfig profile pins
 - `apps/ios/fastlane/Fastfile`
   - resolves version metadata from the pinned iOS helper
+  - creates or verifies Developer Portal bundle IDs/services through Fastlane `produce`
+  - syncs encrypted App Store signing assets with Fastlane `match`
   - increments App Store Connect build numbers for the pinned short version
   - uploads screenshots and release notes before archiving a release build
 

apps/ios/WatchExtension/Assets.xcassets/Contents.json

@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}

apps/ios/WatchExtension/Assets.xcassets/OpenClawIcon.imageset/Contents.json

@@ -0,0 +1,12 @@
+{
+  "images": [
+    {
+      "filename": "openclaw-icon.png",
+      "idiom": "universal"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}

apps/ios/WatchExtension/Sources/OpenClawWatchApp.swift

@@ -42,6 +42,15 @@ struct OpenClawWatchApp: App {
                 },
                 onRefreshExecApprovalReview: {
                     self.refreshExecApprovalReview(force: true)
+                },
+                onRefreshAppSnapshot: {
+                    self.refreshAppSnapshot()
+                },
+                onAppCommand: { command in
+                    self.sendAppCommand(command)
+                },
+                onSendChatMessage: { text in
+                    self.sendChatMessage(text)
                 })
                 .task {
                     if OpenClawWatchApp.isScreenshotMode {
@@ -53,17 +62,57 @@ struct OpenClawWatchApp: App {
                         receiver.activate()
                         self.receiver = receiver
                     }
+                    self.refreshAppSnapshot()
                     self.refreshExecApprovalReview()
                 }
                 .onChange(of: self.scenePhase) { _, newPhase in
                     guard newPhase == .active else { return }
+                    self.refreshAppSnapshot()
                     self.refreshExecApprovalReview()
                 }
         }
     }
 
+    private func refreshAppSnapshot() {
+        guard let receiver else { return }
+        self.inboxStore.markAppSnapshotRequestStarted()
+        Task { @MainActor in
+            let result = await receiver.requestAppSnapshot()
+            self.inboxStore.markAppSnapshotRequestResult(result)
+        }
+    }
+
+    private func sendAppCommand(_ command: WatchAppCommand) {
+        guard let receiver else { return }
+        let message = self.inboxStore.makeAppCommand(command)
+        self.inboxStore.markAppCommandSending(command)
+        Task { @MainActor in
+            let result = await receiver.sendAppCommand(message)
+            self.inboxStore.markAppCommandResult(result, command: command)
+        }
+    }
+
+    private func sendChatMessage(_ text: String) {
+        guard let receiver else { return }
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        guard self.inboxStore.hasGatewayTaggedAppSnapshot else {
+            self.inboxStore.markAppCommandBlocked(.sendChat, reason: "refreshing iPhone state")
+            self.refreshAppSnapshot()
+            return
+        }
+        let message = self.inboxStore.makeAppCommand(.sendChat, text: trimmed)
+        self.inboxStore.markAppCommandSending(.sendChat)
+        Task { @MainActor in
+            let result = await receiver.sendAppCommand(message)
+            self.inboxStore.markAppCommandResult(result, command: .sendChat)
+            try? await Task.sleep(nanoseconds: 900_000_000)
+            self.refreshAppSnapshot()
+        }
+    }
+
     private func refreshExecApprovalReview(force: Bool = false) {
-        guard let receiver = self.receiver else { return }
+        guard let receiver else { return }
         guard force || self.inboxStore.shouldAutoRequestExecApprovalSnapshot else { return }
 
         self.execApprovalRefreshTask?.cancel()
@@ -93,28 +142,42 @@ struct OpenClawWatchApp: App {
 @MainActor
 extension WatchInboxStore {
     fileprivate func configureScreenshotFixture() {
+        let sentAtMs = Int(Date().timeIntervalSince1970 * 1000)
+        self.greetingTextOverride = "Good morning"
         self.consume(
             execApprovalSnapshot: WatchExecApprovalSnapshotMessage(
                 approvals: [],
-                sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
+                sentAtMs: sentAtMs,
                 snapshotId: nil),
             transport: "screenshot")
         self.consume(
-            message: WatchNotifyMessage(
-                id: "watch-screenshot-quick-reply",
-                title: "Molty request",
-                body: "Molty Gateway checklist ready.",
-                sentAtMs: Int(Date().timeIntervalSince1970 * 1000),
-                promptId: "watch-screenshot-prompt",
+            appSnapshot: WatchAppSnapshotMessage(
+                gatewayStatusText: "Connected",
+                gatewayConnected: true,
+                agentName: "Molty",
+                agentAvatarURL: nil,
+                agentAvatarText: "M",
                 sessionKey: "watch-screenshot-session",
-                kind: "release-checklist",
-                details: nil,
-                expiresAtMs: nil,
-                risk: "medium",
-                actions: [
-                    WatchPromptAction(id: "approve", label: "Approve", style: nil),
-                    WatchPromptAction(id: "later", label: "Later", style: "cancel"),
-                ]),
-            transport: "screenshot")
+                gatewayStableID: "watch-screenshot-gateway",
+                talkStatusText: "Ready",
+                talkEnabled: true,
+                talkListening: false,
+                talkSpeaking: false,
+                pendingApprovalCount: 0,
+                chatItems: [
+                    WatchChatItem(
+                        id: "watch-screenshot-user-chat",
+                        role: "user",
+                        text: "What's on deck?",
+                        timestampMs: sentAtMs - 90000),
+                    WatchChatItem(
+                        id: "watch-screenshot-molty-chat",
+                        role: "assistant",
+                        text: "Gateway is online and ready.",
+                        timestampMs: sentAtMs - 30000),
+                ],
+                chatStatusText: "Live gateway conversation",
+                sentAtMs: sentAtMs,
+                snapshotId: "watch-screenshot-now-face"))
     }
 }

apps/ios/WatchExtension/Sources/WatchConnectivityReceiver.swift

@@ -35,13 +35,13 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
     }
 
     func activate() {
-        guard let session = self.session else { return }
+        guard let session else { return }
         session.delegate = self
         session.activate()
     }
 
     private func ensureActivated() async {
-        guard let session = self.session else { return }
+        guard let session else { return }
         if session.activationState == .activated {
             return
         }
@@ -56,7 +56,7 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
 
     func requestExecApprovalSnapshot() async {
         await self.ensureActivated()
-        guard let session = self.session else { return }
+        guard let session else { return }
         let request = WatchExecApprovalSnapshotRequestMessage(
             requestId: UUID().uuidString,
             sentAtMs: Self.nowMs())
@@ -72,9 +72,25 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
         _ = session.transferUserInfo(payload)
     }
 
+    func requestAppSnapshot() async -> WatchReplySendResult {
+        await self.ensureActivated()
+        guard let session else {
+            return WatchReplySendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: false,
+                transport: "none",
+                errorMessage: "watch session unavailable")
+        }
+        let request = WatchAppSnapshotRequestMessage(
+            requestId: UUID().uuidString,
+            sentAtMs: Self.nowMs())
+        let payload = Self.encodeAppSnapshotRequestPayload(request)
+        return await self.sendPayload(payload, session: session)
+    }
+
     func sendReply(_ draft: WatchReplyDraft) async -> WatchReplySendResult {
         await self.ensureActivated()
-        guard let session = self.session else {
+        guard let session else {
             return WatchReplySendResult(
                 deliveredImmediately: false,
                 queuedForDelivery: false,
@@ -111,7 +127,7 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
         decision: WatchExecApprovalDecision) async -> WatchReplySendResult
     {
         await self.ensureActivated()
-        guard let session = self.session else {
+        guard let session else {
             return WatchReplySendResult(
                 deliveredImmediately: false,
                 queuedForDelivery: false,
@@ -128,6 +144,18 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
         return await self.sendPayload(payload, session: session)
     }
 
+    func sendAppCommand(_ message: WatchAppCommandMessage) async -> WatchReplySendResult {
+        await self.ensureActivated()
+        guard let session else {
+            return WatchReplySendResult(
+                deliveredImmediately: false,
+                queuedForDelivery: false,
+                transport: "none",
+                errorMessage: "watch session unavailable")
+        }
+        return await self.sendPayload(Self.encodeAppCommandPayload(message), session: session)
+    }
+
     private func sendPayload(_ payload: [String: Any], session: WCSession) async -> WatchReplySendResult {
         if session.isReachable {
             do {
@@ -364,6 +392,121 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
             snapshotId: snapshotId)
     }
 
+    private static func parseAppSnapshotPayload(_ payload: [String: Any]) -> WatchAppSnapshotMessage? {
+        guard let type = payload["type"] as? String,
+              type == WatchPayloadType.appSnapshot.rawValue
+        else {
+            return nil
+        }
+        let gatewayStatusText = (payload["gatewayStatusText"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let agentName = (payload["agentName"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let agentAvatarURL = (payload["agentAvatarUrl"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let agentAvatarText = (payload["agentAvatarText"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let sessionKey = (payload["sessionKey"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let gatewayStableID = (payload["gatewayStableID"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let talkStatusText = (payload["talkStatusText"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let pendingApprovalCount = (payload["pendingApprovalCount"] as? Int)
+            ?? (payload["pendingApprovalCount"] as? NSNumber)?.intValue
+            ?? 0
+        let sentAtMs = (payload["sentAtMs"] as? Int) ?? (payload["sentAtMs"] as? NSNumber)?.intValue
+        let snapshotId = (payload["snapshotId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let chatItems = (payload["chatItems"] as? [Any])?.compactMap(Self.parseChatItem)
+        let chatStatusText = (payload["chatStatusText"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        return WatchAppSnapshotMessage(
+            gatewayStatusText: gatewayStatusText.isEmpty ? "Unknown" : gatewayStatusText,
+            gatewayConnected: Self.boolValue(payload["gatewayConnected"]),
+            agentName: agentName.isEmpty ? "Main" : agentName,
+            agentAvatarURL: agentAvatarURL?.isEmpty == false ? agentAvatarURL : nil,
+            agentAvatarText: agentAvatarText?.isEmpty == false ? agentAvatarText : nil,
+            sessionKey: sessionKey.isEmpty ? "main" : sessionKey,
+            gatewayStableID: gatewayStableID?.isEmpty == false ? gatewayStableID : nil,
+            talkStatusText: talkStatusText.isEmpty ? "Off" : talkStatusText,
+            talkEnabled: Self.boolValue(payload["talkEnabled"]),
+            talkListening: Self.boolValue(payload["talkListening"]),
+            talkSpeaking: Self.boolValue(payload["talkSpeaking"]),
+            pendingApprovalCount: max(0, pendingApprovalCount),
+            chatItems: chatItems,
+            chatStatusText: chatStatusText?.isEmpty == false ? chatStatusText : nil,
+            sentAtMs: sentAtMs,
+            snapshotId: snapshotId)
+    }
+
+    private static func parseChatItem(_ item: Any) -> WatchChatItem? {
+        guard let dict = item as? [String: Any] else { return nil }
+        guard let id = (dict["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !id.isEmpty
+        else {
+            return nil
+        }
+        let trimmedRole = (dict["role"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let text = (dict["text"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let text, !text.isEmpty else { return nil }
+        let timestampMs = (dict["timestampMs"] as? Int) ?? (dict["timestampMs"] as? NSNumber)?.intValue
+        return WatchChatItem(
+            id: id,
+            role: trimmedRole.isEmpty ? "assistant" : trimmedRole,
+            text: text,
+            timestampMs: timestampMs)
+    }
+
+    private static func boolValue(_ value: Any?) -> Bool {
+        if let bool = value as? Bool {
+            return bool
+        }
+        if let number = value as? NSNumber {
+            return number.boolValue
+        }
+        return false
+    }
+
+    private static func encodeAppSnapshotRequestPayload(
+        _ request: WatchAppSnapshotRequestMessage) -> [String: Any]
+    {
+        var payload: [String: Any] = [
+            "type": WatchPayloadType.appSnapshotRequest.rawValue,
+            "requestId": request.requestId,
+        ]
+        if let sentAtMs = request.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        return payload
+    }
+
+    private static func encodeAppCommandPayload(_ message: WatchAppCommandMessage) -> [String: Any] {
+        var payload: [String: Any] = [
+            "type": WatchPayloadType.appCommand.rawValue,
+            "command": message.command.rawValue,
+            "commandId": message.commandId,
+        ]
+        if let sessionKey = message.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !sessionKey.isEmpty
+        {
+            payload["sessionKey"] = sessionKey
+        }
+        if let gatewayStableID = message.gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !gatewayStableID.isEmpty
+        {
+            payload["gatewayStableID"] = gatewayStableID
+        }
+        if let text = message.text?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !text.isEmpty
+        {
+            payload["text"] = text
+        }
+        if let sentAtMs = message.sentAtMs {
+            payload["sentAtMs"] = sentAtMs
+        }
+        return payload
+    }
+
     private static func encodeSnapshotRequestPayload(
         _ request: WatchExecApprovalSnapshotRequestMessage) -> [String: Any]
     {
@@ -395,10 +538,15 @@ final class WatchConnectivityReceiver: NSObject, @unchecked Sendable {
 
 extension WatchConnectivityReceiver: WCSessionDelegate {
     func session(
-        _: WCSession,
-        activationDidCompleteWith _: WCSessionActivationState,
+        _ session: WCSession,
+        activationDidCompleteWith activationState: WCSessionActivationState,
         error _: (any Error)?)
     {
+        if activationState == .activated, !session.receivedApplicationContext.isEmpty {
+            self.consumeIncomingPayload(
+                session.receivedApplicationContext,
+                transport: "receivedApplicationContext")
+        }
         Task {
             await self.requestExecApprovalSnapshot()
         }
@@ -454,6 +602,12 @@ extension WatchConnectivityReceiver: WCSessionDelegate {
             Task { @MainActor in
                 self.store.consume(execApprovalSnapshot: snapshot, transport: transport)
             }
+            return
+        }
+        if let snapshot = Self.parseAppSnapshotPayload(payload) {
+            Task { @MainActor in
+                self.store.consume(appSnapshot: snapshot)
+            }
         }
     }
 }

apps/ios/WatchExtension/Sources/WatchInboxStore.swift

@@ -6,6 +6,9 @@ import WatchKit
 enum WatchPayloadType: String, Codable, Equatable {
     case notify = "watch.notify"
     case reply = "watch.reply"
+    case appSnapshot = "watch.app.snapshot"
+    case appSnapshotRequest = "watch.app.snapshotRequest"
+    case appCommand = "watch.app.command"
     case execApprovalPrompt = "watch.execApproval.prompt"
     case execApprovalResolve = "watch.execApproval.resolve"
     case execApprovalResolved = "watch.execApproval.resolved"
@@ -83,6 +86,54 @@ struct WatchExecApprovalResolveMessage: Codable, Equatable {
     var sentAtMs: Int?
 }
 
+struct WatchAppSnapshotMessage: Codable, Equatable {
+    var gatewayStatusText: String
+    var gatewayConnected: Bool
+    var agentName: String
+    var agentAvatarURL: String?
+    var agentAvatarText: String?
+    var sessionKey: String
+    var gatewayStableID: String?
+    var talkStatusText: String
+    var talkEnabled: Bool
+    var talkListening: Bool
+    var talkSpeaking: Bool
+    var pendingApprovalCount: Int
+    var chatItems: [WatchChatItem]?
+    var chatStatusText: String?
+    var sentAtMs: Int?
+    var snapshotId: String?
+}
+
+struct WatchChatItem: Codable, Equatable, Identifiable {
+    var id: String
+    var role: String
+    var text: String
+    var timestampMs: Int?
+}
+
+struct WatchAppSnapshotRequestMessage: Codable, Equatable {
+    var requestId: String
+    var sentAtMs: Int?
+}
+
+enum WatchAppCommand: String, Codable, Equatable {
+    case refresh
+    case openChat = "open-chat"
+    case sendChat = "send-chat"
+    case startTalk = "start-talk"
+    case stopTalk = "stop-talk"
+}
+
+struct WatchAppCommandMessage: Codable, Equatable {
+    var command: WatchAppCommand
+    var commandId: String
+    var sessionKey: String?
+    var gatewayStableID: String?
+    var text: String?
+    var sentAtMs: Int?
+}
+
 struct WatchPromptAction: Codable, Equatable, Identifiable {
     var id: String
     var label: String
@@ -138,6 +189,10 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         var lastExecApprovalSnapshotID: String?
         var lastExecApprovalOutcomeText: String?
         var lastExecApprovalOutcomeAt: Date?
+        var appSnapshot: WatchAppSnapshotMessage?
+        var appSnapshotUpdatedAt: Date?
+        var appSnapshotStatusText: String?
+        var appCommandStatusText: String?
     }
 
     private static let persistedStateKey = "watch.inbox.state.v2"
@@ -163,6 +218,11 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
     var selectedExecApprovalID: String?
     var lastExecApprovalOutcomeText: String?
     var lastExecApprovalOutcomeAt: Date?
+    var appSnapshot: WatchAppSnapshotMessage?
+    var appSnapshotUpdatedAt: Date?
+    var appSnapshotStatusText: String?
+    var appCommandStatusText: String?
+    var greetingTextOverride: String?
     var isExecApprovalReviewLoading = false
     var execApprovalReviewStatusText: String?
     var execApprovalReviewStatusAt: Date?
@@ -197,7 +257,7 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
 
     var activeExecApproval: WatchExecApprovalRecord? {
         if let selectedExecApprovalID,
-           let selected = self.execApprovals.first(where: { $0.id == selectedExecApprovalID })
+           let selected = execApprovals.first(where: { $0.id == selectedExecApprovalID })
         {
             return selected
         }
@@ -220,6 +280,35 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         self.execApprovals.isEmpty && !(self.execApprovalReviewStatusText?.isEmpty ?? true)
     }
 
+    var hasAppSnapshot: Bool {
+        self.appSnapshot != nil
+    }
+
+    var hasMessagePrompt: Bool {
+        self.title != Self.defaultTitle
+            || self.body != Self.defaultBody
+            || !self.actions.isEmpty
+    }
+
+    var gatewaySummaryText: String {
+        guard let appSnapshot else { return "Waiting for iPhone" }
+        return appSnapshot.gatewayConnected ? "Connected" : appSnapshot.gatewayStatusText
+    }
+
+    var talkSummaryText: String {
+        guard let appSnapshot else { return "Not synced" }
+        if appSnapshot.talkListening {
+            return "Listening"
+        }
+        if appSnapshot.talkSpeaking {
+            return "Speaking"
+        }
+        if appSnapshot.talkEnabled {
+            return appSnapshot.talkStatusText.isEmpty ? "Ready" : appSnapshot.talkStatusText
+        }
+        return "Off"
+    }
+
     func beginExecApprovalReviewLoading() {
         guard self.execApprovals.isEmpty else {
             self.markExecApprovalReviewLoaded()
@@ -312,12 +401,12 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         transport: String)
     {
         let snapshotID = message.snapshotId?.trimmingCharacters(in: .whitespacesAndNewlines)
-        if let snapshotID, !snapshotID.isEmpty, snapshotID == self.lastExecApprovalSnapshotID {
+        if let snapshotID, !snapshotID.isEmpty, snapshotID == lastExecApprovalSnapshotID {
             return
         }
 
         let existingRecordsByID = Dictionary(
-            uniqueKeysWithValues: self.execApprovals.map { ($0.id, $0) })
+            uniqueKeysWithValues: execApprovals.map { ($0.id, $0) })
         self.execApprovals = message.approvals.map { approval in
             self.mergedExecApprovalRecord(
                 approval: approval,
@@ -330,14 +419,90 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
            !self.execApprovals.contains(where: { $0.id == selectedExecApprovalID })
         {
             self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
-        } else if self.selectedExecApprovalID == nil {
-            self.selectedExecApprovalID = self.sortedExecApprovals.first?.id
+        } else if selectedExecApprovalID == nil {
+            selectedExecApprovalID = self.sortedExecApprovals.first?.id
         }
         self.pruneExpiredExecApprovals(nowMs: Self.nowMs())
         self.markExecApprovalReviewLoaded()
         self.persistState()
     }
 
+    func consume(appSnapshot message: WatchAppSnapshotMessage) {
+        let snapshotID = message.snapshotId?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let snapshotID, !snapshotID.isEmpty, snapshotID == appSnapshot?.snapshotId {
+            return
+        }
+        var merged = message
+        if merged.chatItems == nil {
+            merged.chatItems = self.appSnapshot?.chatItems
+        }
+        if merged.chatStatusText == nil {
+            merged.chatStatusText = self.appSnapshot?.chatStatusText
+        }
+        self.appSnapshot = merged
+        self.appSnapshotUpdatedAt = Date()
+        self.appSnapshotStatusText = nil
+        self.persistState()
+    }
+
+    func markAppSnapshotRequestStarted() {
+        self.appSnapshotStatusText = "Refreshing from iPhone…"
+        self.persistState()
+    }
+
+    func markAppSnapshotRequestResult(_ result: WatchReplySendResult) {
+        if let errorMessage = result.errorMessage, !errorMessage.isEmpty {
+            self.appSnapshotStatusText = "Refresh failed: \(errorMessage)"
+        } else if result.deliveredImmediately {
+            self.appSnapshotStatusText = "Refresh requested"
+        } else if result.queuedForDelivery {
+            self.appSnapshotStatusText = "Refresh queued"
+        } else {
+            self.appSnapshotStatusText = nil
+        }
+        self.persistState()
+    }
+
+    func makeAppCommand(_ command: WatchAppCommand, text: String? = nil) -> WatchAppCommandMessage {
+        let snapshotSessionKey = self.appSnapshot?.sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        return WatchAppCommandMessage(
+            command: command,
+            commandId: UUID().uuidString,
+            sessionKey: (snapshotSessionKey?.isEmpty == false) ? snapshotSessionKey : self.sessionKey,
+            gatewayStableID: self.appSnapshot?.gatewayStableID,
+            text: text,
+            sentAtMs: Self.nowMs())
+    }
+
+    var hasGatewayTaggedAppSnapshot: Bool {
+        let gatewayStableID = self.appSnapshot?.gatewayStableID?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return !gatewayStableID.isEmpty
+    }
+
+    func markAppCommandSending(_ command: WatchAppCommand) {
+        self.appCommandStatusText = "Sending \(Self.commandLabel(command))…"
+        self.persistState()
+    }
+
+    func markAppCommandBlocked(_ command: WatchAppCommand, reason: String) {
+        self.appCommandStatusText = "\(Self.commandLabel(command)): \(reason)"
+        self.persistState()
+    }
+
+    func markAppCommandResult(_ result: WatchReplySendResult, command: WatchAppCommand) {
+        let label = Self.commandLabel(command)
+        if let errorMessage = result.errorMessage, !errorMessage.isEmpty {
+            self.appCommandStatusText = "\(label) failed: \(errorMessage)"
+        } else if result.deliveredImmediately {
+            self.appCommandStatusText = "\(label): sent"
+        } else if result.queuedForDelivery {
+            self.appCommandStatusText = "\(label): queued"
+        } else {
+            self.appCommandStatusText = "\(label): sent"
+        }
+        self.persistState()
+    }
+
     func consume(execApprovalResolved message: WatchExecApprovalResolvedMessage) {
         self.removeExecApproval(id: message.approvalId)
         let statusText = switch message.decision {
@@ -381,7 +546,7 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
     }
 
     func markExecApprovalSending(approvalId: String, decision: WatchExecApprovalDecision) {
-        guard let index = self.execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
+        guard let index = execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
         self.execApprovals[index].isResolving = true
         self.execApprovals[index].pendingDecision = decision
         self.execApprovals[index].statusText = "Sending \(Self.decisionLabel(decision))…"
@@ -394,7 +559,7 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         decision: WatchExecApprovalDecision,
         result: WatchReplySendResult)
     {
-        guard let index = self.execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
+        guard let index = execApprovals.firstIndex(where: { $0.id == approvalId }) else { return }
         if let errorMessage = result.errorMessage, !errorMessage.isEmpty {
             self.execApprovals[index].isResolving = false
             self.execApprovals[index].statusText = "Failed: \(errorMessage)"
@@ -419,7 +584,7 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         keepSelectionIfPossible: Bool,
         resetResolvingState: Bool = false)
     {
-        if let index = self.execApprovals.firstIndex(where: { $0.id == approval.id }) {
+        if let index = execApprovals.firstIndex(where: { $0.id == approval.id }) {
             self.execApprovals[index] = self.mergedExecApprovalRecord(
                 approval: approval,
                 transport: transport,
@@ -486,7 +651,7 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
     }
 
     private func restorePersistedState() {
-        guard let data = self.defaults.data(forKey: Self.persistedStateKey),
+        guard let data = defaults.data(forKey: Self.persistedStateKey),
               let state = try? JSONDecoder().decode(PersistedState.self, from: data)
         else {
             return
@@ -511,30 +676,38 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         self.lastExecApprovalSnapshotID = state.lastExecApprovalSnapshotID
         self.lastExecApprovalOutcomeText = state.lastExecApprovalOutcomeText
         self.lastExecApprovalOutcomeAt = state.lastExecApprovalOutcomeAt
+        self.appSnapshot = state.appSnapshot
+        self.appSnapshotUpdatedAt = state.appSnapshotUpdatedAt
+        self.appSnapshotStatusText = state.appSnapshotStatusText
+        self.appCommandStatusText = state.appCommandStatusText
     }
 
     private func persistState() {
         let updatedAt = self.updatedAt ?? self.lastExecApprovalOutcomeAt ?? Date()
         let state = PersistedState(
-            title: self.title,
-            body: self.body,
-            transport: self.transport,
+            title: title,
+            body: body,
+            transport: transport,
             updatedAt: updatedAt,
-            lastDeliveryKey: self.lastDeliveryKey,
-            promptId: self.promptId,
-            sessionKey: self.sessionKey,
-            kind: self.kind,
-            details: self.details,
-            expiresAtMs: self.expiresAtMs,
-            risk: self.risk,
-            actions: self.actions,
-            replyStatusText: self.replyStatusText,
-            replyStatusAt: self.replyStatusAt,
-            execApprovals: self.execApprovals,
-            selectedExecApprovalID: self.selectedExecApprovalID,
-            lastExecApprovalSnapshotID: self.lastExecApprovalSnapshotID,
-            lastExecApprovalOutcomeText: self.lastExecApprovalOutcomeText,
-            lastExecApprovalOutcomeAt: self.lastExecApprovalOutcomeAt)
+            lastDeliveryKey: lastDeliveryKey,
+            promptId: promptId,
+            sessionKey: sessionKey,
+            kind: kind,
+            details: details,
+            expiresAtMs: expiresAtMs,
+            risk: risk,
+            actions: actions,
+            replyStatusText: replyStatusText,
+            replyStatusAt: replyStatusAt,
+            execApprovals: execApprovals,
+            selectedExecApprovalID: selectedExecApprovalID,
+            lastExecApprovalSnapshotID: lastExecApprovalSnapshotID,
+            lastExecApprovalOutcomeText: lastExecApprovalOutcomeText,
+            lastExecApprovalOutcomeAt: lastExecApprovalOutcomeAt,
+            appSnapshot: appSnapshot,
+            appSnapshotUpdatedAt: appSnapshotUpdatedAt,
+            appSnapshotStatusText: appSnapshotStatusText,
+            appCommandStatusText: appCommandStatusText)
         guard let data = try? JSONEncoder().encode(state) else { return }
         self.defaults.set(data, forKey: Self.persistedStateKey)
     }
@@ -627,6 +800,21 @@ struct WatchExecApprovalRecord: Codable, Equatable, Identifiable {
         }
     }
 
+    private static func commandLabel(_ command: WatchAppCommand) -> String {
+        switch command {
+        case .refresh:
+            "Refresh"
+        case .openChat:
+            "Open Chat"
+        case .sendChat:
+            "Chat"
+        case .startTalk:
+            "Start Talk"
+        case .stopTalk:
+            "Stop Talk"
+        }
+    }
+
     private static func nowMs() -> Int {
         Int(Date().timeIntervalSince1970 * 1000)
     }

apps/ios/fastlane/.env.example

@@ -1,17 +1,26 @@
 # App Store Connect API key (pick one approach)
 #
 # Recommended (use the downloaded .p8 directly):
-# ASC_KEY_ID=XXXXXXXXXX
-# ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-# ASC_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
+# APP_STORE_CONNECT_KEY_ID=XXXXXXXXXX
+# APP_STORE_CONNECT_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+# APP_STORE_CONNECT_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 #
 # Or (JSON key file):
 # APP_STORE_CONNECT_API_KEY_PATH=/absolute/path/to/AuthKey_XXXXXX.json
 #
 # Or:
-# ASC_KEY_ID=XXXXXXXXXX
-# ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-# ASC_KEY_CONTENT=BASE64_P8_CONTENT
+# APP_STORE_CONNECT_KEY_ID=XXXXXXXXXX
+# APP_STORE_CONNECT_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+# APP_STORE_CONNECT_KEY_CONTENT=BASE64_P8_CONTENT
+#
+# Or (macOS Keychain, recommended for maintainer machines):
+# APP_STORE_CONNECT_KEY_ID=XXXXXXXXXX
+# APP_STORE_CONNECT_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+# APP_STORE_CONNECT_KEYCHAIN_SERVICE=openclaw-app-store-connect-key
+# APP_STORE_CONNECT_KEYCHAIN_ACCOUNT=your-macos-user
+
+# Fastlane match signing repo encryption
+# MATCH_PASSWORD=...
 
 # Code signing
 # IOS_DEVELOPMENT_TEAM=XXXXXXXXXX

apps/ios/fastlane/Appfile

@@ -4,12 +4,14 @@ app_identifier("ai.openclawfoundation.app")
 # Provide either:
 # - APP_STORE_CONNECT_API_KEY_PATH=/path/to/AuthKey_XXXXXX.p8.json (recommended)
 # or:
-# - ASC_KEY_PATH=/path/to/AuthKey_XXXXXX.p8 with ASC_KEY_ID and ASC_ISSUER_ID
-# - ASC_KEY_ID, ASC_ISSUER_ID, and ASC_KEY_CONTENT (base64 or raw p8 content)
-# - ASC_KEY_ID and ASC_ISSUER_ID plus Keychain fallback:
-#   ASC_KEYCHAIN_SERVICE (default: openclaw-asc-key)
-#   ASC_KEYCHAIN_ACCOUNT (default: USER/LOGNAME)
+# - APP_STORE_CONNECT_KEY_PATH=/path/to/AuthKey_XXXXXX.p8 with
+#   APP_STORE_CONNECT_KEY_ID and APP_STORE_CONNECT_ISSUER_ID
+# - APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_ISSUER_ID, and
+#   APP_STORE_CONNECT_KEY_CONTENT (base64 or raw p8 content)
+# - APP_STORE_CONNECT_KEY_ID and APP_STORE_CONNECT_ISSUER_ID plus Keychain fallback:
+#   APP_STORE_CONNECT_KEYCHAIN_SERVICE (default: openclaw-app-store-connect-key)
+#   APP_STORE_CONNECT_KEYCHAIN_ACCOUNT (default: USER/LOGNAME)
 #
 # Optional deliver app lookup overrides:
-# - ASC_APP_IDENTIFIER (bundle ID)
-# - ASC_APP_ID (numeric App Store Connect app ID)
+# - APP_STORE_CONNECT_APP_IDENTIFIER (bundle ID)
+# - APP_STORE_CONNECT_APP_ID (numeric App Store Connect app ID)

apps/ios/fastlane/Fastfile

@@ -9,6 +9,7 @@ require "cgi"
 default_platform(:ios)
 
 APP_STORE_APP_IDENTIFIER = "ai.openclawfoundation.app"
+DEFAULT_APP_STORE_CONNECT_KEYCHAIN_SERVICE = "openclaw-app-store-connect-key"
 DEFAULT_SNAPSHOT_DEVICES = ["iPhone 16 Pro Max", "iPad Pro 13-inch (M4)"].freeze
 DEFAULT_WATCH_SNAPSHOT_DEVICE = "Apple Watch Ultra 3 (49mm)"
 WATCH_SCREENSHOT_MODE_DEFAULTS_KEY = "openclaw.watch.screenshotMode"
@@ -18,6 +19,17 @@ REQUIRED_SCREENSHOT_FAMILIES = {
   "iPhone" => /iPhone/,
   "13-inch iPad" => /iPad (Air|Pro) 13-inch/
 }.freeze
+PUBLIC_METADATA_FILENAMES = [
+  "description.txt",
+  "keywords.txt",
+  "marketing_url.txt",
+  "name.txt",
+  "privacy_url.txt",
+  "promotional_text.txt",
+  "release_notes.txt",
+  "subtitle.txt",
+  "support_url.txt"
+].freeze
 
 def load_env_file(path)
   return unless File.exist?(path)
@@ -273,7 +285,7 @@ def capture_watch_screenshot
   device_name = device.fetch("name")
   udid = device.fetch("udid")
   output_dir = File.join(ios_root, "fastlane", "screenshots", "en-US")
-  output_path = File.join(output_dir, "#{device_name}-01-quick-reply.png")
+  output_path = File.join(output_dir, "#{device_name}-01-now-face.png")
   derived_data_path = File.join(ios_root, "build", "WatchScreenshotDerivedData")
   app_path = File.join(derived_data_path, "Build", "Products", "Debug-watchsimulator", "OpenClawWatchApp.app")
 
@@ -349,7 +361,7 @@ def maybe_decode_hex_keychain_secret(value)
     beginPemMarker = %w[BEGIN PRIVATE KEY].join(" ") # pragma: allowlist secret
     endPemMarker = %w[END PRIVATE KEY].join(" ")
     if decoded.include?(beginPemMarker) || decoded.include?(endPemMarker)
-      UI.message("Decoded hex-encoded ASC key content from Keychain.")
+      UI.message("Decoded hex-encoded App Store Connect key content from Keychain.")
       return decoded
     end
   rescue StandardError
@@ -359,11 +371,11 @@ def maybe_decode_hex_keychain_secret(value)
   candidate
 end
 
-def read_asc_key_content_from_keychain
-  service = ENV["ASC_KEYCHAIN_SERVICE"]
-  service = "openclaw-asc-key" unless env_present?(service)
+def read_app_store_connect_key_content_from_keychain
+  service = ENV["APP_STORE_CONNECT_KEYCHAIN_SERVICE"]
+  service = DEFAULT_APP_STORE_CONNECT_KEYCHAIN_SERVICE unless env_present?(service)
 
-  account = ENV["ASC_KEYCHAIN_ACCOUNT"]
+  account = ENV["APP_STORE_CONNECT_KEYCHAIN_ACCOUNT"]
   account = ENV["USER"] unless env_present?(account)
   account = ENV["LOGNAME"] unless env_present?(account)
   return nil unless env_present?(account)
@@ -385,7 +397,7 @@ def read_asc_key_content_from_keychain
     key_content = maybe_decode_hex_keychain_secret(key_content)
     return nil unless env_present?(key_content)
 
-    UI.message("Loaded ASC key content from Keychain service '#{service}' (account '#{account}').")
+    UI.message("Loaded App Store Connect key content from Keychain service '#{service}' (account '#{account}').")
     key_content
   rescue Errno::ENOENT
     nil
@@ -423,8 +435,16 @@ def app_store_signing_manifest
   JSON.parse(File.read(File.join(ios_root, "Config", "AppStoreSigning.json")))
 end
 
+def app_store_signing_targets
+  app_store_signing_manifest.fetch("targets")
+end
+
+def app_store_bundle_identifiers
+  app_store_signing_targets.map { |target| target.fetch("bundleId") }
+end
+
 def app_store_provisioning_profiles
-  app_store_signing_manifest.fetch("targets").each_with_object({}) do |target, profiles|
+  app_store_signing_targets.each_with_object({}) do |target, profiles|
     profiles[target.fetch("bundleId")] = target.fetch("profileName")
   end
 end
@@ -467,8 +487,114 @@ def write_app_store_export_options(path)
   PLIST
 end
 
+def produce_services_for_target(target)
+  services = {}
+  if target.fetch("capabilities").include?("PUSH_NOTIFICATIONS")
+    services[:push_notification] = "on"
+  end
+  services
+end
+
+def ensure_release_bundle_ids!
+  manifest = app_store_signing_manifest
+  app_store_signing_targets.each do |target|
+    options = {
+      app_identifier: target.fetch("bundleId"),
+      app_name: target.fetch("displayName"),
+      skip_itc: true,
+      team_id: manifest.fetch("teamId")
+    }
+    services = produce_services_for_target(target)
+    options[:enable_services] = services unless services.empty?
+    produce(**options)
+    unless services.empty?
+      modify_services(
+        app_identifier: target.fetch("bundleId"),
+        services: services,
+        team_id: manifest.fetch("teamId")
+      )
+    end
+  end
+end
+
+def app_store_match_options(readonly:, target:, api_key:)
+  manifest = app_store_signing_manifest
+  options = {
+    type: manifest.fetch("profileType"),
+    app_identifier: target.fetch("bundleId"),
+    profile_name: target.fetch("profileName"),
+    git_url: manifest.fetch("signingRepo"),
+    git_branch: manifest.fetch("signingBranch"),
+    platform: "ios",
+    team_id: manifest.fetch("teamId"),
+    readonly: readonly
+  }
+  options[:api_key] = api_key if api_key
+  options
+end
+
+def validate_match_profile_mapping!(target)
+  bundle_id = target.fetch("bundleId")
+  expected_profile_name = target.fetch("profileName")
+  actual = lane_context[SharedValues::MATCH_PROVISIONING_PROFILE_MAPPING] || {}
+  actual_profile_name = actual[bundle_id]
+  return if actual_profile_name == expected_profile_name
+
+  UI.user_error!(
+    "Fastlane match did not resolve the pinned App Store profile for #{bundle_id}: expected #{expected_profile_name}, got #{actual_profile_name || "no match output"}"
+  )
+end
+
+def match_profile_env_key(target, suffix)
+  ["sigh", target.fetch("bundleId"), app_store_signing_manifest.fetch("profileType"), suffix].join("_")
+end
+
+def profile_plist_value(profile_path, key_path)
+  Tempfile.create(["openclaw-profile", ".plist"]) do |file|
+    stdout, stderr, status = Open3.capture3("security", "cms", "-D", "-i", profile_path)
+    unless status.success?
+      detail = stderr.to_s.strip
+      detail = stdout.to_s.strip if detail.empty?
+      UI.user_error!("Failed to decode provisioning profile #{profile_path}: #{detail}")
+    end
+
+    file.write(stdout)
+    file.flush
+    value, _plist_stderr, plist_status = Open3.capture3("/usr/libexec/PlistBuddy", "-c", "Print:#{key_path}", file.path)
+    return nil unless plist_status.success?
+
+    value.to_s.strip
+  end
+end
+
+def validate_match_profile_capabilities!(target)
+  capabilities = target.fetch("capabilities")
+  return if capabilities.empty?
+
+  profile_path = ENV[match_profile_env_key(target, "profile-path")]
+  UI.user_error!("Fastlane match did not expose an installed profile path for #{target.fetch("bundleId")}.") unless env_present?(profile_path)
+
+  if capabilities.include?("PUSH_NOTIFICATIONS")
+    aps_environment = profile_plist_value(profile_path, "Entitlements:aps-environment")
+    if aps_environment != "production"
+      UI.user_error!(
+        "Provisioning profile #{target.fetch("profileName")} for #{target.fetch("bundleId")} is missing production push entitlement; expected aps-environment=production, got #{aps_environment || "missing"}."
+      )
+    end
+  end
+end
+
+def sync_app_store_signing!(readonly:)
+  api_key = readonly ? nil : app_store_connect_api_key_config
+  app_store_signing_targets.each do |target|
+    match(**app_store_match_options(readonly: readonly, target: target, api_key: api_key))
+    validate_match_profile_mapping!(target)
+    validate_match_profile_capabilities!(target)
+  end
+end
+
 def release_signing_check!
-  sh(shell_join(["node", File.join(repo_root, "scripts", "ios-release-signing.mjs"), "--mode", "check"]))
+  sync_app_store_signing!(readonly: true)
 end
 
 def release_notes_path
@@ -486,6 +612,19 @@ def release_notes_metadata_path
   temp_root
 end
 
+def public_metadata_path
+  source = File.join(__dir__, "metadata")
+  temp_root = Dir.mktmpdir("openclaw-app-store-metadata")
+  Dir.children(source).each do |entry|
+    source_entry = File.join(source, entry)
+    next unless File.directory?(source_entry)
+    next unless PUBLIC_METADATA_FILENAMES.any? { |filename| File.exist?(File.join(source_entry, filename)) }
+
+    FileUtils.cp_r(source_entry, File.join(temp_root, entry))
+  end
+  temp_root
+end
+
 def read_ios_version_metadata
   script_path = File.join(repo_root, "scripts", "ios-version.ts")
   stdout, stderr, status = Open3.capture3(
@@ -563,7 +702,7 @@ def resolve_release_build_number(api_key:, short_version:)
   next_build.to_s
 end
 
-def release_build_number_needs_asc_auth?
+def release_build_number_needs_app_store_connect_auth?
   explicit = ENV["IOS_RELEASE_BUILD_NUMBER"]
   !env_present?(explicit)
 end
@@ -640,58 +779,58 @@ def build_app_store_release(context)
   }
 end
 
-platform :ios do
-  private_lane :asc_api_key do
-    load_env_file(File.join(__dir__, ".env"))
-    clear_empty_env_var("APP_STORE_CONNECT_API_KEY_PATH")
-    clear_empty_env_var("ASC_KEY_PATH")
-    clear_empty_env_var("ASC_KEY_CONTENT")
+def app_store_connect_api_key_config
+  load_env_file(File.join(__dir__, ".env"))
+  clear_empty_env_var("APP_STORE_CONNECT_API_KEY_PATH")
+  clear_empty_env_var("APP_STORE_CONNECT_KEY_PATH")
+  clear_empty_env_var("APP_STORE_CONNECT_KEY_CONTENT")
 
-    api_key = nil
+  api_key = nil
 
-    key_path = ENV["APP_STORE_CONNECT_API_KEY_PATH"]
-    if env_present?(key_path)
-      api_key = app_store_connect_api_key(path: key_path)
+  key_path = ENV["APP_STORE_CONNECT_API_KEY_PATH"]
+  if env_present?(key_path)
+    api_key = app_store_connect_api_key(path: key_path)
+  else
+    p8_path = ENV["APP_STORE_CONNECT_KEY_PATH"]
+    if env_present?(p8_path)
+      key_id = ENV["APP_STORE_CONNECT_KEY_ID"]
+      issuer_id = ENV["APP_STORE_CONNECT_ISSUER_ID"]
+      UI.user_error!("Missing APP_STORE_CONNECT_KEY_ID or APP_STORE_CONNECT_ISSUER_ID for APP_STORE_CONNECT_KEY_PATH auth.") if [key_id, issuer_id].any? { |v| !env_present?(v) }
+
+      api_key = app_store_connect_api_key(
+        key_id: key_id,
+        issuer_id: issuer_id,
+        key_filepath: p8_path
+      )
     else
-      p8_path = ENV["ASC_KEY_PATH"]
-      if env_present?(p8_path)
-        key_id = ENV["ASC_KEY_ID"]
-        issuer_id = ENV["ASC_ISSUER_ID"]
-        UI.user_error!("Missing ASC_KEY_ID or ASC_ISSUER_ID for ASC_KEY_PATH auth.") if [key_id, issuer_id].any? { |v| !env_present?(v) }
+      key_id = ENV["APP_STORE_CONNECT_KEY_ID"]
+      issuer_id = ENV["APP_STORE_CONNECT_ISSUER_ID"]
+      key_content = ENV["APP_STORE_CONNECT_KEY_CONTENT"]
+      key_content = read_app_store_connect_key_content_from_keychain unless env_present?(key_content)
 
-        api_key = app_store_connect_api_key(
-          key_id: key_id,
-          issuer_id: issuer_id,
-          key_filepath: p8_path
-        )
-      else
-        key_id = ENV["ASC_KEY_ID"]
-        issuer_id = ENV["ASC_ISSUER_ID"]
-        key_content = ENV["ASC_KEY_CONTENT"]
-        key_content = read_asc_key_content_from_keychain unless env_present?(key_content)
+      UI.user_error!(
+        "Missing App Store Connect API key. Set APP_STORE_CONNECT_API_KEY_PATH (json), APP_STORE_CONNECT_KEY_PATH (p8), or APP_STORE_CONNECT_KEY_ID/APP_STORE_CONNECT_ISSUER_ID with APP_STORE_CONNECT_KEY_CONTENT (or Keychain via APP_STORE_CONNECT_KEYCHAIN_SERVICE/APP_STORE_CONNECT_KEYCHAIN_ACCOUNT)."
+      ) if [key_id, issuer_id, key_content].any? { |v| !env_present?(v) }
 
-        UI.user_error!(
-          "Missing App Store Connect API key. Set APP_STORE_CONNECT_API_KEY_PATH (json), ASC_KEY_PATH (p8), or ASC_KEY_ID/ASC_ISSUER_ID with ASC_KEY_CONTENT (or Keychain via ASC_KEYCHAIN_SERVICE/ASC_KEYCHAIN_ACCOUNT)."
-        ) if [key_id, issuer_id, key_content].any? { |v| !env_present?(v) }
+      is_base64 = key_content.include?("BEGIN PRIVATE KEY") ? false : true
 
-        is_base64 = key_content.include?("BEGIN PRIVATE KEY") ? false : true
-
-        api_key = app_store_connect_api_key(
-          key_id: key_id,
-          issuer_id: issuer_id,
-          key_content: key_content,
-          is_key_content_base64: is_base64
-        )
-      end
+      api_key = app_store_connect_api_key(
+        key_id: key_id,
+        issuer_id: issuer_id,
+        key_content: key_content,
+        is_key_content_base64: is_base64
+      )
     end
-
-    api_key
   end
 
+  api_key
+end
+
+platform :ios do
   private_lane :prepare_app_store_context do |options|
     require_api_key = options[:require_api_key] == true
-    needs_api_key = require_api_key || release_build_number_needs_asc_auth?
-    api_key = needs_api_key ? asc_api_key : nil
+    needs_api_key = require_api_key || release_build_number_needs_app_store_connect_auth?
+    api_key = needs_api_key ? app_store_connect_api_key_config : nil
     sync_ios_versioning!
     version_metadata = read_ios_version_metadata
     version = version_metadata[:version]
@@ -708,6 +847,37 @@ platform :ios do
     }
   end
 
+  desc "Print the App Store signing plan"
+  lane :signing_plan do
+    sh(shell_join(["node", File.join(repo_root, "scripts", "ios-release-signing.mjs"), "--mode", "plan"]))
+  end
+
+  desc "Check local App Store signing assets through Fastlane match"
+  lane :signing_check do
+    sync_app_store_signing!(readonly: true)
+    UI.success("Fastlane match App Store signing assets are available locally.")
+  end
+
+  desc "Create Developer Portal bundle IDs/services and sync App Store signing assets"
+  lane :signing_setup do
+    ensure_release_bundle_ids!
+    sync_app_store_signing!(readonly: false)
+    UI.success("Fastlane App Store signing setup is complete.")
+  end
+
+  desc "Pull encrypted App Store signing assets from the shared Fastlane match repo"
+  lane :signing_sync_pull do
+    sync_app_store_signing!(readonly: true)
+    UI.success("Pulled Fastlane match App Store signing assets.")
+  end
+
+  desc "Create or refresh encrypted App Store signing assets in the shared Fastlane match repo"
+  lane :signing_sync_push do
+    ensure_release_bundle_ids!
+    sync_app_store_signing!(readonly: false)
+    UI.success("Pushed Fastlane match App Store signing assets.")
+  end
+
   desc "Build an App Store distribution archive locally without uploading"
   lane :app_store_archive do
     context = prepare_app_store_context(require_api_key: false)
@@ -765,10 +935,10 @@ platform :ios do
   lane :metadata do
     sync_ios_versioning!
     version_metadata = read_ios_version_metadata
-    api_key = asc_api_key
+    api_key = app_store_connect_api_key_config
     clear_empty_env_var("APP_STORE_CONNECT_API_KEY_PATH")
-    app_identifier = ENV["ASC_APP_IDENTIFIER"]
-    app_id = ENV["ASC_APP_ID"]
+    app_identifier = ENV["APP_STORE_CONNECT_APP_IDENTIFIER"]
+    app_id = ENV["APP_STORE_CONNECT_APP_ID"]
     app_identifier = nil unless env_present?(app_identifier)
     app_id = nil unless env_present?(app_id)
 
@@ -780,7 +950,7 @@ platform :ios do
       validate_required_screenshots!(paths)
     end
 
-    metadata_path = File.join(__dir__, "metadata")
+    metadata_path = public_metadata_path
     skip_metadata = ENV["DELIVER_METADATA"] != "1"
     if release_notes_upload_requested? && skip_metadata
       metadata_path = release_notes_metadata_path
@@ -849,7 +1019,7 @@ platform :ios do
 
   desc "Validate App Store Connect API auth"
   lane :auth_check do
-    asc_api_key
+    app_store_connect_api_key_config
     UI.success("App Store Connect API auth loaded successfully.")
   end
 end

apps/ios/fastlane/SETUP.md

@@ -14,7 +14,7 @@ Create an App Store Connect API key:
 Recommended (macOS): store the private key in Keychain and write non-secret vars:
 
 ```bash
-scripts/ios-asc-keychain-setup.sh \
+scripts/ios-app-store-connect-keychain-setup.sh \
   --key-path /absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
   --issuer-id YOUR_ISSUER_ID \
   --write-env
@@ -23,10 +23,10 @@ scripts/ios-asc-keychain-setup.sh \
 This writes these auth variables in `apps/ios/fastlane/.env`:
 
 ```bash
-ASC_KEY_ID=YOUR_KEY_ID
-ASC_ISSUER_ID=YOUR_ISSUER_ID
-ASC_KEYCHAIN_SERVICE=openclaw-asc-key
-ASC_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
+APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID
+APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID
+APP_STORE_CONNECT_KEYCHAIN_SERVICE=openclaw-app-store-connect-key
+APP_STORE_CONNECT_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
 ```
 
 Important: `apps/ios/fastlane/.env` is only for Fastlane/App Store Connect auth and optional release-archive settings. It does **not** configure gateway-side direct APNs push delivery for local iOS builds.
@@ -34,17 +34,17 @@ Important: `apps/ios/fastlane/.env` is only for Fastlane/App Store Connect auth
 Optional app targeting variables (helpful if Fastlane cannot auto-resolve app by bundle):
 
 ```bash
-ASC_APP_IDENTIFIER=ai.openclawfoundation.app
+APP_STORE_CONNECT_APP_IDENTIFIER=ai.openclawfoundation.app
 # or
-ASC_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID
+APP_STORE_CONNECT_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID
 ```
 
 File-based fallback (CI/non-macOS):
 
 ```bash
-ASC_KEY_ID=YOUR_KEY_ID
-ASC_ISSUER_ID=YOUR_ISSUER_ID
-ASC_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
+APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID
+APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID
+APP_STORE_CONNECT_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 ```
 
 Code signing variable (optional in `.env`):
@@ -55,7 +55,7 @@ IOS_DEVELOPMENT_TEAM=YOUR_TEAM_ID
 
 Tip: run `scripts/ios-team-id.sh --require-canonical` from repo root to verify the canonical OpenClaw iOS team (`FWJYW4S8P8`) is available locally. Fastlane uses the same canonical-only path when `IOS_DEVELOPMENT_TEAM` is missing, and rejects non-canonical teams for release archives.
 
-App Store release signing is manual and profile-pinned. The canonical manifest is `apps/ios/Config/AppStoreSigning.json`.
+App Store release signing is manual and profile-pinned. The canonical manifest is `apps/ios/Config/AppStoreSigning.json`, and Fastlane `match` owns the encrypted signing repo and branch named there.
 
 One-time or rotation setup:
 
@@ -65,14 +65,16 @@ pnpm ios:release:signing:check
 pnpm ios:release:signing:setup
 ```
 
+`signing:setup` uses Fastlane `produce` and `modify_services` to create Developer Portal bundle IDs and enable required services before running `match`. If Fastlane does not already have a valid Apple Developer Portal session, run `fastlane spaceauth` for a release-owner Apple ID and export the resulting `FASTLANE_SESSION`.
+
 Shared encrypted signing storage:
 
 ```bash
-ASC_MATCH_PASSWORD=... pnpm ios:release:signing:sync:push
-ASC_MATCH_PASSWORD=... pnpm ios:release:signing:sync:pull
+MATCH_PASSWORD=... pnpm ios:release:signing:sync:push
+MATCH_PASSWORD=... pnpm ios:release:signing:sync:pull
 ```
 
-The signing repo is private and encrypted. Store `ASC_MATCH_PASSWORD` in the release-owner vault, not in this product repo. `sync:pull` writes decrypted assets under `apps/ios/build/signing/`; import the distribution certificate/private key into Keychain before archiving.
+The signing repo is private and encrypted. Store `MATCH_PASSWORD` in the release-owner vault, not in this product repo. `sync:pull` uses Fastlane `match` to decrypt, install profiles, and import the distribution signing identity into the local Keychain.
 
 For local/manual iOS builds that stay on direct APNs, configure the gateway host separately with `OPENCLAW_APNS_TEAM_ID`, `OPENCLAW_APNS_KEY_ID`, and either `OPENCLAW_APNS_PRIVATE_KEY_P8` or `OPENCLAW_APNS_PRIVATE_KEY_PATH`. Those gateway runtime env vars are separate from Fastlane's `.env`.
 
@@ -83,12 +85,12 @@ cd apps/ios
 fastlane ios auth_check
 ```
 
-ASC auth is only required when:
+App Store Connect API auth is required when:
 
 - uploading to App Store Connect
 - auto-resolving the next build number from App Store Connect
 
-If you pass `--build-number` to `pnpm ios:release:archive`, the local archive path does not need ASC auth.
+If you pass `--build-number` to `pnpm ios:release:archive`, the local archive path does not need App Store Connect API auth.
 
 Archive locally without upload:
 
@@ -119,14 +121,14 @@ fastlane ios release_upload
 
 Maintainer recovery path for a fresh clone on the same Mac:
 
-1. Reuse the existing Keychain-backed ASC key on that machine.
+1. Reuse the existing Keychain-backed App Store Connect key on that machine.
 2. Restore or recreate `apps/ios/fastlane/.env` so it contains the non-secret variables:
 
 ```bash
-ASC_KEY_ID=YOUR_KEY_ID
-ASC_ISSUER_ID=YOUR_ISSUER_ID
-ASC_KEYCHAIN_SERVICE=openclaw-asc-key
-ASC_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
+APP_STORE_CONNECT_KEY_ID=YOUR_KEY_ID
+APP_STORE_CONNECT_ISSUER_ID=YOUR_ISSUER_ID
+APP_STORE_CONNECT_KEYCHAIN_SERVICE=openclaw-app-store-connect-key
+APP_STORE_CONNECT_KEYCHAIN_ACCOUNT=YOUR_MAC_USERNAME
 ```
 
 3. Re-run auth validation:

apps/ios/fastlane/metadata/README.md

@@ -6,7 +6,7 @@ This directory is used by `fastlane deliver` for App Store Connect text metadata
 
 ```bash
 cd apps/ios
-ASC_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID \
+APP_STORE_CONNECT_APP_ID=YOUR_APP_STORE_CONNECT_APP_ID \
 DELIVER_METADATA=1 fastlane ios metadata
 ```
 
@@ -31,14 +31,14 @@ DELIVER_METADATA=1 DELIVER_SCREENSHOTS=1 fastlane ios metadata
 The `ios metadata` lane uses App Store Connect API key auth from `apps/ios/fastlane/.env`:
 
 - Keychain-backed (recommended on macOS):
-  - `ASC_KEY_ID`
-  - `ASC_ISSUER_ID`
-  - `ASC_KEYCHAIN_SERVICE` (default: `openclaw-asc-key`)
-  - `ASC_KEYCHAIN_ACCOUNT` (default: current user)
+  - `APP_STORE_CONNECT_KEY_ID`
+  - `APP_STORE_CONNECT_ISSUER_ID`
+  - `APP_STORE_CONNECT_KEYCHAIN_SERVICE` (default: `openclaw-app-store-connect-key`)
+  - `APP_STORE_CONNECT_KEYCHAIN_ACCOUNT` (default: current user)
 - File/path fallback:
-  - `ASC_KEY_ID`
-  - `ASC_ISSUER_ID`
-  - `ASC_KEY_PATH`
+  - `APP_STORE_CONNECT_KEY_ID`
+  - `APP_STORE_CONNECT_ISSUER_ID`
+  - `APP_STORE_CONNECT_KEY_PATH`
 
 Or set `APP_STORE_CONNECT_API_KEY_PATH`.
 
@@ -51,10 +51,6 @@ Or set `APP_STORE_CONNECT_API_KEY_PATH`.
 - The release upload flow uploads release notes and screenshots before the IPA, and never submits for App Review.
 - `privacy_url.txt` is set to `https://openclaw.ai/privacy`.
 - If app lookup fails in `deliver`, set one of:
-  - `ASC_APP_IDENTIFIER` (bundle ID)
-  - `ASC_APP_ID` (numeric App Store Connect app ID, e.g. from `/apps/<id>/...` URL)
-- For first app versions, include review contact files under `metadata/review_information/`:
-  - `first_name.txt`
-  - `last_name.txt`
-  - `email_address.txt`
-  - `phone_number.txt` (E.164-ish, e.g. `+1 415 555 0100`)
+  - `APP_STORE_CONNECT_APP_IDENTIFIER` (bundle ID)
+  - `APP_STORE_CONNECT_APP_ID` (numeric App Store Connect app ID, e.g. from `/apps/<id>/...` URL)
+- App Review submission is manual. Keep review contact, demo account, and reviewer notes outside this repo and enter them directly in App Store Connect when submitting for review.

apps/ios/fastlane/metadata/review_information/email_address.txt

@@ -1 +0,0 @@
-support@openclaw.ai

apps/ios/fastlane/metadata/review_information/last_name.txt

@@ -1 +0,0 @@
-Team

apps/ios/fastlane/metadata/review_information/notes.txt

@@ -1,3 +0,0 @@
-OpenClaw normally pairs with a private Gateway. For App Review, tap Set Up Manually on the Connect Gateway screen, paste APPLE-REVIEW-DEMO in Setup Code, then tap Apply Setup Code. This enables local offline demo mode; no Gateway is required. Reviewers can also scan a QR code containing APPLE-REVIEW-DEMO.
-
-Demo mode marks the app as connected to an Apple Review Demo Gateway and exposes the Chat, Command, Agent, Talk, and Settings surfaces without requiring a running Gateway. Live automation, realtime Talk execution, and external tool calls require pairing with a real OpenClaw Gateway.

apps/ios/fastlane/metadata/review_information/phone_number.txt

@@ -1 +0,0 @@
-+1 415 555 0100

apps/ios/project.yml

@@ -289,6 +289,7 @@ targets:
     deploymentTarget: "11.0"
     sources:
       - path: WatchExtension/Sources
+      - path: WatchExtension/Assets.xcassets
     dependencies:
       - sdk: AppIntents.framework
       - sdk: WatchConnectivity.framework

apps/macos/Sources/OpenClawMacCLI/EntryPoint.swift

@@ -1,41 +1,68 @@
 import Foundation
 
-private struct RootCommand {
+struct RootCommand: Equatable {
     var name: String
     var args: [String]
 }
 
+enum RootCommandAction: Equatable {
+    case usage
+    case connect([String])
+    case configureRemote([String])
+    case discover([String])
+    case wizard([String])
+    case unknown(exitCode: Int32)
+}
+
 @main
 struct OpenClawMacCLI {
     static func main() async {
         let args = Array(CommandLine.arguments.dropFirst())
-        let command = parseRootCommand(args)
-        switch command?.name {
-        case nil:
+        switch resolveRootCommandAction(args) {
+        case .usage:
             printUsage()
-        case "-h", "--help", "help":
-            printUsage()
-        case "connect":
-            await runConnect(command?.args ?? [])
-        case "configure-remote":
-            runConfigureRemote(command?.args ?? [])
-        case "discover":
-            await runDiscover(command?.args ?? [])
-        case "wizard":
-            await runWizardCommand(command?.args ?? [])
-        default:
+        case let .connect(commandArgs):
+            await runConnect(commandArgs)
+        case let .configureRemote(commandArgs):
+            runConfigureRemote(commandArgs)
+        case let .discover(commandArgs):
+            await runDiscover(commandArgs)
+        case let .wizard(commandArgs):
+            await runWizardCommand(commandArgs)
+        case let .unknown(exitCode):
             fputs("openclaw-mac: unknown command\n", stderr)
             printUsage()
-            exit(1)
+            exit(exitCode)
         }
     }
 }
 
-private func parseRootCommand(_ args: [String]) -> RootCommand? {
+func parseRootCommand(_ args: [String]) -> RootCommand? {
     guard let first = args.first else { return nil }
     return RootCommand(name: first, args: Array(args.dropFirst()))
 }
 
+func resolveRootCommandAction(_ args: [String]) -> RootCommandAction {
+    guard let command = parseRootCommand(args) else {
+        return .usage
+    }
+
+    switch command.name {
+    case "-h", "--help", "help":
+        return .usage
+    case "connect":
+        return .connect(command.args)
+    case "configure-remote":
+        return .configureRemote(command.args)
+    case "discover":
+        return .discover(command.args)
+    case "wizard":
+        return .wizard(command.args)
+    default:
+        return .unknown(exitCode: 1)
+    }
+}
+
 private func printUsage() {
     print("""
     openclaw-mac

apps/macos/Tests/OpenClawIPCTests/RootCommandParserTests.swift

@@ -0,0 +1,38 @@
+import Testing
+@testable import OpenClawMacCLI
+
+struct RootCommandParserTests {
+    @Test func `parse root command returns nil for empty args`() {
+        #expect(parseRootCommand([]) == nil)
+    }
+
+    @Test func `parse root command splits command name and args`() throws {
+        let command = try #require(parseRootCommand(["connect", "--json", "--timeout", "3000"]))
+
+        #expect(command.name == "connect")
+        #expect(command.args == ["--json", "--timeout", "3000"])
+    }
+
+    @Test func `help aliases resolve to usage`() {
+        for args in [[], ["-h"], ["--help"], ["help"]] {
+            #expect(resolveRootCommandAction(args) == .usage)
+        }
+    }
+
+    @Test func `known commands preserve trailing args`() {
+        #expect(resolveRootCommandAction(["connect", "--json"]) == .connect(["--json"]))
+        #expect(
+            resolveRootCommandAction(["configure-remote", "--ssh-target", "alice@example.com"])
+                == .configureRemote(["--ssh-target", "alice@example.com"]))
+        #expect(resolveRootCommandAction(["discover", "--include-local"]) == .discover(["--include-local"]))
+        #expect(resolveRootCommandAction(["wizard", "--mode", "local"]) == .wizard(["--mode", "local"]))
+    }
+
+    @Test func `unknown command resolves to nonzero exit action`() {
+        #expect(resolveRootCommandAction(["nope"]) == .unknown(exitCode: 1))
+    }
+
+    @Test func `command names remain case sensitive`() {
+        #expect(resolveRootCommandAction(["Connect"]) == .unknown(exitCode: 1))
+    }
+}

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

@@ -306,6 +306,15 @@
             "fps",
             "screenIndex"
           ]
+        },
+        "screen_snapshot": {
+          "label": "screen snapshot",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "screenIndex",
+            "maxWidth"
+          ]
         }
       }
     },

apps/shared/OpenClawKit/Sources/OpenClawKit/WatchCommands.swift

@@ -8,6 +8,9 @@ public enum OpenClawWatchCommand: String, Codable, Sendable {
 public enum OpenClawWatchPayloadType: String, Codable, Sendable, Equatable {
     case notify = "watch.notify"
     case reply = "watch.reply"
+    case appSnapshot = "watch.app.snapshot"
+    case appSnapshotRequest = "watch.app.snapshotRequest"
+    case appCommand = "watch.app.command"
     case execApprovalPrompt = "watch.execApproval.prompt"
     case execApprovalResolve = "watch.execApproval.resolve"
     case execApprovalResolved = "watch.execApproval.resolved"
@@ -192,6 +195,129 @@ public struct OpenClawWatchExecApprovalSnapshotRequestMessage: Codable, Sendable
     }
 }
 
+public struct OpenClawWatchChatItem: Codable, Sendable, Equatable, Identifiable {
+    public var id: String
+    public var role: String
+    public var text: String
+    public var timestampMs: Int?
+
+    public init(
+        id: String,
+        role: String,
+        text: String,
+        timestampMs: Int? = nil)
+    {
+        self.id = id
+        self.role = role
+        self.text = text
+        self.timestampMs = timestampMs
+    }
+}
+
+public struct OpenClawWatchAppSnapshotMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var gatewayStatusText: String
+    public var gatewayConnected: Bool
+    public var agentName: String
+    public var agentAvatarURL: String?
+    public var agentAvatarText: String?
+    public var sessionKey: String
+    public var gatewayStableID: String?
+    public var talkStatusText: String
+    public var talkEnabled: Bool
+    public var talkListening: Bool
+    public var talkSpeaking: Bool
+    public var pendingApprovalCount: Int
+    public var chatItems: [OpenClawWatchChatItem]?
+    public var chatStatusText: String?
+    public var sentAtMs: Int?
+    public var snapshotId: String?
+
+    public init(
+        gatewayStatusText: String,
+        gatewayConnected: Bool,
+        agentName: String,
+        agentAvatarURL: String? = nil,
+        agentAvatarText: String? = nil,
+        sessionKey: String,
+        gatewayStableID: String? = nil,
+        talkStatusText: String,
+        talkEnabled: Bool,
+        talkListening: Bool,
+        talkSpeaking: Bool,
+        pendingApprovalCount: Int,
+        chatItems: [OpenClawWatchChatItem]? = nil,
+        chatStatusText: String? = nil,
+        sentAtMs: Int? = nil,
+        snapshotId: String? = nil)
+    {
+        self.type = .appSnapshot
+        self.gatewayStatusText = gatewayStatusText
+        self.gatewayConnected = gatewayConnected
+        self.agentName = agentName
+        self.agentAvatarURL = agentAvatarURL
+        self.agentAvatarText = agentAvatarText
+        self.sessionKey = sessionKey
+        self.gatewayStableID = gatewayStableID
+        self.talkStatusText = talkStatusText
+        self.talkEnabled = talkEnabled
+        self.talkListening = talkListening
+        self.talkSpeaking = talkSpeaking
+        self.pendingApprovalCount = pendingApprovalCount
+        self.chatItems = chatItems
+        self.chatStatusText = chatStatusText
+        self.sentAtMs = sentAtMs
+        self.snapshotId = snapshotId
+    }
+}
+
+public struct OpenClawWatchAppSnapshotRequestMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var requestId: String
+    public var sentAtMs: Int?
+
+    public init(requestId: String, sentAtMs: Int? = nil) {
+        self.type = .appSnapshotRequest
+        self.requestId = requestId
+        self.sentAtMs = sentAtMs
+    }
+}
+
+public enum OpenClawWatchAppCommand: String, Codable, Sendable, Equatable {
+    case refresh
+    case openChat = "open-chat"
+    case sendChat = "send-chat"
+    case startTalk = "start-talk"
+    case stopTalk = "stop-talk"
+}
+
+public struct OpenClawWatchAppCommandMessage: Codable, Sendable, Equatable {
+    public var type: OpenClawWatchPayloadType
+    public var command: OpenClawWatchAppCommand
+    public var commandId: String
+    public var sessionKey: String?
+    public var gatewayStableID: String?
+    public var text: String?
+    public var sentAtMs: Int?
+
+    public init(
+        command: OpenClawWatchAppCommand,
+        commandId: String,
+        sessionKey: String? = nil,
+        gatewayStableID: String? = nil,
+        text: String? = nil,
+        sentAtMs: Int? = nil)
+    {
+        self.type = .appCommand
+        self.command = command
+        self.commandId = commandId
+        self.sessionKey = sessionKey
+        self.gatewayStableID = gatewayStableID
+        self.text = text
+        self.sentAtMs = sentAtMs
+    }
+}
+
 public struct OpenClawWatchStatusPayload: Codable, Sendable, Equatable {
     public var supported: Bool
     public var paired: Bool

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

@@ -6156,6 +6156,7 @@ public struct CronListParams: Codable, Sendable {
     public let sortby: AnyCodable?
     public let sortdir: AnyCodable?
     public let agentid: String?
+    public let compact: Bool?
 
     public init(
         includedisabled: Bool?,
@@ -6167,7 +6168,8 @@ public struct CronListParams: Codable, Sendable {
         lastrunstatus: AnyCodable?,
         sortby: AnyCodable?,
         sortdir: AnyCodable?,
-        agentid: String? = nil)
+        agentid: String? = nil,
+        compact: Bool? = nil)
     {
         self.includedisabled = includedisabled
         self.limit = limit
@@ -6179,6 +6181,7 @@ public struct CronListParams: Codable, Sendable {
         self.sortby = sortby
         self.sortdir = sortdir
         self.agentid = agentid
+        self.compact = compact
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -6192,6 +6195,7 @@ public struct CronListParams: Codable, Sendable {
         case sortby = "sortBy"
         case sortdir = "sortDir"
         case agentid = "agentId"
+        case compact
     }
 }
 

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-0485ba902d2afd89d2c41cde7180d0cec2900b2db6804b9f97d42b7d85cd3af5  config-baseline.json
-72bb80be618406f3337eaa2560d2559a35e49bd29576de8dd4a3aec1a6a94d92  config-baseline.core.json
-1218f5555541b61bd5ddcac6441f15061b44789e2471d4ffecbe3059777c55c1  config-baseline.channel.json
-a14ac4261e98403d1a7e047070e6f151938444e27382b860315bd0c74fda4861  config-baseline.plugin.json
+b7ec57a4f38bf44677870fd9a8347be83f3f23a25a73d97931406f0eff572181  config-baseline.json
+99d506f05de601e5b45c98f302650c8608d1e2bb3dcea11bf97881c1263659ac  config-baseline.core.json
+2d735389858305509528e74329b6f8c65d311e1471c3b4e91dc17aaab8e63a80  config-baseline.channel.json
+a973af69b02a27b097b54e49886dd57dbebbc95e2ab29b0c7e222a9f35a105d8  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-303312830e2d7275bfe5abcdbdb3b47fd8648067a7b51ca043503a78bb18d275  plugin-sdk-api-baseline.json
-71e94e1de9f1b03aa44da55ec63d16146ab279740c44854d5998bc0f04d6ae0d  plugin-sdk-api-baseline.jsonl
+99a18e1e8e3af265e233504b6cf1ff8a227a6466dd0d515c56f823503f0b7bc7  plugin-sdk-api-baseline.json
+930a414cf783baa2bedb21a85af6fcaa02a12073d9e06cc49c827e7379f85646  plugin-sdk-api-baseline.jsonl

docs/automation/cron-jobs.md

@@ -465,7 +465,9 @@ openclaw cron edit <jobId> --clear-agent
 
 `openclaw cron run <jobId>` returns after enqueueing the manual run. Use `--wait` for shutdown hooks, maintenance scripts, or other automation that must block until the queued run finishes. Wait mode polls the exact returned `runId`; it exits `0` for status `ok` and non-zero for `error`, `skipped`, or a wait timeout.
 
-`openclaw cron create` is an alias for `openclaw cron add`, and new jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `cron add|create` or `cron edit` to POST the finished run payload to an HTTP endpoint. Webhook delivery cannot be combined with chat delivery flags such as `--announce`, `--channel`, `--to`, `--thread-id`, or `--account`.
+The agent `cron` tool returns compact job summaries (`id`, `name`, `enabled`, `nextRunAtMs`, `scheduleKind`, `lastRunStatus`) from `cron(action: "list")`; use `cron(action: "get", jobId: "...")` for one full job definition. Direct Gateway callers can pass `compact: true` to `cron.list`; omitting it preserves the existing full response with delivery previews.
+
+`openclaw cron create` is an alias for `openclaw cron add`, and new jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `cron add|create` or `cron edit` to POST the finished run payload to an HTTP endpoint. Webhook delivery cannot be combined with chat delivery flags such as `--announce`, `--channel`, `--to`, `--thread-id`, or `--account`. On `cron edit`, `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` unset those routing fields individually (each rejected alongside its matching set flag), which is distinct from `--no-deliver` disabling runner fallback delivery.
 
 <Note>
 Model override note:

docs/channels/groups.md

@@ -50,6 +50,8 @@ Use `messages.groupChat.visibleReplies: "message_tool"` when a shared room shoul
 
 Use `"automatic"` for weaker models or runtimes that do not reliably understand tool-only delivery. In automatic mode, the agent's final assistant text is the visible source reply path, so a model that cannot consistently call `message(action=send)` can still answer normally.
 
+In automatic mode, normal text final replies are posted directly to the room. If the visible reply needs files, images, or other attachments, the agent may still use `message(action=send)` for that attachment instead of trying to force it through the final text reply.
+
 If the message tool is unavailable under the active tool policy, OpenClaw falls
 back to automatic visible replies instead of silently suppressing the response.
 `openclaw doctor` warns about this mismatch.

docs/channels/telegram.md

@@ -111,6 +111,10 @@ After a successful startup, OpenClaw caches the bot identity in the state direct
 
 ## Access control and activation
 
+### Group bot identity
+
+In Telegram groups and forum topics, an explicit mention of the configured bot handle (for example `@my_bot`) is treated as addressing the selected OpenClaw agent, even when the agent persona name differs from the Telegram username. The group silence policy still applies to unrelated group traffic, but the bot handle itself is not considered "someone else."
+
 <Tabs>
   <Tab title="DM policy">
     `channels.telegram.dmPolicy` controls direct message access:
@@ -418,7 +422,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   </Accordion>
 
   <Accordion title="Rich message formatting">
-    Outbound text uses Telegram rich messages.
+    Outbound text uses standard Telegram HTML messages by default so replies remain readable across current Telegram clients.
+
+    Set `channels.telegram.richMessages: true` to opt into Bot API 10.1 rich messages:
+
+```json5
+{
+  channels: {
+    telegram: {
+      richMessages: true,
+    },
+  },
+}
+```
 
     - Markdown text is rendered through OpenClaw's Markdown IR and sent as Telegram rich HTML.
     - Explicit rich HTML payloads preserve supported Bot API 10.1 tags such as headings, tables, details, rich media, and formulas.
@@ -426,6 +442,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
 
     This keeps model text away from Telegram Rich Markdown sigils, so currency like `$400-600K` is not parsed as math. Long rich text is split automatically across Telegram's rich text and rich block limits. Tables over Telegram's column limit are sent as code blocks.
 
+    Rich messages require compatible Telegram clients. Some current Desktop, Web, Android, and third-party clients display accepted rich messages as unsupported, so keep this option disabled unless every client used with the bot can render them.
+
     Link previews are enabled by default. `channels.telegram.linkPreview: false` skips automatic entity detection for rich text.
 
   </Accordion>
@@ -1081,7 +1099,7 @@ Primary reference: [Configuration reference - Telegram](/gateway/config-channels
 - command/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
 - threading/replies: `replyToMode`
 - streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming`
-- formatting/delivery: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
+- formatting/delivery: `textChunkLimit`, `chunkMode`, `richMessages`, `linkPreview`, `responsePrefix`
 - media/network: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
 - custom API root: `apiRoot` (Bot API root only; do not include `/bot<TOKEN>`)
 - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`

docs/channels/whatsapp.md

@@ -164,7 +164,7 @@ handoff path over manual terminal capture.
 
 - Gateway owns the WhatsApp socket and reconnect loop.
 - The reconnect watchdog uses WhatsApp Web transport activity, not only inbound app-message volume, so a quiet linked-device session is not restarted solely because nobody has sent a message recently. A longer application-silence cap still forces a reconnect if transport frames keep arriving but no application messages are handled for the watchdog window; after a transient reconnect for a recently active session, that application-silence check uses the normal message timeout for the first recovery window.
-- Baileys socket timings are explicit under `web.whatsapp.*`: `keepAliveIntervalMs` controls WhatsApp Web application pings, `connectTimeoutMs` controls the opening handshake timeout, and `defaultQueryTimeoutMs` controls Baileys query waits plus OpenClaw's local outbound send/presence operation bound.
+- Baileys socket timings are explicit under `web.whatsapp.*`: `keepAliveIntervalMs` controls WhatsApp Web application pings, `connectTimeoutMs` controls the opening handshake timeout, and `defaultQueryTimeoutMs` controls Baileys query waits plus OpenClaw's local outbound send/presence and inbound read-receipt operation bounds.
 - Outbound sends require an active WhatsApp listener for the target account.
 - Group sends attach native mention metadata for `@+<digits>` and `@<digits>` tokens in text and media captions when the token matches current WhatsApp participant metadata, including LID-backed groups.
 - Status and broadcast chats are ignored (`@status`, `@broadcast`).

docs/cli/acp.md

@@ -63,7 +63,7 @@ Quick rule:
   fallback and do not reconstruct historic tool calls or system notices.
 - If multiple ACP clients share the same Gateway session key, event and cancel
   routing are best-effort rather than strictly isolated per client. Prefer the
-  default isolated `acp:<uuid>` sessions when you need clean editor-local
+  default isolated `acp-bridge:<uuid>` sessions when you need clean editor-local
   turns.
 - Gateway stop states are translated into ACP stop reasons, but that mapping is
   less expressive than a fully ACP-native runtime.
@@ -206,7 +206,7 @@ openclaw acp --session agent:qa:bug-123
 ```
 
 Each ACP session maps to a single Gateway session key. One agent can have many
-sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
+sessions; ACP defaults to an isolated `acp-bridge:<uuid>` session unless you override
 the key or label.
 
 Per-session `mcpServers` are not supported in bridge mode. If an ACP client
@@ -309,8 +309,10 @@ In Zed, open the Agent panel and select "OpenClaw ACP" to start a thread.
 
 ## Session mapping
 
-By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
-To reuse a known session, pass a session key or label:
+By default, ACP bridge sessions get an isolated Gateway session key with an
+`acp-bridge:` prefix. These normal-model bridge sessions are synthetic and
+subject to stale-entry pruning and entry-count caps. To reuse a known session,
+pass a session key or label:
 
 - `--session <key>`: use a specific Gateway session key.
 - `--session-label <label>`: resolve an existing session by label.

docs/cli/cron.md

@@ -93,6 +93,8 @@ Isolated cron chat delivery is shared between the agent and the runner:
 
 Use `cron add|create --webhook <url>` or `cron edit <job-id> --webhook <url>` to set webhook delivery. Do not combine `--webhook` with chat delivery flags such as `--announce`, `--no-deliver`, `--channel`, `--to`, `--thread-id`, or `--account`.
 
+`cron edit <job-id>` can unset individual delivery routing fields with `--clear-channel`, `--clear-to`, `--clear-thread-id`, and `--clear-account` (each is rejected when combined with its matching set flag). Unlike `--no-deliver`, which only disables runner fallback delivery, these remove the stored field so the job resolves that part of its route from defaults again.
+
 `--announce` is runner fallback delivery for the final reply. `--no-deliver` disables that fallback but does not remove the agent's `message` tool when a chat route is available.
 
 Reminders created from an active chat preserve the live chat delivery target for fallback announce delivery. Internal session keys may be lowercase; do not use them as a source of truth for case-sensitive provider IDs such as Matrix room IDs.

docs/cli/policy.md

@@ -54,7 +54,8 @@ doctor can report the missing artifact.
 Policy is authored, not generated from the user's current settings. A minimal
 policy for channels, MCP servers, model providers, network posture, ingress/channel access, Gateway
 exposure, agent workspace posture, configured sandbox runtime posture, OpenClaw
-data-handling posture, config secret provider/auth profile posture, and tool metadata looks like this:
+data-handling posture, config secret provider/auth profile posture, exec approval
+file posture, and tool metadata looks like this:
 
 ```jsonc
 {
@@ -145,6 +146,15 @@ data-handling posture, config secret provider/auth profile posture, and tool met
       "allowModes": ["api_key", "token"],
     },
   },
+  "execApprovals": {
+    "requireFile": true,
+    "defaults": { "allowSecurity": ["deny"] },
+    "agents": {
+      "allowSecurity": ["deny", "allowlist"],
+      "allowAutoAllowSkills": false,
+      "allowlist": { "expected": ["deploy", "status"] },
+    },
+  },
   "tools": {
     "requireMetadata": ["risk", "sensitivity", "owner"],
     "profiles": {
@@ -187,9 +197,11 @@ and `group:runtime` covers shell/process tools. Tool posture policy observes
 `tools.profile`, `tools.allow`, `tools.alsoAllow`, `tools.deny`,
 `tools.fs.workspaceOnly`, `tools.exec.security`, `tools.exec.ask`,
 `tools.exec.host`, `tools.elevated.enabled`, and the same per-agent
-`agents.list[].tools.*` overrides. It does not read runtime/operator approval
-state such as exec-approvals.json, and it does not enforce tool calls at
-runtime. Secret evidence records
+`agents.list[].tools.*` overrides. Exec approval policy reads the named
+`exec-approvals.json` product artifact only when an `execApprovals` rule is
+present; evidence records defaults, per-agent posture, and allowlist patterns
+without socket tokens or last-used command text. Policy does not enforce tool
+calls at runtime. Secret evidence records
 provider/source posture and SecretRef metadata, never raw secret values. Policy
 does not read or attest per-agent credential stores such as `auth-profiles.json`;
 those stores remain owned by the existing auth and credential flows.
@@ -218,8 +230,8 @@ its own finding against the same observed config.
 
 Use `scopes.<scopeName>` when one set of agents or channels needs stricter
 policy than the top-level baseline. Agent-scoped sections use `agentIds`, which
-supports `tools.*`, `agents.workspace.*`, `sandbox.*`, and
-`dataHandling.memory.*`. Channel-scoped
+supports `tools.*`, `agents.workspace.*`, `sandbox.*`, `dataHandling.memory.*`,
+and `execApprovals.*`. Channel-scoped
 ingress uses `channelIds`, which supports `ingress.channels.*`. Unsupported
 sections are rejected instead of being ignored. If an `agentIds` entry is not
 present in `agents.list[]`, OpenClaw evaluates the scoped rule against inherited
@@ -304,10 +316,10 @@ groups where those fields cannot be observed.
 Top-level `ingress.session.requireDmScope` remains global because
 `session.dmScope` is not channel-attributable evidence.
 
-| Selector     | Supported sections                                                | Use when                                          |
-| ------------ | ----------------------------------------------------------------- | ------------------------------------------------- |
-| `agentIds`   | `tools`, `agents.workspace`, `sandbox`, and `dataHandling.memory` | One or more runtime agents need stricter rules.   |
-| `channelIds` | `ingress.channels`                                                | One or more channels need stricter ingress rules. |
+| Selector     | Supported sections                                                                 | Use when                                          |
+| ------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `agentIds`   | `tools`, `agents.workspace`, `sandbox`, `dataHandling.memory`, and `execApprovals` | One or more runtime agents need stricter rules.   |
+| `channelIds` | `ingress.channels`                                                                 | One or more channels need stricter ingress rules. |
 
 Every scope present in `policy.jsonc` must be valid and enforceable.
 
@@ -401,6 +413,69 @@ allowlist such as `["all"]`.
 | `secrets.denySources`             | Secret provider sources and SecretRef sources            | Deny sources such as `exec`, `file`, or another configured source name. |
 | `secrets.allowInsecureProviders`  | Insecure secret-provider posture flags                   | Set to `false` to reject providers that opt into insecure posture.      |
 
+#### Exec approvals
+
+Exec approvals policy observes the active runtime `exec-approvals.json`
+artifact. By default this is `~/.openclaw/exec-approvals.json`; when
+`OPENCLAW_STATE_DIR` is set, Policy reads
+`$OPENCLAW_STATE_DIR/exec-approvals.json`. Actual posture rules such as
+`execApprovals.defaults.*` or `execApprovals.agents.*` require readable artifact
+evidence; a missing or invalid artifact is reported as unobservable evidence
+instead of becoming a best-effort pass against synthetic runtime defaults. Once
+the artifact is readable, omitted approval fields inherit runtime defaults: missing
+`defaults.security` is `full`, and missing agent security inherits that
+default. Evidence includes `defaults`, `agents.*`, and
+`agents.*.allowlist[].pattern` plus optional `argPattern`, effective
+`autoAllowSkills` posture, and entry source. It does not include socket
+path/token, `commandText`, `lastUsedCommand`, resolved paths, or timestamps.
+
+| Policy field                                | Observed state                                                                         | Use when                                                                                |
+| ------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `execApprovals.requireFile`                 | Active runtime `exec-approvals.json` path                                              | Set to `true` to require the approvals artifact to exist and parse.                     |
+| `execApprovals.defaults.allowSecurity`      | `defaults.security`, defaulting to `full`                                              | Allow only approved default approval security modes.                                    |
+| `execApprovals.agents.allowSecurity`        | `agents.*.security`, inheriting defaults                                               | Allow only approved per-agent effective approval security modes.                        |
+| `execApprovals.agents.allowAutoAllowSkills` | `defaults.autoAllowSkills` and `agents.*.autoAllowSkills`, inheriting runtime defaults | Set to `false` to require strict manual allowlists without implicit skill CLI approval. |
+| `execApprovals.agents.allowlist.expected`   | Aggregate `agents.*.allowlist[]` pattern and optional argPattern entries               | Require the approvals allowlist to match the reviewed pattern set.                      |
+
+For example, require the approvals artifact, deny permissive defaults, and
+allow only reviewed exec approval posture for selected agents:
+
+```jsonc
+{
+  "execApprovals": {
+    "requireFile": true,
+    "defaults": {
+      // Security modes: "deny", "allowlist", or "full".
+      // This default permits only the locked-down deny posture.
+      "allowSecurity": ["deny"],
+    },
+  },
+  "scopes": {
+    "restricted-shell": {
+      "agentIds": ["family-agent", "groups-agent"],
+      "execApprovals": {
+        "agents": {
+          // Selected agents may use reviewed allowlist posture, but not "full".
+          "allowSecurity": ["allowlist"],
+          // false means skill CLIs must appear in the reviewed allowlist instead of
+          // being implicitly approved by autoAllowSkills.
+          "allowAutoAllowSkills": false,
+          "allowlist": {
+            "expected": [
+              // Simple entry: exact reviewed executable pattern with no argPattern.
+              "travel-hub",
+              // Constrained entry: pattern plus reviewed argument regex.
+              { "pattern": "calendar-cli", "argPattern": "^sync\\b" },
+              "/bin/date",
+            ],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
 #### Auth profiles
 
 | Policy field                    | Observed state                               | Use when                                                                                   |
@@ -769,6 +844,13 @@ Policy currently verifies:
 | `policy/secrets-insecure-provider`                       | A secret provider opts into insecure posture when policy denies it.               |
 | `policy/auth-profile-invalid-metadata`                   | A config auth profile is missing valid provider or mode metadata.                 |
 | `policy/auth-profile-unapproved-mode`                    | A config auth profile mode is outside the policy allowlist.                       |
+| `policy/exec-approvals-missing`                          | Policy requires `exec-approvals.json`, but the artifact is missing.               |
+| `policy/exec-approvals-invalid`                          | The configured exec approvals artifact cannot be parsed.                          |
+| `policy/exec-approvals-default-security-unapproved`      | Exec approval defaults use a security mode outside the policy allowlist.          |
+| `policy/exec-approvals-agent-security-unapproved`        | A per-agent effective exec approval security mode is outside the allowlist.       |
+| `policy/exec-approvals-auto-allow-skills-enabled`        | An exec approval agent implicitly auto-allows skill CLIs when policy denies it.   |
+| `policy/exec-approvals-allowlist-missing`                | The approvals allowlist is missing a pattern required by policy.                  |
+| `policy/exec-approvals-allowlist-unexpected`             | The approvals allowlist includes a pattern not expected by policy.                |
 | `policy/tools-missing-risk-level`                        | A governed tool declaration is missing risk metadata.                             |
 | `policy/tools-unknown-risk-level`                        | A governed tool declaration uses an unknown risk value.                           |
 | `policy/tools-missing-sensitivity-token`                 | A governed tool declaration is missing sensitivity metadata.                      |

docs/cli/security.md

@@ -44,7 +44,7 @@ For webhook ingress, startup logs a non-fatal security warning and audit flags `
 If Gateway password auth is supplied only at startup, pass the same value to `openclaw security audit --auth password --password <password>` so the audit can check it against `hooks.token`.
 Run `openclaw doctor --fix` to rotate a persisted reused `hooks.token`, then update external hook senders to use the new hook token.
 
-It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when write/edit tools are disabled but `exec` is still available without a constraining sandbox filesystem boundary, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
+It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when write/edit tools are disabled but `exec` is still available without a constraining sandbox filesystem boundary, when open DMs or groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
 It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
 It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
 It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).

docs/cli/sessions.md

@@ -122,7 +122,7 @@ openclaw sessions cleanup --json
 - Cleanup also prunes unreferenced primary transcripts, compaction checkpoints, and trajectory sidecars older than `session.maintenance.pruneAfter`; files still referenced by `sessions.json` are preserved.
 
 - `--dry-run`: preview how many entries would be pruned/capped without writing.
-  - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
+  - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) plus a summary grouped by session label so you can see what would be kept vs removed.
 - `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
 - `--fix-missing`: remove entries whose transcript files are missing or header-only/empty, even if they would not normally age/count out yet.
 - `--fix-dm-scope`: when `session.dmScope` is `main`, retire stale peer-keyed direct-DM rows left behind by earlier `per-peer`, `per-channel-peer`, or `per-account-channel-peer` routing. Use `--dry-run` first; applying the cleanup removes those rows from `sessions.json` and preserves their transcripts as deleted archives.

docs/concepts/timezone.md

@@ -36,7 +36,7 @@ If `userTimezone` is unset, OpenClaw resolves the host timezone at runtime (no c
 
 - **Use UTC envelopes** (`envelopeTimezone: "utc"`) when you want stable timestamps across hosts in different regions, or when you want UTC-aligned logs to match diagnostics output.
 - **Use a fixed IANA zone** (e.g. `"Europe/Vienna"`) when the gateway host is in one zone but the user is in another and you want envelopes to read in the user's zone regardless of host migration.
-- **Set `envelopeTimestamp: "off"`** for low-token envelopes when timestamp context is not useful for the conversation.
+- **Set `envelopeTimestamp: "off"`** when timestamp context is not useful for the conversation. This removes absolute timestamps from envelopes, direct agent prompt prefixes, and embedded model-input prefixes.
 
 For the full behavior reference, examples per provider, and elapsed-time formatting, see [Date & Time](/date-time).
 

docs/date-time.md

@@ -37,7 +37,7 @@ You can override this behavior:
 - `envelopeTimezone: "local"` uses the host timezone.
 - `envelopeTimezone: "user"` uses `agents.defaults.userTimezone` (falls back to host timezone).
 - Use an explicit IANA timezone (e.g., `"America/Chicago"`) for a fixed zone.
-- `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers.
+- `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers, direct agent prompt prefixes, and embedded model-input prefixes.
 - `envelopeElapsed: "off"` removes elapsed time suffixes (the `+2m` style).
 
 ### Examples

docs/docs.json

@@ -1385,7 +1385,8 @@
                 "pages": [
                   "clawhub/api",
                   "clawhub/http-api",
-                  "clawhub/acceptable-usage"
+                  "clawhub/acceptable-usage",
+                  "clawhub/content-rights"
                 ]
               }
             ]

docs/gateway/openai-http-api.md

@@ -99,7 +99,7 @@ Optional request headers:
 
 - `x-openclaw-model: <provider/model-or-bare-id>` overrides the backend model for the selected agent. Shared-secret bearer callers can use this header. Identity-bearing callers, such as trusted-proxy or private no-auth ingress requests with `x-openclaw-scopes`, need `operator.admin`; write-only callers get `403 missing scope: operator.admin`.
 - `x-openclaw-agent-id: <agentId>` remains supported as a compatibility override.
-- `x-openclaw-session-key: <sessionKey>` fully controls session routing.
+- `x-openclaw-session-key: <sessionKey>` explicitly controls session routing. The value must not use reserved internal session namespaces such as `subagent:`, `cron:`, or `acp:`; those requests are rejected with `400 invalid_request_error`.
 - `x-openclaw-message-channel: <channel>` sets the synthetic ingress channel context for channel-aware prompts and policies.
 
 Compatibility aliases still accepted:
@@ -145,7 +145,7 @@ By default the endpoint is **stateless per request** (a new session key is gener
 
 If the request includes an OpenAI `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.
 
-For custom apps, the safest default is to reuse the same `user` value per conversation thread. Avoid account-level identifiers unless you explicitly want multiple conversations or devices to share one OpenClaw session. Use `x-openclaw-session-key` when you need explicit routing control across multiple clients or threads.
+For custom apps, the safest default is to reuse the same `user` value per conversation thread. Avoid account-level identifiers unless you explicitly want multiple conversations or devices to share one OpenClaw session. Use `x-openclaw-session-key` only when you need explicit routing control across multiple clients or threads, and choose application-owned keys that do not start with reserved internal namespaces such as `subagent:`, `cron:`, or `acp:`.
 
 ## Why this surface matters
 

docs/gateway/security/audit-checks.md

@@ -110,8 +110,8 @@ exhaustive):
 | `skills.code_safety`                                          | warn/critical | Skill installer metadata/code contains suspicious or dangerous patterns              | skill install source                                                                                 | no       |
 | `skills.code_safety.scan_failed`                              | warn          | Skill code scan could not complete                                                   | skill scan environment                                                                               | no       |
 | `security.exposure.open_channels_with_exec`                   | warn/critical | Shared/public rooms can reach exec-enabled agents                                    | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*`        | no       |
-| `security.exposure.open_groups_with_elevated`                 | critical      | Open groups + elevated tools create high-impact prompt-injection paths               | `channels.*.groupPolicy`, `tools.elevated.*`                                                         | no       |
-| `security.exposure.open_groups_with_runtime_or_fs`            | critical/warn | Open groups can reach command/file tools without sandbox/workspace guards            | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode`    | no       |
+| `security.exposure.open_groups_with_elevated`                 | critical      | Open DMs/groups + elevated tools create high-impact prompt-injection paths           | top-level or nested DM policy paths, account overrides, `channels.*.groupPolicy`                     | no       |
+| `security.exposure.open_groups_with_runtime_or_fs`            | critical/warn | Open DMs/groups can reach command/file tools without sandbox/workspace guards        | DM/group policy paths, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode`       | no       |
 | `security.trust_model.multi_user_heuristic`                   | warn          | Config looks multi-user while gateway trust model is personal-assistant              | split trust boundaries, or shared-user hardening (`sandbox.mode`, tool deny/workspace scoping`)      | no       |
 | `tools.profile_minimal_overridden`                            | warn          | Agent overrides bypass global minimal profile                                        | `agents.list[].tools.profile`                                                                        | no       |
 | `plugins.tools_reachable_permissive_policy`                   | warn          | Extension tools reachable in permissive contexts                                     | `tools.profile` + tool allow/deny                                                                    | no       |

docs/help/testing.md

@@ -824,7 +824,7 @@ The live-model Docker runners also bind-mount only the needed CLI auth homes (or
 - Release user journey smoke: `pnpm test:docker:release-user-journey` installs the packed OpenClaw tarball globally in a clean Docker home, runs onboarding, configures a mocked OpenAI provider, runs an agent turn, installs/uninstalls external plugins, configures ClickClack against a local fixture, verifies outbound/inbound messaging, restarts Gateway, and runs doctor.
 - Release typed onboarding smoke: `pnpm test:docker:release-typed-onboarding` installs the packed tarball, drives `openclaw onboard` through a real TTY, configures OpenAI as an env-ref provider, verifies no raw key persistence, and runs a mocked agent turn.
 - Release media/memory smoke: `pnpm test:docker:release-media-memory` installs the packed tarball, verifies image understanding from a PNG attachment, OpenAI-compatible image generation output, memory search recall, and recall survival across Gateway restart.
-- Release upgrade user journey smoke: `pnpm test:docker:release-upgrade-user-journey` installs `openclaw@latest` by default, configures provider/plugin/ClickClack state on the published package, upgrades to the candidate tarball, then reruns the core agent/plugin/channel journey. Override the baseline with `OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>`.
+- Release upgrade user journey smoke: `pnpm test:docker:release-upgrade-user-journey` installs the newest published baseline older than the candidate tarball by default, configures provider/plugin/ClickClack state on the published package, upgrades to the candidate tarball, then reruns the core agent/plugin/channel journey. If no older published baseline exists, it reuses the candidate version. Override the baseline with `OPENCLAW_RELEASE_UPGRADE_BASELINE_SPEC=openclaw@<version>`.
 - Release plugin marketplace smoke: `pnpm test:docker:release-plugin-marketplace` installs from a local fixture marketplace, updates the installed plugin, uninstalls it, and verifies the plugin CLI disappears with install metadata pruned.
 - Skill install smoke: `pnpm test:docker:skill-install` installs the packed OpenClaw tarball globally in Docker, disables uploaded archive installs in config, resolves the current live ClawHub skill slug from search, installs it with `openclaw skills install`, and verifies the installed skill plus `.clawhub` origin/lock metadata.
 - Update channel switch smoke: `pnpm test:docker:update-channel-switch` installs the packed OpenClaw tarball globally in Docker, switches from package `stable` to git `dev`, verifies the persisted channel and plugin post-update work, then switches back to package `stable` and checks update status.

docs/platforms/ios.md

@@ -193,8 +193,8 @@ export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"
 ```
 
 These are gateway-host runtime env vars, not Fastlane settings. `apps/ios/fastlane/.env` only stores
-App Store Connect / TestFlight auth such as `ASC_KEY_ID` and `ASC_ISSUER_ID`; it does not configure
-direct APNs delivery for local iOS builds.
+App Store Connect / TestFlight auth such as `APP_STORE_CONNECT_KEY_ID` and
+`APP_STORE_CONNECT_ISSUER_ID`; it does not configure direct APNs delivery for local iOS builds.
 
 Recommended gateway-host storage:
 

docs/plugins/codex-harness.md

@@ -505,9 +505,22 @@ Codex dynamic tools default to `searchable` loading. OpenClaw does not expose
 dynamic tools that duplicate Codex-native workspace operations: `read`, `write`,
 `edit`, `apply_patch`, `exec`, `process`, and `update_plan`. Most remaining
 OpenClaw integration tools such as messaging, media, cron, browser, nodes,
-gateway, `heartbeat_respond`, and `web_search` are available through Codex tool
-search under the `openclaw` namespace, keeping the initial model context
-smaller.
+gateway, and `heartbeat_respond` are available through Codex tool search under
+the `openclaw` namespace, keeping the initial model context smaller. Web search
+uses Codex's hosted `web_search` tool by default when search is enabled and no
+managed provider is selected. Native hosted search and OpenClaw's managed
+`web_search` dynamic tool are mutually exclusive so managed search cannot bypass
+native domain restrictions. OpenClaw uses the managed tool when hosted search is
+unavailable, explicitly disabled, or replaced by a selected managed provider.
+OpenClaw keeps Codex's standalone `web.run` extension disabled because
+production app-server traffic rejects its user-defined `web` namespace.
+`tools.web.search.enabled: false` disables both paths, as do tool-disabled
+LLM-only runs. Codex treats `"cached"` as a preference and resolves it to live
+external access for unrestricted app-server turns. Automatic managed fallback
+fails closed when native `allowedDomains` are set so the allowlist cannot be
+bypassed. Persistent effective search-policy changes rotate the bound Codex
+thread before the next turn. Transient per-turn restrictions use a temporary
+restricted thread and preserve the existing binding for later resume.
 `sessions_yield` and message-tool-only source replies stay direct because
 those are turn-control contracts. `sessions_spawn` stays searchable so Codex's
 native `spawn_agent` remains the primary Codex subagent surface, while explicit

docs/plugins/manifest.md

@@ -1278,6 +1278,7 @@ Important examples:
 | `openclaw.compat.pluginApi`                                                                | Minimum OpenClaw plugin API range required by this package, using a semver floor like `>=2026.5.27`.                                                                                 |
 | `openclaw.install.expectedIntegrity`                                                       | Expected npm dist integrity string such as `sha512-...`; install and update flows verify the fetched artifact against it.                                                            |
 | `openclaw.install.allowInvalidConfigRecovery`                                              | Allows a narrow bundled-plugin reinstall recovery path when config is invalid.                                                                                                       |
+| `openclaw.install.requiredPlatformPackages`                                                | npm package aliases that must materialize when their lockfile platform constraints match the current host.                                                                           |
 | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`                          | Lets setup-runtime channel surfaces load before listen, then defers the full configured channel plugin until post-listen activation.                                                 |
 
 Manifest metadata decides which provider/channel/setup choices appear in
@@ -1290,6 +1291,13 @@ registry loading for non-bundled plugin sources. Invalid values are rejected;
 newer-but-valid values skip external plugins on older hosts. Bundled source
 plugins are assumed to be co-versioned with the host checkout.
 
+`openclaw.install.requiredPlatformPackages` is for npm packages that expose
+required native binaries through optional, platform-specific aliases. List the
+bare npm package name for every supported platform alias. During npm install,
+OpenClaw verifies only the declared alias whose lockfile constraints match the
+current host. If npm reports success but omits that alias, OpenClaw retries once
+with a fresh cache and rolls back the install if the alias is still missing.
+
 `openclaw.compat.pluginApi` is enforced during package install for non-bundled
 plugin sources. Use it for the OpenClaw plugin SDK/runtime API floor that the
 package was built against. It can be stricter than `minHostVersion` when a

docs/plugins/reference/codex.md

@@ -16,7 +16,7 @@ OpenClaw Codex app-server harness and model provider plugin with a Codex-managed
 
 ## Surface
 
-providers: codex; contracts: mediaUnderstandingProviders, migrationProviders
+providers: codex; contracts: mediaUnderstandingProviders, migrationProviders, webSearchProviders
 
 ## Related docs
 

docs/plugins/sdk-setup.md

@@ -163,6 +163,7 @@ Example:
 | `minHostVersion`             | `string`                            | Minimum supported OpenClaw version in the form `>=x.y.z` or `>=x.y.z-prerelease`. |
 | `expectedIntegrity`          | `string`                            | Expected npm dist integrity string, usually `sha512-...`, for pinned installs.    |
 | `allowInvalidConfigRecovery` | `boolean`                           | Lets bundled-plugin reinstall flows recover from specific stale-config failures.  |
+| `requiredPlatformPackages`   | `string[]`                          | Required platform-specific npm aliases verified during npm install.               |
 
 <AccordionGroup>
   <Accordion title="Onboarding behavior">

docs/plugins/sdk-subpaths.md

@@ -250,7 +250,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/session-store-runtime` | Session workflow helpers (`getSessionEntry`, `listSessionEntries`, `patchSessionEntry`, `upsertSessionEntry`), legacy session store path/session-key helpers, updated-at reads, and deprecated whole-store mutation helpers |
     | `plugin-sdk/cron-store-runtime` | Cron store path/load/save helpers |
     | `plugin-sdk/state-paths` | State/OAuth dir path helpers |
-    | `plugin-sdk/plugin-state-runtime` | Plugin sidecar SQLite keyed-state types |
+    | `plugin-sdk/plugin-state-runtime` | Plugin sidecar SQLite keyed-state types plus centralized connection pragma and WAL maintenance setup for plugin-owned databases |
     | `plugin-sdk/routing` | Route/session-key/account binding helpers such as `resolveAgentRoute`, `buildAgentSessionKey`, and `resolveDefaultAgentBoundAccountId` |
     | `plugin-sdk/status-helpers` | Shared channel/account status summary helpers, runtime-state defaults, and issue metadata helpers |
     | `plugin-sdk/target-resolver-runtime` | Shared target resolver helpers |

docs/reference/api-usage-costs.md

@@ -140,7 +140,7 @@ See [Memory](/concepts/memory).
 - **Ollama Web Search**: key-free for a reachable signed-in local Ollama host; direct `https://ollama.com` search uses `OLLAMA_API_KEY`, and auth-protected hosts can reuse normal Ollama provider bearer auth
 - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
 - **Tavily**: `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey`
-- **DuckDuckGo**: key-free fallback (no API billing, but unofficial and HTML-based)
+- **DuckDuckGo**: key-free provider when explicitly selected (no API billing, but unofficial and HTML-based)
 - **SearXNG**: `SEARXNG_BASE_URL` or `plugins.entries.searxng.config.webSearch.baseUrl` (key-free/self-hosted; no hosted API billing)
 
 Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface.

docs/reference/secretref-credential-surface.md

@@ -44,6 +44,7 @@ Scope intent:
 - `plugins.entries.acpx.config.mcpServers.*.env.*`
 - `plugins.entries.brave.config.webSearch.apiKey`
 - `plugins.entries.exa.config.webSearch.apiKey`
+- `plugins.entries.google-meet.config.realtime.providers.*.apiKey`
 - `plugins.entries.google.config.webSearch.apiKey`
 - `plugins.entries.xai.config.webSearch.apiKey`
 - `plugins.entries.moonshot.config.webSearch.apiKey`

docs/reference/secretref-user-supplied-credentials-matrix.json

@@ -568,6 +568,13 @@
       "secretShape": "secret_input",
       "optIn": true
     },
+    {
+      "id": "plugins.entries.google-meet.config.realtime.providers.*.apiKey",
+      "configFile": "openclaw.json",
+      "path": "plugins.entries.google-meet.config.realtime.providers.*.apiKey",
+      "secretShape": "secret_input",
+      "optIn": true
+    },
     {
       "id": "plugins.entries.google.config.webSearch.apiKey",
       "configFile": "openclaw.json",