🐛 fix(desktop): swallow transient net errors in main process

Electron's net stack (SimpleURLLoaderWrapper, used internally by electron-updater's net.request) emits transient connectivity errors (ERR_NETWORK_CHANGED, ERR_NETWORK_IO_SUSPENDED) on Wi-Fi/VPN switch and system sleep. With no global guard they bubble up as an uncaughtException and pop the "A JavaScript error occurred in the main process" dialog. Add a process-level handler that swallows known transient net-stack errors and re-throws everything else, so genuine crashes stay visible. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
✨ feat: workspace device support (#16134 )
2026-06-20 22:26:05 +00:00 · 2026-06-21 00:41:59 +08:00 · 2026-06-21 00:41:06 +08:00 · 2026-06-21 00:35:51 +08:00 · 2026-06-21 00:29:40 +08:00 · 2026-06-21 00:26:03 +08:00
1833 changed files with 125809 additions and 23511 deletions
@@ -111,7 +111,7 @@ First check the repo root for `.env`:
 Do not start the standalone e2e server as the product under test.

 Use `scripts/init-dev-env.sh`. It follows the e2e setup pattern — Postgres,
-migrations, auth/key-vault/S3 test env, seed user — but it is owned by this
+Redis, migrations, auth/key-vault/S3 test env, seed user — but it is owned by this
 skill and starts the repo's dev server (`pnpm run dev:next` / `bun run dev`),
 not `e2e/scripts/setup.ts --start`. The script hard-blocks when root `.env`
 exists, so it cannot accidentally override a user's local config. When `.env`
@@ -132,19 +132,19 @@ fi
 Bootstrap flow when no `.env` exists:

 ```bash
-# From repo root. Managed DB flow requires Docker Desktop.
+# From repo root. Managed Postgres/Redis flow requires Docker Desktop.
 ./.agents/skills/agent-testing/scripts/init-dev-env.sh setup-db
 ./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
 ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
 ```

 If using an existing Postgres instead of the managed Docker DB, set
-`DATABASE_URL` and skip `setup-db`:
+`DATABASE_URL` and `REDIS_URL`, then skip `setup-db`:

 ```bash
-DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh migrate
-DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
-DATABASE_URL=postgresql://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
+DATABASE_URL=postgresql://... REDIS_URL=redis://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh migrate
+DATABASE_URL=postgresql://... REDIS_URL=redis://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user
+DATABASE_URL=postgresql://... REDIS_URL=redis://... ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
 ```

 For backend-only checks, `dev-next` is available, but Web smoke needs the
@@ -170,6 +170,9 @@ Default script env:
 - `APP_URL=http://localhost:3010`
 - `DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres`
 - `DATABASE_DRIVER=node`
+- `AGENT_RUNTIME_MODE=queue` so backend-only agent runtime checks use the
+  same queued execution path as production
+- `REDIS_URL=redis://localhost:6380` for queue-mode agent runtime state
 - `FEATURE_FLAGS=-agent_self_iteration` so local smoke does not require QStash
 - Local QStash defaults (`QSTASH_URL`, `QSTASH_TOKEN`, signing keys) are exported;
  run `init-dev-env.sh qstash` in a separate terminal when the path under test
@@ -177,6 +180,7 @@ Default script env:
 - `KEY_VAULTS_SECRET`, `AUTH_SECRET`, auth verification off
 - S3 mock vars
 - Managed DB container: `lobehub-agent-testing-postgres`
+- Managed Redis container: `lobehub-agent-testing-redis`

 `seed-user` creates `agent-testing@lobehub.com` / `TestPassword123!` with
 onboarding already completed, plus a local API key in
@@ -112,9 +112,14 @@ secret: don't paste it into shared logs, PRs, or commit it anywhere.

 1. `$SCRIPT status --surface web` — green? Start testing. Do not ask for a Cookie header.
 2. Not green and using the seeded local env → `$SCRIPT web-seed`.
-3. Still not green or not using the seed env → `$SCRIPT open-chrome` opens Chrome at `SERVER_URL` with DevTools.
-4. User copies the `Cookie:` header from Network tab → any same-origin request → Request Headers → right-click `Cookie:` → **Copy value**. Must be from Network, NOT `document.cookie` (HttpOnly cookies are invisible to `document.cookie`).
-5. `pbpaste | $SCRIPT web` — filters to better-auth cookies (`session_token`, `session_data`, `state`), builds Playwright `storageState`, loads it into the `agent-browser` session (`lobehub-dev`), opens `SERVER_URL`, and asserts the URL is not `/signin`.
+3. If repo-root `.env` exists and `web-seed` fails, do **not** seed or modify the current DB; treat it as an existing local environment and use Cookie injection.
+4. Still not green or not using the seed env → `$SCRIPT open-chrome` opens Chrome at `SERVER_URL` with DevTools.
+5. User copies the `Cookie:` header from Network tab → any same-origin request → Request Headers → right-click `Cookie:` → **Copy value**. Must be from Network, NOT `document.cookie` (HttpOnly cookies are invisible to `document.cookie`).
+6. `pbpaste | $SCRIPT web` — filters to better-auth cookies (`session_token`, `session_data`, `state`), builds Playwright `storageState`, loads it into the `agent-browser` session (`lobehub-dev`), opens `SERVER_URL`, and asserts the URL is not `/signin`.
+
+`ENABLE_MOCK_DEV_USER` is not Web auth. It only affects server-side API context
+and does not satisfy Better Auth or stop the SPA from redirecting to `/signin`.
+Do not use it as a substitute for `status --surface web` or Cookie injection.

 ### Using the authenticated session

@@ -48,14 +48,15 @@ curl -s -o /dev/null -w '%{http_code}' "$SERVER_URL/"
 ```bash
 # Start backend only.
 # With root .env: use the existing local config.
-pnpm run dev:next
+# Agent runtime queue mode is required to mirror production async execution.
+AGENT_RUNTIME_MODE=queue pnpm run dev:next

 # Without root .env: use the self-contained agent-testing env.
 ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev-next

 # Full-stack SPA + backend. Required for Web smoke.
 # With root .env:
-bun run dev
+AGENT_RUNTIME_MODE=queue bun run dev

 # Without root .env:
 ./.agents/skills/agent-testing/scripts/init-dev-env.sh dev
@@ -91,6 +92,8 @@ in doubt.
 | `ECONNREFUSED`            | Server not running — start it                                                                 |
 | `EADDRINUSE` on the port  | Already running — `lsof -ti:<port> \| xargs kill` first                                       |
 | Stale data / old behavior | Server needs a restart to pick up code changes                                                |
+| Agent call runs inline    | Set `AGENT_RUNTIME_MODE=queue`, make sure `REDIS_URL` is configured, then restart the server  |
+| Queue mode needs Redis    | Run `init-dev-env.sh setup-db`, or provide `REDIS_URL=redis://...` for an existing Redis      |
 | QStash workflow failures  | Start `init-dev-env.sh qstash` and make sure dev server inherited the script's `QSTASH_*` env |

 Marketplace/community endpoints are not part of the local agent-testing auth
@@ -12,16 +12,16 @@
 # Usage:
 #   init-dev-env.sh env              # print shell exports
 #   init-dev-env.sh write [file]     # write a source-able env file
-#   init-dev-env.sh setup-db         # start local Postgres and run migrations
+#   init-dev-env.sh setup-db         # start local Postgres/Redis and run migrations
 #   init-dev-env.sh migrate          # run DB migrations against the configured DB
 #   init-dev-env.sh seed-user        # seed the baseline test user + CLI API key
 #   init-dev-env.sh qstash           # run local Upstash QStash dev server
 #   init-dev-env.sh dev-next         # exec `pnpm run dev:next` with this env
 #   init-dev-env.sh dev              # exec `bun run dev` with this env
-#   init-dev-env.sh clean-db         # remove the managed Postgres container
+#   init-dev-env.sh clean-db         # remove the managed Postgres/Redis containers
 #
 # Overrides:
-#   SERVER_PORT=3010 DB_PORT=5433 DB_CONTAINER=lobehub-agent-testing-postgres QSTASH_DEV_PORT=8080
+#   SERVER_PORT=3010 DB_PORT=5433 DB_CONTAINER=lobehub-agent-testing-postgres REDIS_PORT=6380 REDIS_CONTAINER=lobehub-agent-testing-redis QSTASH_DEV_PORT=8080

 set -euo pipefail

@@ -32,6 +32,9 @@ SERVER_PORT="${SERVER_PORT:-3010}"
 DB_PORT="${DB_PORT:-5433}"
 DB_CONTAINER="${DB_CONTAINER:-lobehub-agent-testing-postgres}"
 DATABASE_URL="${DATABASE_URL:-postgresql://postgres:postgres@localhost:${DB_PORT}/postgres}"
+REDIS_PORT="${REDIS_PORT:-6380}"
+REDIS_CONTAINER="${REDIS_CONTAINER:-lobehub-agent-testing-redis}"
+REDIS_URL="${REDIS_URL:-redis://localhost:${REDIS_PORT}}"
 ENV_FILE_DEFAULT="$REPO_ROOT/.records/env/agent-testing-dev.env"
 CLI_ENV_FILE_DEFAULT="$REPO_ROOT/.records/env/agent-testing-cli.env"
 AGENT_TESTING_API_KEY="${AGENT_TESTING_API_KEY:-sk-lh-agenttesting0001}"
@@ -54,6 +57,7 @@ guard_no_root_env() {
 }

 apply_env() {
+  export AGENT_RUNTIME_MODE="${AGENT_RUNTIME_MODE:-queue}"
  export APP_URL="${APP_URL:-http://localhost:${SERVER_PORT}}"
  export AUTH_EMAIL_VERIFICATION="${AUTH_EMAIL_VERIFICATION:-0}"
  export AUTH_SECRET="${AUTH_SECRET:-agent-testing-local-auth-secret-32chars}"
@@ -69,6 +73,7 @@ apply_env() {
  export QSTASH_NEXT_SIGNING_KEY="${QSTASH_NEXT_SIGNING_KEY:-$QSTASH_LOCAL_NEXT_SIGNING_KEY}"
  export QSTASH_TOKEN="${QSTASH_TOKEN:-$QSTASH_LOCAL_TOKEN}"
  export QSTASH_URL="${QSTASH_URL:-http://127.0.0.1:${QSTASH_DEV_PORT}}"
+  export REDIS_URL
  export S3_ACCESS_KEY_ID="${S3_ACCESS_KEY_ID:-agent-testing-access-key}"
  export S3_BUCKET="${S3_BUCKET:-agent-testing-bucket}"
  export S3_ENDPOINT="${S3_ENDPOINT:-https://agent-testing-s3.localhost}"
@@ -78,6 +83,7 @@ apply_env() {
 env_keys() {
  printf '%s\n' \
    APP_URL \
+    AGENT_RUNTIME_MODE \
    AUTH_EMAIL_VERIFICATION \
    AUTH_SECRET \
    DATABASE_DRIVER \
@@ -92,6 +98,7 @@ env_keys() {
    QSTASH_NEXT_SIGNING_KEY \
    QSTASH_TOKEN \
    QSTASH_URL \
+    REDIS_URL \
    S3_ACCESS_KEY_ID \
    S3_BUCKET \
    S3_ENDPOINT \
@@ -137,6 +144,15 @@ wait_for_db() {
  printf '\n'
 }

+wait_for_redis() {
+  printf '      waiting for Redis'
+  until docker exec "$REDIS_CONTAINER" redis-cli ping > /dev/null 2>&1; do
+    printf '.'
+    sleep 1
+  done
+  printf '\n'
+}
+
 start_db() {
  require_docker

@@ -157,6 +173,25 @@ start_db() {
  wait_for_db
 }

+start_redis() {
+  require_docker
+
+  if docker ps --format '{{.Names}}' | grep -Fxq "$REDIS_CONTAINER"; then
+    ok "Redis container already running: $REDIS_CONTAINER"
+  elif docker ps -a --format '{{.Names}}' | grep -Fxq "$REDIS_CONTAINER"; then
+    docker start "$REDIS_CONTAINER" > /dev/null
+    ok "started existing Redis container: $REDIS_CONTAINER"
+  else
+    docker run -d \
+      --name "$REDIS_CONTAINER" \
+      -p "${REDIS_PORT}:6379" \
+      redis:7-alpine > /dev/null
+    ok "created Redis container: $REDIS_CONTAINER"
+  fi
+
+  wait_for_redis
+}
+
 migrate_db() {
  apply_env
  cd "$REPO_ROOT"
@@ -327,9 +362,11 @@ cmd_status() {
  apply_env
  echo "agent-testing local dev env:"
  note "APP_URL=$APP_URL"
+  note "AGENT_RUNTIME_MODE=$AGENT_RUNTIME_MODE"
  note "DATABASE_URL=$DATABASE_URL"
  note "PORT=$PORT"
  note "QSTASH_URL=$QSTASH_URL"
+  note "REDIS_URL=$REDIS_URL"
  if command -v docker > /dev/null 2>&1; then
    ok "docker CLI available"
    if docker ps --format '{{.Names}}' | grep -Fxq "$DB_CONTAINER"; then
@@ -337,6 +374,11 @@ cmd_status() {
    else
      note "managed Postgres is not running: $DB_CONTAINER"
    fi
+    if docker ps --format '{{.Names}}' | grep -Fxq "$REDIS_CONTAINER"; then
+      ok "managed Redis running: $REDIS_CONTAINER"
+    else
+      note "managed Redis is not running: $REDIS_CONTAINER"
+    fi
  else
    bad "docker CLI is not available"
  fi
@@ -373,6 +415,15 @@ cmd_clean_db() {
  else
    note "Postgres container not found: $DB_CONTAINER"
  fi
+  if docker ps --format '{{.Names}}' | grep -Fxq "$REDIS_CONTAINER"; then
+    docker stop "$REDIS_CONTAINER" > /dev/null
+  fi
+  if docker ps -a --format '{{.Names}}' | grep -Fxq "$REDIS_CONTAINER"; then
+    docker rm "$REDIS_CONTAINER" > /dev/null
+    ok "removed Redis container: $REDIS_CONTAINER"
+  else
+    note "Redis container not found: $REDIS_CONTAINER"
+  fi
 }

 usage() {
@@ -391,6 +442,7 @@ case "$COMMAND" in
  write) shift; write_env "${1:-}" ;;
  setup-db)
    start_db
+    start_redis
    migrate_db
    ;;
  migrate) migrate_db ;;
@@ -81,6 +81,7 @@ SERVER_URL="${SERVER_URL:-$(default_server_url)}"
 SESSION="${SESSION:-lobehub-dev}"
 AUTH_DIR="${AUTH_DIR:-$HOME/.lobehub-agent-testing}"
 STATE_FILE="$AUTH_DIR/web-state.json"
+ROOT_ENV_FILE="$REPO_ROOT/.env"
 CLI_HOME_NAME="${LOBEHUB_CLI_HOME:-.lobehub-dev}"
 CLI_HOME="$HOME/${CLI_HOME_NAME#/}"
 CLI_CREDENTIALS_FILE="$CLI_HOME/credentials.json"
@@ -481,8 +482,13 @@ PY

  if [[ ! "$code" =~ ^[23] ]]; then
    bad "seed user sign-in failed at $SERVER_URL/api/auth/sign-in/email (http_code='$code')"
-    note "make sure the seed user exists:"
-    note "./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user"
+    if [[ -f "$ROOT_ENV_FILE" ]]; then
+      note "root .env exists; do not seed or modify this DB for Web auth."
+      note "Use Chrome Cookie injection instead: $0 open-chrome, then pbpaste | $0 web"
+    else
+      note "make sure the seed user exists:"
+      note "./.agents/skills/agent-testing/scripts/init-dev-env.sh seed-user"
+    fi
    return 1
  fi

@@ -517,6 +523,7 @@ cmd_web_verify() {
    bad "failed to open $SERVER_URL in agent-browser session '$SESSION'"
    return 1
  fi
+  agent-browser --session "$SESSION" wait --load networkidle > /dev/null 2>&1 || true
  local url
  url=$(agent-browser --session "$SESSION" get url 2> /dev/null || true)
  if [[ -z "$url" ]]; then
@@ -38,7 +38,7 @@ Use this skill when the bug or feature lives in the external CLI agent pipeline,

 ## Default Debug Order

-1. Prove whether the raw CLI output is correct before touching UI code.
+1. Prove whether the raw CLI output is correct before touching UI code. The app records every real session — read the most recent one via `cat .heerogeneous-tracing/.last-live-trace` rather than hand-rolling a `claude -p` repro (see references/debug-workflow\.md §2).
 2. If raw output is correct, compare it with adapter output. In dev, `executeHeterogeneousAgent` exposes `window.__HETERO_AGENT_TRACE`.
 3. If adapted events look correct, inspect `persistToolBatch`, `persistToolResult`, step transitions, and subagent routing.
 4. Turn the repro into a focused test before fixing.
@@ -77,6 +77,10 @@ Use this skill when the bug or feature lives in the external CLI agent pipeline,
  look for `tool_result for unknown toolCallId` and missing `result_msg_id` backfill.
 - Subagent tools show up in the main bubble:
  check for subagent chunks reaching the main gateway handler.
+- Wrong terminal-error guide (e.g. "usage limit reached" shown for a network drop):
+  a classifier is branching on a structured field whose mere presence isn't its meaning.
+  Grep the field across all event states in a real trace before trusting it — see
+  references/debug-workflow\.md §8 (CC `rate_limit_info` rides on `status: "allowed"` too).

 ## References

@@ -3,12 +3,13 @@
 ## Contents

 1. Pipeline map
-2. Capture raw CLI traces first
+2. Capture raw CLI traces first (incl. in-app live traces)
 3. Compare raw and adapted events
 4. Check step boundaries before persistence
 5. Check tool persistence invariants
 6. Focused tests
 7. Repro-to-fix workflow
+8. Verify a structured-field classifier against a real trace

 ## 1. Pipeline Map

@@ -27,6 +28,54 @@ Start at the leftmost broken layer. Do not jump straight to UI rendering unless

 ## 2. Capture Raw CLI Traces First

+### In-app live traces (the faithful capture — prefer this)
+
+The running app already records every CLI session it spawns. This is the most
+faithful trace you can get, because it captures the **exact** spawn args, env
+keys, cwd, `--resume`/`--mcp-config` flags, model, and stdin that the app used —
+things a hand-rolled `claude -p` / `codex exec` repro will not reproduce. Reach
+for this before reproducing manually. The recorder lives in
+`apps/desktop/src/main/controllers/HeterogeneousAgentCtr.ts`
+(`createCliTraceSession`, `shouldTraceCliOutput`, `resolveTraceRootDir`).
+
+When it records:
+
+- **Dev build** (`!app.isPackaged`): always.
+- **Packaged build**: only when the user flips the Help-menu developer toggle
+  (`heteroTracingEnabled`). Off by default so normal runs aren't polluted.
+- Never under `NODE_ENV=test`.
+
+Where it writes:
+
+- Toggle **off** (plain dev run): `<cwd>/.heerogeneous-tracing/` — i.e. inside
+  the repo you're running against. (Yes, the dir name is misspelled
+  `heerogeneous`; it is the real path.)
+- Toggle **on**: `<appStoragePath>/heteroAgent/tracing/` — keeps traces out of
+  the user's project. This is the only path packaged builds ever use.
+
+Layout per session — `.../<agentType>/<YYYYMMDD-HHMMSS>-<sessionId>/`:
+
+- `meta.json` — spawn `args`, `command`, `cwd`, `envKeys`, `model`,
+  `resumeSessionId`/`agentSessionId`, attachment summaries. **Read this first**
+  to know exactly how the CLI was invoked.
+- `stdin.txt` — the stream-json request fed to the CLI.
+- `stdout.jsonl` — the raw provider NDJSON (the trace you actually read).
+- `stderr.log` — CLI stderr.
+- `exit.json` — `{ code, signal, finishedAt }`.
+
+`.heerogeneous-tracing/.last-live-trace` always points at the most recent
+session dir, so the fast path to "what just happened" is:
+
+```bash
+dir=$(cat .heerogeneous-tracing/.last-live-trace)
+cat "$dir/meta.json"      # how the CLI was spawned
+wc -l "$dir/stdout.jsonl" # raw event count
+```
+
+Reproduce the same session yourself by reusing the recorded `meta.json` `args`
+together with `stdin.txt` (the args already include `--resume <sessionId>`),
+instead of guessing flags.
+
 ### Codex raw JSONL

 Use a read-only prompt and save traces under the repo-local scratch directory `.heerogeneous-tracing/`.
@@ -244,3 +293,55 @@ When the bug comes from a real trace, distill it into the closest existing test
 6. Only then do an Electron smoke test with the `agent-testing` skill if UI confirmation is still needed.

 Do not start with a broad Electron repro if a raw trace or adapter test can prove the fault zone faster.
+
+## 8. Verify A Structured-Field Classifier Against A Real Trace
+
+Whenever the adapter **branches on a structured field** from the raw stream —
+`status`, `usage`, `rateLimitType`, `stop_reason`, `parent_tool_use_id`,
+`subtype`, etc. — do not trust your mental model of the wire format. The field
+you key on almost always also appears on **benign / non-target** events, and a
+classifier that ignores the surrounding state will misfire on those.
+
+The procedure (recurring — run it every time):
+
+1. Pull the most recent real session: `dir=$(cat .heerogeneous-tracing/.last-live-trace)`.
+
+2. Grep the field across **every** event state, not just the failing one, and
+   count by co-occurring state. Example:
+
+   ```bash
+   # Which event statuses carry a rate_limit_info block?
+   grep -o '"status":"[a-z]*"' "$dir/stdout.jsonl" | sort | uniq -c
+   grep -c 'rate_limit_info' "$dir/stdout.jsonl"
+   ```
+
+3. If the field rides on states you did not account for, the classifier needs an
+   extra gate. Add the trace as a fixture/assertion to the adapter test so the
+   regression can't come back.
+
+### Worked example: CC usage-limit vs. transient throttle (`fix/cc-rate-limit-quota-misclassify`)
+
+- **Symptom:** an unrelated terminal failure (e.g. an `ECONNRESET` network drop)
+  rendered a bogus "usage limit reached, resets at X" guide.
+- **What the trace showed:** Anthropic stamps a `rate_limit_info` block —
+  carrying `resetsAt` and `rateLimitType` (e.g. `seven_day`) — onto events even
+  when the request **goes through** (`status: "allowed"`). In real traces those
+  reset-window fields appear on \~all `rate_limit_info` blocks, the vast majority
+  of which are `allowed`, not `rejected`. So the window is rolling-window
+  _metadata for an allowed call_, NOT evidence the limit was hit.
+- **The bug:** `isUserQuotaRateLimit` keyed only on the presence of a reset
+  window (`info.resetsAt != null || info.rateLimitType != null`). A later
+  terminal error inherited the last allowed event's window → false positive.
+- **The fix:** require `status === 'rejected'` **and** a concrete reset window.
+  A bare `rejected` with no window is the transient server throttle → leave it
+  to the overloaded (retry) classifier. Status codes (429 / 529) and message
+  text are deliberately not consulted — only this structured signal decides the
+  guide.
+  - `packages/heterogeneous-agents/src/adapters/claudeCode.ts` →
+    `isUserQuotaRateLimit`
+  - regression assertions in
+    `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+
+The general lesson: a field's **presence** is not its **meaning**. Confirm which
+event states a discriminator field co-occurs with in a real recorded trace
+before branching on it.
@@ -18,8 +18,8 @@ Periodic review of the project-local skill set under `.agents/skills/`. The goal
 Build a fresh census of all SKILL.md files. Do NOT trust any prior cached list.

 ```bash
-find .agents/skills -name SKILL.md | wc -l                      # total count
-find .agents/skills -name SKILL.md -exec wc -l {} \; | sort -rn # by body length
+find -L .agents/skills -name SKILL.md | wc -l                      # total count, including symlinked skills
+find -L .agents/skills -name SKILL.md -exec wc -l {} \; | sort -rn # by body length, including symlinked skills
 ```

 Group by domain in a mental table (DB / state / UI / agent / testing / workflow / docs / etc.). Note new arrivals since last audit (`git log --since="1 week ago" -- .agents/skills/`).
@@ -1,6 +1,6 @@
 ---
 name: ux
-description: 'LobeHub product design values (自然 Natural / 意义感 Meaningful / 确定性 Certainty / 生长性 Growth) and per-aspect UX execution checklists. Use when designing or reviewing any user-facing flow — empty/loading/error states, confirmations, async feedback, button hierarchy, action parity, lists at scale, pickers, discoverability, and loading visuals.'
+description: 'LobeHub product design values / principles / checklists. Load this skill whenever the work touches user-interface features or implementation — designing or building any user-facing flow — to get better UX results.'
 user-invocable: false
 ---

@@ -10,35 +10,32 @@ How LobeHub products should feel, and concrete rules to get there. Use this when
 **building or reviewing** any user-facing flow. For component/styling choices see
 **react**, for wording see **microcopy**, for imperative modal wiring see **modal**.

-## Design values (设计价值观)
+## Design values

-LobeHub follows four product design values — **自然 Natural・意义感 Meaningful・
-确定性 Certainty・生长性 Growth**. Read them before designing:
+LobeHub follows four product design values — **Natural・Meaningful・Certainty・
+Growth**. Read them before designing:
 **[references/design-values.md](references/design-values.md)** (definitions +
 conflict priority).

 > The checklists below are the execution layer. Each item is tagged with the
 > value(s) it serves; for what those values mean, see the file above.

-## 1. Flow & momentum (操作链路)・自然・意义感
+## How this is organized

-Every action chain must **push the user forward**, never dead-end or block the flow.
+The checklists are grouped by **interaction type** — the kind of thing the user
+is doing. Jump to the module that matches the surface you're building (reading a
+list, editing content, running an action, …); each module collects the rules
+specific to that interaction. The same surface often spans several modules (an
+editable list is Read + Edit + Act) — walk each that applies.

- [ ] **Forward momentum** — after any operation, lead the user to the next step,
-      don't just stop. _(意义感)_
- [ ] **Success state = primary "go to result", secondary "dismiss"** — the strong
-      button is the forward action (take me to the result); "Done" is the weak/
-      secondary button. ✅ After moving topics: primary = "Go to «target»", secondary
-      \= "Done". _(意义感・自然)_
- [ ] **Bulk ⇄ single-item parity** — an action on a multi-select toolbar must also
-      be reachable on a single item (its context menu), and vice versa. _(确定性)_
- [ ] **Confirm → in-progress → done, in one surface** — bulk/irreversible/async
-      ops use a modal state machine: a confirm step stating exactly what happens →
-      an in-progress view with **dismissal locked** → a done (or error) view in the
-      same modal. Never fire-and-forget with only a toast; never leave a dead
-      spinner. _(确定性・意义感)_
+---

-## 2. States: empty /loading/error (状态设计)・意义感・确定性
+## 1. Read — viewing data & lists
+
+Any surface that **displays** records, lists, or detail. Covers the states a data
+view can be in, behavior at scale, and keeping the user's place visible.
+
+### 1.1 Data states: empty / loading / error・Meaningful・Certainty

 Every data surface has **four** states — design all of them, not just "has data".

@@ -46,64 +43,152 @@ Every data surface has **four** states — design all of them, not just "has dat
      this is, why it's empty, and gives a clear next action (CTA + value props).
      ✅ Devices: an empty "Connect your first device" page with primary/secondary
      connect paths and "what you can do once connected" cards — ❌ not a bare title
-      over skeleton rows or a blank body. _(意义感)_
+      over skeleton rows or a blank body. _(Meaningful)_
 - [ ] **Distinguish the empty variants** — "no data yet" (onboarding CTA) vs
-      "no match for filters" (clear-filters affordance) are different screens. _(确定性)_
+      "no match for filters" (clear-filters affordance) are different screens. _(Certainty)_
+- [ ] **Always-rendered chrome still needs a body empty state.** When a surface
+      keeps its toolbar / header mounted even with no data (so a create / `+`
+      affordance stays reachable), the **body** below it must still render an empty
+      placeholder — persistent chrome is not an excuse to leave the content area
+      blank. ✅ The agent **Documents** tab keeps its new-folder / new-doc toolbar
+      and renders an `Empty` below it when there are no documents — ❌ not a toolbar
+      over dead space. _(Meaningful)_
 - [ ] **Loading state** designed (skeleton / NeuralNetworkLoading), not a flash of
-      blank or layout shift. _(自然)_
- [ ] **Error state** designed — surface the reason and a retry/back path. _(意义感)_
+      blank or layout shift. _(Natural)_
+- [ ] **Error state** designed — surface the reason and a retry/back path. _(Meaningful)_

-## 3. Buttons & focus (按钮与焦点)・确定性
-
- [ ] **One primary button per surface.** The single primary CTA tells the user the
-      core action; everything else is secondary/tertiary. Never a pile of primary
-      buttons competing for attention. _(确定性)_
-
-## 4. Lists at scale (列表与规模)・确定性・自然
+### 1.2 Lists at scale・Certainty・Natural

 A list/data page must be designed for its **whole range of sizes**, not just the
 demo data.

 - [ ] **Walk the scale: 1 / 2 / 5 / 20 / 100 / 1k–10k rows.** Pick the right
      mechanism per range — plain render → load-more / pagination → virtual scroll;
-      add batch-select / bulk actions once counts get large. _(确定性)_
- [ ] **Co-design empty / loading / error with the data state** (see §2). A list
-      isn't done until all four render well. _(自然)_
+      add batch-select / bulk actions once counts get large. _(Certainty)_
+- [ ] **Co-design empty / loading / error with the data state** (see §1.1). A list
+      isn't done until all four render well. _(Natural)_

-## 5. Option visibility (选项可见性)・确定性・意义感
+### 1.3 Selection visibility in scrolled lists・Certainty・Natural
+
+A capped / scrollable / virtualized list mounts at `scrollTop = 0`. If the
+active item sits below the fold, the user lands on a valid selection that is
+**off-screen** — and reads it as "nothing is selected" or a broken page. Any
+list that can open with a pre-selected item must **scroll that item into view**.
+This is an easy case to miss: it only shows up once the list is long enough and
+the selection is restored rather than freshly clicked.
+
+- [ ] **Scroll the active item into view on mount / restore.** When the selection
+      is restored from a URL query, deep link, or persisted state (not a fresh
+      click), bring it into view — the container starts at the top otherwise. ✅
+      The nested thread list is capped to \~9 rows; a thread restored from
+      `?thread=` below the fold is scrolled into view on mount. _(Certainty)_
+- [ ] **Hardest when the selection has no other anchor.** If the parent/container
+      row isn't highlighted while a child is active (no breadcrumb, no header
+      echo), an off-screen active row means **zero** visible feedback — design
+      for exactly this case. _(Meaningful)_
+- [ ] **Use `block: 'nearest'` (or equivalent).** Only scroll when the row is
+      actually off-screen; an already-visible selection must not jump. _(Natural)_
+- [ ] **Re-run once async rows mount.** The active id is usually known before the
+      list finishes loading; key the scroll off a list-ready signal (e.g. row
+      count), not only off the id, so a restored selection still lands when the
+      data arrives. _(Certainty)_
+- [ ] **Mirror it across duplicated list variants** so the behavior can't regress
+      in just one (e.g. parallel agent / group lists). _(Certainty)_
+
+### 1.4 Option visibility in pickers・Certainty・Meaningful

 - [ ] **Pickers list every valid target.** Watch for options dropped by backend
      list queries (pagination, `virtual` flags, scope filters) and add them back.
      ✅ The default "LobeAI" (inbox) agent is `virtual` and excluded from the
      sidebar list, so the move picker re-adds it. An empty picker must mean
-      "genuinely none", never "we filtered out the only option". _(意义感)_
+      "genuinely none", never "we filtered out the only option". _(Meaningful)_

-## 6. Loading visuals (Loading 视觉)・自然
+### 1.5 Default view reflects entry intent & data state・Certainty・Meaningful

-**Never use antd `Spin`** — it doesn't match the product's loading visual. Use a
-project loader:
+A surface with multiple tabs / views / panels has a **landing** selection. Don't
+hardcode it to "the first tab" — derive it from **(a) how the user got here** (the
+intent their navigation carried) and **(b) which views actually have data**. A
+static default that lands the user on an empty tab while a sibling holds exactly
+what they came for reads as broken. This pairs with §1.1: the empty state is the
+fallback _within_ a view; this rule is about not landing on that empty view in the
+first place when a better one exists.

-| Need                        | Component                                                                     |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| Default loading (in-flight) | `NeuralNetworkLoading` from `@/components/NeuralNetworkLoading` (`size` prop) |
-| Inline dots                 | `DotsLoading` / `BubblesLoading` from `@/components`                          |
-| Branded full-page           | `Loading` from `@/components/Loading/BrandTextLoading`                        |
-| List / card placeholder     | a skeleton (e.g. `SkeletonList`)                                              |
+- [ ] **Open on the tab the entry implies.** When navigation carries intent — the
+      user clicked a Skill, a file, a record of a specific type — land on the view
+      that shows it, not the static first tab. ✅ Opening a document page by clicking
+      a **skill** lands the right panel on the **Skills** tab; opening a plain
+      document lands on **Documents**. _(Meaningful)_
+- [ ] **Fall back to a populated view when the default would be empty.** If the
+      default tab has no data but a sibling does, default to the populated one so
+      the surface opens on content. ✅ An agent with only skills (no documents)
+      opens the panel on **Skills** instead of an empty **Documents** tab. _(Certainty)_
+- [ ] **Decide from resolved state, not mid-load.** Compute the default once the
+      data has loaded — choosing off an empty _in-flight_ list flips the tab as data
+      arrives. Hold the static default while loading, switch on resolved-empty. _(Certainty)_
+- [ ] **A manual choice wins and sticks.** Once the user picks a tab, stop
+      auto-selecting — track "user-picked" separately (e.g. a nullable `pickedTab`
+      that overrides the derived default) so later data changes don't yank them off
+      their choice. _(Natural)_

-When in doubt, reach for `NeuralNetworkLoading` — it's the default in-flight
-indicator (e.g. modal "in progress" states).
+---

-## 7. Discoverability & growth (可发现性与生长)・生长性
+## 2. Edit — entering & changing content

-The product should grow with the user — deeper power shows up as needs deepen.
+Any surface where the user **types or edits**. Input is expensive effort; the
+overriding rule is **never lose it**.

- [ ] **Progressive disclosure** — keep the novice path clean; reveal advanced
-      capabilities as the user gets there, don't dump everything at once. _(生长性・自然)_
- [ ] **Surface related actions at the moment of need** — make the next capability
-      discoverable in context (e.g. after the first item exists, offer what to do
-      with it), not buried in a far-off menu. _(生长性・意义感)_
+### 2.1 Protect in-progress edits・Certainty・Meaningful

-## 8. Entity lifecycle completeness (实体生命周期完整性)・意义感・确定性
+Typed / edited content is real user effort; losing it is one of the most
+infuriating outcomes a product can produce. Whenever an editor holds unsaved
+input, assume the exit can be **accidental** — a misclick, a refresh, a crash, a
+navigation, a failed save — and build a safety net: back the draft up locally and
+recover it.
+
+- [ ] **Back up the draft locally as the user types.** Persist to
+      localStorage / IndexedDB / store so a refresh, crash, accidental close, or
+      navigation doesn't vaporize the content. _(Certainty)_
+- [ ] **Restore on return.** Coming back to the same editing context auto-restores
+      (or offers to restore) the unsaved draft, rather than showing a blank field. _(Meaningful)_
+- [ ] **Guard destructive exits.** Closing / navigating / switching items away
+      from a dirty editor warns or auto-saves — never silently discards. _(Certainty)_
+- [ ] **Survive a failed save.** If the save errors, keep the user's content in
+      the field / draft and let them retry; never clear the input on failure. _(Meaningful)_
+- [ ] **Scope the draft to its target** (per topic / message / item id) so drafts
+      don't bleed across entities or resurrect on the wrong item. _(Certainty)_
+
+---
+
+## 3. Act — operations, flows & buttons
+
+Any surface where the user **performs an action** — a single op, a bulk op, or a
+multi-step flow. Covers momentum, focus, and full entity lifecycle.
+
+### 3.1 Flow & momentum・Natural・Meaningful
+
+Every action chain must **push the user forward**, never dead-end or block the flow.
+
+- [ ] **Forward momentum** — after any operation, lead the user to the next step,
+      don't just stop. _(Meaningful)_
+- [ ] **Success state = primary "go to result", secondary "dismiss"** — the strong
+      button is the forward action (take me to the result); "Done" is the weak/
+      secondary button. ✅ After moving topics: primary = "Go to «target»", secondary
+      \= "Done". _(Meaningful・Natural)_
+- [ ] **Bulk ⇄ single-item parity** — an action on a multi-select toolbar must also
+      be reachable on a single item (its context menu), and vice versa. _(Certainty)_
+- [ ] **Confirm → in-progress → done, in one surface** — bulk/irreversible/async
+      ops use a modal state machine: a confirm step stating exactly what happens →
+      an in-progress view with **dismissal locked** → a done (or error) view in the
+      same modal. Never fire-and-forget with only a toast; never leave a dead
+      spinner. _(Certainty・Meaningful)_
+
+### 3.2 One primary button per surface・Certainty
+
+- [ ] **One primary button per surface.** The single primary CTA tells the user the
+      core action; everything else is secondary/tertiary. Never a pile of primary
+      buttons competing for attention. _(Certainty)_
+
+### 3.3 Entity lifecycle completeness・Meaningful・Certainty

 The recurring trap: a feature ships only the **display** of a list, but edit /
 delete / management are never built — so the user can add something and then be
@@ -122,28 +207,110 @@ it explicitly _before_ building. Worked example, the tools/connectors list:
 | User-custom (custom connector)      | create  | edit      | delete             |

 - [ ] **No display-only features.** For every listed entity, enumerate CRUD +
-      lifecycle ops and build the ones that apply. _(意义感)_
+      lifecycle ops and build the ones that apply. _(Meaningful)_
 - [ ] **Operation set per source/ownership class** — built-in may be read-only;
      anything the user _installed_ must be removable; anything the user _created_
-      must be editable **and** deletable. _(确定性)_
+      must be editable **and** deletable. _(Certainty)_
 - [ ] **Each item exposes its allowed ops** (hover action / context menu / detail
-      page), and there's a clear entry point to add/create where applicable. _(自然)_
+      page), and there's a clear entry point to add/create where applicable. _(Natural)_
 - [ ] **An intentionally-absent op is a documented decision, not an oversight**
-      (e.g. official tools can't be deleted — by design). _(确定性)_
+      (e.g. official tools can't be deleted — by design). _(Certainty)_
+
+---
+
+## 4. Feedback — loading & system response
+
+How the product **answers back** while and after the user acts — loading visuals
+and proactive guardrails.
+
+### 4.1 Loading visuals・Natural
+
+**Never use antd `Spin`** — it doesn't match the product's loading visual. Use a
+project loader:
+
+| Need                        | Component                                                                     |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| Default loading (in-flight) | `NeuralNetworkLoading` from `@/components/NeuralNetworkLoading` (`size` prop) |
+| Inline dots                 | `DotsLoading` / `BubblesLoading` from `@/components`                          |
+| Branded full-page           | `Loading` from `@/components/Loading/BrandTextLoading`                        |
+| List / card placeholder     | a skeleton (e.g. `SkeletonList`)                                              |
+
+When in doubt, reach for `NeuralNetworkLoading` — it's the default in-flight
+indicator (e.g. modal "in progress" states).
+
+### 4.2 Capability-gated features・Certainty・Meaningful
+
+A feature can be fully built and still produce a broken result when the selected
+model — or its still-loading config — **can't deliver the capability the feature
+depends on** (for example, an agentic run on a model without tool calling). This
+is usually the user's configuration choice, not a defect; but if the product stays
+silent the user reads it as the product being broken. When a feature's success
+depends on a capability the current config may lack, the product owes a
+**proactive, non-blocking reminder** — a guardrail, not a gate.
+
+- [ ] **Surface the mismatch, don't fail silently.** When a feature needs a model
+      capability (tool calling, vision, reasoning, long context) the current model
+      lacks, show a soft inline warning at the point of action — never a hard block
+      or a modal that stops the user. _(Meaningful)_
+- [ ] **Stay reactive.** The reminder clears the moment the user switches to a
+      capable model — derive it from live state, not a one-shot check. _(Natural)_
+- [ ] **Don't warn while config is loading.** A capability that hasn't resolved yet
+      looks "unsupported"; warning then is a false alarm — exactly the glitch users
+      mistake for a product bug. Warn only on a _resolved_ unsupported state. _(Certainty)_
+- [ ] **Scope to the mode that needs it.** Show only when the capability-dependent
+      mode is on; one reminder per root cause, never a pile of overlapping notices. _(Natural・Certainty)_
+- [ ] **State the problem and the remedy.** The copy says what's wrong _and_ what
+      the user should do about it. _(Meaningful)_
+
+---
+
+## 5. Grow — discoverability & progressive disclosure
+
+How the product **deepens** as the user's needs deepen.
+
+### 5.1 Progressive disclosure・Growth
+
+The product should grow with the user — deeper power shows up as needs deepen.
+
+- [ ] **Progressive disclosure** — keep the novice path clean; reveal advanced
+      capabilities as the user gets there, don't dump everything at once. _(Growth・Natural)_
+- [ ] **Surface related actions at the moment of need** — make the next capability
+      discoverable in context (e.g. after the first item exists, offer what to do
+      with it), not buried in a far-off menu. _(Growth・Meaningful)_
+
+---

 ## Quick review checklist

+**Read — viewing data & lists**
+
+- [ ] Empty / loading / error states are all designed; empty is a real page with a CTA. Always-rendered chrome (toolbar/header) still gets a body empty state.
+- [ ] List designed across 1 → 10k rows (virtual scroll / pagination / batch as needed).
+- [ ] Capped/scrollable/virtualized list scrolls the restored active item into view on mount (`block: 'nearest'`, re-run after async rows mount).
+- [ ] Pickers show all valid targets (default/inbox included); empty = truly none.
+- [ ] Multi-tab/view surface lands on the tab the entry intent implies (and falls back to a populated view, decided from resolved state); a manual pick sticks.
+
+**Edit — entering & changing content**
+
+- [ ] Editors back up in-progress input locally and recover it after refresh/crash/failed-save; destructive exits warn, never silently discard.
+
+**Act — operations, flows & buttons**
+
 - [ ] Action leads the user forward; success offers a primary "go to result".
 - [ ] Bulk action has a single-item entry (and vice versa).
 - [ ] Async/bulk/irreversible action: confirm → in-progress (locked) → done/error.
- [ ] Empty / loading / error states are all designed; empty is a real page with a CTA.
 - [ ] Exactly one primary button per surface.
- [ ] List designed across 1 → 10k rows (virtual scroll / pagination / batch as needed).
- [ ] Pickers show all valid targets (default/inbox included); empty = truly none.
- [ ] No antd `Spin`; use `NeuralNetworkLoading` / project loaders.
- [ ] Advanced capability is progressively disclosed / discoverable at the moment of need.
 - [ ] Listed entities have their full lifecycle (not display-only); ops match source (built-in / installed / custom).

+**Feedback — loading & system response**
+
+- [ ] No antd `Spin`; use `NeuralNetworkLoading` / project loaders.
+- [ ] Capability-gated feature warns (soft, reactive, load-gated) when the model can't deliver it; copy gives the remedy.
+
+**Grow — discoverability & progressive disclosure**
+
+- [ ] Advanced capability is progressively disclosed / discoverable at the moment of need.
+
 ## Related skills

 - **modal** — imperative `createModal` state-machine wiring for confirm/progress/done.
@@ -425,14 +425,14 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # MCP_TOOL_TIMEOUT=60000

 # #######################################
-# ######### Klavis Service ##############
+# ######### Composio Service ############
 # #######################################

-# Klavis API Key for accessing Strata hosted MCP servers
-# Get your API key from: https://klavis.io
+# Composio API Key for accessing hosted integrations (Gmail, Slack, etc.)
+# Get your API key from: https://composio.dev
 # IMPORTANT: This key is stored server-side only and NEVER exposed to the client
-# When this key is set, Klavis integration will be automatically enabled
-# KLAVIS_API_KEY=your_klavis_api_key_here
+# When this key is set, Composio integration will be automatically enabled
+# COMPOSIO_API_KEY=your_composio_api_key_here

 # #######################################
 # #### Message Gateway (IM Integration) ##
@@ -6,7 +6,7 @@ const prComment = async ({ github, context, releaseUrl, artifactsUrl, version, t
  const COMMENT_IDENTIFIER = '<!-- DESKTOP-BUILD-COMMENT -->';

  /**
-   * 生成评论内容
+   * Generate comment body content
   */
  const generateCommentBody = async () => {
    try {
@@ -34,7 +34,7 @@ module.exports = defineConfig({
  markdown: {
    reference:
      'You need to maintain the component format of the mdx file; the output text does not need to be wrapped in any code block syntax on the outermost layer.\n' +
-      fs.readFileSync(path.join(__dirname, 'docs/glossary.md'), 'utf8'),
+      fs.readFileSync(path.join(__dirname, 'docs/glossary.mdx'), 'utf8'),
    entry: ['./README.md', './docs/**/*.md', './docs/**/*.mdx'],
    entryLocale: 'en-US',
    outputLocales: ['zh-CN'],
@@ -2,6 +2,31 @@

 # Changelog

+## [Version 2.2.6](https://github.com/lobehub/lobe-chat/compare/v2.2.6-canary.8...v2.2.6)
+
+<sup>Released on **2026-06-17**</sup>
+
+#### ✨ Features
+
+- **agent**: improve connector, document, and fleet workflows.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **agent**: improve connector, document, and fleet workflows, closes [#15936](https://github.com/lobehub/lobe-chat/issues/15936) ([3f82033](https://github.com/lobehub/lobe-chat/commit/3f82033))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ## [Version 2.2.1](https://github.com/lobehub/lobe-chat/compare/v0.0.0-nightly.pr15228.13999...v2.2.1)

 <sup>Released on **2026-05-29**</sup>
@@ -1,4 +1,7 @@
 import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';

 import { describe, expect, it } from 'vitest';

@@ -77,6 +80,40 @@ describe('lh file - E2E', () => {
    });
  });

+  // ── upload (local file) ───────────────────────────────
+
+  describe('upload', () => {
+    it('should upload a local file passed as a positional argument', () => {
+      const tmpFile = path.join(os.tmpdir(), `lh-e2e-upload-${Date.now()}.txt`);
+      fs.writeFileSync(tmpFile, 'hello from lh e2e upload');
+
+      try {
+        const result = runJson<{ id: string }>(`file upload ${tmpFile} --json id`);
+        expect(result).toHaveProperty('id');
+        if (result.id) run(`file delete ${result.id} --yes`);
+      } finally {
+        fs.rmSync(tmpFile, { force: true });
+      }
+    });
+
+    it('should upload a local file passed via --file', () => {
+      const tmpFile = path.join(os.tmpdir(), `lh-e2e-upload-f-${Date.now()}.txt`);
+      fs.writeFileSync(tmpFile, 'hello from lh e2e --file upload');
+
+      try {
+        const result = runJson<{ id: string }>(`file upload --file ${tmpFile} --json id`);
+        expect(result).toHaveProperty('id');
+        if (result.id) run(`file delete ${result.id} --yes`);
+      } finally {
+        fs.rmSync(tmpFile, { force: true });
+      }
+    });
+
+    it('should error when the local file does not exist', () => {
+      expect(() => run('file upload -f /no/such/lh-file.txt')).toThrow();
+    });
+  });
+
  // ── recent ────────────────────────────────────────────

  describe('recent', () => {
@@ -1,6 +1,6 @@
 .\" Code generated by `npm run man:generate`; DO NOT EDIT.
 .\" Manual command details come from the Commander command tree.
-.TH LH 1 "" "@lobehub/cli 0.0.29" "User Commands"
+.TH LH 1 "" "@lobehub/cli 0.0.34" "User Commands"
 .SH NAME
 lh \- LobeHub CLI \- manage and connect to LobeHub services
 .SH SYNOPSIS
@@ -41,6 +41,9 @@ Show a manual page for the CLI or a subcommand
 .B connect
 Connect to the device gateway and listen for tool calls
 .TP
+.B disconnect
+Disconnect from the device gateway (alias for `connect stop`)
+.TP
 .B device
 Manage connected devices
 .TP
@@ -127,6 +130,9 @@ Manage evaluation workflows
 .TP
 .B migrate
 Migrate data from external tools (OpenClaw, ChatGPT, Claude, etc.)
+.TP
+.B update
+Update the LobeHub CLI to the latest published version
 .SH OPTIONS
 .TP
 .B \-V, \-\-version
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.29",
+  "version": "0.0.34",
  "type": "module",
  "bin": {
    "lh": "./dist/index.js",
@@ -37,6 +37,7 @@
    "@lobechat/tool-runtime": "workspace:*",
    "@trpc/client": "^11.8.1",
    "@types/node": "^24.13.2",
+    "@types/semver": "^7.7.1",
    "@types/ws": "^8.18.1",
    "commander": "^13.1.0",
    "dayjs": "^1.11.19",
@@ -45,6 +46,7 @@
    "fast-glob": "^3.3.3",
    "ignore": "^7.0.5",
    "picocolors": "^1.1.1",
+    "semver": "^7.7.3",
    "superjson": "^2.2.6",
    "tsdown": "^0.21.4",
    "typescript": "^6.0.3",
@@ -12,7 +12,8 @@ import { log } from '../utils/logger';
 export type TrpcClient = ReturnType<typeof createTRPCClient<LambdaRouter>>;
 export type ToolsTrpcClient = ReturnType<typeof createTRPCClient<ToolsRouter>>;

-let _client: TrpcClient | undefined;
+const PERSONAL_KEY = '__personal__';
+const _clients = new Map<string, TrpcClient>();
 let _toolsClient: ToolsTrpcClient | undefined;

 async function getAuthAndServer() {
@@ -53,21 +54,40 @@ async function getAuthAndServer() {
  };
 }

-export async function getTrpcClient(): Promise<TrpcClient> {
-  if (_client) return _client;
+/**
+ * Resolve the workspace scope for outbound tRPC calls.
+ *
+ * Precedence: explicit caller arg → `LOBEHUB_WORKSPACE_ID` env (inherited
+ * from a workspace-dispatched parent process, e.g. openclaw spawned by the
+ * device's `runHeteroTask`) → personal mode. Without this, agentNotify
+ * callbacks on workspace topics would resolve through personal-mode
+ * TopicModel and 404.
+ */
+function resolveWorkspaceId(explicit?: string): string | undefined {
+  if (explicit) return explicit;
+  const fromEnv = process.env.LOBEHUB_WORKSPACE_ID;
+  return fromEnv && fromEnv.length > 0 ? fromEnv : undefined;
+}
+
+export async function getTrpcClient(workspaceId?: string): Promise<TrpcClient> {
+  const wsId = resolveWorkspaceId(workspaceId);
+  const cacheKey = wsId ?? PERSONAL_KEY;
+  const cached = _clients.get(cacheKey);
+  if (cached) return cached;

  const { headers, serverUrl } = await getAuthAndServer();
-  _client = createTRPCClient<LambdaRouter>({
+  const client = createTRPCClient<LambdaRouter>({
    links: [
      httpLink({
-        headers,
+        headers: wsId ? { ...headers, 'X-Workspace-Id': wsId } : headers,
        transformer: superjson,
        url: `${serverUrl}/trpc/lambda`,
      }),
    ],
  });
+  _clients.set(cacheKey, client);

-  return _client;
+  return client;
 }

 /**
@@ -77,13 +97,19 @@ export async function getTrpcClient(): Promise<TrpcClient> {
 * via env/stored creds and `process.exit(1)` when none exist, which would
 * abort an otherwise-valid explicit-token session.
 */
-export function createLambdaClient(auth: {
-  serverUrl: string;
-  token: string;
-  tokenType: 'apiKey' | 'jwt' | 'serviceToken';
-}): TrpcClient {
-  const headers =
-    auth.tokenType === 'apiKey' ? { 'X-API-Key': auth.token } : { 'Oidc-Auth': auth.token };
+export function createLambdaClient(
+  auth: {
+    serverUrl: string;
+    token: string;
+    tokenType: 'apiKey' | 'jwt' | 'serviceToken';
+  },
+  /** When set, scopes the request to a workspace (e.g. workspace-device enrollment). */
+  workspaceId?: string,
+): TrpcClient {
+  const headers: Record<string, string> = {
+    ...(auth.tokenType === 'apiKey' ? { 'X-API-Key': auth.token } : { 'Oidc-Auth': auth.token }),
+    ...(workspaceId ? { 'X-Workspace-Id': workspaceId } : {}),
+  };

  return createTRPCClient<LambdaRouter>({
    links: [httpLink({ headers, transformer: superjson, url: `${auth.serverUrl}/trpc/lambda` })],
@@ -21,15 +21,6 @@ vi.mock('../settings', () => ({
  saveSettings: vi.fn(),
 }));

-vi.mock('../device/register', () => ({
-  registerDevice: vi.fn().mockResolvedValue(undefined),
-  resolveDeviceIdentity: vi.fn((userId?: string, explicitDeviceId?: string) =>
-    userId || explicitDeviceId
-      ? { deviceId: explicitDeviceId ?? 'mock-device-id', identitySource: 'machine-id' }
-      : undefined,
-  ),
-}));
-
 vi.mock('../utils/logger', () => ({
  log: {
    debug: vi.fn(),
@@ -235,7 +226,7 @@ describe('connect command', () => {
      type: 'tool_call_request',
    });

-    expect(executeToolCall).toHaveBeenCalledWith('readLocalFile', '{"path":"/test"}', undefined);
+    expect(executeToolCall).toHaveBeenCalledWith('readLocalFile', '{"path":"/test"}');
    expect(lastSentToolResponse).toEqual({
      requestId: 'req-1',
      result: { content: 'tool result', error: undefined, success: true },
@@ -270,8 +261,6 @@ describe('connect command', () => {
  });

  it('should retry auth_failed with token refresh when new token available', async () => {
-    const program = createProgram();
-    await program.parseAsync(['node', 'test', 'connect']);
    vi.mocked(resolveToken).mockResolvedValueOnce({
      serverUrl: 'https://app.lobehub.com',
      token: 'refreshed-token',
@@ -279,6 +268,9 @@ describe('connect command', () => {
      userId: 'test-user',
    });

+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'connect']);
+
    const mockClient = vi.mocked(GatewayClient).mock.results[0].value;

    await clientEventHandlers['auth_failed']?.('token expired');
@@ -288,9 +280,7 @@ describe('connect command', () => {
    expect(exitSpy).not.toHaveBeenCalled();
  });

-  it('should refresh and reconnect on auth_expired', async () => {
-    const program = createProgram();
-    await program.parseAsync(['node', 'test', 'connect']);
+  it('should handle auth_expired', async () => {
    vi.mocked(resolveToken).mockResolvedValueOnce({
      serverUrl: 'https://app.lobehub.com',
      token: 'new-tok',
@@ -298,14 +288,14 @@ describe('connect command', () => {
      userId: 'user',
    });

-    const mockClient = vi.mocked(GatewayClient).mock.results[0].value;
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'connect']);

    await clientEventHandlers['auth_expired']?.();

-    expect(log.info).toHaveBeenCalledWith(expect.stringContaining('Token refreshed'));
-    expect(mockClient.updateToken).toHaveBeenCalledWith('new-tok');
-    expect(mockClient.reconnect).toHaveBeenCalled();
-    expect(exitSpy).not.toHaveBeenCalled();
+    expect(log.error).toHaveBeenCalledWith(expect.stringContaining('expired'));
+    expect(cleanupAllProcesses).toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
  });

  it('should ignore auth_expired for api key auth', async () => {
@@ -450,6 +440,25 @@ describe('connect command', () => {
    });
  });

+  describe('disconnect (alias for connect stop)', () => {
+    it('should stop running daemon', async () => {
+      mockRunningPid = 12345;
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'disconnect']);
+
+      expect(stopDaemon).toHaveBeenCalled();
+      expect(log.info).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
+    });
+
+    it('should warn if no daemon is running', async () => {
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'disconnect']);
+
+      expect(log.warn).toHaveBeenCalledWith(expect.stringContaining('No daemon'));
+    });
+  });
+
  describe('connect status', () => {
    it('should show no daemon running', async () => {
      const program = createProgram();
@@ -18,7 +18,6 @@ import type {
 import { GatewayClient } from '@lobechat/device-gateway-client';
 import type { Command } from 'commander';

-import { getValidToken } from '../auth/refresh';
 import { resolveToken } from '../auth/resolveToken';
 import { CLI_API_KEY_ENV } from '../constants/auth';
 import { OFFICIAL_GATEWAY_URL } from '../constants/urls';
@@ -34,7 +33,13 @@ import {
  writeStatus,
 } from '../daemon/manager';
 import { spawnHeteroAgentRun } from '../device/agentRun';
-import { registerDevice, resolveDeviceIdentity } from '../device/register';
+import {
+  mintWorkspaceConnectToken,
+  registerDevice,
+  registerWorkspaceDevice,
+  resolveDeviceIdentity,
+  resolveWorkspaceDeviceIdentity,
+} from '../device/register';
 import { loadOrCreateConnectionId, loadSettings, normalizeUrl, saveSettings } from '../settings';
 import { executeToolCall } from '../tools';
 import { cleanupAllProcesses } from '../tools/shell';
@@ -47,6 +52,8 @@ interface ConnectOptions {
  gateway?: string;
  token?: string;
  verbose?: boolean;
+  /** Enroll this machine as a device of the given workspace (admin only). */
+  workspace?: string;
 }

 export function registerConnectCommand(program: Command) {
@@ -56,6 +63,7 @@ export function registerConnectCommand(program: Command) {
    .option('--token <jwt>', 'JWT access token')
    .option('--gateway <url>', 'Device gateway URL')
    .option('--device-id <id>', 'Device ID (auto-generated if not provided)')
+    .option('--workspace <id>', 'Enroll as a device of this workspace (admin only)')
    .option('-v, --verbose', 'Enable verbose logging')
    .option('-d, --daemon', 'Run as a background daemon process')
    .option('--daemon-child', 'Internal: runs as the daemon child process')
@@ -74,17 +82,7 @@ export function registerConnectCommand(program: Command) {
    });

  // Subcommands
-  connectCmd
-    .command('stop')
-    .description('Stop the background daemon process')
-    .action(() => {
-      const stopped = stopDaemon();
-      if (stopped) {
-        log.info('Daemon stopped.');
-      } else {
-        log.warn('No daemon is running.');
-      }
-    });
+  connectCmd.command('stop').description('Stop the background daemon process').action(handleStop);

  connectCmd
    .command('status')
@@ -148,10 +146,27 @@ export function registerConnectCommand(program: Command) {
      }
      handleDaemonStart({ ...options, daemon: true });
    });
+
+  // Top-level alias for `connect stop`. Users who run `lh connect` naturally
+  // reach for `lh disconnect` to undo it; the nested `connect stop` is not
+  // discoverable enough on its own.
+  program
+    .command('disconnect')
+    .description('Disconnect from the device gateway (alias for `connect stop`)')
+    .action(handleStop);
 }

 // --- Internal helpers ---

+function handleStop() {
+  const stopped = stopDaemon();
+  if (stopped) {
+    log.info('Daemon stopped.');
+  } else {
+    log.warn('No daemon is running.');
+  }
+}
+
 function handleDaemonStart(options: ConnectOptions) {
  const existingPid = getRunningDaemonPid();
  if (existingPid !== null) {
@@ -178,6 +193,7 @@ function buildDaemonArgs(options: ConnectOptions): string[] {
  if (options.token) args.push('--token', options.token);
  if (options.gateway) args.push('--gateway', options.gateway);
  if (options.deviceId) args.push('--device-id', options.deviceId);
+  if (options.workspace) args.push('--workspace', options.workspace);
  if (options.verbose) args.push('--verbose');

  return args;
@@ -202,10 +218,43 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {

  const resolvedGatewayUrl = gatewayUrl || OFFICIAL_GATEWAY_URL;

+  // Workspace enrollment: the device joins a workspace pool (reachable by all
+  // members) instead of the personal pool. It authenticates with a minted
+  // workspace-device token (carrying the `workspace_id` claim) and uses a
+  // workspace-derived deviceId. `auth` stays the admin's identity — used only to
+  // (re-)mint the connect token and register the row.
+  const workspaceId = options.workspace;
+
  // Resolve a stable device identity. An explicit `--device-id` wins (lets a
  // user pin a VM to a fixed identity); otherwise derive from the machine id so
-  // the same machine + user maps to one device across reconnects.
-  const identity = resolveDeviceIdentity(auth.userId, options.deviceId);
+  // the same machine maps to one device across reconnects.
+  const identity = workspaceId
+    ? resolveWorkspaceDeviceIdentity(workspaceId, options.deviceId)
+    : resolveDeviceIdentity(auth.userId, options.deviceId);
+
+  // The token the gateway socket authenticates with. Re-minted on refresh for
+  // workspace devices (see `refreshConnectToken`).
+  let connectToken = auth.token;
+  let connectTokenType: 'apiKey' | 'jwt' | 'serviceToken' = auth.tokenType;
+  if (workspaceId) {
+    const minted = await mintWorkspaceConnectToken(auth, workspaceId);
+    connectToken = minted.token;
+    connectTokenType = 'jwt';
+  }
+
+  // Re-resolve the admin auth and, for workspace mode, re-mint the connect token.
+  const refreshConnectToken = async (): Promise<string | undefined> => {
+    const refreshed = await resolveToken({});
+    if (!refreshed) return undefined;
+    auth = refreshed;
+    if (workspaceId) {
+      const minted = await mintWorkspaceConnectToken(auth, workspaceId);
+      connectToken = minted.token;
+      return connectToken;
+    }
+    connectToken = refreshed.token;
+    return connectToken;
+  };

  // Freeform channel label (`cli` by default); `LOBEHUB_CLI_CHANNEL` lets a
  // dev build tag itself `cli-dev` so the gateway can prioritise / display it.
@@ -218,9 +267,10 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    gatewayUrl: resolvedGatewayUrl,
    logger: isDaemonChild ? createDaemonLogger() : log,
    serverUrl: auth.serverUrl,
-    token: auth.token,
-    tokenType: auth.tokenType,
-    userId: auth.userId,
+    token: connectToken,
+    tokenType: connectTokenType,
+    userId: workspaceId ? undefined : auth.userId,
+    workspaceId,
  });

  const info = (msg: string) => {
@@ -337,7 +387,6 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
      const ack = await spawnHeteroAgentRun(
        {
          agentType: request.agentType,
-          command: request.command,
          cwd: request.cwd,
          imageList: request.imageList,
          jwt: request.jwt,
@@ -370,15 +419,21 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    updateStatus('reconnecting');
  });

-  // Proactive token refresh — schedule before JWT expires
-  const startProactiveRefresh = () =>
+  // Proactive token refresh — schedule before the connect token expires. For a
+  // workspace device `refreshConnectToken` re-mints the workspace token; for a
+  // personal device it refreshes the user token. Scheduling watches the actual
+  // connect token, so the workspace token's shorter life is respected.
+  const startProactiveRefresh = (): (() => void) | null =>
    scheduleProactiveRefresh(
-      auth,
-      (refreshed) => {
-        client.updateToken(refreshed.token);
-        auth = refreshed;
-        // Schedule next refresh based on the new token
-        cancelRefreshTimer = startProactiveRefresh();
+      connectToken,
+      connectTokenType,
+      async () => {
+        const newToken = await refreshConnectToken();
+        if (newToken) {
+          client.updateToken(newToken);
+          cancelRefreshTimer = startProactiveRefresh();
+        }
+        return newToken;
      },
      info,
      error,
@@ -389,15 +444,15 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
  // (e.g., auto-reconnect may send an expired JWT before proactive refresh fires)
  let authFailedRefreshAttempted = false;
  client.on('auth_failed', async (reason) => {
-    if (auth.tokenType === 'jwt' && !authFailedRefreshAttempted) {
+    if (connectTokenType === 'jwt' && !authFailedRefreshAttempted) {
      authFailedRefreshAttempted = true;
      info(`Authentication failed (${reason}). Attempting token refresh...`);
      try {
-        const refreshed = await resolveToken({});
-        if (refreshed && refreshed.token !== auth.token) {
+        const prev = connectToken;
+        const newToken = await refreshConnectToken();
+        if (newToken && newToken !== prev) {
          info('Token refreshed successfully. Reconnecting...');
-          client.updateToken(refreshed.token);
-          auth = refreshed;
+          client.updateToken(newToken);
          authFailedRefreshAttempted = false;
          cancelRefreshTimer = startProactiveRefresh();
          await client.reconnect();
@@ -418,7 +473,7 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {

  // Handle auth expired — refresh token and reconnect automatically
  client.on('auth_expired', async () => {
-    if (auth.tokenType === 'apiKey') {
+    if (connectTokenType === 'apiKey') {
      // API keys don't expire; ignore stale auth_expired signals
      return;
    }
@@ -426,11 +481,10 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    info('Authentication expired. Attempting to refresh token...');

    try {
-      const refreshed = await resolveToken({});
-      if (refreshed) {
+      const newToken = await refreshConnectToken();
+      if (newToken) {
        info('Token refreshed successfully. Reconnecting...');
-        client.updateToken(refreshed.token);
-        auth = refreshed;
+        client.updateToken(newToken);
        cancelRefreshTimer = startProactiveRefresh();
        await client.reconnect();
        return;
@@ -480,7 +534,8 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    try {
      // Reuse the already-resolved auth (respects `--token` mode) so we don't
      // re-discover creds and exit when none are found.
-      await registerDevice(auth, identity);
+      if (workspaceId) await registerWorkspaceDevice(auth, identity, workspaceId);
+      else await registerDevice(auth, identity);
    } catch (err) {
      error(`Device registration failed (non-fatal): ${(err as Error).message}`);
    }
@@ -528,47 +583,49 @@ function parseJwtExp(token: string): number | undefined {
 }

 /**
- * Schedule a proactive token refresh before the JWT expires.
- * Returns a cleanup function that cancels the scheduled timer.
+ * Schedule a proactive token refresh before the (connect) token expires.
+ * `refresh` performs the actual refresh — re-minting a workspace token or
+ * refreshing the user token — and returns the new token. Returns a cleanup
+ * function that cancels the scheduled timer.
 */
 function scheduleProactiveRefresh(
-  auth: { token: string; tokenType: string },
-  onRefreshed: (newAuth: Awaited<ReturnType<typeof resolveToken>>) => void,
+  token: string,
+  tokenType: string,
+  refresh: () => Promise<string | undefined>,
  info: (msg: string) => void,
  error: (msg: string) => void,
 ): (() => void) | null {
-  if (auth.tokenType !== 'jwt') return null;
+  if (tokenType !== 'jwt') return null;

-  const exp = parseJwtExp(auth.token);
+  const exp = parseJwtExp(token);
  if (!exp) return null;

-  const refreshAt = (exp - PROACTIVE_REFRESH_BUFFER) * 1000;
-  const delay = refreshAt - Date.now();
-
-  if (delay < 0) {
-    // Already past the refresh window — refresh immediately on next tick
+  const lifetimeMs = exp * 1000 - Date.now();
+  if (lifetimeMs <= 0) {
+    // Token already expired — refresh once on next tick.
    void doRefresh();
    return null;
  }

+  // Refresh ahead of expiry, but never let the buffer meet or exceed the token's
+  // remaining lifetime: a buffer >= lifetime collapses the refresh window to <=0
+  // and busy-loops re-minting (e.g. a 1h token with a 1h buffer). Cap the buffer
+  // at half the remaining lifetime so a short-lived token refreshes about once per
+  // half-life instead of spinning.
+  const bufferMs = Math.min(PROACTIVE_REFRESH_BUFFER * 1000, lifetimeMs / 2);
+  const delay = lifetimeMs - bufferMs;
+
  const timer = setTimeout(() => void doRefresh(), delay);
  return () => clearTimeout(timer);

  async function doRefresh() {
    try {
-      // Use the same buffer so getValidToken actually triggers a refresh
-      const result = await getValidToken(PROACTIVE_REFRESH_BUFFER);
-      if (!result) {
+      const newToken = await refresh();
+      if (!newToken) {
        error('Proactive token refresh failed — no valid credentials.');
        return;
      }
-
-      const refreshed = await resolveToken({});
-      // Only notify if the token actually changed to avoid reschedule loops
-      if (refreshed.token !== auth.token) {
-        info('Proactively refreshed token.');
-        onRefreshed(refreshed);
-      }
+      if (newToken !== token) info('Proactively refreshed token.');
    } catch {
      error('Proactive token refresh failed.');
    }
@@ -1,3 +1,7 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
 import { Command } from 'commander';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

@@ -17,6 +21,9 @@ const { mockTrpcClient } = vi.hoisted(() => ({
      removeFiles: { mutate: vi.fn() },
      updateFile: { mutate: vi.fn() },
    },
+    upload: {
+      createS3PreSignedUrl: { mutate: vi.fn() },
+    },
  },
 }));

@@ -38,9 +45,11 @@ describe('file command', () => {
    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    for (const method of Object.values(mockTrpcClient.file)) {
-      for (const fn of Object.values(method)) {
-        (fn as ReturnType<typeof vi.fn>).mockReset();
+    for (const group of [mockTrpcClient.file, mockTrpcClient.upload]) {
+      for (const method of Object.values(group)) {
+        for (const fn of Object.values(method)) {
+          (fn as ReturnType<typeof vi.fn>).mockReset();
+        }
      }
    }
  });
@@ -205,6 +214,111 @@ describe('file command', () => {
      expect(mockTrpcClient.file.createFile.mutate).not.toHaveBeenCalled();
      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('already exists'));
    });
+
+    it('should upload a local file passed as a positional argument', async () => {
+      const tmpFile = path.join(os.tmpdir(), `lh-upload-${process.pid}.txt`);
+      fs.writeFileSync(tmpFile, 'hello world');
+
+      const fetchSpy = vi
+        .spyOn(globalThis, 'fetch')
+        .mockResolvedValue({ ok: true, status: 200, statusText: 'OK' } as Response);
+      mockTrpcClient.file.checkFileHash.mutate.mockResolvedValue({ isExist: false });
+      mockTrpcClient.upload.createS3PreSignedUrl.mutate.mockResolvedValue('https://s3/presigned');
+      mockTrpcClient.file.createFile.mutate.mockResolvedValue({
+        id: 'f-local',
+        url: 'files/x.txt',
+      });
+
+      try {
+        const program = createProgram();
+        await program.parseAsync(['node', 'test', 'file', 'upload', tmpFile]);
+
+        expect(mockTrpcClient.upload.createS3PreSignedUrl.mutate).toHaveBeenCalled();
+        expect(fetchSpy).toHaveBeenCalledWith(
+          'https://s3/presigned',
+          expect.objectContaining({ method: 'PUT' }),
+        );
+        expect(mockTrpcClient.file.createFile.mutate).toHaveBeenCalledWith(
+          expect.objectContaining({
+            fileType: 'text/plain',
+            name: path.basename(tmpFile),
+            url: expect.stringContaining('.txt'),
+          }),
+        );
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('File created'));
+      } finally {
+        fetchSpy.mockRestore();
+        fs.rmSync(tmpFile, { force: true });
+      }
+    });
+
+    it('should upload a local file passed via --file', async () => {
+      const tmpFile = path.join(os.tmpdir(), `lh-upload-f-${process.pid}.json`);
+      fs.writeFileSync(tmpFile, '{}');
+
+      const fetchSpy = vi
+        .spyOn(globalThis, 'fetch')
+        .mockResolvedValue({ ok: true, status: 200, statusText: 'OK' } as Response);
+      mockTrpcClient.file.checkFileHash.mutate.mockResolvedValue({ isExist: false });
+      mockTrpcClient.upload.createS3PreSignedUrl.mutate.mockResolvedValue('https://s3/presigned');
+      mockTrpcClient.file.createFile.mutate.mockResolvedValue({ id: 'f-json' });
+
+      try {
+        const program = createProgram();
+        await program.parseAsync(['node', 'test', 'file', 'upload', '--file', tmpFile]);
+
+        expect(mockTrpcClient.file.createFile.mutate).toHaveBeenCalledWith(
+          expect.objectContaining({ fileType: 'application/json' }),
+        );
+      } finally {
+        fetchSpy.mockRestore();
+        fs.rmSync(tmpFile, { force: true });
+      }
+    });
+
+    it('should skip the S3 upload when the local file hash already exists', async () => {
+      const tmpFile = path.join(os.tmpdir(), `lh-upload-dedup-${process.pid}.txt`);
+      fs.writeFileSync(tmpFile, 'dedup me');
+
+      const fetchSpy = vi.spyOn(globalThis, 'fetch');
+      mockTrpcClient.file.checkFileHash.mutate.mockResolvedValue({
+        isExist: true,
+        url: 'files/2024-01-01/existing.txt',
+      });
+      mockTrpcClient.file.createFile.mutate.mockResolvedValue({ id: 'f-dedup' });
+
+      try {
+        const program = createProgram();
+        await program.parseAsync(['node', 'test', 'file', 'upload', tmpFile]);
+
+        // No pre-sign and no S3 PUT should happen
+        expect(mockTrpcClient.upload.createS3PreSignedUrl.mutate).not.toHaveBeenCalled();
+        expect(fetchSpy).not.toHaveBeenCalled();
+        // The record reuses the existing url
+        expect(mockTrpcClient.file.createFile.mutate).toHaveBeenCalledWith(
+          expect.objectContaining({ url: 'files/2024-01-01/existing.txt' }),
+        );
+      } finally {
+        fetchSpy.mockRestore();
+        fs.rmSync(tmpFile, { force: true });
+      }
+    });
+
+    it('should error when local file does not exist', async () => {
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'file', 'upload', '-f', '/no/such/file.txt']);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('File not found'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('should error when no source is provided', async () => {
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'file', 'upload']);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('Provide a local file path'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
  });

  describe('edit', () => {
@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import { getTrpcClient } from '../api/client';
 import { confirm, outputJson, printTable, timeAgo, truncate } from '../utils/format';
 import { log } from '../utils/logger';
+import { uploadLocalFile } from '../utils/uploadLocalFile';

 export function registerFileCommand(program: Command) {
  const file = program.command('file').description('Manage files');
@@ -113,18 +114,20 @@ export function registerFileCommand(program: Command) {
  // ── upload ───────────────────────────────────────────

  file
-    .command('upload <url>')
-    .description('Upload a file by URL (checks hash first)')
-    .option('--hash <hash>', 'File hash for deduplication check')
-    .option('--name <name>', 'File name')
-    .option('--type <type>', 'File MIME type')
-    .option('--size <size>', 'File size in bytes')
+    .command('upload [source]')
+    .description('Upload a file from a local path or a URL')
+    .option('-f, --file <path>', 'Local file path to upload')
+    .option('--hash <hash>', 'File hash for deduplication check (URL mode)')
+    .option('--name <name>', 'File name (URL mode)')
+    .option('--type <type>', 'File MIME type (URL mode)')
+    .option('--size <size>', 'File size in bytes (URL mode)')
    .option('--parent-id <id>', 'Parent folder ID')
    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
    .action(
      async (
-        url: string,
+        source: string | undefined,
        options: {
+          file?: string;
          hash?: string;
          json?: string | boolean;
          name?: string;
@@ -133,8 +136,47 @@ export function registerFileCommand(program: Command) {
          type?: string;
        },
      ) => {
+        const isUrl = (value: string) =>
+          value.startsWith('http://') || value.startsWith('https://');
+
+        // Resolve the local file path: explicit --file, or a positional that is
+        // not a URL (e.g. `lh file upload ./games_list.txt`).
+        const localPath = options.file ?? (source && !isUrl(source) ? source : undefined);
+
        const client = await getTrpcClient();

+        // ── Local file upload ──
+        if (localPath) {
+          let result;
+          try {
+            result = await uploadLocalFile(client, localPath, { parentId: options.parentId });
+          } catch (error) {
+            log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+            return;
+          }
+
+          if (options.json !== undefined) {
+            const fields = typeof options.json === 'string' ? options.json : undefined;
+            outputJson(result, fields);
+            return;
+          }
+
+          const r = result as any;
+          console.log(`${pc.green('✓')} File created: ${pc.bold(r.id || '')}`);
+          if (r.url) console.log(`  URL: ${pc.dim(r.url)}`);
+          return;
+        }
+
+        // ── URL upload ──
+        if (!source) {
+          log.error('Provide a local file path, --file <path>, or a URL to upload.');
+          process.exit(1);
+          return;
+        }
+
+        const url = source;
+
        // Check hash first if provided
        if (options.hash) {
          const check = await client.file.checkFileHash.mutate({ hash: options.hash });
@@ -1,3 +1,7 @@
+import { rm as fsRm, writeFile as fsWriteFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
 import { Command } from 'commander';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

@@ -6,6 +10,9 @@ import { registerGenerateCommand } from './generate';

 const { mockTrpcClient } = vi.hoisted(() => ({
  mockTrpcClient: {
+    asr: {
+      transcribe: { mutate: vi.fn() },
+    },
    generation: {
      deleteGeneration: { mutate: vi.fn() },
      getGenerationStatus: { query: vi.fn() },
@@ -35,6 +42,15 @@ const { writeFileSync: mockWriteFileSync } = vi.hoisted(() => ({
  writeFileSync: vi.fn(),
 }));

+const { uploadLocalFile: mockUploadLocalFile } = vi.hoisted(() => ({
+  uploadLocalFile: vi.fn(),
+}));
+
+vi.mock('../utils/uploadLocalFile', async (importOriginal) => {
+  const actual: Record<string, unknown> = await importOriginal();
+  return { ...actual, uploadLocalFile: mockUploadLocalFile };
+});
+
 vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
 vi.mock('../api/http', () => ({ getAuthInfo: mockGetAuthInfo }));
 vi.mock('node:fs', async (importOriginal) => {
@@ -369,6 +385,130 @@ describe('generate command', () => {
      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('not found'));
      expect(exitSpy).toHaveBeenCalledWith(1);
    });
+
+    it('should upload large local audio and transcribe by fileId', async () => {
+      // Real >3MB temp file so existsSync/statSync (unmocked) see it as large.
+      const bigPath = path.join(os.tmpdir(), `lh-asr-test-${process.pid}-${Date.now()}.mp3`);
+      await fsWriteFile(bigPath, Buffer.alloc(4 * 1024 * 1024));
+      mockUploadLocalFile.mockResolvedValue({ id: 'file_999' });
+      mockTrpcClient.asr.transcribe.mutate.mockResolvedValue({ text: 'big result' });
+
+      try {
+        const program = createProgram();
+        await program.parseAsync(['node', 'test', 'generate', 'asr', bigPath]);
+
+        expect(mockUploadLocalFile).toHaveBeenCalledWith(expect.anything(), bigPath);
+        expect(mockTrpcClient.asr.transcribe.mutate).toHaveBeenCalledWith(
+          expect.objectContaining({ fileId: 'file_999', model: 'whisper-1', provider: 'openai' }),
+        );
+        // never inlines bytes for the large file
+        expect(mockTrpcClient.asr.transcribe.mutate.mock.calls[0][0]).not.toHaveProperty(
+          'audioBase64',
+        );
+        expect(stdoutSpy).toHaveBeenCalledWith('big result');
+      } finally {
+        await fsRm(bigPath, { force: true });
+      }
+    });
+
+    it('should download and transcribe an audio URL', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        arrayBuffer: vi.fn().mockResolvedValue(new TextEncoder().encode('audio-bytes').buffer),
+        headers: new Headers(),
+        ok: true,
+      });
+      vi.stubGlobal('fetch', fetchMock);
+      mockTrpcClient.asr.transcribe.mutate.mockResolvedValue({ text: 'hello world' });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'generate',
+        'asr',
+        'https://example.com/audio/sample.mp3',
+      ]);
+
+      expect(fetchMock).toHaveBeenCalledWith('https://example.com/audio/sample.mp3');
+      expect(mockTrpcClient.asr.transcribe.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          audioBase64: Buffer.from('audio-bytes').toString('base64'),
+          fileName: 'sample.mp3',
+          model: 'whisper-1',
+          provider: 'openai',
+        }),
+      );
+      expect(stdoutSpy).toHaveBeenCalledWith('hello world');
+      expect(exitSpy).not.toHaveBeenCalled();
+    });
+
+    it('should derive an extension and mime type from Content-Type when the URL has none', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          arrayBuffer: vi.fn().mockResolvedValue(new TextEncoder().encode('audio-bytes').buffer),
+          headers: new Headers({ 'content-type': 'audio/mpeg; charset=binary' }),
+          ok: true,
+        }),
+      );
+      mockTrpcClient.asr.transcribe.mutate.mockResolvedValue({ text: 'ok' });
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'generate', 'asr', 'https://example.com/download']);
+
+      expect(mockTrpcClient.asr.transcribe.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          fileName: 'download.mp3',
+          mimeType: 'audio/mpeg',
+        }),
+      );
+    });
+
+    it('should prefer the filename from Content-Disposition', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({
+          arrayBuffer: vi.fn().mockResolvedValue(new TextEncoder().encode('audio-bytes').buffer),
+          headers: new Headers({
+            'content-disposition': 'attachment; filename="recording.wav"',
+          }),
+          ok: true,
+        }),
+      );
+      mockTrpcClient.asr.transcribe.mutate.mockResolvedValue({ text: 'ok' });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'generate',
+        'asr',
+        'https://example.com/files/abc123?sig=xyz',
+      ]);
+
+      expect(mockTrpcClient.asr.transcribe.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ fileName: 'recording.wav' }),
+      );
+    });
+
+    it('should exit when audio URL download fails', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn().mockResolvedValue({ ok: false, status: 404, statusText: 'Not Found' }),
+      );
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'generate',
+        'asr',
+        'https://example.com/missing.mp3',
+      ]);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('Failed to download audio'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
  });

  describe('delete', () => {
@@ -1,16 +1,27 @@
-import { createReadStream, existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';

 import type { Command } from 'commander';

-import { getAuthInfo } from '../../api/http';
+import { getTrpcClient } from '../../api/client';
 import { log } from '../../utils/logger';
+import { uploadLocalFile } from '../../utils/uploadLocalFile';
+
+// Audio at or below this size is sent inline as base64; anything larger is
+// uploaded first and transcribed by `fileId`. Kept in sync with the server-side
+// inline cap in `apps/server/src/routers/lambda/asr.ts`.
+const MAX_INLINE_AUDIO_BYTES = 3 * 1024 * 1024;

 export function registerAsrCommand(parent: Command) {
  parent
    .command('asr <audio-file>')
-    .description('Convert speech to text (automatic speech recognition)')
+    .description(
+      'Convert speech to text (automatic speech recognition). Accepts a local path or a URL',
+    )
    .option('--model <model>', 'STT model', 'whisper-1')
+    .option('--provider <provider>', 'AI provider', 'openai')
    .option('--language <lang>', 'Language code (e.g. en, zh)')
    .option('--json', 'Output raw JSON')
    .action(
@@ -20,58 +31,175 @@ export function registerAsrCommand(parent: Command) {
          json?: boolean;
          language?: string;
          model: string;
+          provider: string;
        },
      ) => {
-        if (!existsSync(audioFile)) {
+        const isUrl = audioFile.startsWith('http://') || audioFile.startsWith('https://');
+
+        if (!isUrl && !existsSync(audioFile)) {
          log.error(`File not found: ${audioFile}`);
          process.exit(1);
          return;
        }

-        const { serverUrl, headers } = await getAuthInfo();
-
-        const sttOptions: Record<string, any> = { model: options.model };
-        if (options.language) sttOptions.language = options.language;
-
-        const formData = new FormData();
-        const fileBuffer = await readFileAsBlob(audioFile);
-        formData.append('speech', fileBuffer, path.basename(audioFile));
-        formData.append('options', JSON.stringify(sttOptions));
-
-        // Remove Content-Type for multipart/form-data (let fetch set it with boundary)
-        const { 'Content-Type': _, ...formHeaders } = headers;
-
-        const res = await fetch(`${serverUrl}/webapi/stt/openai`, {
-          body: formData,
-          headers: formHeaders,
-          method: 'POST',
-        });
-
-        if (!res.ok) {
-          const errText = await res.text();
-          log.error(`ASR failed: ${res.status} ${errText}`);
+        // Resolve the input to a local file path (downloading URLs to a temp
+        // file) so large audio can reuse the shared upload flow.
+        let localPath: string;
+        let fileName: string;
+        let mimeType: string | undefined;
+        let size: number;
+        let tempPath: string | undefined;
+        try {
+          if (isUrl) {
+            const downloaded = await fetchAudioFromUrl(audioFile);
+            fileName = downloaded.name;
+            mimeType = downloaded.mimeType;
+            size = downloaded.bytes.byteLength;
+            tempPath = path.join(os.tmpdir(), `lh-asr-${process.pid}-${Date.now()}-${fileName}`);
+            await writeFile(tempPath, downloaded.bytes);
+            localPath = tempPath;
+          } else {
+            localPath = audioFile;
+            fileName = path.basename(audioFile);
+            size = statSync(audioFile).size;
+          }
+        } catch (error) {
+          log.error(error instanceof Error ? error.message : String(error));
          process.exit(1);
          return;
        }

-        const result = await res.json();
+        try {
+          const client = await getTrpcClient();

-        if (options.json) {
-          console.log(JSON.stringify(result, null, 2));
-        } else {
-          const text = (result as any).text || JSON.stringify(result);
-          process.stdout.write(text);
-          process.stdout.write('\n');
+          let result: { text: string };
+          if (size > MAX_INLINE_AUDIO_BYTES) {
+            // Large audio: upload to storage, then transcribe by fileId so the
+            // bytes never travel inline through tRPC.
+            process.stderr.write(
+              `Audio is ${(size / 1024 / 1024).toFixed(1)}MB — uploading before transcription…\n`,
+            );
+            const record = (await uploadLocalFile(client, localPath)) as { id: string };
+            result = await client.asr.transcribe.mutate({
+              fileId: record.id,
+              language: options.language,
+              model: options.model,
+              provider: options.provider,
+            });
+          } else {
+            const bytes = await readFile(localPath);
+            result = await client.asr.transcribe.mutate({
+              audioBase64: Buffer.from(bytes).toString('base64'),
+              fileName,
+              language: options.language,
+              mimeType,
+              model: options.model,
+              provider: options.provider,
+            });
+          }
+
+          if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+          } else {
+            process.stdout.write(result.text);
+            process.stdout.write('\n');
+          }
+        } catch (error) {
+          log.error(`ASR failed: ${error instanceof Error ? error.message : String(error)}`);
+          process.exit(1);
+        } finally {
+          if (tempPath) {
+            await rm(tempPath, { force: true }).catch(() => {});
+          }
        }
      },
    );
 }

-async function readFileAsBlob(filePath: string): Promise<Blob> {
-  const chunks: Uint8Array[] = [];
-  const stream = createReadStream(filePath);
-  for await (const chunk of stream) {
-    chunks.push(chunk as Uint8Array);
+// Common audio MIME types mapped to a file extension the transcription
+// provider can recognize. Keep the extensions within the set OpenAI's
+// /audio/transcriptions endpoint accepts.
+const AUDIO_MIME_TO_EXT: Record<string, string> = {
+  'audio/aac': 'aac',
+  'audio/flac': 'flac',
+  'audio/m4a': 'm4a',
+  'audio/mp3': 'mp3',
+  'audio/mp4': 'm4a',
+  'audio/mpeg': 'mp3',
+  'audio/mpga': 'mp3',
+  'audio/ogg': 'ogg',
+  'audio/opus': 'ogg',
+  'audio/wav': 'wav',
+  'audio/wave': 'wav',
+  'audio/webm': 'webm',
+  'audio/x-m4a': 'm4a',
+  'audio/x-wav': 'wav',
+};
+
+async function fetchAudioFromUrl(
+  url: string,
+): Promise<{ bytes: Uint8Array; mimeType?: string; name: string }> {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to download audio: ${res.status} ${res.statusText}`);
+  }
+
+  const bytes = new Uint8Array(await res.arrayBuffer());
+
+  // Strip any parameters from the Content-Type (e.g. `audio/mpeg; charset=...`).
+  const contentType = res.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+  const mimeType = contentType?.startsWith('audio/') ? contentType : undefined;
+
+  // Prefer the name the server advertises, then the URL path, then a fallback.
+  const name =
+    fileNameFromContentDisposition(res.headers.get('content-disposition')) ||
+    basenameFromUrl(url) ||
+    'audio';
+
+  // Transcription providers infer the audio format from the file extension, so
+  // make sure the name carries one. Signed URLs and /download endpoints often
+  // have no extension in the path — in that case borrow it from the
+  // Content-Type when we recognize it.
+  const ext = contentType ? AUDIO_MIME_TO_EXT[contentType] : undefined;
+  const finalName = path.extname(name) || !ext ? name : `${name}.${ext}`;
+
+  return { bytes, mimeType, name: finalName };
+}
+
+// Extract a file name from a Content-Disposition header, handling both the
+// plain `filename="x"` form and the RFC 5987 extended `filename*=UTF-8''x` form.
+function fileNameFromContentDisposition(header: string | null): string | undefined {
+  if (!header) return undefined;
+
+  // Extended form takes precedence and may be percent-encoded.
+  const extended = /filename\*=\s*(?:UTF-8|ISO-8859-1)?''([^;]+)/i.exec(header);
+  if (extended?.[1]) {
+    try {
+      return path.basename(decodeURIComponent(extended[1].trim()));
+    } catch {
+      // Malformed encoding — fall through to the plain form.
+    }
+  }
+
+  const plain = /filename=\s*"?([^";]+)"?/i.exec(header);
+  const value = plain?.[1]?.trim();
+  return value ? path.basename(value) : undefined;
+}
+
+// Derive the (URL-decoded) last path segment of a URL, if any.
+function basenameFromUrl(url: string): string | undefined {
+  let pathname: string;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    return undefined;
+  }
+
+  const base = path.basename(pathname);
+  if (!base) return undefined;
+  try {
+    return decodeURIComponent(base);
+  } catch {
+    return base;
  }
-  return new Blob(chunks);
 }
@@ -649,6 +649,53 @@ describe('hetero exec command', () => {
    ]);
  });

+  it('finishes with result "error" when a terminal error event is pushed despite a clean exit', async () => {
+    // CC relays an API/rate-limit error as an in-stream `error` event but still
+    // exits 0. The finish result must NOT be derived from the exit code alone,
+    // otherwise the topic/task is wrongly marked completed.
+    mockSpawnAgent.mockReturnValue(
+      createFakeHandle({
+        events: [
+          {
+            data: {
+              error: 'API Error: Server is temporarily limiting requests · Rate limited',
+              message: 'API Error: Server is temporarily limiting requests · Rate limited',
+            },
+            operationId: 'op-err',
+            stepIndex: 0,
+            timestamp: 1,
+            type: 'error',
+          },
+        ],
+        exitCode: 0,
+      }),
+    );
+
+    await runCmd([
+      'hetero',
+      'exec',
+      '--type',
+      'claude-code',
+      '--prompt',
+      'hi',
+      '--topic',
+      'topic-1',
+      '--operation-id',
+      'op-err',
+      '--render',
+      'none',
+    ]);
+
+    expect(mockHeteroFinishMutate).toHaveBeenCalledTimes(1);
+    expect(mockHeteroFinishMutate.mock.calls[0][0]).toMatchObject({
+      error: {
+        message: 'API Error: Server is temporarily limiting requests · Rate limited',
+        type: 'AgentRuntimeError',
+      },
+      result: 'error',
+    });
+  });
+
  it('resets the per-message text accumulator at message boundaries (no cross-message duplication)', async () => {
    // The `replace` snapshot accumulator must not span
    // message boundaries. Two assistant messages separated by a
@@ -467,6 +467,11 @@ const exec = async (options: ExecOptions): Promise<void> => {
   *   sessionId     — CC session id from `system.init` (undefined on resume failure)
   *   ingestError   — true when a batch could not be flushed after retries
   *   resumeNotFound — true when a resume-not-found error was intercepted
+   *   sawTerminalError — true when a terminal `error` event was pushed to the
+   *                      ingester (CC can relay an API/rate-limit error this way
+   *                      and still exit 0, so the exit code alone is not enough)
+   *   terminalErrorMessage — the message from that terminal `error` event, used
+   *                      as the task-level error detail in the finish payload
   *   stderrContent  — accumulated stderr (only when interceptResumeErrors=true)
   */
  const runOneAgent = async (
@@ -477,9 +482,11 @@ const exec = async (options: ExecOptions): Promise<void> => {
    code: number | null;
    ingestError: boolean;
    resumeNotFound: boolean;
+    sawTerminalError: boolean;
    sessionId: string | undefined;
    signal: NodeJS.Signals | null;
    stderrContent: string;
+    terminalErrorMessage: string | undefined;
  }> => {
    // One raw-dump file pair per spawn attempt (the resume retry is a second
    // attempt). The stdout tee runs inside `spawnAgent` before the adapter.
@@ -549,6 +556,8 @@ const exec = async (options: ExecOptions): Promise<void> => {
    // into the ingester.  When intercepting resume errors, a matching
    // `error` event is withheld from the ingester and flags a retry instead.
    let resumeNotFound = false;
+    let sawTerminalError = false;
+    let terminalErrorMessage: string | undefined;
    const ingestError = false;
    try {
      for await (const event of handle.events) {
@@ -563,6 +572,16 @@ const exec = async (options: ExecOptions): Promise<void> => {
            continue;
          }
        }
+        // A terminal `error` event (e.g. an API/rate-limit error relayed by CC)
+        // must mark the run as failed even when the child exits 0 — track it so
+        // the finish result is not derived from the exit code alone. Capture the
+        // message too, so the finish payload can surface it as the task-level
+        // error detail (CC relays these on stdout, not stderr).
+        if (event.type === 'error') {
+          sawTerminalError = true;
+          const data = event.data as Record<string, unknown> | undefined;
+          terminalErrorMessage = String(data?.message ?? data?.error ?? '') || undefined;
+        }
        if (emitJsonl) process.stdout.write(`${JSON.stringify(event)}\n`);
        serverIngester?.push(event);
      }
@@ -608,9 +627,11 @@ const exec = async (options: ExecOptions): Promise<void> => {
      code,
      ingestError,
      resumeNotFound,
+      sawTerminalError,
      sessionId: handle.sessionId,
      signal,
      stderrContent,
+      terminalErrorMessage,
    };
  };

@@ -675,16 +696,23 @@ const exec = async (options: ExecOptions): Promise<void> => {
      result = { ...result, ingestError: true };
    }

-    const exitedClean = !result.ingestError && (code === 0 || signal === 'SIGTERM');
+    // CC relays API/rate-limit errors as an in-stream terminal `error` event but
+    // still exits 0, so the exit code alone would report `success`. Treat any
+    // pushed terminal error as a failed run so the topic/task is marked failed.
+    const exitedClean =
+      !result.ingestError && !result.sawTerminalError && (code === 0 || signal === 'SIGTERM');

-    // When the run failed, pass stderr as the error detail so the server can
-    // surface a useful message instead of the generic "Agent execution failed"
-    // fallback.  Trim to the last 1 KB — the tail is most informative and
-    // keeps the tRPC payload small.
+    // When the run failed, pass an error detail so the server surfaces a useful
+    // message instead of the generic "Agent execution failed" fallback. Prefer
+    // the in-stream terminal error (CC relays API/rate-limit errors here while
+    // exiting 0, so stderr is empty); otherwise fall back to the stderr tail.
+    // Trim to the last 1 KB — the tail is most informative and keeps the tRPC
+    // payload small.
    const stderrTail = result.stderrContent.trim();
+    const errorDetail = result.terminalErrorMessage || stderrTail;
    const finishError =
-      !exitedClean && stderrTail
-        ? { message: stderrTail.slice(-1024), type: 'AgentRuntimeError' }
+      !exitedClean && errorDetail
+        ? { message: errorDetail.slice(-1024), type: 'AgentRuntimeError' }
        : undefined;

    try {
@@ -1,14 +1,12 @@
-import crypto from 'node:crypto';
-import fs from 'node:fs';
 import path from 'node:path';

 import type { Command } from 'commander';
 import pc from 'picocolors';

 import { getTrpcClient } from '../api/client';
-import { getAuthInfo } from '../api/http';
 import { confirm, outputJson, printTable, timeAgo, truncate } from '../utils/format';
 import { log } from '../utils/logger';
+import { uploadLocalFile } from '../utils/uploadLocalFile';

 function formatFileType(fileType: string): string {
  if (!fileType) return '';
@@ -324,81 +322,22 @@ export function registerKbCommand(program: Command) {
    .description('Upload a file to a knowledge base')
    .option('--parent <parentId>', 'Parent folder ID')
    .action(async (knowledgeBaseId: string, filePath: string, options: { parent?: string }) => {
-      const resolved = path.resolve(filePath);
-      if (!fs.existsSync(resolved)) {
-        log.error(`File not found: ${resolved}`);
-        process.exit(1);
-      }
-
-      const stat = fs.statSync(resolved);
-      const fileName = path.basename(resolved);
-      const fileBuffer = fs.readFileSync(resolved);
-
-      // Compute SHA-256 hash
-      const hash = crypto.createHash('sha256').update(fileBuffer).digest('hex');
-
-      // Detect MIME type from extension
-      const ext = path.extname(fileName).toLowerCase().slice(1);
-      const mimeMap: Record<string, string> = {
-        csv: 'text/csv',
-        doc: 'application/msword',
-        docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-        gif: 'image/gif',
-        jpeg: 'image/jpeg',
-        jpg: 'image/jpeg',
-        json: 'application/json',
-        md: 'text/markdown',
-        mp3: 'audio/mpeg',
-        mp4: 'video/mp4',
-        pdf: 'application/pdf',
-        png: 'image/png',
-        pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-        svg: 'image/svg+xml',
-        txt: 'text/plain',
-        webp: 'image/webp',
-        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-      };
-      const fileType = mimeMap[ext] || 'application/octet-stream';
-
      const client = await getTrpcClient();
-      const { serverUrl, headers } = await getAuthInfo();

-      // 1. Get presigned URL
-      const date = new Date().toLocaleDateString('en-CA'); // YYYY-MM-DD
-      const pathname = `files/${date}/${hash}.${ext}`;
-      const presigned = await client.upload.createS3PreSignedUrl.mutate({ pathname });
-
-      // 2. Upload to S3
-      const presignedUrl = typeof presigned === 'string' ? presigned : (presigned as any).url;
-      const uploadRes = await fetch(presignedUrl, {
-        body: fileBuffer,
-        headers: { 'Content-Type': fileType },
-        method: 'PUT',
-      });
-      if (!uploadRes.ok) {
-        log.error(`Upload failed: ${uploadRes.status} ${uploadRes.statusText}`);
+      let result;
+      try {
+        result = await uploadLocalFile(client, filePath, {
+          knowledgeBaseId,
+          parentId: options.parent,
+        });
+      } catch (error) {
+        log.error(error instanceof Error ? error.message : String(error));
        process.exit(1);
+        return;
      }

-      // 3. Create file record
-      const result = await client.file.createFile.mutate({
-        fileType,
-        hash,
-        knowledgeBaseId,
-        metadata: {
-          date,
-          dirname: '',
-          filename: fileName,
-          path: pathname,
-        },
-        name: fileName,
-        parentId: options.parent,
-        size: stat.size,
-        url: pathname,
-      });
-
      console.log(
-        `${pc.green('✓')} Uploaded ${pc.bold(fileName)} → ${pc.bold((result as any).id)}`,
+        `${pc.green('✓')} Uploaded ${pc.bold(path.basename(filePath))} → ${pc.bold((result as any).id)}`,
      );
    });
 }
@@ -1,7 +1,8 @@
 import { Command } from 'commander';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';

 import { clearCredentials } from '../auth/credentials';
+import { stopDaemon } from '../daemon/manager';
 import { log } from '../utils/logger';
 import { registerLogoutCommand } from './logout';

@@ -9,6 +10,10 @@ vi.mock('../auth/credentials', () => ({
  clearCredentials: vi.fn(),
 }));

+vi.mock('../daemon/manager', () => ({
+  stopDaemon: vi.fn(),
+}));
+
 vi.mock('../utils/logger', () => ({
  log: {
    debug: vi.fn(),
@@ -19,6 +24,11 @@ vi.mock('../utils/logger', () => ({
 }));

 describe('logout command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(stopDaemon).mockReturnValue(false);
+  });
+
  function createProgram() {
    const program = new Command();
    program.exitOverride();
@@ -44,4 +54,24 @@ describe('logout command', () => {

    expect(log.info).toHaveBeenCalledWith(expect.stringContaining('Already logged out'));
  });
+
+  it('should stop the connect daemon before clearing credentials', async () => {
+    vi.mocked(stopDaemon).mockReturnValue(true);
+    vi.mocked(clearCredentials).mockReturnValue(true);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'logout']);
+
+    expect(stopDaemon).toHaveBeenCalled();
+    expect(log.info).toHaveBeenCalledWith(expect.stringContaining('Disconnected device daemon'));
+  });
+
+  it('should still attempt daemon teardown when no credentials exist', async () => {
+    vi.mocked(clearCredentials).mockReturnValue(false);
+
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'logout']);
+
+    expect(stopDaemon).toHaveBeenCalled();
+  });
 });
@@ -1,6 +1,7 @@
 import type { Command } from 'commander';

 import { clearCredentials } from '../auth/credentials';
+import { stopDaemon } from '../daemon/manager';
 import { log } from '../utils/logger';

 export function registerLogoutCommand(program: Command) {
@@ -8,6 +9,14 @@ export function registerLogoutCommand(program: Command) {
    .command('logout')
    .description('Log out and remove stored credentials')
    .action(() => {
+      // Tear down the connect daemon first — otherwise it keeps the device
+      // online on the gateway with the cached token even after credentials are
+      // gone, leaving the machine remotely driveable past "logout".
+      const stopped = stopDaemon();
+      if (stopped) {
+        log.info('Disconnected device daemon.');
+      }
+
      const removed = clearCredentials();
      if (removed) {
        log.info('Logged out. Credentials removed.');
@@ -100,6 +100,19 @@ describe('model command', () => {

      expect(consoleSpy).toHaveBeenCalledWith(JSON.stringify(visibleModels, null, 2));
    });
+
+    it('should normalize the legacy `stt` type to `asr` when filtering', async () => {
+      mockTrpcClient.aiModel.getAiProviderModelList.query.mockResolvedValue([
+        { displayName: 'Whisper', enabled: true, id: 'whisper-1', type: 'asr' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'model', 'list', 'openai', '--type', 'stt']);
+
+      expect(mockTrpcClient.aiModel.getAiProviderModelList.query).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 'openai', type: 'asr' }),
+      );
+    });
  });

  describe('view', () => {
@@ -157,6 +170,28 @@ describe('model command', () => {
      );
      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Created model'));
    });
+
+    it('should normalize the legacy `stt` type to `asr`', async () => {
+      mockTrpcClient.aiModel.createAiModel.mutate.mockResolvedValue('whisper-1');
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'model',
+        'create',
+        '--id',
+        'whisper-1',
+        '--provider',
+        'openai',
+        '--type',
+        'stt',
+      ]);
+
+      expect(mockTrpcClient.aiModel.createAiModel.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 'whisper-1', providerId: 'openai', type: 'asr' }),
+      );
+    });
  });

  describe('edit', () => {
@@ -184,6 +219,29 @@ describe('model command', () => {
      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Updated model'));
    });

+    it('should normalize the legacy `stt` type to `asr`', async () => {
+      mockTrpcClient.aiModel.updateAiModel.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'model',
+        'edit',
+        'whisper-1',
+        '--provider',
+        'openai',
+        '--type',
+        'stt',
+      ]);
+
+      expect(mockTrpcClient.aiModel.updateAiModel.mutate).toHaveBeenCalledWith({
+        id: 'whisper-1',
+        providerId: 'openai',
+        value: expect.objectContaining({ type: 'asr' }),
+      });
+    });
+
    it('should error when no changes specified', async () => {
      const program = createProgram();
      await program.parseAsync(['node', 'test', 'model', 'edit', 'gpt-4', '--provider', 'openai']);
@@ -7,6 +7,11 @@ import { log } from '../utils/logger';

 const isVisibleModel = (model: { visible?: boolean }) => model.visible !== false;

+// The model type `stt` was renamed to the standard `asr`. Accept the legacy
+// alias on CLI input and forward/compare `asr`, so existing scripts and muscle
+// memory keep working against the new router schema.
+const normalizeModelType = (type: string): string => (type === 'stt' ? 'asr' : type);
+
 export function registerModelCommand(program: Command) {
  const model = program.command('model').description('Manage AI models');

@@ -19,7 +24,7 @@ export function registerModelCommand(program: Command) {
    .option('--enabled', 'Only show enabled models')
    .option(
      '--type <type>',
-      'Filter by model type (chat|embedding|tts|stt|image|video|text2music|realtime)',
+      'Filter by model type (chat|embedding|tts|asr|image|video|text2music|realtime)',
    )
    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
    .action(
@@ -29,18 +34,20 @@ export function registerModelCommand(program: Command) {
      ) => {
        const client = await getTrpcClient();

+        const typeFilter = options.type ? normalizeModelType(options.type) : undefined;
+
        const input: Record<string, any> = { id: providerId };
        if (options.limit) input.limit = Number.parseInt(options.limit, 10);
        if (options.enabled) input.enabled = true;
-        if (options.type) input.type = options.type;
+        if (typeFilter) input.type = typeFilter;

        const result = await client.aiModel.getAiProviderModelList.query(input as any);
        let items = (Array.isArray(result) ? result : ((result as any).items ?? [])).filter(
          isVisibleModel,
        );

-        if (options.type) {
-          items = items.filter((m: any) => m.type === options.type);
+        if (typeFilter) {
+          items = items.filter((m: any) => m.type === typeFilter);
        }

        if (options.json !== undefined) {
@@ -106,7 +113,7 @@ export function registerModelCommand(program: Command) {
    .option('--display-name <name>', 'Display name')
    .option(
      '--type <type>',
-      'Model type (chat|embedding|tts|stt|image|video|text2music|realtime)',
+      'Model type (chat|embedding|tts|asr|image|video|text2music|realtime)',
      'chat',
    )
    .action(
@@ -116,7 +123,7 @@ export function registerModelCommand(program: Command) {
        const input: Record<string, any> = {
          id: options.id,
          providerId: options.provider,
-          type: options.type || 'chat',
+          type: normalizeModelType(options.type || 'chat'),
        };
        if (options.displayName) input.displayName = options.displayName;

@@ -132,7 +139,7 @@ export function registerModelCommand(program: Command) {
    .description('Update model info')
    .requiredOption('--provider <providerId>', 'Provider ID')
    .option('--display-name <name>', 'Display name')
-    .option('--type <type>', 'Model type (chat|embedding|tts|stt|image|video|text2music|realtime)')
+    .option('--type <type>', 'Model type (chat|embedding|tts|asr|image|video|text2music|realtime)')
    .action(
      async (id: string, options: { displayName?: string; provider: string; type?: string }) => {
        if (!options.displayName && !options.type) {
@@ -144,7 +151,7 @@ export function registerModelCommand(program: Command) {

        const value: Record<string, any> = {};
        if (options.displayName) value.displayName = options.displayName;
-        if (options.type) value.type = options.type;
+        if (options.type) value.type = normalizeModelType(options.type);

        await client.aiModel.updateAiModel.mutate({
          id,
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildInstallCommand, isNewerVersion } from './update';
+
+describe('isNewerVersion', () => {
+  it('compares core versions', () => {
+    expect(isNewerVersion('1.2.3', '1.2.2')).toBe(true);
+    expect(isNewerVersion('1.2.2', '1.2.3')).toBe(false);
+    expect(isNewerVersion('1.2.3', '1.2.3')).toBe(false);
+    expect(isNewerVersion('2.0.0', '1.9.9')).toBe(true);
+  });
+
+  it('tolerates a leading v and missing segments', () => {
+    expect(isNewerVersion('v1.2.0', '1.2.0')).toBe(false);
+    expect(isNewerVersion('1.2', '1.2.0')).toBe(false);
+    expect(isNewerVersion('1.3', '1.2.9')).toBe(true);
+  });
+
+  it('ranks a stable release above a prerelease of the same core', () => {
+    expect(isNewerVersion('1.2.3', '1.2.3-beta.1')).toBe(true);
+    expect(isNewerVersion('1.2.3-beta.1', '1.2.3')).toBe(false);
+    expect(isNewerVersion('1.2.3-beta.2', '1.2.3-beta.1')).toBe(true);
+    expect(isNewerVersion('1.2.3-beta.1', '1.2.3-beta.1')).toBe(false);
+  });
+
+  it('orders numeric prerelease identifiers numerically, not lexicographically', () => {
+    // The bug a raw string compare gets wrong: beta.10 must outrank beta.9.
+    expect(isNewerVersion('1.0.0-beta.10', '1.0.0-beta.9')).toBe(true);
+    expect(isNewerVersion('1.0.0-beta.9', '1.0.0-beta.10')).toBe(false);
+    expect(isNewerVersion('1.0.0-beta.2', '1.0.0-beta.10')).toBe(false);
+  });
+
+  it('returns false for an unparseable latest version', () => {
+    expect(isNewerVersion('not-a-version', '1.0.0')).toBe(false);
+  });
+});
+
+describe('buildInstallCommand', () => {
+  it('builds the global install command per package manager', () => {
+    expect(buildInstallCommand('npm', '@lobehub/cli@1.0.0')).toEqual({
+      args: ['install', '-g', '@lobehub/cli@1.0.0'],
+      command: 'npm',
+    });
+    expect(buildInstallCommand('pnpm', '@lobehub/cli@1.0.0')).toEqual({
+      args: ['add', '-g', '@lobehub/cli@1.0.0'],
+      command: 'pnpm',
+    });
+    expect(buildInstallCommand('bun', '@lobehub/cli@1.0.0')).toEqual({
+      args: ['add', '-g', '@lobehub/cli@1.0.0'],
+      command: 'bun',
+    });
+    expect(buildInstallCommand('yarn', '@lobehub/cli@1.0.0')).toEqual({
+      args: ['global', 'add', '@lobehub/cli@1.0.0'],
+      command: 'yarn',
+    });
+  });
+});
@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+
+import type { Command } from 'commander';
+import pc from 'picocolors';
+import semver from 'semver';
+
+// Pull package metadata from the shared `src/pkg.ts` module (resolved at the
+// bundled entry's depth) rather than a local `require('../../package.json')`,
+// which would point outside the package once bundled into dist/index.js.
+import { cliPackageName, cliVersion } from '../pkg';
+import { log } from '../utils/logger';
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+const PACKAGE_MANAGERS: PackageManager[] = ['npm', 'pnpm', 'yarn', 'bun'];
+
+interface UpdateOptions {
+  check?: boolean;
+  packageManager?: PackageManager;
+  tag?: string;
+}
+
+/**
+ * Detect which package manager installed the CLI so we run the matching global
+ * upgrade command. We first trust an explicit `npm_config_user_agent` (set when
+ * invoked through a package-manager script) and otherwise infer from the path of
+ * the running binary. Falls back to npm.
+ */
+export function detectPackageManager(): PackageManager {
+  const ua = process.env.npm_config_user_agent;
+  if (ua) {
+    if (ua.startsWith('pnpm')) return 'pnpm';
+    if (ua.startsWith('yarn')) return 'yarn';
+    if (ua.startsWith('bun')) return 'bun';
+    if (ua.startsWith('npm')) return 'npm';
+  }
+
+  try {
+    const binPath = realpathSync(process.argv[1] ?? '').replaceAll('\\', '/');
+    if (binPath.includes('/pnpm/')) return 'pnpm';
+    if (binPath.includes('/.bun/') || binPath.includes('/bun/')) return 'bun';
+    if (binPath.includes('/yarn/') || binPath.includes('/.yarn/')) return 'yarn';
+  } catch {
+    // ignore – fall back to npm
+  }
+
+  return 'npm';
+}
+
+/** Build the global-install command for the detected package manager. */
+export function buildInstallCommand(
+  pm: PackageManager,
+  spec: string,
+): { args: string[]; command: string } {
+  switch (pm) {
+    case 'pnpm': {
+      return { args: ['add', '-g', spec], command: 'pnpm' };
+    }
+    case 'yarn': {
+      return { args: ['global', 'add', spec], command: 'yarn' };
+    }
+    case 'bun': {
+      return { args: ['add', '-g', spec], command: 'bun' };
+    }
+    default: {
+      return { args: ['install', '-g', spec], command: 'npm' };
+    }
+  }
+}
+
+/**
+ * Whether `latest` is a newer version than `current`. Delegates to `semver` so
+ * prerelease identifiers order correctly (e.g. `1.0.0-beta.10` > `1.0.0-beta.9`,
+ * which a lexicographic compare gets wrong). Tolerates a leading `v` and missing
+ * segments via coercion; an unparseable `latest` is treated as "not newer".
+ */
+export function isNewerVersion(latest: string, current: string): boolean {
+  const latestParsed = semver.coerce(latest, { includePrerelease: true }) ?? semver.parse(latest);
+  const currentParsed =
+    semver.coerce(current, { includePrerelease: true }) ?? semver.parse(current);
+  if (!latestParsed || !currentParsed) return false;
+  return semver.gt(latestParsed, currentParsed);
+}
+
+async function fetchLatestVersion(name: string, tag: string): Promise<string> {
+  const url = `https://registry.npmjs.org/${name}/${encodeURIComponent(tag)}`;
+  const res = await fetch(url, { headers: { accept: 'application/json' } });
+
+  if (!res.ok) {
+    throw new Error(`npm registry returned status ${res.status} for tag "${tag}"`);
+  }
+
+  const data = (await res.json()) as { version?: string };
+  if (!data.version) {
+    throw new Error('npm registry response is missing the "version" field');
+  }
+
+  return data.version;
+}
+
+function runInstall(command: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      shell: process.platform === 'win32',
+      stdio: 'inherit',
+    });
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with code ${code ?? 'null'}`));
+    });
+  });
+}
+
+export function registerUpdateCommand(program: Command) {
+  program
+    .command('update')
+    .description('Update the LobeHub CLI to the latest published version')
+    .option('--check', 'Only check for a newer version without installing')
+    .option('--tag <tag>', 'npm dist-tag to update to', 'latest')
+    .option(
+      '--package-manager <pm>',
+      `Force a package manager (${PACKAGE_MANAGERS.join(', ')}) instead of auto-detecting`,
+    )
+    .action(async (options: UpdateOptions) => {
+      if (options.packageManager && !PACKAGE_MANAGERS.includes(options.packageManager)) {
+        log.error(
+          `Unsupported package manager "${options.packageManager}". Use one of: ${PACKAGE_MANAGERS.join(', ')}.`,
+        );
+        process.exit(1);
+        return;
+      }
+
+      const current = cliVersion;
+      const tag = options.tag || 'latest';
+
+      log.info(`Current version: ${pc.bold(current)}`);
+
+      let latest: string;
+      try {
+        latest = await fetchLatestVersion(cliPackageName, tag);
+      } catch (error) {
+        log.error(`Unable to check for updates: ${(error as Error).message}`);
+        process.exit(1);
+        return;
+      }
+
+      log.info(`Latest version:  ${pc.bold(latest)} ${pc.dim(`(${tag})`)}`);
+
+      if (!isNewerVersion(latest, current)) {
+        log.info(pc.green('Already on the latest version.'));
+        return;
+      }
+
+      if (options.check) {
+        log.info(
+          `Update available: ${current} → ${pc.green(latest)}. Run ${pc.cyan('lh update')} to upgrade.`,
+        );
+        return;
+      }
+
+      const pm = options.packageManager || detectPackageManager();
+      const spec = `${cliPackageName}@${latest}`;
+      const { args, command } = buildInstallCommand(pm, spec);
+
+      log.info(`Upgrading via ${pc.bold(pm)}: ${pc.dim([command, ...args].join(' '))}`);
+
+      try {
+        await runInstall(command, args);
+        log.info(pc.green(`Successfully updated to ${latest}. Restart any running sessions.`));
+      } catch (error) {
+        log.error(`Update failed: ${(error as Error).message}`);
+        log.error(`You can upgrade manually: ${[command, ...args].join(' ')}`);
+        process.exit(1);
+      }
+    });
+}
@@ -88,3 +88,45 @@ describe('verify rubric config commands', () => {
    expect(printed).toContain('4');
  });
 });
+
+describe('verify evidence upload command', () => {
+  let exitSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    mockGetTrpcClient.mockReset();
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`process.exit ${code}`);
+    }) as any);
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+  });
+
+  const run = async (args: string[]) => {
+    const program = new Command();
+    program.exitOverride();
+    registerVerifyCommand(program);
+    await program.parseAsync(['node', 'lh', 'verify', ...args]);
+  };
+
+  it('rejects evidence with both file and inline content', async () => {
+    await expect(
+      run([
+        'evidence',
+        'upload',
+        '--check',
+        'result-1',
+        '--type',
+        'text',
+        '--file',
+        'artifact.txt',
+        '--content',
+        'inline payload',
+      ]),
+    ).rejects.toThrow('process.exit 1');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(mockGetTrpcClient).not.toHaveBeenCalled();
+  });
+});
@@ -1,9 +1,13 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
 import type { Command } from 'commander';
 import pc from 'picocolors';

 import { getTrpcClient } from '../api/client';
 import { confirm, outputJson, printTable, timeAgo, truncate } from '../utils/format';
 import { log } from '../utils/logger';
+import { uploadLocalFile } from '../utils/uploadLocalFile';

 // ── Helpers ────────────────────────────────────────────────

@@ -32,6 +36,36 @@ function assertEnum<T extends string>(value: T | undefined, allowed: T[], flag:
  }
 }

+type Verdict = 'failed' | 'passed' | 'uncertain';
+type EvidenceType = 'dom_snapshot' | 'gif' | 'screenshot' | 'text' | 'transcript' | 'video';
+
+/** Map a free-form case/summary result token onto the verify verdict vocabulary. */
+function toVerdict(raw: unknown): Verdict {
+  const s = String(raw ?? '').toLowerCase();
+  if (['pass', 'passed', 'ok', 'success'].includes(s)) return 'passed';
+  if (['fail', 'failed', 'error'].includes(s)) return 'failed';
+  return 'uncertain'; // partial / blocked / skipped / pending / unknown
+}
+
+/** Pick an evidence medium from a file extension. */
+function evidenceTypeForFile(file: string): EvidenceType {
+  const ext = path.extname(file).toLowerCase().slice(1);
+  if (ext === 'gif') return 'gif';
+  if (['png', 'jpg', 'jpeg', 'webp', 'svg', 'bmp'].includes(ext)) return 'screenshot';
+  if (['mp4', 'webm', 'mov', 'm4v'].includes(ext)) return 'video';
+  if (['html', 'htm'].includes(ext)) return 'dom_snapshot';
+  return 'text';
+}
+
+/** Normalize a case's `evidence` field (string | string[] | {path}[]) to path strings. */
+function evidencePaths(evidence: unknown): string[] {
+  if (!evidence) return [];
+  const arr = Array.isArray(evidence) ? evidence : [evidence];
+  return arr
+    .map((e) => (typeof e === 'string' ? e : (e?.path ?? e?.file)))
+    .filter((p): p is string => typeof p === 'string' && p.length > 0);
+}
+
 // ── Command Registration ───────────────────────────────────

 export function registerVerifyCommand(program: Command) {
@@ -368,9 +402,9 @@ export function registerVerifyCommand(program: Command) {
      console.log(`${pc.green('✓')} Skipped verification for run ${pc.bold(operationId)}`);
    });

-  // ════════════ run / results ════════════
+  // ════════════ execute (agent path) ════════════
  verify
-    .command('run <operationId>')
+    .command('execute <operationId>')
    .description('Execute the confirmed plan against a deliverable (LLM judge)')
    .requiredOption('--goal <goal>', "The run's task")
    .requiredOption('--deliverable <text>', 'The output to judge')
@@ -406,13 +440,147 @@ export function registerVerifyCommand(program: Command) {
      },
    );

-  verify
-    .command('results <operationId>')
-    .description('List check results for a run')
+  // ════════════ run (verification session entity) ════════════
+  const run = verify.command('run').description('Verification sessions (verify_runs)');
+
+  run
+    .command('create')
+    .description('Create a standalone verification session')
+    .option('--source <source>', 'agent | agent-testing', 'agent-testing')
+    .option('--operation <id>', 'Link to an existing Agent Run')
+    .option('--title <title>', 'Session title')
+    .option('--goal <goal>', 'Goal/task being verified')
    .option('--json [fields]', 'Output JSON')
-    .action(async (operationId: string, options: { json?: boolean | string }) => {
+    .action(
+      async (options: {
+        goal?: string;
+        json?: boolean | string;
+        operation?: string;
+        source?: string;
+        title?: string;
+      }) => {
+        const client = await getTrpcClient();
+        const created = await client.verify.createRun.mutate({
+          goal: options.goal,
+          operationId: options.operation,
+          source: options.source as any,
+          title: options.title,
+        });
+        if (options.json !== undefined) {
+          outputJson(created, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        console.log(`${pc.green('✓')} Created run ${pc.bold(created.id)}`);
+      },
+    );
+
+  run
+    .command('list')
+    .description('List recent verification sessions')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (options: { json?: boolean | string }) => {
      const client = await getTrpcClient();
-      const results = await client.verify.listResults.query({ operationId });
+      const runs = await client.verify.listRuns.query();
+      if (options.json !== undefined) {
+        outputJson(runs, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (runs.length === 0) return void console.log('No runs found.');
+      printTable(
+        runs.map((r: any) => [
+          r.id,
+          truncate(r.title || '', 40),
+          r.source,
+          r.status ?? '',
+          r.operationId ? 'agent' : 'standalone',
+          r.createdAt ? timeAgo(r.createdAt) : '',
+        ]),
+        ['ID', 'TITLE', 'SOURCE', 'STATUS', 'KIND', 'CREATED'],
+      );
+    });
+
+  run
+    .command('get <runId>')
+    .description('Show a verification session')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (runId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const item = await client.verify.getRun.query({ verifyRunId: runId });
+      if (options.json !== undefined) {
+        outputJson(item, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (!item) return void console.log('Run not found.');
+      console.log(JSON.stringify(item, null, 2));
+    });
+
+  // ════════════ result (check result entity) ════════════
+  const result = verify.command('result').description('Check results (verify_check_results)');
+
+  result
+    .command('ingest')
+    .description('Upsert one check result by (run, checkItemId) from a supplied verdict')
+    .requiredOption('--run <verifyRunId>', 'Target session id')
+    .requiredOption('--check <checkItemId>', 'Stable check item id within the session')
+    .requiredOption('--verdict <verdict>', 'passed|failed|uncertain')
+    .option('--title <title>', 'Check title')
+    .option('--index <n>', 'Display index')
+    .option('--confidence <n>', '0-1 confidence')
+    .option('--status <status>', 'pending|running|passed|failed|skipped (derived from verdict)')
+    .option('--evidence <text>', 'Key observation (stored as Toulmin evidence)')
+    .option('--suggestion <text>', 'Remediation hint')
+    .option('--soft', 'Non-blocking (required=false); defaults to blocking')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (options: {
+        check: string;
+        confidence?: string;
+        evidence?: string;
+        index?: string;
+        json?: boolean | string;
+        run: string;
+        soft?: boolean;
+        status?: string;
+        suggestion?: string;
+        title?: string;
+        verdict: string;
+      }) => {
+        const client = await getTrpcClient();
+        const created = await client.verify.ingestResult.mutate({
+          checkItemId: options.check,
+          checkItemIndex: options.index ? Number.parseInt(options.index, 10) : undefined,
+          checkItemTitle: options.title,
+          confidence: options.confidence ? Number.parseFloat(options.confidence) : undefined,
+          required: options.soft ? false : undefined,
+          status: options.status as any,
+          suggestion: options.suggestion,
+          toulmin: options.evidence ? { evidence: options.evidence } : undefined,
+          verdict: options.verdict as any,
+          verifyRunId: options.run,
+        });
+        if (options.json !== undefined) {
+          outputJson(created, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        console.log(`${pc.green('✓')} Result ${pc.bold(created.id)} (${created.verdict})`);
+      },
+    );
+
+  result
+    .command('list')
+    .description('List check results — by session (--run) or by Agent Run (--operation)')
+    .option('--run <verifyRunId>', 'List by verification session')
+    .option('--operation <operationId>', 'List by Agent Run')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (options: { json?: boolean | string; operation?: string; run?: string }) => {
+      if (!options.run && !options.operation) {
+        log.error('Provide either --run or --operation');
+        process.exit(1);
+      }
+      const client = await getTrpcClient();
+      const results = options.run
+        ? await client.verify.listResultsByRun.query({ verifyRunId: options.run })
+        : await client.verify.listResults.query({ operationId: options.operation! });
      if (options.json !== undefined) {
        outputJson(results, typeof options.json === 'string' ? options.json : undefined);
        return;
@@ -421,6 +589,143 @@ export function registerVerifyCommand(program: Command) {
      printResults(results);
    });

+  // ════════════ evidence (artifact entity) ════════════
+  const evidence = verify.command('evidence').description('Evidence artifacts (verify_evidence)');
+
+  evidence
+    .command('upload')
+    .description('Attach an evidence artifact (file or inline text) to a check result')
+    .requiredOption('--check <checkResultId>', 'Target check result id')
+    .requiredOption('--type <type>', 'screenshot|gif|video|text|dom_snapshot|transcript')
+    .option('--file <path>', 'Local file to upload as the artifact')
+    .option('--content <text>', 'Inline text payload (instead of a file)')
+    .option('--by <capturedBy>', 'agent-browser|cdp|cli|program|llm_judge', 'cli')
+    .option('--desc <text>', 'Human-readable caption')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (options: {
+        by?: string;
+        check: string;
+        content?: string;
+        desc?: string;
+        file?: string;
+        json?: boolean | string;
+        type: string;
+      }) => {
+        if (Boolean(options.file) === Boolean(options.content)) {
+          log.error('Provide exactly one of --file or --content');
+          process.exit(1);
+        }
+        const client = await getTrpcClient();
+        let fileId: string | undefined;
+        if (options.file) {
+          const uploaded = await uploadLocalFile(client, options.file);
+          fileId = uploaded.id;
+        }
+        const ev = await client.verify.uploadEvidence.mutate({
+          capturedBy: options.by as any,
+          checkResultId: options.check,
+          content: options.content,
+          description: options.desc,
+          fileId,
+          type: options.type as any,
+        });
+        if (options.json !== undefined) {
+          outputJson(ev, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        console.log(
+          `${pc.green('✓')} Evidence ${pc.bold(ev.id)}${fileId ? ` (file ${fileId})` : ''}`,
+        );
+      },
+    );
+
+  evidence
+    .command('list <checkResultId>')
+    .description('List evidence for a check result')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (checkResultId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const rows = await client.verify.listEvidence.query({ checkResultId });
+      if (options.json !== undefined) {
+        outputJson(rows, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (rows.length === 0) return void console.log('No evidence.');
+      printTable(
+        rows.map((e: any) => [
+          e.id,
+          e.type,
+          e.capturedBy ?? '',
+          e.fileId ? 'file' : 'inline',
+          truncate(e.description || '', 40),
+        ]),
+        ['ID', 'TYPE', 'BY', 'PAYLOAD', 'DESC'],
+      );
+    });
+
+  // ════════════ report (narrative entity) ════════════
+  const report = verify.command('report').description('Verification reports (verify_reports)');
+
+  report
+    .command('upsert')
+    .description('Write (overwrite) the report for a session')
+    .requiredOption('--run <verifyRunId>', 'Target session id')
+    .option('--verdict <verdict>', 'passed|failed|uncertain')
+    .option('--summary <text>', 'Short summary')
+    .option('--content <markdown>', 'Full markdown body')
+    .option('--total <n>', 'Total checks')
+    .option('--passed <n>', 'Passed checks')
+    .option('--failed <n>', 'Failed checks')
+    .option('--uncertain <n>', 'Uncertain checks')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (options: {
+        content?: string;
+        failed?: string;
+        json?: boolean | string;
+        passed?: string;
+        run: string;
+        summary?: string;
+        total?: string;
+        uncertain?: string;
+        verdict?: string;
+      }) => {
+        const num = (s?: string) => (s === undefined ? undefined : Number.parseInt(s, 10));
+        const client = await getTrpcClient();
+        const created = await client.verify.upsertReport.mutate({
+          content: options.content,
+          failedChecks: num(options.failed),
+          passedChecks: num(options.passed),
+          summary: options.summary,
+          totalChecks: num(options.total),
+          uncertainChecks: num(options.uncertain),
+          verdict: options.verdict as any,
+          verifyRunId: options.run,
+        });
+        if (options.json !== undefined) {
+          outputJson(created, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        console.log(`${pc.green('✓')} Report ${pc.bold(created.id)} (${created.verdict ?? '—'})`);
+      },
+    );
+
+  report
+    .command('get <runId>')
+    .description('Show the report for a session')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (runId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const item = await client.verify.getReport.query({ verifyRunId: runId });
+      if (options.json !== undefined) {
+        outputJson(item, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (!item) return void console.log('No report.');
+      console.log(JSON.stringify(item, null, 2));
+    });
+
  // ════════════ feedback ════════════
  verify
    .command('decision <resultId> <decision>')
@@ -431,6 +736,128 @@ export function registerVerifyCommand(program: Command) {
      await client.verify.submitDecision.mutate({ decision, resultId });
      console.log(`${pc.green('✓')} Recorded ${pc.bold(decision)} on result ${pc.bold(resultId)}`);
    });
+
+  // ════════════ ingest (aggregate convenience over the atomic commands) ════════════
+  verify
+    .command('ingest-report <reportDir>')
+    .description(
+      'Ingest a local agent-testing report (result.json + report.md + assets) as a verify session',
+    )
+    .option('--source <source>', 'agent | agent-testing', 'agent-testing')
+    .option('--operation <id>', 'Link the session to an existing Agent Run')
+    .option('--title <title>', 'Override the session title')
+    .option('--goal <goal>', 'The goal/task being verified')
+    .option('--open', 'Print the in-app URL to open the report')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (
+        reportDir: string,
+        options: {
+          goal?: string;
+          json?: boolean | string;
+          open?: boolean;
+          operation?: string;
+          source?: string;
+          title?: string;
+        },
+      ) => {
+        const dir = path.resolve(reportDir);
+        const resultPath = path.join(dir, 'result.json');
+        if (!existsSync(resultPath)) {
+          log.error(`result.json not found in ${dir}`);
+          process.exit(1);
+        }
+
+        let result: any;
+        try {
+          result = JSON.parse(readFileSync(resultPath, 'utf8'));
+        } catch {
+          log.error('result.json is not valid JSON');
+          process.exit(1);
+        }
+
+        const cases: any[] = Array.isArray(result.cases) ? result.cases : [];
+        const summary = result.summary ?? {};
+        const reportMdPath = path.join(dir, 'report.md');
+        const content = existsSync(reportMdPath) ? readFileSync(reportMdPath, 'utf8') : undefined;
+
+        const client = await getTrpcClient();
+
+        // 1. Create the verification session.
+        const run = await client.verify.createRun.mutate({
+          goal: options.goal,
+          operationId: options.operation,
+          source: options.source as any,
+          title: options.title ?? result.title,
+        });
+
+        // 2. Ingest each case as a check result + its evidence.
+        let uploaded = 0;
+        for (const [index, c] of cases.entries()) {
+          const checkItemId = String(c.id ?? c.checkItemId ?? `case-${index + 1}`);
+          const verdict = toVerdict(c.result ?? c.status ?? c.verdict);
+          const observation = c.keyObservation ?? c.observation ?? c.note;
+          const checkResult = await client.verify.ingestResult.mutate({
+            checkItemId,
+            checkItemIndex: index,
+            checkItemTitle: c.name ?? c.case ?? c.title ?? checkItemId,
+            required: c.required ?? true,
+            // The case's key observation is recorded as Toulmin evidence; a real
+            // remediation hint (if the report provides one) goes to `suggestion`.
+            suggestion: typeof c.suggestion === 'string' ? c.suggestion : undefined,
+            toulmin: typeof observation === 'string' ? { evidence: observation } : undefined,
+            verdict,
+            verifierType: 'agent',
+            verifyRunId: run.id,
+          });
+
+          for (const rel of evidencePaths(c.evidence)) {
+            const abs = path.isAbsolute(rel) ? rel : path.join(dir, rel);
+            if (!existsSync(abs)) {
+              log.warn(`evidence not found, skipping: ${rel}`);
+              continue;
+            }
+            const file = await uploadLocalFile(client, abs);
+            await client.verify.uploadEvidence.mutate({
+              capturedBy: 'cli',
+              checkResultId: checkResult.id,
+              description: c.name ?? path.basename(abs),
+              fileId: file.id,
+              type: evidenceTypeForFile(abs),
+            });
+            uploaded += 1;
+          }
+        }
+
+        // 3. Write the report (full markdown + stats snapshot).
+        await client.verify.upsertReport.mutate({
+          content,
+          failedChecks: summary.failed,
+          passedChecks: summary.passed,
+          summary: typeof summary.note === 'string' ? summary.note : undefined,
+          totalChecks: summary.total ?? cases.length,
+          uncertainChecks: (summary.blocked ?? 0) + (summary.uncertain ?? 0) || undefined,
+          verdict: summary.verdict ? toVerdict(summary.verdict) : undefined,
+          verifyRunId: run.id,
+        });
+
+        if (options.json !== undefined) {
+          outputJson(
+            { cases: cases.length, evidence: uploaded, verifyRunId: run.id },
+            typeof options.json === 'string' ? options.json : undefined,
+          );
+          return;
+        }
+
+        console.log(
+          `${pc.green('✓')} Ingested ${pc.bold(String(cases.length))} case(s), ${pc.bold(String(uploaded))} evidence file(s)`,
+        );
+        console.log(`${pc.bold('verifyRunId')}: ${run.id}`);
+        if (options.open) {
+          console.log(`${pc.bold('open')}: /verify/${run.id}`);
+        }
+      },
+    );
 }

 function printResults(results: any[]): void {
@@ -19,11 +19,22 @@ vi.mock('node:os', async (importOriginal) => {
  };
 });

+// Mock only `execFileSync` (used by isDaemonProcess to read a process command
+// line); keep the real `spawn` so nothing else changes.
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, any>>();
+  return { ...actual, execFileSync: vi.fn() };
+});
+
+// eslint-disable-next-line import-x/first
+import { execFileSync } from 'node:child_process';
+
 // eslint-disable-next-line import-x/first
 import {
  appendLog,
  getLogPath,
  getRunningDaemonPid,
+  isDaemonProcess,
  isProcessAlive,
  readPid,
  readStatus,
@@ -35,9 +46,15 @@ import {
  writeStatus,
 } from './manager';

+// A command line that matches the daemon signature (`connect … --daemon-child`).
+const DAEMON_COMMAND = '/usr/local/bin/node /path/to/cli.js connect --daemon-child';
+
 describe('daemon manager', () => {
  beforeEach(async () => {
    await mkdir(mockDir, { recursive: true });
+    // Default: any inspected PID looks like our daemon. Tests that need a
+    // reused / unrelated PID override this per-case.
+    vi.mocked(execFileSync).mockReturnValue(DAEMON_COMMAND as any);
  });

  afterEach(() => {
@@ -80,6 +97,36 @@ describe('daemon manager', () => {
    });
  });

+  describe('isDaemonProcess', () => {
+    it('should return true when the command line matches the daemon signature', () => {
+      vi.mocked(execFileSync).mockReturnValue(DAEMON_COMMAND as any);
+      expect(isDaemonProcess(12345)).toBe(true);
+      expect(execFileSync).toHaveBeenCalledWith(
+        'ps',
+        ['-ww', '-p', '12345', '-o', 'command='],
+        expect.any(Object),
+      );
+    });
+
+    it('should return false for an unrelated process command line', () => {
+      vi.mocked(execFileSync).mockReturnValue('/usr/bin/vim notes.txt' as any);
+      expect(isDaemonProcess(12345)).toBe(false);
+    });
+
+    it('should return false when the signature is only partially present', () => {
+      // `connect` without the internal `--daemon-child` flag is not our daemon.
+      vi.mocked(execFileSync).mockReturnValue('/usr/bin/node /path/cli connect' as any);
+      expect(isDaemonProcess(12345)).toBe(false);
+    });
+
+    it('should return false when ps is unavailable / throws', () => {
+      vi.mocked(execFileSync).mockImplementation(() => {
+        throw new Error('ps: command not found');
+      });
+      expect(isDaemonProcess(12345)).toBe(false);
+    });
+  });
+
  describe('getRunningDaemonPid', () => {
    it('should return null when no PID file', () => {
      expect(getRunningDaemonPid()).toBeNull();
@@ -110,6 +157,23 @@ describe('daemon manager', () => {

      expect(readStatus()).toBeNull();
    });
+
+    it('should treat a live but reused (non-daemon) PID as stale and clean up', () => {
+      // process.pid is alive, but the inspected command line is not our daemon —
+      // simulates the OS reusing a dead daemon's PID for an unrelated process.
+      writePid(process.pid);
+      writeStatus({
+        connectionStatus: 'connected',
+        gatewayUrl: 'https://test.com',
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+      });
+      vi.mocked(execFileSync).mockReturnValue('/usr/bin/some-other-process' as any);
+
+      expect(getRunningDaemonPid()).toBeNull();
+      expect(readPid()).toBeNull();
+      expect(readStatus()).toBeNull();
+    });
  });

  describe('status file', () => {
@@ -232,5 +296,23 @@ describe('daemon manager', () => {

      killSpy.mockRestore();
    });
+
+    it('should NOT SIGTERM a live PID that is not our daemon', () => {
+      // Stale daemon.pid whose PID was reused by an unrelated, living process.
+      writePid(process.pid);
+      vi.mocked(execFileSync).mockReturnValue('/usr/bin/some-other-process' as any);
+
+      const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
+
+      const result = stopDaemon();
+
+      expect(result).toBe(false);
+      // Only the liveness probe (signal 0) is allowed — never a real SIGTERM.
+      expect(killSpy).not.toHaveBeenCalledWith(process.pid, 'SIGTERM');
+      // Stale metadata is cleaned up so we don't keep re-checking it.
+      expect(readPid()).toBeNull();
+
+      killSpy.mockRestore();
+    });
  });
 });
@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -70,6 +70,34 @@ export function isProcessAlive(pid: number): boolean {
  }
 }

+/**
+ * Verify a live PID actually belongs to a LobeHub connect daemon.
+ *
+ * A bare `isProcessAlive` check is not enough: if a daemon dies without cleaning
+ * up `daemon.pid` (crash, `kill -9`, reboot), the OS can later reuse that PID
+ * for an unrelated process. Acting on the stale PID would let `lh logout` /
+ * `connect stop` SIGTERM a stranger. The daemon is always spawned as
+ * `<node> … connect … --daemon-child`, so we confirm that signature in the
+ * process command line before trusting the PID.
+ *
+ * Best-effort and deliberately conservative: if the command line can't be read
+ * (e.g. `ps` is unavailable), we return `false` so callers never kill a process
+ * we can't positively identify.
+ */
+export function isDaemonProcess(pid: number): boolean {
+  try {
+    // `-ww` disables column truncation so the trailing `--daemon-child` flag is
+    // never cut off; stderr is silenced so a dead PID just yields an empty match.
+    const command = execFileSync('ps', ['-ww', '-p', String(pid), '-o', 'command='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return command.includes('--daemon-child') && command.includes('connect');
+  } catch {
+    return false;
+  }
+}
+
 /**
 * Get the PID of a running daemon, cleaning up stale PID files.
 * Returns null if no daemon is running.
@@ -78,9 +106,11 @@ export function getRunningDaemonPid(): number | null {
  const pid = readPid();
  if (pid === null) return null;

-  if (isProcessAlive(pid)) return pid;
+  // Require both liveness AND identity — a live-but-reused PID is treated as
+  // stale so we never act on a process that isn't ours.
+  if (isProcessAlive(pid) && isDaemonProcess(pid)) return pid;

-  // Stale PID file — process is dead
+  // Stale PID file — process is dead or the PID now belongs to someone else.
  removePid();
  removeStatus();
  return null;
@@ -10,6 +10,11 @@ export interface TaskEntry {
  startedAt: string;
  taskId: string;
  topicId: string;
+  /**
+   * Workspace that owns the dispatched topic. Persisted so the cancel-time
+   * notify still scopes to the right workspace after the daemon restarts.
+   */
+  workspaceId?: string;
 }

 function getRegistryPath(): string {
@@ -103,16 +103,6 @@ describe('spawnHeteroAgentRun', () => {
    expect(args).toContain('sess-9');
  });

-  it('passes an explicit CLI command through to `lh hetero exec`', () => {
-    const child = makeFakeChild();
-    spawnMock.mockReturnValue(child);
-
-    void spawnHeteroAgentRun({ ...baseParams, command: '/opt/bin/codex' });
-
-    const [, args] = spawnMock.mock.calls[0];
-    expect(args).toEqual(expect.arrayContaining(['--command', '/opt/bin/codex']));
-  });
-
  it('sends a content-block array to stdin when systemContext is provided', async () => {
    const child = makeFakeChild();
    spawnMock.mockReturnValue(child);
@@ -7,7 +7,6 @@ import {

 export interface SpawnHeteroAgentRunParams {
  agentType: string;
-  command?: string;
  cwd?: string;
  /** Image attachments (signed URLs) appended as image content blocks. */
  imageList?: HeteroExecImageRef[];
@@ -53,7 +52,6 @@ export function spawnHeteroAgentRun(
 ): Promise<AgentRunAckResult> {
  const {
    agentType,
-    command,
    cwd,
    imageList,
    jwt,
@@ -74,7 +72,6 @@ export function spawnHeteroAgentRun(
    'exec',
    '--type',
    agentType,
-    ...(command ? ['--command', command] : []),
    '--operation-id',
    operationId,
    '--topic',
@@ -38,3 +38,45 @@ export async function registerDevice(
    platform: process.platform,
  });
 }
+
+type Auth = { serverUrl: string; token: string; tokenType: 'apiKey' | 'jwt' | 'serviceToken' };
+
+/**
+ * Identity for a WORKSPACE device: derived from the workspaceId (namespaced) so
+ * the same physical machine enrolled into a workspace is a distinct device from
+ * its personal identity, and stable across reconnects.
+ */
+export function resolveWorkspaceDeviceIdentity(
+  workspaceId: string,
+  explicitDeviceId?: string,
+): DeviceIdentity {
+  if (explicitDeviceId) return { deviceId: explicitDeviceId, identitySource: 'fallback' };
+  return deriveDeviceId(`workspace:${workspaceId}`);
+}
+
+/**
+ * Mint a workspace-device connect token (owner-only on the server). The returned
+ * token carries the `workspace_id` claim the gateway routes by.
+ */
+export async function mintWorkspaceConnectToken(
+  auth: Auth,
+  workspaceId: string,
+): Promise<{ token: string; workspaceId: string }> {
+  const trpc = createLambdaClient(auth, workspaceId);
+  return trpc.device.mintWorkspaceConnectToken.mutate();
+}
+
+/** Register this machine as a device of the given workspace (owner-only). */
+export async function registerWorkspaceDevice(
+  auth: Auth,
+  identity: DeviceIdentity,
+  workspaceId: string,
+): Promise<void> {
+  const trpc = createLambdaClient(auth, workspaceId);
+  await trpc.device.registerWorkspaceDevice.mutate({
+    deviceId: identity.deviceId,
+    hostname: os.hostname(),
+    identitySource: identity.identitySource,
+    platform: process.platform,
+  });
+}
@@ -0,0 +1,16 @@
+import { createRequire } from 'node:module';
+
+/**
+ * Single source of truth for this package's own metadata.
+ *
+ * Must live directly under `src/` (depth 1), the same depth as the bundled
+ * entry `dist/index.js`, so `../package.json` resolves to `@lobehub/cli`'s own
+ * package.json both when running from source (`bun src/index.ts`) and from the
+ * tsdown bundle (`dist/index.js`). A module one directory deeper would resolve
+ * the path outside the package once everything is bundled into a single file.
+ */
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json') as { name: string; version: string };
+
+export const cliPackageName = pkg.name;
+export const cliVersion = pkg.version;
@@ -1,5 +1,3 @@
-import { createRequire } from 'node:module';
-
 import { Command } from 'commander';

 import { registerAgentCommand } from './commands/agent';
@@ -33,11 +31,10 @@ import { registerStatusCommand } from './commands/status';
 import { registerTaskCommand } from './commands/task';
 import { registerThreadCommand } from './commands/thread';
 import { registerTopicCommand } from './commands/topic';
+import { registerUpdateCommand } from './commands/update';
 import { registerUserCommand } from './commands/user';
 import { registerVerifyCommand } from './commands/verify';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../package.json');
+import { cliVersion } from './pkg';

 export function createProgram() {
  const program = new Command();
@@ -45,7 +42,7 @@ export function createProgram() {
  program
    .name('lh')
    .description('LobeHub CLI - manage and connect to LobeHub services')
-    .version(version);
+    .version(cliVersion);

  registerLoginCommand(program);
  registerLogoutCommand(program);
@@ -80,8 +77,9 @@ export function createProgram() {
  registerConfigCommand(program);
  registerEvalCommand(program);
  registerMigrateCommand(program);
+  registerUpdateCommand(program);

  return program;
 }

-export { version as cliVersion };
+export { cliPackageName, cliVersion } from './pkg';
@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

+import { getTrpcClient } from '../../api/client';
 import { removeTask, saveTask } from '../../daemon/taskRegistry';
 import { runHeteroTask } from '../heteroTask';

@@ -34,6 +35,8 @@ vi.mock('../../api/client', () => ({
  }),
 }));

+const getTrpcClientMock = vi.mocked(getTrpcClient);
+
 vi.mock('../../utils/logger', () => ({
  log: { error: vi.fn(), info: vi.fn(), warn: vi.fn() },
 }));
@@ -248,4 +251,56 @@ describe('runHeteroTask (openclaw)', () => {
    expect(removeTask).toHaveBeenCalledWith('task-1');
    killSpy.mockRestore();
  });
+
+  it('threads workspaceId into the saved task entry and the spawned child env', async () => {
+    const child = makeMockChild(6666);
+    spawnMock.mockReturnValue(child);
+
+    await runHeteroTask({
+      agentId: 'agent-ws',
+      agentType: 'openclaw',
+      operationId: 'op-ws',
+      prompt: 'workspace dispatch',
+      taskId: 'task-ws',
+      topicId: 'topic-ws',
+      workspaceId: 'ws-42',
+    });
+
+    expect(saveTask).toHaveBeenCalledWith(expect.objectContaining({ workspaceId: 'ws-42' }));
+
+    const [, , spawnOpts] = spawnMock.mock.calls[0] as [
+      string,
+      string[],
+      { env: NodeJS.ProcessEnv },
+    ];
+    expect(spawnOpts.env.LOBEHUB_WORKSPACE_ID).toBe('ws-42');
+  });
+
+  it('passes workspaceId to getTrpcClient when the close handler auto-notifies', async () => {
+    const child = makeMockChild(7777);
+    spawnMock.mockReturnValue(child);
+
+    await runHeteroTask({
+      agentId: 'agent-ws',
+      agentType: 'openclaw',
+      operationId: 'op-ws-2',
+      prompt: 'ws prompt',
+      taskId: 'task-ws-2',
+      topicId: 'topic-ws-2',
+      workspaceId: 'ws-99',
+    });
+
+    getTrpcClientMock.mockClear();
+    // Abnormal exit triggers sendAutoNotify + sendDoneSignal — both must scope
+    // to the dispatching workspace or agentNotify resolves the topic in
+    // personal mode and 404s.
+    child._emit('close', 1, null);
+    // Await microtask drain so the close-handler promise chain settles.
+    await new Promise((r) => setImmediate(r));
+
+    expect(getTrpcClientMock.mock.calls.length).toBeGreaterThan(0);
+    for (const call of getTrpcClientMock.mock.calls) {
+      expect(call[0]).toBe('ws-99');
+    }
+  });
 });
@@ -57,6 +57,13 @@ export interface RunHeteroTaskParams {
  prompt: string;
  taskId: string;
  topicId: string;
+  /**
+   * Workspace id seeded by the server when the dispatched topic lives in a
+   * workspace. Threaded into auto-notify calls (as `X-Workspace-Id`) and into
+   * the spawned child's `LOBEHUB_WORKSPACE_ID` env so its own `lh notify`
+   * shells inherit the same scope.
+   */
+  workspaceId?: string;
 }

 export interface CancelHeteroTaskParams {
@@ -69,9 +76,10 @@ async function sendAutoNotify(
  taskId: string,
  text: string,
  agentId?: string,
+  workspaceId?: string,
 ): Promise<void> {
  try {
-    const client = await getTrpcClient();
+    const client = await getTrpcClient(workspaceId);
    await client.agentNotify.notify.mutate({
      agentId,
      content: text,
@@ -90,9 +98,13 @@ async function sendAutoNotify(
 * `sendAutoNotify` which writes an error message AND triggers completion via
 * the `done` flag.
 */
-async function sendDoneSignal(topicId: string, agentId?: string): Promise<void> {
+async function sendDoneSignal(
+  topicId: string,
+  agentId?: string,
+  workspaceId?: string,
+): Promise<void> {
  try {
-    const client = await getTrpcClient();
+    const client = await getTrpcClient(workspaceId);
    await client.agentNotify.notify.mutate({
      agentId,
      content: '',
@@ -138,9 +150,15 @@ function buildNotifyProtocol(lhPath: string, topicId: string): string {
 }

 export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string> {
-  const { agentId, agentType, cwd, operationId, prompt, taskId, topicId } = params;
+  const { agentId, agentType, cwd, operationId, prompt, taskId, topicId, workspaceId } = params;
  const workDir = cwd || process.cwd();
  const lhPath = resolveLhPath();
+  // Propagate workspace scope into the spawned child so its own `lh notify`
+  // invocations (and any grandchildren it shells out) inherit the same scope
+  // via getTrpcClient → resolveWorkspaceId.
+  const childEnv: NodeJS.ProcessEnv = workspaceId
+    ? { ...process.env, LOBEHUB_WORKSPACE_ID: workspaceId }
+    : { ...process.env };

  if (agentType === 'openclaw') {
    // openclaw agent --local is one-shot: each invocation processes one message and exits.
@@ -182,7 +200,7 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
      {
        cwd: workDir,
        detached: true,
-        env: { ...process.env },
+        env: childEnv,
        stdio: 'ignore',
      },
    );
@@ -201,6 +219,7 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
      startedAt: new Date().toISOString(),
      taskId,
      topicId,
+      workspaceId,
    });
    log.info(`OpenClaw task started: taskId=${taskId} pid=${pid} agent=${openclawAgent}`);

@@ -216,12 +235,12 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
          : `Task failed (exit code: ${code})`;
        // Send error message first, THEN signal done (sequential).
        // Fire-and-forget both, but ensure done is always sent even if notify fails.
-        void sendAutoNotify(topicId, taskId, text, agentId).finally(() =>
-          sendDoneSignal(topicId, agentId),
+        void sendAutoNotify(topicId, taskId, text, agentId, workspaceId).finally(() =>
+          sendDoneSignal(topicId, agentId, workspaceId),
        );
      } else {
        // Clean exit — openclaw already sent its final message; just signal done.
-        void sendDoneSignal(topicId, agentId);
+        void sendDoneSignal(topicId, agentId, workspaceId);
      }
    });

@@ -253,7 +272,7 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
    const child = spawn('hermes', hermesArgs, {
      cwd: workDir,
      detached: true,
-      env: { ...process.env },
+      env: childEnv,
      stdio: ['ignore', 'pipe', 'ignore'],
    });

@@ -269,6 +288,7 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
      startedAt: new Date().toISOString(),
      taskId,
      topicId,
+      workspaceId,
    });
    log.info(`Hermes task started: taskId=${taskId} pid=${pid}`);

@@ -284,8 +304,8 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
        const text = signal
          ? `Task cancelled (signal: ${signal})`
          : `Task failed (exit code: ${code})`;
-        void sendAutoNotify(topicId, taskId, text, agentId).finally(() =>
-          sendDoneSignal(topicId, agentId),
+        void sendAutoNotify(topicId, taskId, text, agentId, workspaceId).finally(() =>
+          sendDoneSignal(topicId, agentId, workspaceId),
        );
        return;
      }
@@ -298,11 +318,11 @@ export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string
      if (sessionId) saveHermesSessionId(topicId, sessionId);

      if (response) {
-        void sendAutoNotify(topicId, taskId, response, agentId).finally(() =>
-          sendDoneSignal(topicId, agentId),
+        void sendAutoNotify(topicId, taskId, response, agentId, workspaceId).finally(() =>
+          sendDoneSignal(topicId, agentId, workspaceId),
        );
      } else {
-        void sendDoneSignal(topicId, agentId);
+        void sendDoneSignal(topicId, agentId, workspaceId);
      }
    });

@@ -334,6 +354,7 @@ export async function cancelHeteroTask(params: CancelHeteroTaskParams): Promise<
      taskId,
      'Task already completed or cancelled',
      entry.agentId,
+      entry.workspaceId,
    );
  }

@@ -0,0 +1,125 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { TrpcClient } from '../api/client';
+
+/**
+ * Minimal extension → MIME map for files uploaded from the local filesystem.
+ * Unknown extensions fall back to `application/octet-stream`.
+ */
+const MIME_MAP: Record<string, string> = {
+  aac: 'audio/aac',
+  csv: 'text/csv',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  flac: 'audio/flac',
+  gif: 'image/gif',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  json: 'application/json',
+  m4a: 'audio/mp4',
+  md: 'text/markdown',
+  mp3: 'audio/mpeg',
+  mp4: 'video/mp4',
+  ogg: 'audio/ogg',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  svg: 'image/svg+xml',
+  txt: 'text/plain',
+  wav: 'audio/wav',
+  webm: 'audio/webm',
+  webp: 'image/webp',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+
+/**
+ * Detect a MIME type from a file name's extension.
+ */
+export const detectMimeType = (fileName: string): string => {
+  const ext = path.extname(fileName).toLowerCase().slice(1);
+  return MIME_MAP[ext] || 'application/octet-stream';
+};
+
+export interface UploadLocalFileOptions {
+  knowledgeBaseId?: string;
+  parentId?: string;
+}
+
+/**
+ * Read a file from the local filesystem, upload it to S3 via a pre-signed URL,
+ * and create the corresponding file record. Shared by `file upload` and
+ * `kb upload`.
+ *
+ * @returns the created file record
+ */
+export const uploadLocalFile = async (
+  client: TrpcClient,
+  filePath: string,
+  options: UploadLocalFileOptions = {},
+) => {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+
+  const stat = fs.statSync(resolved);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${resolved}`);
+  }
+
+  const fileName = path.basename(resolved);
+  const fileBuffer = fs.readFileSync(resolved);
+
+  // Compute SHA-256 hash for deduplication
+  const hash = crypto.createHash('sha256').update(fileBuffer).digest('hex');
+
+  const ext = path.extname(fileName).toLowerCase().slice(1);
+  const fileType = detectMimeType(fileName);
+
+  const date = new Date().toLocaleDateString('en-CA'); // YYYY-MM-DD
+
+  // 1. Dedup: if the same bytes are already stored (and the object still
+  // exists), skip the S3 upload entirely and reuse the existing url.
+  const existing = (await client.file.checkFileHash.mutate({ hash })) as {
+    isExist?: boolean;
+    url?: string;
+  };
+
+  let pathname: string;
+  if (existing?.isExist && existing.url) {
+    pathname = existing.url;
+  } else {
+    // 2. Get a pre-signed upload URL and PUT the bytes to S3
+    pathname = ext ? `files/${date}/${hash}.${ext}` : `files/${date}/${hash}`;
+    const presigned = await client.upload.createS3PreSignedUrl.mutate({ pathname });
+
+    const presignedUrl = typeof presigned === 'string' ? presigned : (presigned as any).url;
+    const uploadRes = await fetch(presignedUrl, {
+      body: fileBuffer,
+      headers: { 'Content-Type': fileType },
+      method: 'PUT',
+    });
+    if (!uploadRes.ok) {
+      throw new Error(`Upload failed: ${uploadRes.status} ${uploadRes.statusText}`);
+    }
+  }
+
+  // 3. Create the file record
+  return await client.file.createFile.mutate({
+    fileType,
+    hash,
+    knowledgeBaseId: options.knowledgeBaseId,
+    metadata: {
+      date,
+      dirname: '',
+      filename: fileName,
+      path: pathname,
+    },
+    name: fileName,
+    parentId: options.parentId,
+    size: stat.size,
+    url: pathname,
+  });
+};
@@ -9,14 +9,6 @@ export default defineConfig({
        find: '@lobechat/device-gateway-client',
        replacement: path.resolve(__dirname, '../../packages/device-gateway-client/src/index.ts'),
      },
-      {
-        find: '@lobechat/device-identity',
-        replacement: path.resolve(__dirname, '../../packages/device-identity/src/index.ts'),
-      },
-      {
-        find: '@lobechat/device-control',
-        replacement: path.resolve(__dirname, '../../packages/device-control/src/index.ts'),
-      },
      {
        find: '@lobechat/local-file-shell',
        replacement: path.resolve(__dirname, '../../packages/local-file-shell/src/index.ts'),
@@ -127,8 +127,8 @@
    ],
    "overrides": {
      "node-gyp": "^12.4.0",
-      "react": "19.2.4",
-      "react-dom": "19.2.4",
+      "react": "19.2.7",
+      "react-dom": "19.2.7",
      "vitest": "3.2.6"
    }
  }
@@ -17,3 +17,9 @@ packages:
  - './stubs/business-const'
  - './stubs/types'
  - '.'
+allowBuilds:
+  electron: set this to true or false
+  electron-winstaller: set this to true or false
+  esbuild: set this to true or false
+  get-windows: set this to true or false
+  node-mac-permissions: set this to true or false
@@ -77,6 +77,12 @@ interface PlatformTaskEntry {
  operationId: string;
  pid: number;
  topicId: string;
+  /**
+   * Workspace that owns the dispatched topic — used at exit time so the
+   * cleanup notify still scopes to the workspace agentNotify resolves the
+   * topic in (the server seeds this via the `runHeteroTask` args).
+   */
+  workspaceId?: string;
 }

 /**
@@ -286,12 +292,11 @@ export default class GatewayConnectionCtr extends ControllerModule {
        return { reason: 'Remote server URL not configured', status: 'rejected' };
      }

-      // Hand off to `lh hetero exec`; the spawned CLI then owns adapt ->
+      // Fire-and-forget: lh hetero exec handles spawn -> adapt ->
      // BatchIngester -> heteroIngest/heteroFinish -> server -> Gateway -> clients.
      // Same command as spawnHeteroSandbox() on the server side.
-      await this.heterogeneousAgentCtr.spawnLhHeteroExec({
+      this.heterogeneousAgentCtr.spawnLhHeteroExec({
        agentType: request.agentType,
-        command: request.command,
        cwd: request.cwd,
        imageList: request.imageList,
        jwt: request.jwt,
@@ -525,6 +530,7 @@ export default class GatewayConnectionCtr extends ControllerModule {
            prompt: string;
            taskId: string;
            topicId: string;
+            workspaceId?: string;
          },
        );
        return { content: json, state: safeJsonParse(json), success: true };
@@ -766,8 +772,9 @@ export default class GatewayConnectionCtr extends ControllerModule {
    prompt: string;
    taskId: string;
    topicId: string;
+    workspaceId?: string;
  }): Promise<string> {
-    const { agentId, agentType, cwd, operationId, prompt, taskId, topicId } = args;
+    const { agentId, agentType, cwd, operationId, prompt, taskId, topicId, workspaceId } = args;
    const workDir = cwd || process.cwd();

    const [serverUrl, accessToken] = await Promise.all([
@@ -775,11 +782,15 @@ export default class GatewayConnectionCtr extends ControllerModule {
      this.remoteServerConfigCtr.getAccessToken(),
    ]);

-    // Inject auth into child env so `lh notify` can authenticate without CLI config.
+    // Inject auth + workspace scope into child env so `lh notify` can
+    // authenticate AND target the same workspace as the dispatched topic
+    // (without LOBEHUB_WORKSPACE_ID, the CLI's notify falls back to personal
+    // mode and the workspace topic 404s).
    const childEnv: NodeJS.ProcessEnv = {
      ...process.env,
      ...(accessToken && { LOBEHUB_JWT: accessToken }),
      ...(serverUrl && { LOBEHUB_SERVER: serverUrl }),
+      ...(workspaceId && { LOBEHUB_WORKSPACE_ID: workspaceId }),
    };

    if (agentType === 'openclaw') {
@@ -824,7 +835,14 @@ export default class GatewayConnectionCtr extends ControllerModule {
      if (pid === undefined) throw new Error('Failed to get PID for openclaw process');
      child.unref();

-      this.platformTasks.set(taskId, { agentId, agentType, operationId, pid, topicId });
+      this.platformTasks.set(taskId, {
+        agentId,
+        agentType,
+        operationId,
+        pid,
+        topicId,
+        workspaceId,
+      });

      child.on('close', (code, signal) => {
        this.platformTasks.delete(taskId);
@@ -832,11 +850,31 @@ export default class GatewayConnectionCtr extends ControllerModule {
          const text = signal
            ? `Task cancelled (signal: ${signal})`
            : `Task failed (exit code: ${code})`;
-          void this.sendNotify({ agentId, content: text, role: 'assistant', topicId }).finally(() =>
-            this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId }),
+          void this.sendNotify({
+            agentId,
+            content: text,
+            role: 'assistant',
+            topicId,
+            workspaceId,
+          }).finally(() =>
+            this.sendNotify({
+              agentId,
+              content: '',
+              done: true,
+              role: 'assistant',
+              topicId,
+              workspaceId,
+            }),
          );
        } else {
-          void this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId });
+          void this.sendNotify({
+            agentId,
+            content: '',
+            done: true,
+            role: 'assistant',
+            topicId,
+            workspaceId,
+          });
        }
      });

@@ -875,7 +913,14 @@ export default class GatewayConnectionCtr extends ControllerModule {
      if (pid === undefined) throw new Error('Failed to get PID for hermes process');
      child.unref();

-      this.platformTasks.set(taskId, { agentId, agentType, operationId, pid, topicId });
+      this.platformTasks.set(taskId, {
+        agentId,
+        agentType,
+        operationId,
+        pid,
+        topicId,
+        workspaceId,
+      });

      let stdout = '';
      child.stdout.on('data', (chunk: Buffer) => {
@@ -889,8 +934,21 @@ export default class GatewayConnectionCtr extends ControllerModule {
          const text = signal
            ? `Task cancelled (signal: ${signal})`
            : `Task failed (exit code: ${code})`;
-          void this.sendNotify({ agentId, content: text, role: 'assistant', topicId }).finally(() =>
-            this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId }),
+          void this.sendNotify({
+            agentId,
+            content: text,
+            role: 'assistant',
+            topicId,
+            workspaceId,
+          }).finally(() =>
+            this.sendNotify({
+              agentId,
+              content: '',
+              done: true,
+              role: 'assistant',
+              topicId,
+              workspaceId,
+            }),
          );
          return;
        }
@@ -903,11 +961,31 @@ export default class GatewayConnectionCtr extends ControllerModule {
        if (sessionId) this.hermesSessionMap.set(topicId, sessionId);

        if (response) {
-          void this.sendNotify({ agentId, content: response, role: 'assistant', topicId }).finally(
-            () => this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId }),
+          void this.sendNotify({
+            agentId,
+            content: response,
+            role: 'assistant',
+            topicId,
+            workspaceId,
+          }).finally(() =>
+            this.sendNotify({
+              agentId,
+              content: '',
+              done: true,
+              role: 'assistant',
+              topicId,
+              workspaceId,
+            }),
          );
        } else {
-          void this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId });
+          void this.sendNotify({
+            agentId,
+            content: '',
+            done: true,
+            role: 'assistant',
+            topicId,
+            workspaceId,
+          });
        }
      });

@@ -935,6 +1013,7 @@ export default class GatewayConnectionCtr extends ControllerModule {
        content: 'Task already completed or cancelled',
        role: 'assistant',
        topicId: entry.topicId,
+        workspaceId: entry.workspaceId,
      });
    }

@@ -952,6 +1031,12 @@ export default class GatewayConnectionCtr extends ControllerModule {
    done?: boolean;
    role: string;
    topicId: string;
+    /**
+     * Workspace scope for the notify. When set, attaches `X-Workspace-Id` so
+     * agentNotify resolves the workspace-owned topic instead of falling back
+     * to personal mode (which would 404 the lookup).
+     */
+    workspaceId?: string;
  }): Promise<void> {
    try {
      const [serverUrl, token] = await Promise.all([
@@ -960,12 +1045,16 @@ export default class GatewayConnectionCtr extends ControllerModule {
      ]);
      if (!serverUrl || !token) return;

+      const { workspaceId, ...body } = params;
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'Oidc-Auth': token,
+      };
+      if (workspaceId) headers['X-Workspace-Id'] = workspaceId;
+
      await fetch(`${serverUrl}/trpc/lambda/agentNotify.notify`, {
-        body: JSON.stringify({ json: params }),
-        headers: {
-          'Content-Type': 'application/json',
-          'Oidc-Auth': token,
-        },
+        body: JSON.stringify({ json: body }),
+        headers,
        method: 'POST',
      });
    } catch {
@@ -15,6 +15,7 @@ import type {
  GitWorkingTreeFiles,
  GitWorkingTreePatches,
  GitWorkingTreeStatus,
+  GitWorktreeListItem,
 } from '@lobechat/electron-client-ipc';
 import {
  checkoutGitBranch as runCheckoutGitBranch,
@@ -30,6 +31,7 @@ import {
  gitInfo as computeGitInfo,
  listGitBranches as computeListGitBranches,
  listGitRemoteBranches as computeListGitRemoteBranches,
+  listGitWorktrees as computeListGitWorktrees,
  pullGitBranch as runPullGitBranch,
  pushGitBranch as runPushGitBranch,
  renameGitBranch as runRenameGitBranch,
@@ -83,6 +85,11 @@ export default class GitController extends ControllerModule {
    return computeListGitRemoteBranches(dirPath);
  }

+  @IpcMethod()
+  async listGitWorktrees(dirPath: string): Promise<GitWorktreeListItem[]> {
+    return computeListGitWorktrees(dirPath);
+  }
+
  @IpcMethod()
  async getGitWorkingTreeStatus(dirPath: string): Promise<GitWorkingTreeStatus> {
    return computeGitWorkingTreeStatus(dirPath);
@@ -36,7 +36,6 @@ import {
 import { app as electronApp, BrowserWindow } from 'electron';

 import { HETERO_AGENT_FILES_DIR, HETERO_AGENT_TRACING_DIR } from '@/const/heteroAgent';
-import type { ToolStatus } from '@/core/infrastructure/ToolDetectorManager';
 import { getHeterogeneousAgentDriver } from '@/modules/heterogeneousAgent';
 import type {
  HeterogeneousAgentBuildPlan,
@@ -220,11 +219,6 @@ interface CliTraceSession {
  writeQueue: Promise<void>;
 }

-interface ResolvedDeviceHeteroCommand {
-  command: string;
-  resolvedPathEnv?: string;
-}
-
 /**
 * External Agent Controller — manages external agent CLI processes via Electron IPC.
 *
@@ -265,58 +259,6 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
    return session.agentType === 'codex' ? 'codex' : 'claude';
  }

-  private getDefaultCommandForAgentType(agentType: string): string | undefined {
-    if (agentType === 'codex') return 'codex';
-    if (agentType === 'claude-code') return 'claude';
-  }
-
-  private isBareCommand(command: string): boolean {
-    return !command.includes('/') && !command.includes('\\');
-  }
-
-  private async resolveDeviceHeteroCommand(
-    agentType: string,
-    command?: string,
-  ): Promise<ResolvedDeviceHeteroCommand | undefined> {
-    const requestedCommand = command?.trim() || this.getDefaultCommandForAgentType(agentType);
-    if (!requestedCommand) return;
-
-    if (agentType !== 'claude-code' && agentType !== 'codex') {
-      return { command: requestedCommand };
-    }
-
-    const defaultCommand = this.getDefaultCommandForAgentType(agentType);
-    let status: ToolStatus | undefined;
-    try {
-      status =
-        requestedCommand === defaultCommand && defaultCommand
-          ? await this.app.toolDetectorManager?.detect?.(defaultCommand, true)
-          : await detectHeterogeneousCliCommand(
-              agentType === 'claude-code' ? 'claude-code' : 'codex',
-              requestedCommand,
-            );
-
-      if (status?.available && status.path && this.isBareCommand(requestedCommand)) {
-        return { command: status.path, resolvedPathEnv: status.resolvedPathEnv };
-      }
-    } catch (err) {
-      logger.warn(
-        'resolveDeviceHeteroCommand: failed to resolve %s command "%s": %s',
-        agentType,
-        requestedCommand,
-        err instanceof Error ? err.message : String(err),
-      );
-    }
-
-    if (status && !status.available) {
-      throw new Error(
-        `${agentType} CLI command "${requestedCommand}" was not found on this device`,
-      );
-    }
-
-    return { command: requestedCommand };
-  }
-
  private buildCodexCliMissingError(session: AgentSession): HeterogeneousAgentSessionError {
    const command = this.resolveSessionCommand(session);

@@ -1527,9 +1469,8 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
   * AgentStreamPipeline or IPC broadcast needed. Mirrors
   * `spawnHeteroSandbox()` on the server side.
   */
-  async spawnLhHeteroExec(params: {
+  spawnLhHeteroExec(params: {
    agentType: string;
-    command?: string;
    cwd?: string;
    /** Image attachments (signed URLs) appended as image content blocks. */
    imageList?: HeteroExecImageRef[];
@@ -1540,10 +1481,9 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
    serverUrl: string;
    systemContext?: string;
    topicId: string;
-  }): Promise<void> {
+  }): void {
    const {
      agentType,
-      command,
      cwd,
      imageList,
      jwt,
@@ -1555,7 +1495,6 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
      topicId,
    } = params;
    const workDir = cwd ?? process.cwd();
-    const resolvedCommand = await this.resolveDeviceHeteroCommand(agentType, command);

    // When CLI tracing is enabled (dev builds, or the Help-menu toggle in
    // packaged builds), have `lh hetero exec` persist the agent process's RAW
@@ -1570,7 +1509,6 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
      'exec',
      '--type',
      agentType,
-      ...(resolvedCommand?.command ? ['--command', resolvedCommand.command] : []),
      '--operation-id',
      operationId,
      '--topic',
@@ -1588,7 +1526,6 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
    const env = {
      ...process.env,
      ...buildProxyEnv(this.app.storeManager.get('networkProxy')),
-      ...(resolvedCommand?.resolvedPathEnv ? { PATH: resolvedCommand.resolvedPathEnv } : {}),
      LOBEHUB_JWT: jwt,
      LOBEHUB_SERVER: serverUrl,
    };
@@ -366,14 +366,14 @@ export default class LocalFileCtr extends ControllerModule {
  }

  @IpcMethod()
-  async readFiles({ paths }: LocalReadFilesParams): Promise<LocalReadFileResult[]> {
+  async readFiles({ paths, cwd }: LocalReadFilesParams): Promise<LocalReadFileResult[]> {
    logger.debug('Starting batch file reading:', { count: paths.length });

    const results: LocalReadFileResult[] = [];

    for (const filePath of paths) {
      logger.debug('Reading single file:', { filePath });
-      const result = await readLocalFile({ path: filePath });
+      const result = await readLocalFile({ cwd, path: filePath });
      results.push(result);
    }

@@ -400,9 +400,9 @@ export default class LocalFileCtr extends ControllerModule {
  }

  @IpcMethod()
-  async handleMoveFiles({ items }: MoveLocalFilesParams): Promise<LocalMoveFilesResultItem[]> {
+  async handleMoveFiles({ items, cwd }: MoveLocalFilesParams): Promise<LocalMoveFilesResultItem[]> {
    logger.debug('Starting batch file move:', { itemsCount: items?.length });
-    return moveLocalFiles({ items });
+    return moveLocalFiles({ cwd, items });
  }

  @IpcMethod()
@@ -418,9 +418,9 @@ export default class LocalFileCtr extends ControllerModule {
  }

  @IpcMethod()
-  async handleWriteFile({ path: filePath, content }: WriteLocalFileParams) {
+  async handleWriteFile({ path: filePath, content, cwd }: WriteLocalFileParams) {
    logger.debug(`Writing file ${filePath}`, { contentLength: content?.length });
-    return writeLocalFile({ content, path: filePath });
+    return writeLocalFile({ content, cwd, path: filePath });
  }

  @IpcMethod()
@@ -438,12 +438,14 @@ export default class LocalFileCtr extends ControllerModule {
  @IpcMethod()
  async getLocalFilePreviewUrl({
    accept,
+    allowExternalFile,
    path: filePath,
    workingDirectory,
  }: LocalFilePreviewUrlParams): Promise<LocalFilePreviewUrlResult> {
    try {
      const url = await this.app.localFileProtocolManager.createPreviewUrl({
        accept,
+        allowExternalFile,
        filePath,
        workspaceRoot: workingDirectory,
      });
@@ -462,12 +464,14 @@ export default class LocalFileCtr extends ControllerModule {
  @IpcMethod()
  async getLocalFilePreview({
    accept,
+    allowExternalFile,
    path: filePath,
    workingDirectory,
  }: LocalFilePreviewUrlParams): Promise<LocalFilePreviewResult> {
    try {
      const preview = await this.app.localFileProtocolManager.readPreviewFile({
        accept,
+        allowExternalFile,
        filePath,
        workspaceRoot: workingDirectory,
      });
@@ -199,10 +199,6 @@ vi.mock('@lobechat/device-gateway-client', () => ({
  GatewayClient: MockGatewayClient,
 }));

-vi.mock('@lobechat/device-identity', () => ({
-  deriveDeviceId: vi.fn(() => 'mock-device-id'),
-}));
-
 vi.mock('@/services/imessageBridgeSrv', () => ({
  default: class ImessageBridgeService {},
 }));
@@ -849,10 +845,9 @@ describe('GatewayConnectionCtr', () => {
      },
    );

-    it('forwards cwd, command, and systemContext from the request to spawnLhHeteroExec', async () => {
+    it('forwards cwd and systemContext from the request to spawnLhHeteroExec', async () => {
      const client = await connectAndOpen();
      client.simulateAgentRunRequest('claude-code', 'op-ctx', 'hi', 'mock-jwt', {
-        command: '/custom/bin/claude',
        cwd: '/Users/alice/repo',
        systemContext: 'WORKSPACE CONTEXT',
      });
@@ -860,7 +855,6 @@ describe('GatewayConnectionCtr', () => {

      expect(mockHeterogeneousAgentCtr.spawnLhHeteroExec).toHaveBeenCalledWith(
        expect.objectContaining({
-          command: '/custom/bin/claude',
          cwd: '/Users/alice/repo',
          systemContext: 'WORKSPACE CONTEXT',
        }),
@@ -127,71 +127,6 @@ describe('HeterogeneousAgentCtr', () => {
    await rm(appStoragePath, { force: true, recursive: true });
  });

-  describe('spawnLhHeteroExec', () => {
-    beforeEach(() => {
-      spawnCalls.length = 0;
-      execFileMock.mockReset();
-      nextFakeProc = null;
-    });
-
-    it('passes the detector-resolved Codex command to remote-device lh hetero exec', async () => {
-      const resolvedPath = '/Applications/Codex.app/Contents/Resources/codex';
-      const searchPath = '/Users/h/.local/share/mise/shims:/usr/bin:/bin';
-      const detect = vi
-        .fn()
-        .mockResolvedValue({ available: true, path: resolvedPath, resolvedPathEnv: searchPath });
-      const { proc, writes } = createFakeProc();
-      nextFakeProc = proc;
-
-      const ctr = new HeterogeneousAgentCtr({
-        appStoragePath,
-        storeManager: { get: vi.fn() },
-        toolDetectorManager: { detect },
-      } as any);
-
-      await ctr.spawnLhHeteroExec({
-        agentType: 'codex',
-        command: 'codex',
-        jwt: 'jwt-1',
-        operationId: 'op-1',
-        prompt: 'hello codex',
-        serverUrl: 'https://server.example.com',
-        topicId: 'topic-1',
-      });
-
-      expect(detect).toHaveBeenCalledWith('codex', true);
-      expect(spawnCalls[0].command).toBe('lh');
-      expect(spawnCalls[0].args).toEqual(
-        expect.arrayContaining(['--type', 'codex', '--command', resolvedPath]),
-      );
-      expect(spawnCalls[0].options.env.PATH).toBe(searchPath);
-      expect(writes).toEqual([JSON.stringify('hello codex')]);
-    });
-
-    it('rejects before spawning lh when the Codex command is unavailable on the device', async () => {
-      const detect = vi.fn().mockResolvedValue({ available: false });
-      const ctr = new HeterogeneousAgentCtr({
-        appStoragePath,
-        storeManager: { get: vi.fn() },
-        toolDetectorManager: { detect },
-      } as any);
-
-      await expect(
-        ctr.spawnLhHeteroExec({
-          agentType: 'codex',
-          command: 'codex',
-          jwt: 'jwt-1',
-          operationId: 'op-1',
-          prompt: 'hello codex',
-          serverUrl: 'https://server.example.com',
-          topicId: 'topic-1',
-        }),
-      ).rejects.toThrow('codex CLI command "codex" was not found on this device');
-
-      expect(spawnCalls).toHaveLength(0);
-    });
-  });
-
  describe('image cache (delegates to shared `normalizeImage`)', () => {
    // Image fetch + cache moved to `@lobechat/heterogeneous-agents/spawn`'s
    // `normalizeImage`. The desktop controller passes its own cacheDir so the
@@ -226,6 +226,7 @@ describe('LocalFileCtr', () => {

      expect(mockLocalFileProtocolManager.createPreviewUrl).toHaveBeenCalledWith({
        accept: undefined,
+        allowExternalFile: undefined,
        filePath: '/workspace/app.ts',
        workspaceRoot: '/workspace',
      });
@@ -262,6 +263,7 @@ describe('LocalFileCtr', () => {

      expect(mockLocalFileProtocolManager.createPreviewUrl).toHaveBeenCalledWith({
        accept: 'image',
+        allowExternalFile: undefined,
        filePath: '/workspace/image.png',
        workspaceRoot: '/workspace',
      });
@@ -270,6 +272,29 @@ describe('LocalFileCtr', () => {
        url: 'localfile://file/workspace/image.png?token=abc',
      });
    });
+
+    it('should forward user-approved external preview URL access', async () => {
+      mockLocalFileProtocolManager.createPreviewUrl.mockResolvedValue(
+        'localfile://file/tmp/worktree-switcher-demo.html?token=abc',
+      );
+
+      const result = await localFileCtr.getLocalFilePreviewUrl({
+        allowExternalFile: true,
+        path: '/tmp/worktree-switcher-demo.html',
+        workingDirectory: '/tmp',
+      });
+
+      expect(mockLocalFileProtocolManager.createPreviewUrl).toHaveBeenCalledWith({
+        allowExternalFile: true,
+        accept: undefined,
+        filePath: '/tmp/worktree-switcher-demo.html',
+        workspaceRoot: '/tmp',
+      });
+      expect(result).toEqual({
+        success: true,
+        url: 'localfile://file/tmp/worktree-switcher-demo.html?token=abc',
+      });
+    });
  });

  describe('getLocalFilePreview', () => {
@@ -287,6 +312,7 @@ describe('LocalFileCtr', () => {

      expect(mockLocalFileProtocolManager.readPreviewFile).toHaveBeenCalledWith({
        accept: undefined,
+        allowExternalFile: undefined,
        filePath: '/workspace/app.ts',
        workspaceRoot: '/workspace',
      });
@@ -329,6 +355,7 @@ describe('LocalFileCtr', () => {

      expect(mockLocalFileProtocolManager.readPreviewFile).toHaveBeenCalledWith({
        accept: 'image',
+        allowExternalFile: undefined,
        filePath: '/workspace/image.png',
        workspaceRoot: '/workspace',
      });
@@ -341,6 +368,35 @@ describe('LocalFileCtr', () => {
        success: true,
      });
    });
+
+    it('should forward user-approved external preview reads', async () => {
+      mockLocalFileProtocolManager.readPreviewFile.mockResolvedValue({
+        buffer: Buffer.from('<h1>Demo</h1>'),
+        contentType: 'text/html',
+        realPath: '/tmp/worktree-switcher-demo.html',
+      });
+
+      const result = await localFileCtr.getLocalFilePreview({
+        allowExternalFile: true,
+        path: '/tmp/worktree-switcher-demo.html',
+        workingDirectory: '/tmp',
+      });
+
+      expect(mockLocalFileProtocolManager.readPreviewFile).toHaveBeenCalledWith({
+        allowExternalFile: true,
+        accept: undefined,
+        filePath: '/tmp/worktree-switcher-demo.html',
+        workspaceRoot: '/tmp',
+      });
+      expect(result).toEqual({
+        preview: {
+          content: '<h1>Demo</h1>',
+          contentType: 'text/html',
+          type: 'text',
+        },
+        success: true,
+      });
+    });
  });

  describe('handleWriteFile', () => {
@@ -21,6 +21,7 @@ const LOCAL_FILE_PROTOCOL_PRIVILEGES = {

 const logger = createLogger('core:LocalFileProtocolManager');
 const PREVIEW_TOKEN_TTL_MS = 5 * 60 * 1000;
+const EXTERNAL_PREVIEW_APPROVAL_TTL_MS = 10 * 60 * 1000;

 const normalizeAbsolutePath = (filePath: string): string | null => {
  const normalized = path.normalize(filePath);
@@ -59,10 +60,7 @@ type PreviewFileAccept = 'image';
 const normalizeContentType = (contentType: string): string =>
  contentType.split(';')[0].trim().toLowerCase();

-const isAcceptedPreviewContentType = (
-  contentType: string,
-  accept?: PreviewFileAccept,
-): boolean => {
+const isAcceptedPreviewContentType = (contentType: string, accept?: PreviewFileAccept): boolean => {
  if (!accept) return true;

  const normalizedContentType = normalizeContentType(contentType);
@@ -84,6 +82,8 @@ const isAcceptedPreviewContentType = (
 export class LocalFileProtocolManager {
  private readonly approvedWorkspaceRoots = new Set<string>();

+  private readonly externalPreviewApprovals = new Map<string, number>();
+
  private readonly indexedProjectRoots = new Set<string>();

  private handlerRegistered = false;
@@ -229,10 +229,12 @@ export class LocalFileProtocolManager {

  async createPreviewUrl({
    accept,
+    allowExternalFile,
    filePath,
    workspaceRoot,
  }: {
    accept?: PreviewFileAccept;
+    allowExternalFile?: boolean;
    filePath: string;
    workspaceRoot: string;
  }): Promise<string | null> {
@@ -243,11 +245,12 @@ export class LocalFileProtocolManager {
      ? (
          await this.readPreviewFile({
            accept,
+            allowExternalFile,
            filePath,
            workspaceRoot,
          })
        )?.realPath
-      : await this.resolveApprovedPreviewPath({ filePath, workspaceRoot });
+      : await this.resolveApprovedPreviewPath({ allowExternalFile, filePath, workspaceRoot });
    if (!realFilePath) return null;

    this.cleanupExpiredTokens();
@@ -263,14 +266,21 @@ export class LocalFileProtocolManager {

  async readPreviewFile({
    accept,
+    allowExternalFile,
    filePath,
    workspaceRoot,
  }: {
    accept?: PreviewFileAccept;
+    allowExternalFile?: boolean;
    filePath: string;
    workspaceRoot: string;
  }): Promise<PreviewFileReadResult | null> {
-    const realFilePath = await this.resolveApprovedPreviewPath({ filePath, workspaceRoot });
+    const realFilePath = await this.resolveApprovedPreviewPath({
+      allowExternalFile,
+      filePath,
+      persistExternalApproval: false,
+      workspaceRoot,
+    });
    if (!realFilePath) return null;

    const fileStat = await stat(realFilePath);
@@ -280,6 +290,10 @@ export class LocalFileProtocolManager {
    const contentType = resolveLocalFileMimeType(realFilePath, buffer);
    if (!isAcceptedPreviewContentType(contentType, accept)) return null;

+    if (allowExternalFile) {
+      this.grantExternalPreviewApproval(realFilePath);
+    }
+
    return {
      buffer,
      contentType,
@@ -327,10 +341,14 @@ export class LocalFileProtocolManager {
  }

  private async resolveApprovedPreviewPath({
+    allowExternalFile,
    filePath,
+    persistExternalApproval = true,
    workspaceRoot,
  }: {
+    allowExternalFile?: boolean;
    filePath: string;
+    persistExternalApproval?: boolean;
    workspaceRoot: string;
  }): Promise<string | null> {
    const normalizedFilePath = normalizeAbsolutePath(filePath);
@@ -345,15 +363,44 @@ export class LocalFileProtocolManager {
    const normalizedRealWorkspaceRoot = normalizeAbsolutePath(realWorkspaceRoot);

    if (!normalizedRealFilePath || !normalizedRealWorkspaceRoot) return null;
+    const workspaceRootApproved =
+      this.approvedWorkspaceRoots.has(normalizedRealWorkspaceRoot) ||
+      this.indexedProjectRoots.has(normalizedRealWorkspaceRoot);
    if (
-      !this.approvedWorkspaceRoots.has(normalizedRealWorkspaceRoot) &&
-      !this.indexedProjectRoots.has(normalizedRealWorkspaceRoot)
+      workspaceRootApproved &&
+      isPathWithinRoot(normalizedRealFilePath, normalizedRealWorkspaceRoot)
    ) {
-      return null;
+      return normalizedRealFilePath;
    }
-    if (!isPathWithinRoot(normalizedRealFilePath, normalizedRealWorkspaceRoot)) return null;

-    return normalizedRealFilePath;
+    if (this.hasExternalPreviewApproval(normalizedRealFilePath)) return normalizedRealFilePath;
+
+    if (allowExternalFile) {
+      return this.approveExternalPreviewFile(normalizedRealFilePath, {
+        persist: persistExternalApproval,
+      });
+    }
+
+    return null;
+  }
+
+  private async approveExternalPreviewFile(
+    realFilePath: string,
+    { persist = true }: { persist?: boolean } = {},
+  ): Promise<string | null> {
+    const fileStat = await stat(realFilePath);
+    if (!fileStat.isFile()) return null;
+
+    if (persist) {
+      this.grantExternalPreviewApproval(realFilePath);
+    }
+
+    return realFilePath;
+  }
+
+  private grantExternalPreviewApproval(realFilePath: string) {
+    this.cleanupExpiredExternalPreviewApprovals();
+    this.externalPreviewApprovals.set(realFilePath, Date.now() + EXTERNAL_PREVIEW_APPROVAL_TTL_MS);
  }

  private cleanupExpiredTokens() {
@@ -365,6 +412,15 @@ export class LocalFileProtocolManager {
    }
  }

+  private cleanupExpiredExternalPreviewApprovals() {
+    const now = Date.now();
+    for (const [realPath, expiresAt] of this.externalPreviewApprovals) {
+      if (expiresAt <= now) {
+        this.externalPreviewApprovals.delete(realPath);
+      }
+    }
+  }
+
  private hasPreviewToken(token: string): boolean {
    const record = this.previewTokens.get(token);
    if (!record) return false;
@@ -383,4 +439,16 @@ export class LocalFileProtocolManager {

    return record.realPath === realResolvedPath;
  }
+
+  private hasExternalPreviewApproval(realFilePath: string): boolean {
+    const expiresAt = this.externalPreviewApprovals.get(realFilePath);
+    if (!expiresAt) return false;
+
+    if (expiresAt <= Date.now()) {
+      this.externalPreviewApprovals.delete(realFilePath);
+      return false;
+    }
+
+    return true;
+  }
 }
@@ -263,6 +263,31 @@ describe('LocalFileProtocolManager', () => {
    expect(url).toBeNull();
  });

+  it('mints preview URLs for user-approved external files only', async () => {
+    const manager = new LocalFileProtocolManager();
+
+    const url = await manager.createPreviewUrl({
+      allowExternalFile: true,
+      filePath: '/tmp/worktree-switcher-demo.html',
+      workspaceRoot: '/tmp',
+    });
+    if (!url) throw new Error('Expected external local file preview URL');
+
+    expect(url).toContain('token=');
+
+    const repeatedUrl = await manager.createPreviewUrl({
+      filePath: '/tmp/worktree-switcher-demo.html',
+      workspaceRoot: '/tmp',
+    });
+    expect(repeatedUrl).toContain('token=');
+
+    const neighborUrl = await manager.createPreviewUrl({
+      filePath: '/tmp/other.html',
+      workspaceRoot: '/tmp',
+    });
+    expect(neighborUrl).toBeNull();
+  });
+
  it('can approve a project root derived from an already approved nested scope', async () => {
    const manager = new LocalFileProtocolManager();
    await manager.approveWorkspaceRoot('/Users/alice/project/packages/app');
@@ -326,6 +351,26 @@ describe('LocalFileProtocolManager', () => {
    expect(mockReadFile).toHaveBeenCalledWith('/Users/alice/project/.env');
  });

+  it('does not keep external approval when an image-only external preview rejects text', async () => {
+    const manager = new LocalFileProtocolManager();
+    mockReadFile.mockResolvedValue(Buffer.from('SECRET=value'));
+
+    const result = await manager.readPreviewFile({
+      accept: 'image',
+      allowExternalFile: true,
+      filePath: '/tmp/secret.txt',
+      workspaceRoot: '/tmp',
+    });
+
+    expect(result).toBeNull();
+
+    const repeatedUrl = await manager.createPreviewUrl({
+      filePath: '/tmp/secret.txt',
+      workspaceRoot: '/tmp',
+    });
+    expect(repeatedUrl).toBeNull();
+  });
+
  it('does not read preview payloads outside the approved workspace root', async () => {
    const manager = new LocalFileProtocolManager();
    await manager.approveIndexedProjectRoot('/Users/alice/project');
@@ -3,6 +3,11 @@ import './pre-app-init';
 import fixPath from 'fix-path';

 import { App } from './core/App';
+import { installProcessErrorHandlers } from './process-error-handlers';
+
+// Guard the main process against transient network blips (Wi-Fi/VPN switch,
+// system sleep) emitted by Electron's net stack as uncaught exceptions.
+installProcessErrorHandlers();

 const app = new App();

@@ -1,5 +1,5 @@
 // apps/desktop/src/main/menus/impl/BaseMenuPlatform.ts
-import type { MenuItemConstructorOptions } from 'electron';
+import type { BaseWindow, MenuItemConstructorOptions } from 'electron';
 import { BrowserWindow } from 'electron';

 import type { App } from '@/core/App';
@@ -34,6 +34,26 @@ export abstract class BaseMenuPlatform {
    ];
  }

+  protected closeFocusedTabOrWindow(targetWindow?: BaseWindow | null): void {
+    const focused =
+      targetWindow && 'webContents' in targetWindow
+        ? (targetWindow as BrowserWindow)
+        : BrowserWindow.getFocusedWindow();
+    if (!focused) return;
+
+    if (focused.webContents.isDevToolsOpened()) {
+      focused.webContents.closeDevTools();
+      return;
+    }
+
+    const mainWindow = this.app.browserManager.getMainWindow();
+    if (focused === mainWindow.browserWindow) {
+      mainWindow.broadcast('closeCurrentTabOrWindow');
+    } else {
+      focused.close();
+    }
+  }
+
  private buildZoomMenuItemOption(
    action: ZoomAction,
    label: string,
@@ -1,4 +1,4 @@
-import { app, dialog, Menu, shell } from 'electron';
+import { app, BrowserWindow, dialog, Menu, shell } from 'electron';
 import { beforeEach, describe, expect, it, vi } from 'vitest';

 import type { App } from '@/core/App';
@@ -7,6 +7,9 @@ import { LinuxMenu } from './linux';

 // Mock Electron modules
 vi.mock('electron', () => ({
+  BrowserWindow: class BrowserWindow {
+    static getFocusedWindow = vi.fn();
+  },
  Menu: {
    buildFromTemplate: vi.fn((template) => ({ template })),
    setApplicationMenu: vi.fn(),
@@ -339,6 +342,100 @@ describe('LinuxMenu', () => {
      expect(closeItem.role).toBeUndefined();
    });

+    it('should close open DevTools before delegating CmdOrCtrl+W to renderer window logic', () => {
+      linuxMenu.buildAndSetAppMenu();
+
+      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
+      const fileMenu = template.find((item: any) => item.label === 'File');
+      const closeItem = fileMenu.submenu.find((item: any) => item.label === 'Close');
+      const focusedWindow = {
+        close: vi.fn(),
+        webContents: {
+          closeDevTools: vi.fn(),
+          isDevToolsOpened: vi.fn(() => true),
+        },
+      };
+
+      closeItem.click(undefined, focusedWindow);
+
+      expect(focusedWindow.webContents.closeDevTools).toHaveBeenCalled();
+      expect(focusedWindow.close).not.toHaveBeenCalled();
+      expect(mockApp.browserManager.getMainWindow).not.toHaveBeenCalled();
+    });
+
+    it('should broadcast tab close when CmdOrCtrl+W targets the main window', () => {
+      linuxMenu.buildAndSetAppMenu();
+
+      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
+      const fileMenu = template.find((item: any) => item.label === 'File');
+      const closeItem = fileMenu.submenu.find((item: any) => item.label === 'Close');
+      const mainBrowserWindow = {
+        close: vi.fn(),
+        webContents: {
+          closeDevTools: vi.fn(),
+          isDevToolsOpened: vi.fn(() => false),
+        },
+      };
+      const broadcast = vi.fn();
+      vi.mocked(mockApp.browserManager.getMainWindow).mockReturnValue({
+        broadcast,
+        browserWindow: mainBrowserWindow,
+      } as any);
+
+      closeItem.click(undefined, mainBrowserWindow);
+
+      expect(broadcast).toHaveBeenCalledWith('closeCurrentTabOrWindow');
+      expect(mainBrowserWindow.close).not.toHaveBeenCalled();
+    });
+
+    it('should close non-main windows when CmdOrCtrl+W has no DevTools panel to close', () => {
+      linuxMenu.buildAndSetAppMenu();
+
+      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
+      const fileMenu = template.find((item: any) => item.label === 'File');
+      const closeItem = fileMenu.submenu.find((item: any) => item.label === 'Close');
+      const mainBrowserWindow = {
+        webContents: {
+          isDevToolsOpened: vi.fn(() => false),
+        },
+      };
+      const focusedWindow = {
+        close: vi.fn(),
+        webContents: {
+          closeDevTools: vi.fn(),
+          isDevToolsOpened: vi.fn(() => false),
+        },
+      };
+      vi.mocked(mockApp.browserManager.getMainWindow).mockReturnValue({
+        broadcast: vi.fn(),
+        browserWindow: mainBrowserWindow,
+      } as any);
+
+      closeItem.click(undefined, focusedWindow);
+
+      expect(focusedWindow.close).toHaveBeenCalled();
+    });
+
+    it('should use the focused window when Electron does not pass a menu target window', () => {
+      linuxMenu.buildAndSetAppMenu();
+
+      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
+      const fileMenu = template.find((item: any) => item.label === 'File');
+      const closeItem = fileMenu.submenu.find((item: any) => item.label === 'Close');
+      const focusedWindow = {
+        close: vi.fn(),
+        webContents: {
+          closeDevTools: vi.fn(),
+          isDevToolsOpened: vi.fn(() => true),
+        },
+      };
+      vi.mocked(BrowserWindow.getFocusedWindow).mockReturnValue(focusedWindow as any);
+
+      closeItem.click();
+
+      expect(focusedWindow.webContents.closeDevTools).toHaveBeenCalled();
+    });
+
    it('should use role for minimize (accelerator handled by Electron)', () => {
      linuxMenu.buildAndSetAppMenu();

@@ -1,7 +1,7 @@
 import path from 'node:path';

 import type { MenuItemConstructorOptions } from 'electron';
-import { app, BrowserWindow, clipboard, dialog, Menu, shell } from 'electron';
+import { app, clipboard, dialog, Menu, shell } from 'electron';

 import { isDev } from '@/const/env';
 import { HETERO_AGENT_DIR } from '@/const/heteroAgent';
@@ -122,16 +122,7 @@ export class LinuxMenu extends BaseMenuPlatform implements IMenuPlatform {
          { type: 'separator' },
          {
            accelerator: 'CmdOrCtrl+W',
-            click: () => {
-              const focused = BrowserWindow.getFocusedWindow();
-              if (!focused) return;
-              const mainWindow = this.app.browserManager.getMainWindow();
-              if (focused === mainWindow.browserWindow) {
-                mainWindow.broadcast('closeCurrentTabOrWindow');
-              } else {
-                focused.close();
-              }
-            },
+            click: (_item, targetWindow) => this.closeFocusedTabOrWindow(targetWindow),
            label: t('window.close'),
          },
          { label: t('window.minimize'), role: 'minimize' },
@@ -1,7 +1,7 @@
 import path from 'node:path';

 import type { MenuItemConstructorOptions } from 'electron';
-import { app, BrowserWindow, clipboard, Menu, shell } from 'electron';
+import { app, clipboard, Menu, shell } from 'electron';

 import { isDev } from '@/const/env';
 import { HETERO_AGENT_DIR } from '@/const/heteroAgent';
@@ -164,16 +164,7 @@ export class MacOSMenu extends BaseMenuPlatform implements IMenuPlatform {
          { type: 'separator' },
          {
            accelerator: 'CmdOrCtrl+W',
-            click: () => {
-              const focused = BrowserWindow.getFocusedWindow();
-              if (!focused) return;
-              const mainWindow = this.app.browserManager.getMainWindow();
-              if (focused === mainWindow.browserWindow) {
-                mainWindow.broadcast('closeCurrentTabOrWindow');
-              } else {
-                focused.close();
-              }
-            },
+            click: (_item, targetWindow) => this.closeFocusedTabOrWindow(targetWindow),
            label: t('window.close'),
          },
        ],
@@ -1,7 +1,7 @@
 import path from 'node:path';

 import type { MenuItemConstructorOptions } from 'electron';
-import { app, BrowserWindow, clipboard, Menu, shell } from 'electron';
+import { app, clipboard, Menu, shell } from 'electron';

 import { isDev } from '@/const/env';
 import { HETERO_AGENT_DIR } from '@/const/heteroAgent';
@@ -185,16 +185,7 @@ export class WindowsMenu extends BaseMenuPlatform implements IMenuPlatform {
          { label: t('window.minimize'), role: 'minimize' },
          {
            accelerator: 'CmdOrCtrl+W',
-            click: () => {
-              const focused = BrowserWindow.getFocusedWindow();
-              if (!focused) return;
-              const mainWindow = this.app.browserManager.getMainWindow();
-              if (focused === mainWindow.browserWindow) {
-                mainWindow.broadcast('closeCurrentTabOrWindow');
-              } else {
-                focused.close();
-              }
-            },
+            click: (_item, targetWindow) => this.closeFocusedTabOrWindow(targetWindow),
            label: t('window.close'),
          },
        ],
@@ -0,0 +1,77 @@
+import { createLogger } from '@/utils/logger';
+
+const logger = createLogger('main:process-error-handlers');
+
+/**
+ * Transient Chromium network errors emitted by Electron's `net` stack
+ * (`SimpleURLLoaderWrapper`). These happen during normal operation — switching
+ * Wi-Fi / VPN, the machine sleeping, the network interface dropping — and are
+ * NOT application bugs. Electron emits them as an `error` event on the internal
+ * loader; when nothing is listening they bubble up as an `uncaughtException`
+ * and pop the "A JavaScript error occurred in the main process" dialog, even
+ * though the request layer already handles the failure via promise rejection.
+ *
+ * We swallow these specific cases so transient connectivity blips never crash
+ * the main process. Everything else is re-thrown to preserve normal crash
+ * visibility.
+ *
+ * @see https://github.com/electron/electron/issues/24948
+ */
+const TRANSIENT_NET_ERROR_CODES = new Set([
+  'ERR_NETWORK_CHANGED',
+  'ERR_NETWORK_IO_SUSPENDED',
+  'ERR_INTERNET_DISCONNECTED',
+  'ERR_NETWORK_ACCESS_DENIED',
+  'ERR_CONNECTION_RESET',
+  'ERR_CONNECTION_ABORTED',
+  'ERR_CONNECTION_CLOSED',
+  'ERR_NAME_NOT_RESOLVED',
+  'ERR_TIMED_OUT',
+]);
+
+const isTransientNetError = (error: unknown): boolean => {
+  if (!error) return false;
+
+  const message = error instanceof Error ? error.message : String(error);
+
+  // Electron net errors are formatted as `net::ERR_XXX`.
+  const match = message.match(/net::(ERR_[A-Z_]+)/);
+  if (match && TRANSIENT_NET_ERROR_CODES.has(match[1])) return true;
+
+  // Belt-and-suspenders: these only ever originate from the net loader.
+  const stack = error instanceof Error ? (error.stack ?? '') : '';
+  return /net::ERR_/.test(message) && stack.includes('SimpleURLLoaderWrapper');
+};
+
+/**
+ * Install global guards for the Electron main process. Must be called as early
+ * as possible (before the rest of the app boots) so it catches errors from any
+ * module's top-level / async work.
+ */
+export const installProcessErrorHandlers = () => {
+  process.on('uncaughtException', (error) => {
+    if (isTransientNetError(error)) {
+      logger.warn('Ignoring transient network error in main process:', error.message);
+      return;
+    }
+
+    // Re-throw so genuine bugs still surface as a crash instead of being
+    // silently swallowed by this handler.
+    logger.error('Uncaught exception in main process:', error);
+    throw error;
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    if (isTransientNetError(reason)) {
+      logger.warn(
+        'Ignoring transient network rejection in main process:',
+        reason instanceof Error ? reason.message : String(reason),
+      );
+      return;
+    }
+
+    logger.error('Unhandled rejection in main process:', reason);
+  });
+
+  logger.info('Process error handlers installed');
+};
@@ -6,7 +6,6 @@ export default defineConfig({
    alias: {
      '@': resolve(__dirname, './src/main'),
      '~common': resolve(__dirname, './src/common'),
-      '@lobechat/device-control': resolve(__dirname, '../../packages/device-control/src'),
      '@lobechat/local-file-shell': resolve(__dirname, '../../packages/local-file-shell/src'),
    },
    coverage: {
@@ -28,8 +28,8 @@ const mockGlobalConfigDependencies = (
    ENABLE_BUSINESS_FEATURES: enableBusinessFeatures,
  }));

-  vi.doMock('@/config/klavis', () => ({
-    klavisEnv: {},
+  vi.doMock('@/config/composio', () => ({
+    composioEnv: {},
  }));

  vi.doMock('@/const/version', () => ({
@@ -1,7 +1,7 @@
 import { ENABLE_BUSINESS_FEATURES } from '@lobechat/business-const';
 import { ModelProvider } from 'model-bank';

-import { klavisEnv } from '@/config/klavis';
+import { composioEnv } from '@/config/composio';
 import { isDesktop } from '@/const/version';
 import { appEnv, getAppConfig } from '@/envs/app';
 import { authEnv } from '@/envs/auth';
@@ -104,9 +104,9 @@ export const getServerGlobalConfig = async () => {
    disableEmailPassword: authEnv.AUTH_DISABLE_EMAIL_PASSWORD,
    enableBusinessFeatures: ENABLE_BUSINESS_FEATURES,
    enableEmailVerification: authEnv.AUTH_EMAIL_VERIFICATION,
+    enableComposio: !!composioEnv.COMPOSIO_API_KEY,
    enableGatewayMode:
      ENABLE_BUSINESS_FEATURES || (!!appEnv.ENABLE_AGENT_GATEWAY && !!appEnv.AGENT_GATEWAY_URL),
-    enableKlavis: !!klavisEnv.KLAVIS_API_KEY,
    enableLobehubSkill: !!(appEnv.MARKET_TRUSTED_CLIENT_SECRET && appEnv.MARKET_TRUSTED_CLIENT_ID),
    enableMagicLink: authEnv.AUTH_ENABLE_MAGIC_LINK,
    enableMarketTrustedClient: !!(
@@ -14,14 +14,14 @@ import {
 } from '@lobechat/agent-runtime';
 import { LobeActivatorIdentifier } from '@lobechat/builtin-tool-activator';
 import {
+  type ComposioServiceSummary,
  type CredSummary,
+  generateComposioServicesList,
  generateCredsList,
-  generateKlavisServicesList,
-  type KlavisServiceSummary,
 } from '@lobechat/builtin-tool-creds';
 import { LocalSystemManifest } from '@lobechat/builtin-tool-local-system';
 import { BRANDING_PROVIDER } from '@lobechat/business-const';
-import { KLAVIS_SERVER_TYPES } from '@lobechat/const';
+import { COMPOSIO_APP_TYPES } from '@lobechat/const';
 import {
  type AgentContextDocument,
  type AgentGroupConfig,
@@ -38,7 +38,12 @@ import {
  ToolResolver,
 } from '@lobechat/context-engine';
 import { parse } from '@lobechat/conversation-flow';
-import { consumeStreamUntilDone } from '@lobechat/model-runtime';
+import {
+  applyModelExtendParams,
+  type ChatStreamPayload,
+  consumeStreamUntilDone,
+  type ModelExtendParams,
+} from '@lobechat/model-runtime';
 import {
  context as otelContext,
  SpanKind,
@@ -67,8 +72,9 @@ import {
 } from '@lobechat/types';
 import { sanitizeToolCallArguments, serializePartsForStorage } from '@lobechat/utils';
 import debug from 'debug';
+import { type ExtendParamsType, ModelProvider } from 'model-bank';

-import { klavisEnv } from '@/config/klavis';
+import { composioEnv } from '@/config/composio';
 import { type MessageModel, MessageModel as MessageModelClass } from '@/database/models/message';
 import { TopicModel } from '@/database/models/topic';
 import { UserModel } from '@/database/models/user';
@@ -80,6 +86,10 @@ import { type EvalContext } from '@/server/modules/Mecha/ContextEngineering/type
 import { initModelRuntimeFromDB } from '@/server/modules/ModelRuntime';
 import { AgentDocumentsService } from '@/server/services/agentDocuments';
 import type { HookDispatcher } from '@/server/services/agentRuntime/hooks/HookDispatcher';
+import type {
+  ExecGroupMemberParams,
+  ExecGroupMemberResult,
+} from '@/server/services/agentRuntime/types';
 import {
  type DeviceAccessReason,
  isDeviceToolIdentifier,
@@ -89,6 +99,7 @@ import { FileService } from '@/server/services/file';
 import { MessageService } from '@/server/services/message';
 import { OnboardingService } from '@/server/services/onboarding';
 import {
+  type ServerAgentMemberRunner,
  type ServerSubAgentRunner,
  type ToolExecutionResultResponse,
  type ToolExecutionService,
@@ -405,6 +416,147 @@ const buildServerVirtualSubAgentRunner = (
  };
 };

+/**
+ * Build the per-tool "call agent member" runner for the group orchestration
+ * server tool (`lobe-group-management`). Mirrors {@link buildServerVirtualSubAgentRunner}
+ * but for group members: it owns the group tool message (the parked tool call)
+ * and the per-member anchors that drive the K=N member barrier.
+ *
+ * For each `agentMember.run(...)` it:
+ *   1. creates the group tool placeholder (`tool_call_id` = the group-management
+ *      call id) stamped with the barrier target + finish disposition;
+ *   2. for a single member uses that placeholder as the member anchor; for
+ *      multiple members creates one child anchor per member under it;
+ *   3. forks each member via `ctx.execGroupMember` (in-group or isolated);
+ *   4. backfills anchors for members that failed to start so the barrier can
+ *      still complete, and tears everything down when none started.
+ *
+ * Returns `undefined` when group-member execution is unavailable (no
+ * `execGroupMember` callback, or missing agent/topic/group context).
+ */
+const buildServerAgentMemberRunner = (
+  ctx: RuntimeExecutorContext,
+  state: AgentState,
+  chatToolPayload: ChatToolPayload,
+  parentMessageId: string,
+): ServerAgentMemberRunner | undefined => {
+  const execGroupMember = ctx.execGroupMember;
+  if (!execGroupMember) return undefined;
+
+  const agentId = state.metadata?.agentId;
+  const topicId = ctx.topicId ?? state.metadata?.topicId;
+  const groupId = state.metadata?.groupId ?? undefined;
+  if (!agentId || !topicId || !groupId) return undefined;
+
+  return {
+    run: async ({ members, mode, onComplete, disableTools, timeout }) => {
+      const expectedMembers = members.length;
+      if (expectedMembers === 0) return { started: false, startedCount: 0 };
+
+      // 1. Group tool placeholder — the parked tool call the supervisor op waits
+      //    on. Stamped with the barrier target + finish disposition so the resume
+      //    path (and verify watchdog) resolve resume-vs-finish on their own.
+      const groupTool = await ctx.messageModel.create({
+        agentId,
+        content: '',
+        parentId: parentMessageId,
+        plugin: chatToolPayload as any,
+        pluginState: { expectedMembers, onComplete, status: 'pending' },
+        role: 'tool',
+        threadId: state.metadata?.threadId,
+        tool_call_id: chatToolPayload.id,
+        topicId,
+      });
+
+      // 2. Per-member anchors. A single member collapses onto the group tool
+      //    message; multiple members each get a child anchor under it.
+      const anchorIds: string[] = [];
+      if (expectedMembers === 1) {
+        anchorIds.push(groupTool.id);
+      } else {
+        for (let i = 0; i < expectedMembers; i += 1) {
+          const memberToolCallId = `${chatToolPayload.id}::m${i}`;
+          const anchor = await ctx.messageModel.create({
+            agentId,
+            content: '',
+            parentId: groupTool.id,
+            plugin: { ...(chatToolPayload as any), id: memberToolCallId },
+            pluginState: { status: 'pending' },
+            role: 'tool',
+            threadId: state.metadata?.threadId,
+            tool_call_id: memberToolCallId,
+            topicId,
+          });
+          anchorIds.push(anchor.id);
+        }
+      }
+
+      // 3. Fork members.
+      let startedCount = 0;
+      await Promise.all(
+        members.map(async (member, i) => {
+          const anchorMessageId = anchorIds[i];
+          try {
+            const result = await execGroupMember({
+              agentId: member.agentId,
+              anchorMessageId,
+              disableTools,
+              expectedMembers,
+              groupId,
+              groupToolMessageId: groupTool.id,
+              instruction: member.instruction,
+              mode,
+              onComplete,
+              parentOperationId: ctx.operationId,
+              timeout,
+              topicId,
+            });
+            if (result?.started) {
+              startedCount += 1;
+              return;
+            }
+          } catch (error) {
+            log(
+              'buildServerAgentMemberRunner: member %s failed to start: %O',
+              member.agentId,
+              error,
+            );
+          }
+          // Member failed to start — its completion bridge will never fire, so
+          // backfill the anchor as errored to keep the K=N barrier reachable.
+          try {
+            await ctx.messageModel.updateToolMessage(anchorMessageId, {
+              content: `Agent member "${member.agentId}" failed to start.`,
+              pluginState: { status: 'error' },
+            });
+          } catch (error) {
+            log(
+              'buildServerAgentMemberRunner: failed to mark anchor %s as errored: %O',
+              anchorMessageId,
+              error,
+            );
+          }
+        }),
+      );
+
+      // None started — no bridge will ever fire, so tear down the placeholders
+      // and let the caller surface an inline tool error instead of parking.
+      if (startedCount === 0) {
+        for (const id of new Set([...anchorIds, groupTool.id])) {
+          try {
+            await ctx.messageModel.deleteMessage(id);
+          } catch (error) {
+            log('buildServerAgentMemberRunner: cleanup failed for %s: %O', id, error);
+          }
+        }
+        return { started: false, startedCount: 0 };
+      }
+
+      return { started: true, startedCount };
+    },
+  };
+};
+
 const shouldRetryLLM = (kind: LLMErrorKind, attempt: number, maxRetries: number) =>
  kind === 'retry' && attempt <= maxRetries;

@@ -522,6 +674,12 @@ export interface RuntimeExecutorContext {
  botPlatformContext?: BotPlatformContext;
  discordContext?: any;
  evalContext?: EvalContext;
+  /**
+   * Callback to fork a group member ("call agent member") under a
+   * `lobe-group-management` tool call. Injected by AiAgentService; powers the
+   * per-tool `agentMember` runner (in-group + isolated members, K=N barrier).
+   */
+  execGroupMember?: (params: ExecGroupMemberParams) => Promise<ExecGroupMemberResult>;
  /**
   * Callback to run a legacy agent invocation server-side.
   * Injected by AiAgentService so exec_sub_agent / exec_sub_agents executors
@@ -721,6 +879,7 @@ export const createRuntimeExecutors = (
      type ContentPart = { text: string; type: 'text' } | { image: string; type: 'image' };
      let shouldReplayAssistantReasoning = false;
      let preserveThinkingForPayload: boolean | undefined;
+      let resolvedExtendParams: ModelExtendParams | undefined;

      // Process messages through serverMessagesEngine to inject system role, knowledge, etc.
      // Rebuild params from agentConfig at execution time (capabilities built dynamically)
@@ -736,19 +895,39 @@ export const createRuntimeExecutors = (
            : undefined;
        const preserveThinkingRequested = preserveThinkingConfigured === true;

+        const readExtendParams = (
+          card: (typeof builtinModels)[number] | undefined,
+        ): string[] | undefined =>
+          card &&
+          'settings' in card &&
+          card.settings &&
+          typeof card.settings === 'object' &&
+          'extendParams' in card.settings
+            ? (card.settings as { extendParams?: string[] }).extendParams
+            : undefined;
+
        const modelCard = builtinModels.find(
          (item) =>
            item.providerId === provider &&
            (item.id === model || item.config?.deploymentName === model),
        );
-        const modelExtendParams =
-          modelCard &&
-          'settings' in modelCard &&
-          modelCard.settings &&
-          typeof modelCard.settings === 'object' &&
-          'extendParams' in modelCard.settings
-            ? (modelCard.settings as { extendParams?: string[] }).extendParams
-            : undefined;
+        const canonicalModelCard = builtinModels.find(
+          (item) => item.id === model || item.config?.deploymentName === model,
+        );
+        const modelKnowledgeCutoff =
+          modelCard?.knowledgeCutoff ??
+          (provider === ModelProvider.LobeHub ? canonicalModelCard?.knowledgeCutoff : undefined);
+
+        let modelExtendParams = readExtendParams(modelCard);
+
+        // Aggregation providers (e.g. `lobehub`) may serve a model without copying
+        // its origin `settings.extendParams`. Fall back to the canonical model card
+        // (matched by id across any provider) so reasoning/thinking params like
+        // `thinkingLevel` still reach the model. Mirrors the client-side
+        // `transformToAiModelList` re-namespacing behavior.
+        if (!modelExtendParams || modelExtendParams.length === 0) {
+          modelExtendParams = readExtendParams(canonicalModelCard);
+        }

        const modelSupportsPreserveThinkingFromCard =
          Array.isArray(modelExtendParams) && modelExtendParams.includes('preserveThinking');
@@ -763,6 +942,19 @@ export const createRuntimeExecutors = (
          modelSupportsPreserveThinking && typeof preserveThinkingConfigured === 'boolean'
            ? preserveThinkingConfigured
            : undefined;
+
+        // Resolve model extend params (thinkingLevel, reasoning effort, urlContext, …)
+        // from the agent chat config so the server-side agent runtime forwards the same
+        // runtime params the client chat service does. Without this, e.g. Gemini 3 Pro's
+        // `thinkingLevel` never reaches the request and thought summaries come back empty.
+        if (agentConfig.chatConfig) {
+          resolvedExtendParams = applyModelExtendParams({
+            chatConfig: agentConfig.chatConfig,
+            extendParams: modelExtendParams as ExtendParamsType[] | undefined,
+            model,
+          });
+        }
+
        const messagesForContext = shouldReplayAssistantReasoning
          ? (llmPayload.messages as UIChatMessage[])
          : stripAssistantReasoningForReplay(llmPayload.messages as UIChatMessage[]);
@@ -999,39 +1191,38 @@ export const createRuntimeExecutors = (
          }
        }

-        // {{KLAVIS_SERVICES_LIST}} — used by lobe-creds system role (Klavis integrations section).
-        // Mirrors client-side: klavisStoreSelectors.getServers() filtered by connection status.
-        let klavisServicesListStr = '';
-        if (ctx.serverDB && ctx.userId && !!klavisEnv.KLAVIS_API_KEY) {
+        // {{COMPOSIO_SERVICES_LIST}} — used by lobe-creds system role (Composio integrations section).
+        let composioServicesListStr = '';
+        if (ctx.serverDB && ctx.userId && !!composioEnv.COMPOSIO_API_KEY) {
          try {
            const { PluginModel } = await import('@/database/models/plugin');
            const pluginModel = new PluginModel(ctx.serverDB, ctx.userId, ctx.workspaceId);
            const allPlugins = await pluginModel.query();
-            const validKlavisIds = new Set(KLAVIS_SERVER_TYPES.map((t) => t.identifier));
+            const validComposioIds = new Set(COMPOSIO_APP_TYPES.map((t) => t.identifier));
            const connectedIds = new Set(
              allPlugins
                .filter(
                  (p) =>
-                    validKlavisIds.has(p.identifier) &&
-                    (p.customParams as any)?.klavis?.isAuthenticated === true,
+                    validComposioIds.has(p.identifier) &&
+                    (p.customParams as any)?.composio?.status === 'ACTIVE',
                )
                .map((p) => p.identifier),
            );
-            const connected: KlavisServiceSummary[] = KLAVIS_SERVER_TYPES.filter((t) =>
+            const connected: ComposioServiceSummary[] = COMPOSIO_APP_TYPES.filter((t) =>
              connectedIds.has(t.identifier),
            ).map((t) => ({ identifier: t.identifier, name: t.label }));
-            const available: KlavisServiceSummary[] = KLAVIS_SERVER_TYPES.filter(
+            const available: ComposioServiceSummary[] = COMPOSIO_APP_TYPES.filter(
              (t) => !connectedIds.has(t.identifier),
            ).map((t) => ({ identifier: t.identifier, name: t.label }));
-            klavisServicesListStr = generateKlavisServicesList(connected, available);
+            composioServicesListStr = generateComposioServicesList(connected, available);
            log(
-              'Fetched Klavis services for {{KLAVIS_SERVICES_LIST}}: connected=%d, available=%d',
+              'Fetched Composio services for {{COMPOSIO_SERVICES_LIST}}: connected=%d, available=%d',
              connected.length,
              available.length,
            );
          } catch (error) {
            log(
-              'Failed to fetch Klavis services for {{KLAVIS_SERVICES_LIST}} substitution: %O',
+              'Failed to fetch Composio services for {{COMPOSIO_SERVICES_LIST}} substitution: %O',
              error,
            );
          }
@@ -1055,12 +1246,18 @@ export const createRuntimeExecutors = (
            sandbox_enabled: sandboxEnabled,
            sandbox_uploaded_files: sandboxUploadedFiles,
            CREDS_LIST: credsListStr,
-            KLAVIS_SERVICES_LIST: klavisServicesListStr,
+            COMPOSIO_SERVICES_LIST: composioServicesListStr,
            // Memory tool variables
            memory_effort: memoryEffort,
          },
          userTimezone: ctx.userTimezone,
          capabilities: {
+            isCanUseAudio: (m: string, p: string) => {
+              const info =
+                builtinModels.find((item) => item.id === m && item.providerId === p) ??
+                builtinModels.find((item) => item.id === m);
+              return info?.abilities?.audio ?? false;
+            },
            isCanUseFC: (m: string, p: string) => {
              const info = builtinModels.find((item) => item.id === m && item.providerId === p);
              return info?.abilities?.functionCall ?? true;
@@ -1106,6 +1303,7 @@ export const createRuntimeExecutors = (
          },
          messages: messagesForContext,
          model,
+          modelKnowledgeCutoff,
          provider,
          systemRole: agentConfig.systemRole ?? undefined,
          toolDiscoveryConfig,
@@ -1205,6 +1403,9 @@ export const createRuntimeExecutors = (
        model,
        stream,
        tools,
+        // ModelExtendParams keeps provider-specific effort/thinking values as loose
+        // strings (e.g. hy3's 'no_think'); the runtime payload narrows them, so cast.
+        ...(resolvedExtendParams as Partial<ChatStreamPayload>),
        ...(typeof preserveThinkingForPayload === 'boolean' && {
          preserveThinking: preserveThinkingForPayload,
        }),
@@ -2446,7 +2647,7 @@ export const createRuntimeExecutors = (
          execution = { attempts: 1, result: dispatchResult };
        } else {
          // Inject source from sourceMap so BuiltinToolsExecutor can route
-          // lobehubSkill / klavis tools correctly (LLM responses don't carry source)
+          // lobehubSkill / composio tools correctly (LLM responses don't carry source)
          if (toolSource && !chatToolPayload.source) {
            chatToolPayload.source = toolSource;
          }
@@ -2463,7 +2664,14 @@ export const createRuntimeExecutors = (
              toolExecutionService.executeTool(chatToolPayload, {
                activeDeviceId: state.metadata?.activeDeviceId,
                agentId: state.metadata?.agentId,
+                agentMember: buildServerAgentMemberRunner(
+                  ctx,
+                  state,
+                  chatToolPayload,
+                  payload.parentMessageId,
+                ),
                documentId: state.metadata?.documentId,
+                editingAgentId: state.metadata?.editingAgentId,
                execSubAgent: ctx.execSubAgent,
                executionTimeoutMs: timeoutMs,
                groupId: state.metadata?.groupId,
@@ -2496,6 +2704,10 @@ export const createRuntimeExecutors = (
                toolResultMaxLength,
                topicId: ctx.topicId,
                userId: ctx.userId,
+                // Device-bound cwd folded into deviceSystemInfo at operation
+                // creation; resume-safe via computeDeviceContext (recovers it
+                // from the prior tool message's pluginState.metadata).
+                workingDirectory: state.metadata?.deviceSystemInfo?.workingDirectory,
                workspaceId: state.metadata?.workspaceId ?? ctx.workspaceId,
              }),
            {
@@ -3026,7 +3238,7 @@ export const createRuntimeExecutors = (
              execution = { attempts: 1, result: dispatchResult };
            } else {
              // Inject source from sourceMap so BuiltinToolsExecutor can route
-              // lobehubSkill / klavis tools correctly (LLM responses don't carry source)
+              // lobehubSkill / composio tools correctly (LLM responses don't carry source)
              const batchToolSource =
                state.operationToolSet?.sourceMap?.[chatToolPayload.identifier] ??
                state.toolSourceMap?.[chatToolPayload.identifier];
@@ -3045,6 +3257,12 @@ export const createRuntimeExecutors = (
                  toolExecutionService.executeTool(chatToolPayload, {
                    activeDeviceId: state.metadata?.activeDeviceId,
                    agentId: state.metadata?.agentId,
+                    agentMember: buildServerAgentMemberRunner(
+                      ctx,
+                      state,
+                      chatToolPayload,
+                      payload.parentMessageId,
+                    ),
                    documentId: state.metadata?.documentId,
                    execSubAgent: ctx.execSubAgent,
                    executionTimeoutMs: timeoutMs,
@@ -14,6 +14,7 @@ const mockBuiltinModels = vi.hoisted(() => [
  {
    abilities: { functionCall: true, video: false, vision: true },
    id: 'gpt-4',
+    knowledgeCutoff: '2024-06',
    providerId: 'openai',
  },
  {
@@ -58,6 +59,9 @@ vi.mock('@/server/services/message', () => ({
 // @lobechat/model-runtime resolves to @cloud/business-model-runtime which has
 // cloud-specific dependencies that are unavailable in the test environment
 vi.mock('@lobechat/model-runtime', () => ({
+  // The executor resolves extend params via this helper; an empty result keeps
+  // the runtime payload unchanged, matching this suite's pre-existing behavior.
+  applyModelExtendParams: vi.fn(() => ({})),
  consumeStreamUntilDone: vi.fn().mockResolvedValue(undefined),
  // `llmErrorClassification.ts` reads these at module-load time; an empty
  // spec map is fine here because this suite never exercises the runtime
@@ -74,13 +78,16 @@ vi.mock('@/business/client/model-bank/loadModels', () => ({
 // model-bank is a TypeScript source file that cannot be dynamically imported in vitest
 vi.mock('model-bank', () => ({
  LOBE_DEFAULT_MODEL_LIST: mockBuiltinModels,
+  ModelProvider: {
+    LobeHub: 'lobehub',
+  },
 }));

-// klavisEnv uses @t3-oss/env-nextjs which throws in jsdom (treats it as client context)
-vi.mock('@/config/klavis', () => ({
-  getKlavisConfig: vi.fn(),
-  getServerKlavisApiKey: vi.fn().mockReturnValue(undefined),
-  klavisEnv: { KLAVIS_API_KEY: undefined },
+// composioEnv uses @t3-oss/env-nextjs which throws in jsdom (treats it as client context)
+vi.mock('@/config/composio', () => ({
+  getComposioConfig: vi.fn(),
+  getServerComposioApiKey: vi.fn().mockReturnValue(undefined),
+  composioEnv: { COMPOSIO_API_KEY: undefined },
 }));

 // fileEnv uses @t3-oss/env-core; stub the only field the runtime reads so the
@@ -125,6 +132,7 @@ describe('RuntimeExecutors', () => {

    mockMessageModel = {
      create: vi.fn().mockResolvedValue({ id: 'msg-123' }),
+      deleteMessage: vi.fn().mockResolvedValue({ success: true }),
      // call_llm does a parent existence preflight; return a truthy row by
      // default so existing tests don't have to stub it.
      findById: vi.fn().mockResolvedValue({ id: 'msg-existing' }),
@@ -1571,6 +1579,87 @@ describe('RuntimeExecutors', () => {
        );
      });

+      it('should pass model knowledge cutoff into serverMessagesEngine', async () => {
+        const ctxWithConfig: RuntimeExecutorContext = {
+          ...ctx,
+          agentConfig: {
+            plugins: [],
+            systemRole: 'You are a helpful assistant',
+          },
+        };
+        const executors = createRuntimeExecutors(ctxWithConfig);
+        const state = createMockState();
+
+        const instruction = {
+          payload: {
+            messages: [{ content: 'Hello', role: 'user' }],
+            model: 'gpt-4',
+            provider: 'openai',
+          },
+          type: 'call_llm' as const,
+        };
+
+        await executors.call_llm!(instruction, state);
+
+        expect(engineSpy).toHaveBeenCalledWith(
+          expect.objectContaining({ modelKnowledgeCutoff: '2024-06' }),
+        );
+      });
+
+      it('should resolve LobeHub routed model knowledge cutoff by model id fallback', async () => {
+        const ctxWithConfig: RuntimeExecutorContext = {
+          ...ctx,
+          agentConfig: {
+            plugins: [],
+            systemRole: 'You are a helpful assistant',
+          },
+        };
+        const executors = createRuntimeExecutors(ctxWithConfig);
+        const state = createMockState();
+
+        await executors.call_llm!(
+          {
+            payload: {
+              messages: [{ content: 'Hello', role: 'user' }],
+              model: 'gpt-4',
+              provider: 'lobehub',
+            },
+            type: 'call_llm' as const,
+          },
+          state,
+        );
+
+        expect(engineSpy).toHaveBeenCalledWith(
+          expect.objectContaining({ modelKnowledgeCutoff: '2024-06' }),
+        );
+      });
+
+      it('should omit model knowledge cutoff for unknown non-LobeHub providers', async () => {
+        const ctxWithConfig: RuntimeExecutorContext = {
+          ...ctx,
+          agentConfig: {
+            plugins: [],
+            systemRole: 'You are a helpful assistant',
+          },
+        };
+        const executors = createRuntimeExecutors(ctxWithConfig);
+        const state = createMockState();
+
+        await executors.call_llm!(
+          {
+            payload: {
+              messages: [{ content: 'Hello', role: 'user' }],
+              model: 'gpt-4',
+              provider: 'custom-openai',
+            },
+            type: 'call_llm' as const,
+          },
+          state,
+        );
+
+        expect(engineSpy.mock.calls[0][0]).toHaveProperty('modelKnowledgeCutoff', undefined);
+      });
+
      it('should keep current turn when agent historyCount is 0', async () => {
        const ctxWithConfig: RuntimeExecutorContext = {
          ...ctx,
@@ -4850,10 +4939,9 @@ describe('RuntimeExecutors', () => {
      ...overrides,
    });

-    it('call_tool sets stop:true in tool_result payload when tool returns execSubAgent state', async () => {
-      // Simulate agentManagement.callAgent returning execSubAgent state
+    it('call_tool preserves stop:true for legacy execSubAgent state', async () => {
      mockToolExecutionService.executeTool.mockResolvedValue({
-        content: '🚀 Triggered async task to call agent "target-agent"',
+        content: 'Legacy async task result',
        executionTime: 10,
        state: {
          parentMessageId: 'tool-msg-id',
@@ -4894,13 +4982,112 @@ describe('RuntimeExecutors', () => {
      expect((result.nextContext?.payload as any).stop).toBe(true);
    });

-    it('exec_sub_agent executor creates task message and calls execSubAgent callback', async () => {
-      const mockExecSubAgentTask = vi
+    it('call_tool lets server callAgent run as a deferred tool via the subAgent runner', async () => {
+      const mockExecVirtualSubAgent = vi
        .fn()
        .mockResolvedValue({ success: true, operationId: 'child-op', threadId: 'thread-child' });
      const ctxWithCallback = {
        ...ctx,
-        execSubAgent: mockExecSubAgentTask,
+        execVirtualSubAgent: mockExecVirtualSubAgent,
+        topicId: 'topic-123',
+      };
+
+      mockMessageModel.create.mockResolvedValueOnce({ id: 'tool-msg-id' });
+      mockToolExecutionService.executeTool.mockImplementation(
+        async (_payload: any, context: any) => {
+          const subAgent = await context.subAgent.run({
+            agentId: 'target-agent-id',
+            description: 'Call agent target-agent',
+            instruction: 'Do something useful',
+            timeout: 1_800_000,
+          });
+
+          return {
+            content: '',
+            deferred: true,
+            executionTime: 10,
+            state: {
+              status: 'pending',
+              subOperationId: subAgent.subOperationId,
+              targetAgentId: 'target-agent-id',
+              threadId: subAgent.threadId,
+            },
+            success: subAgent.started,
+          };
+        },
+      );
+
+      const executors = createRuntimeExecutors(ctxWithCallback);
+      const state = createMockState();
+      const instruction = {
+        payload: {
+          parentMessageId: 'assistant-msg-id',
+          toolCalling: {
+            apiName: 'callAgent',
+            arguments: JSON.stringify({
+              agentId: 'target-agent-id',
+              instruction: 'Do something useful',
+              runAsTask: true,
+            }),
+            id: 'tool-call-1',
+            identifier: 'lobe-agent-management',
+            type: 'default' as const,
+          },
+        },
+        type: 'call_tool' as const,
+      };
+
+      const result = await executors.call_tool!(instruction, state);
+
+      expect(mockMessageModel.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          agentId: 'parent-agent-id',
+          plugin: expect.objectContaining({
+            apiName: 'callAgent',
+            identifier: 'lobe-agent-management',
+          }),
+          pluginState: { status: 'pending' },
+          parentId: 'assistant-msg-id',
+          role: 'tool',
+          tool_call_id: 'tool-call-1',
+          topicId: 'topic-123',
+        }),
+      );
+      expect(mockExecVirtualSubAgent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          agentId: 'target-agent-id',
+          instruction: 'Do something useful',
+          parentMessageId: 'tool-msg-id',
+          parentOperationId: 'op-123',
+          title: 'Call agent target-agent',
+          topicId: 'topic-123',
+        }),
+      );
+      expect(result.newState.status).toBe('waiting_for_async_tool');
+      expect(result.newState.pendingToolsCalling).toEqual([
+        expect.objectContaining({
+          apiName: 'callAgent',
+          id: 'tool-call-1',
+          identifier: 'lobe-agent-management',
+        }),
+      ]);
+      expect(result.events).toEqual([
+        expect.objectContaining({
+          canResume: true,
+          reason: 'async_tool',
+          type: 'interrupted',
+        }),
+      ]);
+      expect(result.nextContext).toBeUndefined();
+    });
+
+    it('exec_sub_agent executor creates task message and calls execSubAgent callback', async () => {
+      const mockExecSubAgent = vi
+        .fn()
+        .mockResolvedValue({ success: true, operationId: 'child-op', threadId: 'thread-child' });
+      const ctxWithCallback = {
+        ...ctx,
+        execSubAgent: mockExecSubAgent,
        topicId: 'topic-123',
      };

@@ -4926,6 +5113,9 @@ describe('RuntimeExecutors', () => {
      expect(mockMessageModel.create).toHaveBeenCalledWith(
        expect.objectContaining({
          agentId: 'parent-agent-id',
+          metadata: expect.objectContaining({
+            targetAgentId: 'target-agent-id',
+          }),
          role: 'task',
          parentId: 'tool-msg-id',
          topicId: 'topic-123',
@@ -4933,7 +5123,7 @@ describe('RuntimeExecutors', () => {
      );

      // execSubAgent callback fired with targetAgentId
-      expect(mockExecSubAgentTask).toHaveBeenCalledWith(
+      expect(mockExecSubAgent).toHaveBeenCalledWith(
        expect.objectContaining({
          agentId: 'target-agent-id',
          instruction: 'Do something useful',
@@ -4947,10 +5137,10 @@ describe('RuntimeExecutors', () => {
    });

    it('exec_sub_agent blocks nested dispatch when current state is already a sub-agent', async () => {
-      const mockExecSubAgentTask = vi.fn();
+      const mockExecSubAgent = vi.fn();
      const ctxWithCallback = {
        ...ctx,
-        execSubAgentTask: mockExecSubAgentTask,
+        execSubAgent: mockExecSubAgent,
        topicId: 'topic-123',
      };

@@ -4983,7 +5173,7 @@ describe('RuntimeExecutors', () => {
        success: false,
      });
      expect(mockMessageModel.create).not.toHaveBeenCalled();
-      expect(mockExecSubAgentTask).not.toHaveBeenCalled();
+      expect(mockExecSubAgent).not.toHaveBeenCalled();
    });

    it('exec_sub_agent gracefully skips dispatch when execSubAgent not injected', async () => {
@@ -1,3 +1,4 @@
+import { AgentRuntimeErrorType } from '@lobechat/types';
 import { describe, expect, it } from 'vitest';

 import { formatErrorEventData } from '../formatErrorEventData';
@@ -62,6 +63,75 @@ describe('formatErrorEventData', () => {
  });

  describe('business-typed errors (must not be overridden)', () => {
+    it('preserves traceable runtime payload body for gateway error events', () => {
+      const out = formatErrorEventData(
+        {
+          error: { message: 'Upstream failed', traceId: 'trace-123' },
+          errorType: AgentRuntimeErrorType.ProviderBizError,
+          provider: 'openai',
+        },
+        'llm_execution',
+      );
+
+      expect(out).toMatchObject({
+        body: {
+          message: 'Upstream failed',
+          provider: 'openai',
+          traceId: 'trace-123',
+        },
+        error: 'Upstream failed',
+        errorType: AgentRuntimeErrorType.ProviderBizError,
+        phase: 'llm_execution',
+      });
+    });
+
+    it('uses the normalized runtime type for gateway error events', () => {
+      const out = formatErrorEventData(
+        {
+          error: { message: 'Payment required', status: 402, traceId: 'trace-402' },
+          errorType: AgentRuntimeErrorType.ProviderBizError,
+          provider: 'lobehub',
+        },
+        'llm_execution',
+      );
+
+      expect(out).toMatchObject({
+        body: {
+          message: 'Payment required',
+          provider: 'lobehub',
+          status: 402,
+          traceId: 'trace-402',
+        },
+        error: 'Payment required',
+        errorType: AgentRuntimeErrorType.InsufficientQuota,
+        phase: 'llm_execution',
+      });
+    });
+
+    it('uses the normalized runtime message when the payload message is a placeholder', () => {
+      const out = formatErrorEventData(
+        {
+          error: { message: 'Payment required', status: 402, traceId: 'trace-402' },
+          errorType: AgentRuntimeErrorType.ProviderBizError,
+          message: 'error',
+          provider: 'lobehub',
+        },
+        'llm_execution',
+      );
+
+      expect(out).toMatchObject({
+        body: {
+          message: 'Payment required',
+          provider: 'lobehub',
+          status: 402,
+          traceId: 'trace-402',
+        },
+        error: 'Payment required',
+        errorType: AgentRuntimeErrorType.InsufficientQuota,
+        phase: 'llm_execution',
+      });
+    });
+
    it('preserves ConversationParentMissing errorType and message even when .cause has PG info', () => {
      // Mirrors createConversationParentMissingError from messagePersistErrors.ts:
      // the user-facing errorType lives on the error object directly, and the
@@ -1,5 +1,11 @@
+import { pickNonEmptyString, toRecord } from '@lobechat/utils/object';
+
+import { formatErrorForState } from './formatErrorForState';
 import { formatPgError, pgErrorType, unwrapPgError } from './pgError';

+const isErrorType = (value: unknown): value is string | number =>
+  typeof value === 'string' || typeof value === 'number';
+
 /**
 * Normalize an arbitrary thrown value into the shape the runtime stream-event
 * protocol expects. Extracts a human-readable `error` string and a best-effort
@@ -23,55 +29,38 @@ import { formatPgError, pgErrorType, unwrapPgError } from './pgError';
 * DB failures by SQLSTATE.
 */
 export const formatErrorEventData = (error: unknown, phase: string) => {
-  let errorMessage = 'Unknown error';
-  let errorType: string | undefined;
-  // True when `errorType` came from a business-typed field on the error
-  // payload (step 1 above). Driver class names assigned via `error.name`
-  // do NOT set this flag, so raw `PostgresError` / `DatabaseError` instances
-  // still fall through to the PG unwrap step.
-  let hasBusinessErrorType = false;
-
-  if (error && typeof error === 'object') {
-    const payload = error as { error?: unknown; errorType?: unknown; message?: unknown };
-
-    if (typeof payload.errorType === 'string') {
-      errorType = payload.errorType;
-      hasBusinessErrorType = true;
-    }
-
-    if (typeof payload.message === 'string' && payload.message.length > 0) {
-      errorMessage = payload.message;
-    } else if (typeof payload.error === 'string' && payload.error.length > 0) {
-      errorMessage = payload.error;
-    } else if (
-      payload.error &&
-      typeof payload.error === 'object' &&
-      'message' in payload.error &&
-      typeof payload.error.message === 'string'
-    ) {
-      errorMessage = payload.error.message;
-    } else if (error instanceof Error && error.message.length > 0) {
-      errorMessage = error.message;
-    } else if (errorType) {
-      errorMessage = errorType;
-    }
-  } else if (error instanceof Error && error.message.length > 0) {
-    errorMessage = error.message;
-    errorType = error.name;
-  } else if (typeof error === 'string' && error.length > 0) {
-    errorMessage = error;
-  }
+  const payload = toRecord(error);
+  const rawPayloadErrorType = payload?.errorType ?? payload?.type;
+  const payloadErrorType = isErrorType(rawPayloadErrorType) ? rawPayloadErrorType : undefined;
+  const structuredError =
+    error instanceof Error || payloadErrorType === undefined
+      ? undefined
+      : formatErrorForState(payload);
+  const body = structuredError?.body;
+  const hasPayloadErrorType = payloadErrorType !== undefined;
+  let errorType = hasPayloadErrorType
+    ? String(structuredError?.type ?? payloadErrorType)
+    : undefined;
+  const payloadError = payload?.error;
+  let errorMessage =
+    pickNonEmptyString(structuredError?.message) ??
+    pickNonEmptyString(payload?.message) ??
+    pickNonEmptyString(payloadError) ??
+    pickNonEmptyString(toRecord(payloadError)?.message) ??
+    (error instanceof Error ? pickNonEmptyString(error.message) : pickNonEmptyString(error)) ??
+    errorType ??
+    'Unknown error';

  if (!errorType && error instanceof Error && error.name) {
    errorType = error.name;
  }

-  // Enrichment: run PG unwrap whenever no *business-typed* errorType was
+  // Enrichment: run PG unwrap whenever no payload errorType was
  // declared. This covers both Drizzle-wrapped errors (PG info under .cause)
  // AND raw top-level driver errors like `PostgresError` / `DatabaseError`
  // which carry a specific `name` but are still real PG errors deserving
  // `pg_<sqlstate>` classification on the dashboard.
-  if (!hasBusinessErrorType) {
+  if (!hasPayloadErrorType) {
    const pg = unwrapPgError(error);
    if (pg) {
      errorMessage = formatPgError(pg);
@@ -80,6 +69,7 @@ export const formatErrorEventData = (error: unknown, phase: string) => {
  }

  return {
+    ...(body === undefined ? {} : { body }),
    error: errorMessage,
    errorType,
    phase,
@@ -16,7 +16,35 @@ describe('formatErrorForState', () => {

      expect(result.type).toBe(AgentRuntimeErrorType.InvalidProviderAPIKey);
      expect(result.message).toBe('Invalid API key');
-      expect(result.body).toEqual({ detail: 'Unauthorized' });
+      expect(result.body).toEqual({
+        detail: 'Unauthorized',
+        message: 'Invalid API key',
+        provider: 'openai',
+      });
+    });
+
+    it('preserves top-level context from ChatCompletionErrorPayload', () => {
+      const budget = { required: 12 };
+
+      const result = formatErrorForState({
+        budget,
+        error: { message: 'Budget exceeded' },
+        errorType: ChatErrorType.FreePlanLimit,
+        provider: 'lobehub',
+      });
+
+      expect(result).toMatchObject({
+        attribution: 'user',
+        body: {
+          budget,
+          message: 'Budget exceeded',
+          provider: 'lobehub',
+        },
+        category: 'quota',
+        httpStatus: 402,
+        message: 'Budget exceeded',
+        type: ChatErrorType.FreePlanLimit,
+      });
    });

    it('wraps standard Error as InternalServerError', () => {
@@ -180,6 +208,43 @@ describe('formatErrorForState', () => {
      expect(result.category).toBe('quota');
    });

+    it('keeps payload.error available when _responseBody is present', () => {
+      const result = formatErrorForState({
+        _responseBody: { provider: 'lobehub' },
+        error: { status: 402 },
+        errorType: AgentRuntimeErrorType.ProviderBizError,
+        message: 'opaque upstream message',
+      });
+
+      expect(result).toMatchObject({
+        body: {
+          error: { status: 402 },
+          message: 'opaque upstream message',
+          provider: 'lobehub',
+        },
+        category: 'quota',
+        type: AgentRuntimeErrorType.InsufficientQuota,
+      });
+    });
+
+    it('merges payload status into an existing _responseBody error object', () => {
+      const result = formatErrorForState({
+        _responseBody: { error: { message: 'Payment required' }, provider: 'lobehub' },
+        error: { status: 402 },
+        errorType: AgentRuntimeErrorType.ProviderBizError,
+        message: 'opaque upstream message',
+      });
+
+      expect(result).toMatchObject({
+        body: {
+          error: { message: 'Payment required', status: 402 },
+          provider: 'lobehub',
+        },
+        category: 'quota',
+        type: AgentRuntimeErrorType.InsufficientQuota,
+      });
+    });
+
    it('keeps a genuine residual as ProviderBizError (E8002)', () => {
      const result = formatErrorForState({
        errorType: AgentRuntimeErrorType.ProviderBizError,
@@ -1,5 +1,6 @@
 import { getErrorCodeSpec, refineErrorCode } from '@lobechat/model-runtime';
 import { AgentRuntimeErrorType, ChatErrorType, type ChatMessageError } from '@lobechat/types';
+import { isRecord } from '@lobechat/utils';

 /** Pull a usable HTTP status out of the nested upstream error object. */
 const extractHttpStatus = (body: unknown): number | undefined => {
@@ -19,6 +20,80 @@ const extractProvider = (body: unknown): string | undefined => {
  return typeof p === 'string' ? p : undefined;
 };

+const extractMessage = (value: unknown): string | undefined => {
+  if (!isRecord(value)) return undefined;
+
+  const message = value.message;
+  if (typeof message === 'string' && message) return message;
+
+  const nestedError = value.error;
+  if (isRecord(nestedError)) {
+    const nestedMessage = nestedError.message;
+    if (typeof nestedMessage === 'string' && nestedMessage) return nestedMessage;
+  }
+};
+
+interface ChatCompletionErrorPayloadLike {
+  _responseBody?: unknown;
+  budget?: unknown;
+  error?: unknown;
+  errorType: ChatMessageError['type'];
+  message?: string;
+  provider?: unknown;
+}
+
+const mergePayloadError = (
+  sourceBody: Record<string, unknown>,
+  payload: ChatCompletionErrorPayloadLike,
+): unknown | undefined => {
+  if (payload._responseBody === undefined || payload.error === undefined) return undefined;
+  if (!('error' in sourceBody)) return payload.error;
+  if (isRecord(sourceBody.error) && isRecord(payload.error)) {
+    return { ...payload.error, ...sourceBody.error };
+  }
+};
+
+const buildPayloadBody = (
+  payload: ChatCompletionErrorPayloadLike,
+  originalError: unknown,
+  message: string,
+): unknown => {
+  // Runtime payloads often keep UI context (for example quota hints) next to
+  // `error`, while `error` itself only carries the display message. Merge both
+  // layers so normalizing `{ errorType, error }` does not drop the fields the
+  // chat error renderer needs later.
+  const sourceBody = payload._responseBody ?? payload.error ?? originalError;
+  const context: Record<string, unknown> = {};
+
+  if (payload.budget !== undefined) context.budget = payload.budget;
+  if (typeof payload.provider === 'string') context.provider = payload.provider;
+
+  if (isRecord(sourceBody)) {
+    const payloadError = mergePayloadError(sourceBody, payload);
+
+    return {
+      ...sourceBody,
+      // `_responseBody` is the display-facing body, but gateway/model-runtime
+      // still carries status/provider details in `error` for some failures:
+      // `{ _responseBody: { error: { message } }, error: { status: 402 } }`.
+      ...(payloadError === undefined ? {} : { error: payloadError }),
+      ...(payload.budget !== undefined && !('budget' in sourceBody)
+        ? { budget: payload.budget }
+        : {}),
+      ...(typeof payload.provider === 'string' && !('provider' in sourceBody)
+        ? { provider: payload.provider }
+        : {}),
+      ...('message' in sourceBody ? {} : { message }),
+    };
+  }
+
+  return {
+    ...context,
+    ...(sourceBody === undefined ? {} : { error: sourceBody }),
+    message,
+  };
+};
+
 /**
 * Merge classification metadata from `ERROR_CODE_SPECS` onto a normalized
 * `ChatMessageError`. Codes that aren't in the spec table (fallbacks like
@@ -79,14 +154,16 @@ const enrichWithSpec = (formatted: ChatMessageError): ChatMessageError => {
 */
 export const formatErrorForState = (error: unknown): ChatMessageError => {
  if (error && typeof error === 'object' && 'errorType' in error) {
-    const payload = error as {
-      error?: unknown;
-      errorType: ChatMessageError['type'];
-      message?: string;
-    };
+    const payload = error as ChatCompletionErrorPayloadLike;
+    const message =
+      (payload.message && payload.message !== 'error' ? payload.message : undefined) ??
+      extractMessage(payload._responseBody) ??
+      extractMessage(payload.error) ??
+      String(payload.errorType);
+
    return enrichWithSpec({
-      body: payload.error || error,
-      message: payload.message || String(payload.errorType),
+      body: buildPayloadBody(payload, error, message),
+      message,
      type: payload.errorType,
    });
  }
@@ -659,6 +659,59 @@ describe('createServerAgentToolsEngine', () => {
      expect(result.enabledToolIds).not.toContain(RemoteDeviceManifest.identifier);
    });

+    it('should disable RemoteDevice when a device is explicitly bound (locked to the selection)', () => {
+      // A user-selected (bound) device locks the run to that device — the
+      // activate-device tool is never offered, so the model cannot switch.
+      const context = createMockContext();
+      const engine = createServerAgentToolsEngine(context, {
+        agentConfig: { plugins: [RemoteDeviceManifest.identifier] },
+        canUseDevice: true,
+        deviceContext: {
+          autoActivated: true,
+          boundDeviceId: 'device-001',
+          deviceOnline: true,
+          gatewayConfigured: true,
+        },
+        model: 'gpt-4',
+        provider: 'openai',
+      });
+
+      const result = engine.generateToolsDetailed({
+        toolIds: [RemoteDeviceManifest.identifier],
+        model: 'gpt-4',
+        provider: 'openai',
+      });
+
+      expect(result.enabledToolIds).not.toContain(RemoteDeviceManifest.identifier);
+    });
+
+    it('should disable RemoteDevice when the bound device is OFFLINE — no silent hop to another machine', () => {
+      // The bound device going offline makes the plan device-unrouted, so
+      // `autoActivated` is false. Without the `boundDeviceId` gate the tool
+      // would resurface and let the model activate a *different* online device.
+      // The explicit selection must keep the run locked instead.
+      const context = createMockContext();
+      const engine = createServerAgentToolsEngine(context, {
+        agentConfig: { plugins: [RemoteDeviceManifest.identifier] },
+        canUseDevice: true,
+        deviceContext: {
+          boundDeviceId: 'device-001',
+          deviceOnline: true,
+          gatewayConfigured: true,
+        },
+        model: 'gpt-4',
+        provider: 'openai',
+      });
+
+      const result = engine.generateToolsDetailed({
+        toolIds: [RemoteDeviceManifest.identifier],
+        model: 'gpt-4',
+        provider: 'openai',
+      });
+
+      expect(result.enabledToolIds).not.toContain(RemoteDeviceManifest.identifier);
+    });
+
    it('should enable RemoteDevice in bot conversations when caller is trusted (canUseDevice=true)', () => {
      // The `!isBotConversation` clause was dropped in — the
      // confused-deputy concern that motivated it is now handled at a
@@ -9,7 +9,6 @@
 * - Gets model capabilities from provided function
 * - No dependency on frontend stores (useToolStore, useAgentStore, etc.)
 */
-import { AgentDocumentsManifest } from '@lobechat/builtin-tool-agent-documents';
 import { CloudSandboxManifest } from '@lobechat/builtin-tool-cloud-sandbox';
 import { KnowledgeBaseManifest } from '@lobechat/builtin-tool-knowledge-base';
 import { LocalSystemManifest } from '@lobechat/builtin-tool-local-system';
@@ -28,7 +27,11 @@ import { ToolsEngine } from '@lobechat/context-engine';
 import { type RuntimeEnvMode, type RuntimePlatform } from '@lobechat/types';
 import debug from 'debug';

-import { executionTargetToRuntimeMode, resolveExecutionTarget } from '@/helpers/executionTarget';
+import {
+  executionTargetToRuntimeMode,
+  resolveExecutionTarget,
+  resolveToolMode,
+} from '@/helpers/executionTarget';
 import {
  buildAllowedBuiltinTools,
  DEVICE_TOOL_IDENTIFIERS,
@@ -86,7 +89,7 @@ export const createServerToolsEngine = (
  // Combine all manifests, then drop anything whose identifier the caller
  // has explicitly forbidden for this turn. The post-merge filter closes
  // the second half of the wall: an installed plugin or a
-  // Skill/Klavis manifest claiming `lobe-remote-device` would otherwise
+  // Skill/Composio manifest claiming `lobe-remote-device` would otherwise
  // slip through `buildAllowedBuiltinTools` (which only touches the
  // builtin source).
  const combinedManifests = [...pluginManifests, ...builtinManifests, ...additionalManifests];
@@ -131,7 +134,6 @@ export const createServerAgentToolsEngine = (
    disableLocalSystem = false,
    executionPlan,
    globalMemoryEnabled = false,
-    hasAgentDocuments = false,
    hasEnabledKnowledgeBases = false,
    isBotConversation = false,
    model,
@@ -157,7 +159,7 @@ export const createServerAgentToolsEngine = (
  const executionTarget =
    executionPlan?.target ??
    resolveExecutionTarget(agentConfig.agencyConfig, {
-      isDesktop: platform === 'desktop',
+      clientExecutionAvailable: platform === 'desktop',
    });
  const runtimeMode: RuntimeEnvMode = executionTargetToRuntimeMode(executionTarget);
  // Device tools (local-system, remote-device proxy) only exist for
@@ -170,9 +172,7 @@ export const createServerAgentToolsEngine = (
  const isSearchEnabled = searchMode !== 'off';
  // Tool mode: explicit `toolMode` wins; otherwise derive from `enableAgentMode`
  // (undefined = agent). `custom` = toolset is exactly the agent's plugins.
-  const toolMode: 'agent' | 'chat' | 'custom' =
-    agentConfig.chatConfig?.toolMode ??
-    (agentConfig.chatConfig?.enableAgentMode === false ? 'chat' : 'agent');
+  const toolMode = resolveToolMode(agentConfig.chatConfig ?? undefined);
  const isChatMode = toolMode === 'chat';
  const isCustomMode = toolMode === 'custom';

@@ -231,13 +231,20 @@ export const createServerAgentToolsEngine = (
    // Only auto-enable in bot conversations; otherwise let user's plugin selection take effect
    ...(isBotConversation && { [MessageManifest.identifier]: true }),
    // Remote-device proxy: shown only for device-capable targets when the
-    // server has a proxy but no specific device is auto-activated yet (user
-    // must pick). External bot senders never reach it: the plan degrades
-    // denied targets to `none` (→ not deviceCapable) and the physical
-    // manifest walls drop it for `canUseDevice=false` turns.
+    // server has a proxy, no specific device is auto-activated yet, AND the
+    // user has NOT explicitly selected a device. Once a device is explicitly
+    // selected (`boundDeviceId`), the run is locked to it: we never expose the
+    // activate-device tool, so the model can never switch to another machine —
+    // not even when the selected device is offline (the run stays unrouted
+    // until that device comes back, rather than silently hopping elsewhere).
+    // External bot senders never reach it: the plan degrades denied targets to
+    // `none` (→ not deviceCapable) and the physical manifest walls drop it for
+    // `canUseDevice=false` turns.
    [RemoteDeviceManifest.identifier]:
-      deviceCapable && hasDeviceProxy && !deviceContext?.autoActivated,
-    [AgentDocumentsManifest.identifier]: hasAgentDocuments,
+      deviceCapable &&
+      hasDeviceProxy &&
+      !deviceContext?.autoActivated &&
+      !deviceContext?.boundDeviceId,
    [WebBrowsingManifest.identifier]: isSearchEnabled,
  };

@@ -256,7 +263,7 @@ export const createServerAgentToolsEngine = (
      : isChatMode
        ? chatModeAllowedToolIds
        : defaultToolIds,
-    // Post-merge wall: a plugin or Skill/Klavis manifest claiming a
+    // Post-merge wall: a plugin or Skill/Composio manifest claiming a
    // device identifier survives `buildAllowedBuiltinTools` (which only
    // filters the builtin source). Excluding the identifiers here drops
    // them from the combined `manifestSchemas` so the activator cannot
@@ -22,7 +22,7 @@ export interface ServerAgentToolsContext {
 * Configuration options for createServerToolsEngine
 */
 export interface ServerAgentToolsEngineConfig {
-  /** Additional manifests to include (e.g., Klavis tools) */
+  /** Additional manifests to include (e.g., Composio tools) */
  additionalManifests?: LobeToolManifest[];
  /**
   * Override the list of builtin tools fed into the engine's
@@ -39,7 +39,7 @@ export interface ServerAgentToolsEngineConfig {
  /**
   * Identifiers to drop from `manifestSchemas` after combining plugin,
   * builtin, and additional manifests. Filtering builtins alone is not
-   * enough: an installed plugin or a Skill/Klavis manifest can declare
+   * enough: an installed plugin or a Skill/Composio manifest can declare
   * `identifier: 'lobe-remote-device'` and slip past `buildAllowedBuiltinTools`.
   * This is the final post-merge wall referenced in .
   */
@@ -101,8 +101,6 @@ export interface ServerCreateAgentToolsEngineParams {
  executionPlan?: ExecutionPlan;
  /** Whether the user's global memory setting is enabled */
  globalMemoryEnabled?: boolean;
-  /** Whether agent has agent documents */
-  hasAgentDocuments?: boolean;
  /** Whether agent has enabled knowledge bases */
  hasEnabledKnowledgeBases?: boolean;
  /** Whether the request originates from a bot conversation (auto-enables message tool) */
@@ -70,6 +70,25 @@ describe('serverMessagesEngine', () => {
      expect(result[0].content).toBe(systemRole + '\n\n' + getCurrentDateContent());
    });

+    it('should inject model knowledge cutoff when provided', async () => {
+      const messages = createBasicMessages();
+
+      const result = await serverMessagesEngine({
+        messages,
+        model: 'gpt-4',
+        modelKnowledgeCutoff: '2024-06',
+        provider: 'openai',
+        systemRole: 'You are a helpful assistant',
+      });
+
+      expect(result[0].role).toBe('system');
+      expect(result[0].content).toBe(
+        'You are a helpful assistant\n\n' +
+          getCurrentDateContent() +
+          '\n\nModel knowledge cutoff: 2024-06',
+      );
+    });
+
    it('should handle empty messages', async () => {
      const result = await serverMessagesEngine({
        messages: [],
@@ -51,6 +51,7 @@ const createServerVariableGenerators = (params: {
 export const serverMessagesEngine = async ({
  messages = [],
  model,
+  modelKnowledgeCutoff,
  provider,
  systemRole,
  inputTemplate,
@@ -83,6 +84,7 @@ export const serverMessagesEngine = async ({
  const engine = new MessagesEngine({
    // Capability injection
    capabilities: {
+      isCanUseAudio: capabilities?.isCanUseAudio,
      isCanUseFC: capabilities?.isCanUseFC,
      isCanUseVideo: capabilities?.isCanUseVideo,
      isCanUseVision: capabilities?.isCanUseVision,
@@ -120,6 +122,7 @@ export const serverMessagesEngine = async ({

    // Model info
    model,
+    modelKnowledgeCutoff,

    provider,
    systemRole,
@@ -23,6 +23,8 @@ import type { RuntimeInitialContext, UIChatMessage } from '@lobechat/types';
 * Model capability checker functions for server-side
 */
 export interface ServerModelCapabilities {
+  /** Check if audio input is supported */
+  isCanUseAudio?: (model: string, provider: string) => boolean;
  /** Check if function calling is supported */
  isCanUseFC?: (model: string, provider: string) => boolean;
  /** Check if video is supported */
@@ -130,6 +132,8 @@ export interface ServerMessagesEngineParams {

  /** Model ID */
  model: string;
+  /** Model knowledge cutoff date, e.g. `2024-06`. Omit when unknown. */
+  modelKnowledgeCutoff?: string;

  /** Page content context (optional, for document editing) */
  pageContentContext?: PageContentContext;
@@ -20,8 +20,8 @@ import { GenerationModel } from '@/database/models/generation';
 import { asyncAuthedProcedure, asyncRouter as router } from '@/libs/trpc/async';
 import { initModelRuntimeFromDB } from '@/server/modules/ModelRuntime';
 import { VideoGenerationService } from '@/server/services/generation/video';
+import { buildVideoGenerationFilePayload } from '@/server/services/generation/videoFile';
 import { FileSource } from '@/types/files';
-import { sanitizeFileName } from '@/utils/sanitizeFileName';

 const log = debug('lobe-video:async');

@@ -196,13 +196,11 @@ export const videoRouter = router({
            url: processResult.videoKey,
            width: processResult.width,
          },
-          {
-            fileHash: processResult.fileHash,
-            fileType: processResult.mimeType,
-            name: `${sanitizeFileName(batch?.prompt ?? '', generationId)}.mp4`,
-            size: processResult.fileSize,
-            url: processResult.videoKey,
-          },
+          buildVideoGenerationFilePayload({
+            generationId,
+            processResult,
+            prompt: batch?.prompt,
+          }),
          FileSource.VideoGeneration,
        );

@@ -393,6 +393,7 @@ describe('agentRouter', () => {
          expiresAt: new Date(),
          holderId: userId,
          lockedByOther: false,
+          ownerId: null,
        });

        const caller = agentRouter.createCaller(wsCtx());
@@ -410,6 +411,7 @@ describe('agentRouter', () => {
          expiresAt: new Date(),
          holderId: userId,
          lockedByOther: false,
+          ownerId: null,
        });

        const caller = agentRouter.createCaller(wsCtx());
@@ -0,0 +1,146 @@
+// @vitest-environment node
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type * as AgentDocumentModels from '@/database/models/agentDocuments';
+import { createCallerFactory } from '@/libs/trpc/lambda';
+import { createContextInner } from '@/libs/trpc/lambda/context';
+import { AgentDocumentsService } from '@/server/services/agentDocuments';
+
+import { agentDocumentRouter } from '../agentDocument';
+
+const mocks = vi.hoisted(() => ({
+  associate: vi.fn(),
+  createTopic: vi.fn(),
+  findByAgentAndDocumentTrigger: vi.fn(),
+  findRowByDocumentId: vi.fn(),
+  getServerDB: vi.fn(),
+}));
+
+vi.mock('@/database/core/db-adaptor', () => ({
+  getServerDB: mocks.getServerDB,
+}));
+
+vi.mock('@/database/models/agentDocuments', async (importOriginal) => {
+  const actual = await importOriginal<typeof AgentDocumentModels>();
+
+  return {
+    ...actual,
+    AgentDocumentModel: vi.fn(),
+  };
+});
+
+vi.mock('@/database/models/topic', () => ({
+  TopicModel: vi.fn().mockImplementation(() => ({
+    create: mocks.createTopic,
+    findByAgentAndDocumentTrigger: mocks.findByAgentAndDocumentTrigger,
+  })),
+}));
+
+vi.mock('@/database/models/topicDocument', () => ({
+  TopicDocumentModel: vi.fn().mockImplementation(() => ({
+    associate: mocks.associate,
+  })),
+}));
+
+vi.mock('@/server/services/agentDocuments', () => ({
+  AgentDocumentsService: vi.fn(),
+}));
+
+vi.mock('@/server/services/agentDocumentVfs', () => ({
+  AgentDocumentVfsService: vi.fn(),
+}));
+
+vi.mock('@/server/services/agentDocuments/toolOutcome', () => ({
+  emitAgentDocumentToolOutcomeSafely: vi.fn(),
+}));
+
+const createCaller = createCallerFactory(agentDocumentRouter);
+
+describe('agentDocumentRouter.getOrCreateChatTopic', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.getServerDB.mockResolvedValue({ kind: 'server-db' });
+
+    vi.mocked(AgentDocumentsService).mockImplementation(
+      () =>
+        ({ findRowByDocumentId: mocks.findRowByDocumentId }) as unknown as AgentDocumentsService,
+    );
+  });
+
+  it('returns the existing topic when a doc-anchored row is already linked', async () => {
+    mocks.findByAgentAndDocumentTrigger.mockResolvedValue({ id: 'topic-existing' });
+
+    const caller = createCaller(await createContextInner({ userId: 'user-1' }));
+    const result = await caller.getOrCreateChatTopic({
+      agentId: 'agent-1',
+      documentId: 'docs_abc',
+    });
+
+    expect(result).toEqual({ topicId: 'topic-existing' });
+    expect(mocks.findByAgentAndDocumentTrigger).toHaveBeenCalledWith({
+      agentId: 'agent-1',
+      documentId: 'docs_abc',
+      trigger: 'document',
+    });
+    expect(mocks.createTopic).not.toHaveBeenCalled();
+    expect(mocks.associate).not.toHaveBeenCalled();
+  });
+
+  it('creates a new doc-anchored topic and associates it when none exists', async () => {
+    mocks.findByAgentAndDocumentTrigger.mockResolvedValue(undefined);
+    mocks.findRowByDocumentId.mockResolvedValue({
+      filename: 'spec.md',
+      id: 'agent-document-1',
+      title: 'Spec',
+    });
+    mocks.createTopic.mockResolvedValue({ id: 'topic-new' });
+
+    const caller = createCaller(await createContextInner({ userId: 'user-1' }));
+    const result = await caller.getOrCreateChatTopic({
+      agentId: 'agent-1',
+      documentId: 'docs_abc',
+    });
+
+    expect(result).toEqual({ topicId: 'topic-new' });
+    expect(mocks.createTopic).toHaveBeenCalledWith({
+      agentId: 'agent-1',
+      title: 'Spec',
+      trigger: 'document',
+    });
+    expect(mocks.associate).toHaveBeenCalledWith({
+      documentId: 'docs_abc',
+      topicId: 'topic-new',
+    });
+  });
+
+  it('falls back to the filename when the document has no title', async () => {
+    mocks.findByAgentAndDocumentTrigger.mockResolvedValue(undefined);
+    mocks.findRowByDocumentId.mockResolvedValue({
+      filename: 'fallback.md',
+      id: 'agent-document-1',
+      title: undefined,
+    });
+    mocks.createTopic.mockResolvedValue({ id: 'topic-new' });
+
+    const caller = createCaller(await createContextInner({ userId: 'user-1' }));
+    await caller.getOrCreateChatTopic({ agentId: 'agent-1', documentId: 'docs_abc' });
+
+    expect(mocks.createTopic).toHaveBeenCalledWith({
+      agentId: 'agent-1',
+      title: 'fallback.md',
+      trigger: 'document',
+    });
+  });
+
+  it('throws NOT_FOUND when the document is missing or not owned by the agent', async () => {
+    mocks.findByAgentAndDocumentTrigger.mockResolvedValue(undefined);
+    mocks.findRowByDocumentId.mockResolvedValue(undefined);
+
+    const caller = createCaller(await createContextInner({ userId: 'user-1' }));
+    await expect(
+      caller.getOrCreateChatTopic({ agentId: 'agent-1', documentId: 'docs_missing' }),
+    ).rejects.toThrow(/Document not found/);
+    expect(mocks.createTopic).not.toHaveBeenCalled();
+    expect(mocks.associate).not.toHaveBeenCalled();
+  });
+});
@@ -500,6 +500,7 @@ describe('agentGroupRouter', () => {
          expiresAt: new Date(),
          holderId: userId,
          lockedByOther: false,
+          ownerId: null,
        });

        const caller = agentGroupRouter.createCaller(wsCtx());
@@ -517,6 +518,7 @@ describe('agentGroupRouter', () => {
          expiresAt: new Date(),
          holderId: userId,
          lockedByOther: false,
+          ownerId: null,
        });

        const caller = agentGroupRouter.createCaller(wsCtx());
@@ -29,10 +29,12 @@ describe('aiModelRouter', () => {

  it('should create ai model', async () => {
    const mockCreate = vi.fn().mockResolvedValue({ id: 'model-1' });
+    const mockFindByIdAndProvider = vi.fn().mockResolvedValue(null);
    vi.mocked(AiModelModel).mockImplementation(
      () =>
        ({
          create: mockCreate,
+          findByIdAndProvider: mockFindByIdAndProvider,
        }) as any,
    );

@@ -44,12 +46,68 @@ describe('aiModelRouter', () => {
    });

    expect(result).toBe('model-1');
+    expect(mockFindByIdAndProvider).toHaveBeenCalledWith('test-model', 'test-provider');
    expect(mockCreate).toHaveBeenCalledWith({
      id: 'test-model',
      providerId: 'test-provider',
    });
  });

+  it('should reject duplicate ai model before creating', async () => {
+    const mockCreate = vi.fn();
+    const mockFindByIdAndProvider = vi.fn().mockResolvedValue({ id: 'test-model' });
+    vi.mocked(AiModelModel).mockImplementation(
+      () =>
+        ({
+          create: mockCreate,
+          findByIdAndProvider: mockFindByIdAndProvider,
+        }) as any,
+    );
+
+    const caller = aiModelRouter.createCaller(mockCtx);
+
+    await expect(
+      caller.createAiModel({
+        id: 'test-model',
+        providerId: 'test-provider',
+      }),
+    ).rejects.toMatchObject({
+      code: 'CONFLICT',
+      message: 'Model "test-model" already exists',
+    });
+    expect(mockCreate).not.toHaveBeenCalled();
+  });
+
+  it('should convert duplicate insert races to conflict errors', async () => {
+    const duplicateError = Object.assign(new Error('failed query'), {
+      cause: Object.assign(new Error('duplicate key'), {
+        code: '23505',
+        constraint: 'ai_models_id_provider_id_user_id_pk',
+      }),
+    });
+    const mockCreate = vi.fn().mockRejectedValue(duplicateError);
+    const mockFindByIdAndProvider = vi.fn().mockResolvedValue(null);
+    vi.mocked(AiModelModel).mockImplementation(
+      () =>
+        ({
+          create: mockCreate,
+          findByIdAndProvider: mockFindByIdAndProvider,
+        }) as any,
+    );
+
+    const caller = aiModelRouter.createCaller(mockCtx);
+
+    await expect(
+      caller.createAiModel({
+        id: 'test-model',
+        providerId: 'test-provider',
+      }),
+    ).rejects.toMatchObject({
+      code: 'CONFLICT',
+      message: 'Model "test-model" already exists',
+    });
+  });
+
  it('should get ai model by id', async () => {
    const mockModel = {
      id: 'model-1',
@@ -0,0 +1,118 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { asrRouter } from '../asr';
+
+vi.mock('@/database/core/db-adaptor', () => ({
+  getServerDB: vi.fn(() => ({})),
+}));
+
+const transcribeMock = vi.fn();
+vi.mock('@/server/modules/ModelRuntime', () => ({
+  initModelRuntimeFromDB: vi.fn(async () => ({ transcribe: transcribeMock })),
+}));
+
+const findByIdMock = vi.fn();
+vi.mock('@/database/models/file', () => ({
+  FileModel: vi.fn(() => ({ findById: findByIdMock })),
+}));
+
+const getFileByteArrayMock = vi.fn();
+vi.mock('@/server/services/file', () => ({
+  FileService: vi.fn(() => ({ getFileByteArray: getFileByteArrayMock })),
+}));
+
+const caller = asrRouter.createCaller({ jwtPayload: { userId: 'u1' }, userId: 'u1' } as any);
+
+beforeEach(() => {
+  transcribeMock.mockResolvedValue({ text: 'hello world' });
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('asrRouter.transcribe', () => {
+  it('transcribes inline base64 audio', async () => {
+    const res = await caller.transcribe({
+      audioBase64: Buffer.from('audio-bytes').toString('base64'),
+      fileName: 'clip.mp3',
+      model: 'whisper-1',
+      provider: 'openai',
+    });
+
+    expect(res).toEqual({ text: 'hello world' });
+    expect(findByIdMock).not.toHaveBeenCalled();
+
+    const payload = transcribeMock.mock.calls[0][0];
+    expect(payload.file).toBeInstanceOf(File);
+    expect(payload.fileName).toBe('clip.mp3');
+    expect(await payload.file.text()).toBe('audio-bytes');
+  });
+
+  it('resolves a fileId by downloading the bytes from storage', async () => {
+    findByIdMock.mockResolvedValue({
+      fileType: 'audio/mp4',
+      name: 'meeting.m4a',
+      url: 's3-key/meeting.m4a',
+    });
+    getFileByteArrayMock.mockResolvedValue(new Uint8Array(Buffer.from('from-s3')));
+
+    const res = await caller.transcribe({ fileId: 'file_123', model: 'whisper-1' });
+
+    expect(res).toEqual({ text: 'hello world' });
+    expect(findByIdMock).toHaveBeenCalledWith('file_123');
+    expect(getFileByteArrayMock).toHaveBeenCalledWith('s3-key/meeting.m4a');
+
+    const payload = transcribeMock.mock.calls[0][0];
+    expect(payload.fileName).toBe('meeting.m4a');
+    expect(payload.file.type).toBe('audio/mp4');
+    expect(await payload.file.text()).toBe('from-s3');
+  });
+
+  it('rejects when neither fileId nor audioBase64 is provided', async () => {
+    await expect(caller.transcribe({ model: 'whisper-1' } as any)).rejects.toThrow();
+  });
+
+  it('rejects oversized inline base64 and guides to fileId', async () => {
+    // > 3MB decoded → base64 string exceeds the cap
+    const tooBig = 'A'.repeat(5 * 1024 * 1024);
+
+    await expect(caller.transcribe({ audioBase64: tooBig, model: 'whisper-1' })).rejects.toThrow(
+      /fileId/i,
+    );
+    expect(transcribeMock).not.toHaveBeenCalled();
+  });
+
+  it('rejects when both fileId and audioBase64 are provided', async () => {
+    await expect(
+      caller.transcribe({
+        audioBase64: Buffer.from('x').toString('base64'),
+        fileId: 'file_123',
+        model: 'whisper-1',
+      } as any),
+    ).rejects.toThrow();
+  });
+
+  it('throws NOT_FOUND when the fileId does not exist', async () => {
+    findByIdMock.mockResolvedValue(undefined);
+
+    await expect(caller.transcribe({ fileId: 'missing', model: 'whisper-1' })).rejects.toThrow(
+      /not found/i,
+    );
+    expect(getFileByteArrayMock).not.toHaveBeenCalled();
+  });
+
+  it('throws NOT_FOUND when the stored object is gone (NoSuchKey)', async () => {
+    findByIdMock.mockResolvedValue({
+      fileType: 'audio/mp4',
+      name: 'gone.m4a',
+      url: 's3-key/gone.m4a',
+    });
+    getFileByteArrayMock.mockRejectedValue({ Code: 'NoSuchKey' });
+
+    await expect(caller.transcribe({ fileId: 'file_x', model: 'whisper-1' })).rejects.toThrow(
+      /no longer available/i,
+    );
+  });
+});
@@ -0,0 +1,70 @@
+import { TRPCError } from '@trpc/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { DeviceModel } from '@/database/models/device';
+
+import { assertWorkspaceRootApproved } from '../deviceWorkspaceGuard';
+
+const mockModel = (row: { defaultCwd?: string | null; workingDirs?: { path: string }[] } | null) =>
+  ({
+    findByDeviceId: vi.fn().mockResolvedValue(row),
+  }) as unknown as DeviceModel;
+
+describe('assertWorkspaceRootApproved', () => {
+  it('allows a root that exactly matches a bound workingDir', async () => {
+    const model = mockModel({ workingDirs: [{ path: '/Users/me/proj' }] });
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/proj'),
+    ).resolves.toBeUndefined();
+  });
+
+  it('allows a root nested inside a bound workingDir', async () => {
+    const model = mockModel({ workingDirs: [{ path: '/Users/me/proj' }] });
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/proj/packages/app'),
+    ).resolves.toBeUndefined();
+  });
+
+  it('allows a root matching defaultCwd when no workingDirs match', async () => {
+    const model = mockModel({ defaultCwd: '/Users/me/default', workingDirs: [] });
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/default'),
+    ).resolves.toBeUndefined();
+  });
+
+  it('rejects a root that escapes the approved roots (filesystem root)', async () => {
+    const model = mockModel({ workingDirs: [{ path: '/Users/me/proj' }] });
+    await expect(assertWorkspaceRootApproved(model, 'dev-1', '/')).rejects.toMatchObject({
+      code: 'FORBIDDEN',
+    });
+  });
+
+  it('rejects a sibling directory that shares a path prefix but is not contained', async () => {
+    const model = mockModel({ workingDirs: [{ path: '/Users/me/proj' }] });
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/proj-evil'),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+
+  it('rejects when the device has no approved roots at all', async () => {
+    const model = mockModel({ workingDirs: [] });
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/proj'),
+    ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+
+  it('rejects when the device row is missing', async () => {
+    const model = mockModel(null);
+    await expect(
+      assertWorkspaceRootApproved(model, 'dev-1', '/Users/me/proj'),
+    ).rejects.toBeInstanceOf(TRPCError);
+  });
+
+  it('rejects an empty workspace root with BAD_REQUEST before hitting the DB', async () => {
+    const model = mockModel({ workingDirs: [{ path: '/Users/me/proj' }] });
+    await expect(assertWorkspaceRootApproved(model, 'dev-1', '')).rejects.toMatchObject({
+      code: 'BAD_REQUEST',
+    });
+    expect(model.findByDeviceId).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,289 @@
+// @vitest-environment node
+/**
+ * Integration test for the server `lobe-agent-management.callAgent` deferred
+ * execution flow.
+ *
+ * Verifies the full lifecycle end-to-end on the in-memory runtime:
+ *   1. Parent op LLM emits a `lobe-agent-management____callAgent` tool call.
+ *   2. The real server executor parks the parent, creates a pending tool
+ *      placeholder, and forks the target agent as a child op.
+ *   3. The child op completes.
+ *   4. The completion bridge backfills the placeholder and resumes the parent.
+ *   5. The parent reaches `done`.
+ */
+import { type LobeChatDatabase } from '@lobechat/database';
+import { agentOperations, agents, messagePlugins, messages } from '@lobechat/database/schemas';
+import { getTestDB } from '@lobechat/database/test-utils';
+import { and, eq } from 'drizzle-orm';
+import OpenAI from 'openai';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { inMemoryAgentStateManager } from '@/server/modules/AgentRuntime/InMemoryAgentStateManager';
+import { inMemoryStreamEventManager } from '@/server/modules/AgentRuntime/InMemoryStreamEventManager';
+
+import { aiAgentRouter } from '../../../aiAgent';
+import { cleanupTestUser, createTestUser } from '../setup';
+import { createMockResponsesStream, waitForOperationComplete } from './helpers';
+
+process.env.OPENAI_API_KEY = 'sk-test-fake-api-key-for-testing';
+
+let testDB: LobeChatDatabase;
+vi.mock('@/database/core/db-adaptor', () => ({
+  getServerDB: vi.fn(() => testDB),
+}));
+
+vi.mock('@/server/services/file', () => ({
+  FileService: vi.fn().mockImplementation(() => ({
+    getFullFileUrl: vi.fn().mockImplementation((path: string) => (path ? `/files${path}` : null)),
+  })),
+}));
+
+let mockResponsesCreate: any;
+let serverDB: LobeChatDatabase;
+let userId: string;
+let parentAgentId: string;
+let targetAgentId: string;
+
+const TARGET_ANSWER = 'The target agent completed the delegated callAgent work.';
+const PARENT_FINAL = 'I received the target agent result and the delegated work is complete.';
+
+const createTestContext = () => ({ jwtPayload: { userId }, userId });
+
+const createCallAgentResponse = () => {
+  const responseId = `resp_call_agent_${Date.now()}`;
+  const msgItemId = `msg_call_agent_${Date.now()}`;
+  const callId = 'call_agent_1';
+  const fnCall = {
+    arguments: JSON.stringify({
+      agentId: targetAgentId,
+      instruction: 'Handle the delegated backend integration task.',
+      runAsTask: true,
+      taskTitle: 'Delegated backend integration task',
+      timeout: 30_000,
+    }),
+    call_id: callId,
+    name: 'lobe-agent-management____callAgent',
+    type: 'function_call',
+  };
+
+  return createMockResponsesStream([
+    {
+      response: {
+        created_at: Math.floor(Date.now() / 1000),
+        id: responseId,
+        model: 'gpt-5-pro',
+        object: 'response',
+        output: [],
+        status: 'in_progress',
+      },
+      type: 'response.created',
+    },
+    {
+      item: {
+        content: [],
+        id: msgItemId,
+        role: 'assistant',
+        status: 'in_progress',
+        type: 'message',
+      },
+      output_index: 0,
+      type: 'response.output_item.added',
+    },
+    {
+      content_index: 0,
+      delta: 'I will delegate this to the target agent.',
+      item_id: msgItemId,
+      output_index: 0,
+      type: 'response.output_text.delta',
+    },
+    { item: fnCall, output_index: 1, type: 'response.output_item.added' },
+    {
+      response: {
+        created_at: Math.floor(Date.now() / 1000),
+        id: responseId,
+        model: 'gpt-5-pro',
+        object: 'response',
+        output: [
+          {
+            content: [{ text: 'I will delegate this to the target agent.', type: 'output_text' }],
+            id: msgItemId,
+            role: 'assistant',
+            status: 'completed',
+            type: 'message',
+          },
+          fnCall,
+        ],
+        status: 'completed',
+        usage: { input_tokens: 30, output_tokens: 20, total_tokens: 50 },
+      },
+      type: 'response.completed',
+    },
+  ]);
+};
+
+const createFinalTextResponse = (content: string) => {
+  const responseId = `resp_final_${Date.now()}_${content.length}`;
+  const msgItemId = `msg_final_${Date.now()}_${content.length}`;
+
+  return createMockResponsesStream([
+    {
+      response: {
+        created_at: Math.floor(Date.now() / 1000),
+        id: responseId,
+        model: 'gpt-5-pro',
+        object: 'response',
+        output: [],
+        status: 'in_progress',
+      },
+      type: 'response.created',
+    },
+    {
+      content_index: 0,
+      delta: content,
+      item_id: msgItemId,
+      output_index: 0,
+      type: 'response.output_text.delta',
+    },
+    {
+      response: {
+        created_at: Math.floor(Date.now() / 1000),
+        id: responseId,
+        model: 'gpt-5-pro',
+        object: 'response',
+        output: [
+          {
+            content: [{ text: content, type: 'output_text' }],
+            id: msgItemId,
+            role: 'assistant',
+            status: 'completed',
+            type: 'message',
+          },
+        ],
+        status: 'completed',
+        usage: { input_tokens: 40, output_tokens: 20, total_tokens: 60 },
+      },
+      type: 'response.completed',
+    },
+  ]);
+};
+
+beforeEach(async () => {
+  serverDB = await getTestDB();
+  testDB = serverDB;
+  userId = await createTestUser(serverDB);
+
+  const insertedAgents = await serverDB
+    .insert(agents)
+    .values([
+      {
+        chatConfig: {},
+        model: 'gpt-5-pro',
+        plugins: ['lobe-agent-management'],
+        provider: 'openai',
+        systemRole: 'You are a supervisor that delegates work to other agents.',
+        title: 'callAgent Supervisor',
+        userId,
+      },
+      {
+        chatConfig: {},
+        model: 'gpt-5-pro',
+        plugins: [],
+        provider: 'openai',
+        systemRole: 'You are the target agent. Return a concise result.',
+        title: 'callAgent Target',
+        userId,
+      },
+    ])
+    .returning();
+
+  parentAgentId = insertedAgents[0].id;
+  targetAgentId = insertedAgents[1].id;
+
+  // `create` is overloaded (streaming / non-streaming); its precise spy type
+  // isn't assignable to the generic MockInstance fallback, so widen via unknown.
+  mockResponsesCreate = vi.spyOn(
+    OpenAI.Responses.prototype,
+    'create',
+  ) as unknown as typeof mockResponsesCreate;
+});
+
+afterEach(async () => {
+  await cleanupTestUser(serverDB, userId);
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+  inMemoryAgentStateManager.clear();
+  inMemoryStreamEventManager.clear();
+});
+
+describe('Server callAgent deferred execution', () => {
+  it('parks the parent, runs the target agent, backfills the tool message and resumes', async () => {
+    let callCount = 0;
+    mockResponsesCreate.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) return Promise.resolve(createCallAgentResponse() as any);
+      if (callCount === 2) return Promise.resolve(createFinalTextResponse(TARGET_ANSWER) as any);
+      return Promise.resolve(createFinalTextResponse(PARENT_FINAL) as any);
+    });
+
+    const caller = aiAgentRouter.createCaller(createTestContext());
+
+    const createResult = await caller.execAgent({
+      agentId: parentAgentId,
+      prompt: 'Delegate this work to the target agent and report back.',
+      userInterventionConfig: { approvalMode: 'headless' },
+    });
+    expect(createResult.success).toBe(true);
+
+    const finalState = await waitForOperationComplete(
+      inMemoryAgentStateManager,
+      createResult.operationId,
+      { maxWaitTime: 20_000 },
+    );
+
+    expect(finalState.status).toBe('done');
+    expect(finalState.pendingToolsCalling ?? []).toHaveLength(0);
+    expect(mockResponsesCreate).toHaveBeenCalledTimes(3);
+
+    const childOps = await serverDB
+      .select()
+      .from(agentOperations)
+      .where(eq(agentOperations.parentOperationId, createResult.operationId));
+    expect(childOps).toHaveLength(1);
+    expect(childOps[0]).toMatchObject({
+      agentId: targetAgentId,
+      status: 'done',
+    });
+
+    const toolMessages = await serverDB
+      .select({
+        content: messages.content,
+        role: messages.role,
+        state: messagePlugins.state,
+        identifier: messagePlugins.identifier,
+        apiName: messagePlugins.apiName,
+        toolCallId: messagePlugins.toolCallId,
+      })
+      .from(messages)
+      .innerJoin(messagePlugins, eq(messagePlugins.id, messages.id))
+      .where(
+        and(
+          eq(messages.userId, userId),
+          eq(messagePlugins.identifier, 'lobe-agent-management'),
+          eq(messagePlugins.apiName, 'callAgent'),
+        ),
+      );
+
+    expect(toolMessages).toHaveLength(1);
+    expect(toolMessages[0]).toMatchObject({
+      apiName: 'callAgent',
+      content: TARGET_ANSWER,
+      identifier: 'lobe-agent-management',
+      role: 'tool',
+      toolCallId: 'call_agent_1',
+    });
+    expect(toolMessages[0].state).toMatchObject({
+      status: 'completed',
+      threadId: childOps[0].threadId,
+    });
+  }, 30_000);
+});
@@ -348,6 +348,72 @@ describe('Task Router Integration', () => {
    });
  });

+  describe('verify config', () => {
+    it('should set and retrieve verify config (round-trip)', async () => {
+      const task = await caller.create({ instruction: 'Test' });
+
+      await caller.updateVerifyConfig({
+        id: task.data.id,
+        verify: {
+          enabled: true,
+          maxIterations: 3,
+          verifierAgentId: 'agt_codex',
+          verifyCriteriaIds: ['c1', 'c2'],
+          verifyRubricId: 'rub_1',
+        },
+      });
+
+      const verify = await caller.getVerifyConfig({ id: task.data.id });
+      expect(verify.data).toEqual({
+        enabled: true,
+        maxIterations: 3,
+        verifierAgentId: 'agt_codex',
+        verifyCriteriaIds: ['c1', 'c2'],
+        verifyRubricId: 'rub_1',
+      });
+
+      // task.detail must surface the saved verify config (not leave it undefined).
+      const detail = await caller.detail({ id: task.data.id });
+      expect(detail.data!.verify).toEqual({
+        enabled: true,
+        maxIterations: 3,
+        verifierAgentId: 'agt_codex',
+        verifyCriteriaIds: ['c1', 'c2'],
+        verifyRubricId: 'rub_1',
+      });
+    });
+
+    it('should clear a saved field when passed null', async () => {
+      const task = await caller.create({ instruction: 'Test' });
+
+      await caller.updateVerifyConfig({
+        id: task.data.id,
+        verify: { enabled: true, verifierAgentId: 'agt_codex', verifyRubricId: 'rub_1' },
+      });
+
+      // Switch the verifier back to default + drop the rubric.
+      await caller.updateVerifyConfig({
+        id: task.data.id,
+        verify: { verifierAgentId: null, verifyRubricId: null },
+      });
+
+      const verify = await caller.getVerifyConfig({ id: task.data.id });
+      expect(verify.data).toEqual({ enabled: true });
+    });
+
+    it('getVerifyConfig falls back to the legacy review key', async () => {
+      const task = await caller.create({ instruction: 'Test' });
+
+      await caller.updateReview({
+        id: task.data.id,
+        review: { autoRetry: true, enabled: true, maxIterations: 4, rubrics: [] },
+      });
+
+      const verify = await caller.getVerifyConfig({ id: task.data.id });
+      expect(verify.data).toEqual({ enabled: true, maxIterations: 4 });
+    });
+  });
+
  describe('run idempotency', () => {
    it('should reject run when a topic is already running', async () => {
      const task = await caller.create({
@@ -12,6 +12,7 @@ const mockFindById = vi.fn();

 const mockCountTopicsForMemoryExtractor = vi.fn();
 const mockDeleteAll = vi.fn();
+const mockDeletePersona = vi.fn();
 const { mockTriggerProcessUsers } = vi.hoisted(() => ({
  mockTriggerProcessUsers: vi.fn(),
 }));
@@ -43,6 +44,12 @@ vi.mock('@/database/models/userMemory', () => ({
  UserMemoryPreferenceModel: vi.fn(() => ({})),
 }));

+vi.mock('@/database/models/userMemory/persona', () => ({
+  UserPersonaModel: vi.fn(() => ({
+    deletePersona: mockDeletePersona,
+  })),
+}));
+
 vi.mock('@/envs/app', () => ({
  appEnv: {
    APP_URL: 'https://example.com',
@@ -301,11 +308,13 @@ describe('userMemoryRouter.deleteAll', () => {

  it('purges all user memories through the aggregate model', async () => {
    mockDeleteAll.mockResolvedValue(undefined);
+    mockDeletePersona.mockResolvedValue(undefined);

    const caller = createCaller();
    const result = await caller.deleteAll();

    expect(mockDeleteAll).toHaveBeenCalledOnce();
+    expect(mockDeletePersona).toHaveBeenCalledOnce();
    expect(result).toEqual({ success: true });
  });
 });
@@ -0,0 +1,252 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { verifyRouter } from '@/server/routers/lambda/verify';
+import { FileService } from '@/server/services/file';
+
+const modelMocks = vi.hoisted(() => ({
+  findRunById: vi.fn(),
+  findResultById: vi.fn(),
+  getFullFileUrl: vi.fn(),
+  getServerDB: vi.fn(async () => ({})),
+  upsertByCheckItem: vi.fn(),
+}));
+
+vi.mock('@/database/core/db-adaptor', () => ({
+  getServerDB: modelMocks.getServerDB,
+}));
+
+vi.mock('@/database/models/verifyCheckResult', () => ({
+  VerifyCheckResultModel: vi.fn(() => ({
+    findById: modelMocks.findResultById,
+    upsertByCheckItem: modelMocks.upsertByCheckItem,
+  })),
+}));
+
+vi.mock('@/database/models/verifyRun', () => ({
+  VerifyRunModel: vi.fn(() => ({
+    findById: modelMocks.findRunById,
+  })),
+}));
+
+vi.mock('@/server/services/verify', () => ({
+  VerifyExecutorService: class VerifyExecutorService {},
+  VerifyFeedbackService: class VerifyFeedbackService {},
+  VerifyPlanGeneratorService: class VerifyPlanGeneratorService {},
+}));
+
+vi.mock('@/server/services/file', () => ({
+  FileService: vi.fn(() => ({
+    getFullFileUrl: modelMocks.getFullFileUrl,
+  })),
+}));
+
+const createCaller = () => verifyRouter.createCaller({ userId: 'verify-router-test-user' } as any);
+const createPublicCaller = () => verifyRouter.createCaller({} as any);
+
+const selectRows = <T>(rows: T[]) => ({
+  from: vi.fn(() => ({
+    where: vi.fn(() => ({
+      orderBy: vi.fn(async () => rows),
+    })),
+  })),
+});
+
+describe('verifyRouter', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    modelMocks.getServerDB.mockResolvedValue({});
+    vi.mocked(FileService).mockImplementation(
+      () =>
+        ({
+          getFullFileUrl: modelMocks.getFullFileUrl,
+        }) as any,
+    );
+  });
+
+  describe('ingestResult', () => {
+    it("rejects a run outside the caller's scope before upserting the result", async () => {
+      modelMocks.findRunById.mockResolvedValueOnce(undefined);
+
+      await expect(
+        createCaller().ingestResult({
+          checkItemId: 'shared-check',
+          checkItemTitle: 'attacker update',
+          status: 'passed',
+          verdict: 'passed',
+          verifyRunId: 'other-user-run',
+        }),
+      ).rejects.toThrow('Verification run not found');
+
+      expect(modelMocks.findRunById).toHaveBeenCalledWith('other-user-run');
+      expect(modelMocks.upsertByCheckItem).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('uploadEvidence', () => {
+    it('rejects evidence with both inline content and fileId', async () => {
+      await expect(
+        createCaller().uploadEvidence({
+          checkResultId: 'result-1',
+          content: 'inline payload',
+          fileId: 'files-1',
+          type: 'text',
+        }),
+      ).rejects.toThrow('Provide exactly one of `content` or `fileId`.');
+    });
+
+    it('rejects evidence without inline content or fileId', async () => {
+      await expect(
+        createCaller().uploadEvidence({
+          checkResultId: 'result-1',
+          type: 'text',
+        }),
+      ).rejects.toThrow('Provide exactly one of `content` or `fileId`.');
+    });
+  });
+
+  describe('getReportBundle', () => {
+    it('reads a standalone report without a logged-in user', async () => {
+      const run = {
+        goal: 'Ship a working page',
+        id: 'run-1',
+        title: 'Run report',
+        userId: 'owner-user',
+        workspaceId: null,
+      };
+      const report = {
+        id: 'report-1',
+        totalChecks: 1,
+        verdict: 'passed',
+        verifyRunId: 'run-1',
+      };
+      const result = {
+        checkItemId: 'check-1',
+        checkItemIndex: 0,
+        checkItemTitle: 'Page renders',
+        id: 'result-1',
+        required: true,
+        status: 'passed',
+        verdict: 'passed',
+        verifyRunId: 'run-1',
+      };
+      const evidence = {
+        checkResultId: 'result-1',
+        content: null,
+        description: 'Homepage screenshot',
+        fileId: 'file-1',
+        id: 'evidence-1',
+        type: 'screenshot',
+      };
+      const serverDB = {
+        query: {
+          files: {
+            findFirst: vi.fn(async () => ({ id: 'file-1', url: 'verify/evidence.png' })),
+          },
+          verifyReports: {
+            findFirst: vi.fn(async () => report),
+          },
+          verifyRuns: {
+            findFirst: vi.fn(async () => run),
+          },
+        },
+        select: vi
+          .fn()
+          .mockReturnValueOnce(selectRows([result]))
+          .mockReturnValueOnce(selectRows([evidence])),
+      };
+      modelMocks.getServerDB.mockResolvedValue(serverDB);
+      modelMocks.getFullFileUrl.mockResolvedValue('https://cdn.example.com/verify/evidence.png');
+
+      const bundle = await createPublicCaller().getReportBundle({ verifyRunId: 'run-1' });
+
+      expect(bundle).toMatchObject({
+        report,
+        results: [
+          {
+            checkItemId: 'check-1',
+            evidence: [
+              {
+                fileId: 'file-1',
+                fileUrl: 'https://cdn.example.com/verify/evidence.png',
+              },
+            ],
+          },
+        ],
+        run,
+      });
+      expect(modelMocks.findRunById).not.toHaveBeenCalled();
+    });
+
+    it('keeps returning the bundle when file URL resolution is unavailable', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      vi.mocked(FileService).mockImplementation(() => {
+        throw new Error('S3 env missing');
+      });
+
+      const run = {
+        goal: 'Ship a working page',
+        id: 'run-1',
+        title: 'Run report',
+        userId: 'owner-user',
+        workspaceId: null,
+      };
+      const result = {
+        checkItemId: 'check-1',
+        checkItemIndex: 0,
+        checkItemTitle: 'Page renders',
+        id: 'result-1',
+        required: true,
+        status: 'passed',
+        verdict: 'passed',
+        verifyRunId: 'run-1',
+      };
+      const evidence = {
+        checkResultId: 'result-1',
+        content: null,
+        description: 'Homepage screenshot',
+        fileId: 'file-1',
+        id: 'evidence-1',
+        type: 'screenshot',
+      };
+      const serverDB = {
+        query: {
+          files: {
+            findFirst: vi.fn(async () => ({ id: 'file-1', url: 'verify/evidence.png' })),
+          },
+          verifyReports: {
+            findFirst: vi.fn(async () => null),
+          },
+          verifyRuns: {
+            findFirst: vi.fn(async () => run),
+          },
+        },
+        select: vi
+          .fn()
+          .mockReturnValueOnce(selectRows([result]))
+          .mockReturnValueOnce(selectRows([evidence])),
+      };
+      modelMocks.getServerDB.mockResolvedValue(serverDB);
+
+      const bundle = await createPublicCaller().getReportBundle({ verifyRunId: 'run-1' });
+
+      expect(bundle).toMatchObject({
+        results: [
+          {
+            evidence: [
+              {
+                fileId: 'file-1',
+                fileUrl: null,
+              },
+            ],
+          },
+        ],
+        run,
+      });
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[verify:getReportBundle:resolveFileUrl]',
+        expect.any(Error),
+      );
+      consoleErrorSpy.mockRestore();
+    });
+  });
+});
@@ -41,6 +41,7 @@ export const updateDocumentInputSchema = z.object({
  editorData: z.string().optional(),
  fileType: z.string().optional(),
  id: z.string(),
+  lockOwnerId: z.string().optional(),
  metadata: z.record(z.any()).optional(),
  parentId: z.string().nullable().optional(),
  restoreFromHistoryId: z.string().optional(),
@@ -51,6 +52,7 @@ export const updateDocumentInputSchema = z.object({
 export const saveDocumentHistoryInputSchema = z.object({
  documentId: z.string(),
  editorData: z.string(),
+  lockOwnerId: z.string().optional(),
  saveSource: documentHistorySaveSourceSchema,
 });

@@ -98,6 +100,8 @@ export interface UpdateDocumentOutput {
 export interface SaveDocumentHistoryInput {
  documentId: string;
  editorData: string;
+  /** Edit-session id proving the client still holds the workspace page lease. */
+  lockOwnerId?: string;
  saveSource: DocumentHistorySaveSource;
 }

@@ -130,6 +134,7 @@ export interface UpdateDocumentInput {
  editorData?: string;
  fileType?: string;
  id: string;
+  lockOwnerId?: string;
  metadata?: Record<string, any>;
  parentId?: string | null;
  restoreFromHistoryId?: string;
@@ -8,6 +8,7 @@ import { z } from 'zod';

 import { withScopedPermission } from '@/business/server/trpc-middlewares/rbacPermission';
 import { wsCompatProcedure } from '@/business/server/trpc-middlewares/workspaceAuth';
+import { TopicTrigger } from '@/const/topic';
 import { AgentDocumentModel } from '@/database/models/agentDocuments';
 import { TopicModel } from '@/database/models/topic';
 import { TopicDocumentModel } from '@/database/models/topicDocument';
@@ -254,6 +255,56 @@ export const agentDocumentRouter = router({
      return ctx.agentDocumentService.getDocument(input.agentId, input.filename);
    }),

+  /**
+   * Return the chat topic that anchors the doc-scoped conversation for this
+   * `(documentId, agentId)` pair, creating it idempotently on the first call.
+   *
+   * Topics are marked with `trigger='document'` so they stay out of the main
+   * sidebar history (`MAIN_SIDEBAR_EXCLUDE_TRIGGERS` already excludes them).
+   * The mapping is persisted through `topic_documents`, so subsequent calls
+   * resolve the same topic id.
+   */
+  getOrCreateChatTopic: agentDocumentProcedure
+    .input(
+      z.object({
+        agentId: z.string(),
+        documentId: z.string(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const existing = await ctx.topicModel.findByAgentAndDocumentTrigger({
+        agentId: input.agentId,
+        documentId: input.documentId,
+        trigger: TopicTrigger.Document,
+      });
+      if (existing) return { topicId: existing.id };
+
+      const document = await ctx.agentDocumentService.findRowByDocumentId(
+        input.agentId,
+        input.documentId,
+      );
+      if (!document) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: `Document not found for agentId=${input.agentId}`,
+        });
+      }
+
+      const title = document.title || document.filename || 'Document chat';
+      const topic = await ctx.topicModel.create({
+        agentId: input.agentId,
+        title,
+        trigger: TopicTrigger.Document,
+      });
+
+      await ctx.topicDocumentModel.associate({
+        documentId: input.documentId,
+        topicId: topic.id,
+      });
+
+      return { topicId: topic.id };
+    }),
+
  /**
   * Create or update a document
   */
@@ -372,12 +423,16 @@ export const agentDocumentRouter = router({
    .input(
      z.object({
        agentId: z.string(),
+        // Reveal the auto-created `.tool-results` archive. Off by default so
+        // user-facing lists stay clean; the agent document-listing tool opts in.
+        includeArchivedToolResults: z.boolean().optional().default(false),
        scope: z.enum(['agent', 'currentTopic']).optional().default('agent'),
        sourceType: z.enum(['all', 'file', 'web']).optional().default('all'),
        topicId: z.string().optional(),
      }),
    )
    .query(async ({ ctx, input }) => {
+      const { includeArchivedToolResults } = input;
      if (input.scope === 'currentTopic') {
        if (!input.topicId) throw new Error('topicId is required to list current topic documents');

@@ -385,10 +440,13 @@ export const agentDocumentRouter = router({
          input.agentId,
          input.topicId,
          input.sourceType,
+          { includeArchivedToolResults },
        );
      }

-      return ctx.agentDocumentService.listDocuments(input.agentId, input.sourceType);
+      return ctx.agentDocumentService.listDocuments(input.agentId, input.sourceType, {
+        includeArchivedToolResults,
+      });
    }),

  /**
@@ -139,6 +139,8 @@ const ExecAgentSchema = z
      .object({
        defaultTaskAssigneeAgentId: z.string().optional(),
        documentId: z.string().optional().nullable(),
+        /** The agent being edited when scope is 'agent_builder' (not the builder builtin itself). */
+        editingAgentId: z.string().optional(),
        groupId: z.string().optional().nullable(),
        initialTopicMetadata: z
          .object({
@@ -1,3 +1,4 @@
+import { TRPCError } from '@trpc/server';
 import { type AiProviderModelListItem } from 'model-bank';
 import {
  AiModelTypeSchema,
@@ -18,6 +19,30 @@ import { getServerGlobalConfig } from '@/server/globalConfig';
 import { KeyVaultsGateKeeper } from '@/server/modules/KeyVaultsEncrypt';
 import { type ProviderConfig } from '@/types/user/settings';

+const AI_MODEL_UNIQUE_CONSTRAINT = 'ai_models_id_provider_id_user_id_pk';
+
+const getPostgresErrorField = (error: unknown, field: 'code' | 'constraint') => {
+  let current = error;
+
+  while (current && typeof current === 'object') {
+    const value = (current as Record<string, unknown>)[field];
+    if (typeof value === 'string') return value;
+
+    current = (current as { cause?: unknown }).cause;
+  }
+};
+
+const isDuplicateAiModelError = (error: unknown) =>
+  getPostgresErrorField(error, 'code') === '23505' &&
+  getPostgresErrorField(error, 'constraint') === AI_MODEL_UNIQUE_CONSTRAINT;
+
+const throwDuplicateAiModelError = (id: string): never => {
+  throw new TRPCError({
+    code: 'CONFLICT',
+    message: `Model "${id}" already exists`,
+  });
+};
+
 const aiModelProcedure = wsCompatProcedure.use(serverDatabase).use(async (opts) => {
  const { ctx } = opts;
  const wsId = ctx.workspaceId ?? undefined;
@@ -82,9 +107,18 @@ export const aiModelRouter = router({
    .use(withScopedPermission('ai_model:create'))
    .input(CreateAiModelSchema)
    .mutation(async ({ input, ctx }) => {
-      const data = await ctx.aiModelModel.create(input);
+      const existingModel = await ctx.aiModelModel.findByIdAndProvider(input.id, input.providerId);
+      if (existingModel) throwDuplicateAiModelError(input.id);

-      return data?.id;
+      try {
+        const data = await ctx.aiModelModel.create(input);
+
+        return data?.id;
+      } catch (error) {
+        if (isDuplicateAiModelError(error)) throwDuplicateAiModelError(input.id);
+
+        throw error;
+      }
    }),

  getAiModelById: aiModelProcedure
@@ -0,0 +1,161 @@
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+
+import { wsCompatProcedure } from '@/business/server/trpc-middlewares/workspaceAuth';
+import { FileModel } from '@/database/models/file';
+import type { LobeChatDatabase } from '@/database/type';
+import { router } from '@/libs/trpc/lambda';
+import { serverDatabase } from '@/libs/trpc/lambda/middleware';
+import { initModelRuntimeFromDB } from '@/server/modules/ModelRuntime';
+import { FileService } from '@/server/services/file';
+
+const asrProcedure = wsCompatProcedure.use(serverDatabase);
+
+// Inline base64 is only for short clips. The whole request must fit inside the
+// platform body limit (≈4.5MB on serverless deploys) and base64 inflates bytes
+// by ~4/3, so cap the decoded audio well under that — anything larger should be
+// uploaded and passed as `fileId`.
+const MAX_INLINE_AUDIO_BYTES = 3 * 1024 * 1024;
+// base64 length ≈ ceil(bytes / 3) * 4; validating the string length lets us
+// reject oversized payloads before allocating/decoding them.
+const MAX_INLINE_AUDIO_BASE64_CHARS = Math.ceil(MAX_INLINE_AUDIO_BYTES / 3) * 4;
+
+interface ResolvedAudio {
+  bytes: Uint8Array;
+  fileName: string;
+  mimeType?: string;
+}
+
+export const asrRouter = router({
+  /**
+   * Automatic Speech Recognition (speech-to-text).
+   *
+   * Accepts the audio either as an already-uploaded `fileId` (preferred — the
+   * server streams the bytes from storage, nothing large travels over tRPC) or
+   * inline as base64 for short clips (capped at `MAX_INLINE_AUDIO_BYTES`;
+   * larger payloads are rejected with guidance to upload and pass `fileId`).
+   *
+   * Note on base64: tRPC here uses an `httpLink` + superjson (JSON only), which
+   * has no binary representation for a `Buffer`/`Uint8Array` — a raw buffer would
+   * serialize to a per-byte JSON object, far worse than base64. So inline bytes
+   * stay base64; use `fileId` to avoid inlining entirely.
+   *
+   * Transcription is a single request/response (not streamed), so a mutation is
+   * the right shape.
+   */
+  transcribe: asrProcedure
+    .input(
+      z
+        .object({
+          /** Base64-encoded audio bytes (short clips only). Mutually exclusive with `fileId`. */
+          audioBase64: z
+            .string()
+            .min(1)
+            .max(MAX_INLINE_AUDIO_BASE64_CHARS, {
+              message: `Inline audio is limited to ${MAX_INLINE_AUDIO_BYTES / 1024 / 1024}MB. Upload the file and pass \`fileId\` instead.`,
+            })
+            .optional(),
+          /** Already-uploaded audio file id. Mutually exclusive with `audioBase64`. */
+          fileId: z.string().min(1).optional(),
+          /** Original file name (base64 path); its extension helps format detection. */
+          fileName: z.string().optional(),
+          /** ISO-639-1 language code (e.g. `en`, `zh`). */
+          language: z.string().optional(),
+          /** Audio mime type (base64 path, e.g. `audio/mp4`). */
+          mimeType: z.string().optional(),
+          model: z.string().min(1),
+          /** Optional text to guide the model's style. */
+          prompt: z.string().optional(),
+          provider: z.string().default('openai'),
+          responseFormat: z.enum(['json', 'srt', 'text', 'verbose_json', 'vtt']).optional(),
+        })
+        .refine((d) => Boolean(d.fileId) !== Boolean(d.audioBase64), {
+          message: 'Provide exactly one of `fileId` or `audioBase64`.',
+        }),
+    )
+    .mutation(async ({ ctx, input }): Promise<{ text: string }> => {
+      const workspaceId = ctx.workspaceId ?? undefined;
+
+      const { bytes, fileName, mimeType } = await resolveAudio(ctx, input, workspaceId);
+
+      // Resolve the user's provider config (key + baseURL) from the database,
+      // falling back to server env keys, exactly like chat/embeddings do.
+      const runtime = await initModelRuntimeFromDB(
+        ctx.serverDB,
+        ctx.userId,
+        input.provider,
+        workspaceId,
+      );
+
+      // `Uint8Array` is a valid BlobPart at runtime; the cast sidesteps the
+      // `Uint8Array<ArrayBufferLike>` vs BlobPart generic mismatch in lib.dom.
+      const file = new File([bytes as BlobPart], fileName, {
+        type: mimeType || 'application/octet-stream',
+      });
+
+      const result = await runtime.transcribe(
+        {
+          file,
+          fileName,
+          language: input.language,
+          model: input.model,
+          prompt: input.prompt,
+          responseFormat: input.responseFormat,
+        },
+        { user: ctx.userId },
+      );
+
+      if (!result) {
+        throw new TRPCError({
+          code: 'NOT_IMPLEMENTED',
+          message: `Provider "${input.provider}" does not support ASR.`,
+        });
+      }
+
+      return result;
+    }),
+});
+
+/**
+ * Turn the request into raw audio bytes + metadata, from either a stored file
+ * (downloaded from S3, ownership enforced by the userId-scoped FileModel) or the
+ * inline base64 payload.
+ */
+async function resolveAudio(
+  ctx: { serverDB: LobeChatDatabase; userId: string },
+  input: { audioBase64?: string; fileId?: string; fileName?: string; mimeType?: string },
+  workspaceId?: string,
+): Promise<ResolvedAudio> {
+  if (input.fileId) {
+    const fileModel = new FileModel(ctx.serverDB, ctx.userId, workspaceId);
+    const fileItem = await fileModel.findById(input.fileId);
+
+    if (!fileItem) {
+      throw new TRPCError({ code: 'NOT_FOUND', message: `File "${input.fileId}" not found.` });
+    }
+
+    const fileService = new FileService(ctx.serverDB, ctx.userId, workspaceId);
+    let bytes: Uint8Array;
+    try {
+      bytes = await fileService.getFileByteArray(fileItem.url);
+    } catch (error) {
+      if ((error as { Code?: string }).Code === 'NoSuchKey') {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: `File "${input.fileId}" is no longer available in storage.`,
+        });
+      }
+      throw error;
+    }
+
+    return { bytes, fileName: fileItem.name, mimeType: fileItem.fileType };
+  }
+
+  return {
+    bytes: new Uint8Array(Buffer.from(input.audioBase64!, 'base64')),
+    fileName: input.fileName || 'audio',
+    mimeType: input.mimeType,
+  };
+}
+
+export type AsrRouter = typeof asrRouter;
@@ -0,0 +1,256 @@
+import { type ToolManifest } from '@lobechat/types';
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+
+import { getServerComposioAuthConfigId } from '@/config/composio';
+import { PluginModel } from '@/database/models/plugin';
+import { getComposioClient } from '@/libs/composio';
+import { authedProcedure, router } from '@/libs/trpc/lambda';
+import { serverDatabase } from '@/libs/trpc/lambda/middleware';
+
+const composioProcedure = authedProcedure.use(serverDatabase).use(async (opts) => {
+  const client = getComposioClient();
+  const pluginModel = new PluginModel(opts.ctx.serverDB, opts.ctx.userId);
+
+  return opts.next({
+    ctx: { ...opts.ctx, composioClient: client, pluginModel },
+  });
+});
+
+export const composioRouter = router({
+  createConnection: composioProcedure
+    .input(
+      z.object({
+        appSlug: z.string(),
+        identifier: z.string(),
+        label: z.string(),
+      }),
+    )
+    .mutation(async ({ input, ctx }) => {
+      const { appSlug, identifier, label } = input;
+      const { userId } = ctx;
+
+      const callbackUrl = `${process.env.APP_URL || process.env.NEXTAUTH_URL || ''}/api/composio/oauth/callback`;
+
+      // Prefer a pre-configured auth config (e.g. a custom/white-label config
+      // created in the Composio dashboard), pinned per toolkit via env. Falls
+      // back to discovering an existing config for this toolkit, and finally to
+      // auto-creating a Composio-managed one.
+      let authConfigId = getServerComposioAuthConfigId(identifier);
+      if (!authConfigId) {
+        const authConfigs = await (ctx.composioClient.authConfigs as any).list();
+        let authConfig = authConfigs?.items?.find(
+          (c: any) => c.toolkit?.slug?.toLowerCase() === appSlug.toLowerCase(),
+        );
+        if (!authConfig) {
+          authConfig = await (ctx.composioClient.authConfigs as any).create(appSlug, {
+            name: appSlug,
+            type: 'use_composio_managed_auth',
+          });
+        }
+        authConfigId = authConfig.id;
+      }
+
+      if (!authConfigId) {
+        throw new TRPCError({
+          code: 'INTERNAL_SERVER_ERROR',
+          message: `Failed to resolve a Composio auth config for "${appSlug}".`,
+        });
+      }
+
+      // Composio-managed OAuth auth configs no longer support `initiate`; use
+      // `link` (POST /api/v3/connected_accounts/link) to get the redirect URL.
+      const connReq = await (ctx.composioClient.connectedAccounts as any).link(
+        userId,
+        authConfigId,
+        { callbackUrl },
+      );
+
+      let rawTools: any[] = [];
+      try {
+        const toolsResp = await (ctx.composioClient.tools as any).getRawComposioTools({
+          toolkits: [appSlug],
+        });
+        rawTools = toolsResp?.items || toolsResp || [];
+      } catch {
+        // tools may not be available before auth
+      }
+
+      const manifest: ToolManifest = {
+        api: Array.isArray(rawTools)
+          ? rawTools.map((tool: any) => ({
+              description: tool.description || '',
+              name: tool.slug || tool.name || '',
+              parameters: tool.inputParameters ||
+                tool.inputSchema || {
+                  properties: {},
+                  type: 'object',
+                },
+            }))
+          : [],
+        identifier,
+        meta: {
+          avatar: '🔌',
+          description: `Composio: ${label}`,
+          title: label,
+        },
+        type: 'default',
+      };
+
+      await ctx.pluginModel.create({
+        customParams: {
+          composio: {
+            appSlug,
+            authConfigId,
+            connectedAccountId: connReq.id,
+            redirectUrl: connReq.redirectUrl,
+            status: 'PENDING',
+          },
+        },
+        identifier,
+        manifest,
+        source: 'composio',
+        type: 'plugin',
+      });
+
+      return {
+        authConfigId,
+        connectedAccountId: connReq.id,
+        identifier,
+        redirectUrl: connReq.redirectUrl,
+      };
+    }),
+
+  deleteConnection: composioProcedure
+    .input(
+      z.object({
+        connectedAccountId: z.string(),
+        identifier: z.string(),
+      }),
+    )
+    .mutation(async ({ input, ctx }) => {
+      try {
+        await (ctx.composioClient.connectedAccounts as any).delete(input.connectedAccountId);
+      } catch (error) {
+        console.warn('[Composio] Failed to delete remote connection:', error);
+      }
+
+      await ctx.pluginModel.delete(input.identifier);
+
+      return { success: true };
+    }),
+
+  getComposioPlugins: composioProcedure.query(async ({ ctx }) => {
+    const allPlugins = await ctx.pluginModel.query();
+    return allPlugins.filter((plugin) => plugin.customParams?.composio);
+  }),
+
+  getConnection: composioProcedure
+    .input(
+      z.object({
+        connectedAccountId: z.string(),
+      }),
+    )
+    .query(async ({ input, ctx }) => {
+      try {
+        const account = await (ctx.composioClient.connectedAccounts as any).get(
+          input.connectedAccountId,
+        );
+        return {
+          appSlug: account?.toolkit?.slug || '',
+          connectedAccountId: input.connectedAccountId,
+          error: undefined as 'AUTH_ERROR' | undefined,
+          status: (account?.status || 'PENDING') as string,
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const isAuthError = errorMessage.includes('401') || errorMessage.includes('Unauthorized');
+
+        if (isAuthError) {
+          return {
+            appSlug: '',
+            connectedAccountId: input.connectedAccountId,
+            error: 'AUTH_ERROR' as const,
+            status: 'FAILED',
+          };
+        }
+        throw error;
+      }
+    }),
+
+  removeComposioPlugin: composioProcedure
+    .input(z.object({ identifier: z.string() }))
+    .mutation(async ({ input, ctx }) => {
+      await ctx.pluginModel.delete(input.identifier);
+      return { success: true };
+    }),
+
+  updateComposioPlugin: composioProcedure
+    .input(
+      z.object({
+        appSlug: z.string(),
+        authConfigId: z.string(),
+        connectedAccountId: z.string(),
+        identifier: z.string(),
+        label: z.string(),
+        redirectUrl: z.string().optional(),
+        status: z.string(),
+        tools: z.array(
+          z.object({
+            description: z.string().optional(),
+            inputSchema: z.any().optional(),
+            name: z.string(),
+          }),
+        ),
+      }),
+    )
+    .mutation(async ({ input, ctx }) => {
+      const {
+        identifier,
+        label,
+        appSlug,
+        authConfigId,
+        connectedAccountId,
+        tools,
+        status,
+        redirectUrl,
+      } = input;
+
+      const existingPlugin = await ctx.pluginModel.findById(identifier);
+
+      const manifest: ToolManifest = {
+        api: tools.map((tool) => ({
+          description: tool.description || '',
+          name: tool.name,
+          parameters: tool.inputSchema || { properties: {}, type: 'object' },
+        })),
+        identifier,
+        meta: existingPlugin?.manifest?.meta || {
+          avatar: '🔌',
+          description: `Composio: ${label}`,
+          title: label,
+        },
+        type: 'default',
+      };
+
+      const customParams = {
+        composio: { appSlug, authConfigId, connectedAccountId, redirectUrl, status },
+      };
+
+      if (existingPlugin) {
+        await ctx.pluginModel.update(identifier, { customParams, manifest });
+      } else {
+        await ctx.pluginModel.create({
+          customParams,
+          identifier,
+          manifest,
+          source: 'composio',
+          type: 'plugin',
+        });
+      }
+
+      return { savedCount: tools.length };
+    }),
+});
+
+export type ComposioRouter = typeof composioRouter;
@@ -115,6 +115,33 @@ export const connectorRouter = router({
    return toolsByConnector;
  }),

+  /**
+   * Return the connector record with decrypted user-set credentials so the
+   * edit form can pre-fill accurately. Only the connector owner can call this
+   * (enforced by connectorProcedure ownership check).
+   *
+   * Machine-managed secrets are intentionally excluded:
+   * - OAuth access/refresh tokens (type 'oauth2') → stripped, returned as null
+   * - oidcConfig.clientSecret (DCR-registered secret)  → stripped
+   * User-set credentials (bearer token, custom headers) are returned as-is so
+   * the edit form can display them.
+   */
+  getForEdit: connectorProcedure
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ input, ctx }) => {
+      const connector = await ctx.connectorModel.findById(input.id);
+      if (!connector)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Connector not found' });
+
+      const { oidcConfig, credentials, ...rest } = connector;
+      const safeOidcConfig = oidcConfig ? { ...oidcConfig, clientSecret: undefined } : oidcConfig;
+      // OAuth tokens are machine-managed — don't return them; the UI only needs
+      // to know an OAuth flow is configured (reflected via oidcConfig presence).
+      const safeCredentials = credentials?.type === 'oauth2' ? null : credentials;
+
+      return { ...rest, credentials: safeCredentials, oidcConfig: safeOidcConfig };
+    }),
+
  /**
   * The exact redirect URI the server will send to the OAuth/DCR endpoints.
   * The Add modal must display THIS value (not a client-derived origin) so the
@@ -268,9 +295,14 @@ export const connectorRouter = router({
      await ctx.connectorModel.update(input.id, {
        ...patch,
        // undefined → leave untouched; null → clear; object → encrypt the JSON string.
+        // When credentials are cleared, also drop the cached expiry timestamp so
+        // token-refresh logic doesn't act on a stale value for the new server.
        ...(credentials === undefined
          ? {}
-          : { credentials: credentials ? JSON.stringify(credentials) : null }),
+          : {
+              credentials: credentials ? JSON.stringify(credentials) : null,
+              ...(credentials === null ? { tokenExpiresAt: null } : {}),
+            }),
      } as any);
    }),

@@ -358,7 +390,7 @@ export const connectorRouter = router({
    }),

  /**
-   * Sync tools from a client-provided list (for Lobehub OAuth skills, Klavis, etc.
+   * Sync tools from a client-provided list (for Lobehub OAuth skills, Composio, etc.
   * that already have their tool list available on the client side).
   * Idempotent — safe to call whenever the detail panel opens.
   */
@@ -1,13 +1,19 @@
 import { REMOTE_HETEROGENEOUS_AGENT_CONFIGS } from '@lobechat/heterogeneous-agents';
-import type { DeviceChannel, DeviceListItem, WorkingDirEntry } from '@lobechat/types';
+import type { DeviceChannel, DeviceListItem, DeviceScope, WorkingDirEntry } from '@lobechat/types';
 import { z } from 'zod';

+import {
+  wsCompatProcedure,
+  wsOwnerProcedure,
+} from '@/business/server/trpc-middlewares/workspaceAuth';
 import { DeviceModel } from '@/database/models/device';
-import { authedProcedure, router } from '@/libs/trpc/lambda';
+import { router } from '@/libs/trpc/lambda';
 import { serverDatabase } from '@/libs/trpc/lambda/middleware';
-import { deviceGateway } from '@/server/services/deviceGateway';
+import { signWorkspaceDeviceToken } from '@/libs/trpc/utils/internalJwt';
+import { type DeviceAttachment, deviceGateway } from '@/server/services/deviceGateway';

 import { preserveWorkspaceCache } from './deviceWorkingDirs';
+import { assertWorkspaceRootApproved } from './deviceWorkspaceGuard';

 // Derive the zod enum from the canonical config so new platforms are
 // automatically covered without touching this file.
@@ -21,14 +27,39 @@ const remotePlatformEnum = z.enum(
 const CAPABILITY_TIMEOUT_MS = 5_000;
 const PROFILE_TIMEOUT_MS = 5_000;

-const deviceProcedure = authedProcedure.use(serverDatabase).use(async (opts) => {
+// Workspace-aware (compat): with an `X-Workspace-Id` header the device list also
+// surfaces the workspace's shared devices; without it, the personal path is
+// unchanged (`ctx.workspaceId === undefined`).
+const deviceProcedure = wsCompatProcedure.use(serverDatabase).use(async (opts) => {
  const { ctx } = opts;
+  const wsId = ctx.workspaceId ?? undefined;

  return opts.next({
-    ctx: { deviceModel: new DeviceModel(ctx.serverDB, ctx.userId), userId: ctx.userId },
+    ctx: {
+      deviceModel: new DeviceModel(ctx.serverDB, ctx.userId, wsId),
+      userId: ctx.userId,
+      workspaceId: wsId,
+    },
  });
 });

+const workspaceFileInput = z.object({
+  deviceId: z.string(),
+  workingDirectory: z.string(),
+});
+
+/**
+ * `deviceProcedure` that additionally requires `workingDirectory` to be an
+ * approved workspace root for the device. Builds the guard into the procedure
+ * so every file-mutating route inherits it and can never forget the check —
+ * see {@link assertWorkspaceRootApproved} for why the check is necessary.
+ */
+const workspaceFileProcedure = deviceProcedure.input(workspaceFileInput).use(async (opts) => {
+  const { deviceId, workingDirectory } = workspaceFileInput.parse(await opts.getRawInput());
+  await assertWorkspaceRootApproved(opts.ctx.deviceModel, deviceId, workingDirectory);
+  return opts.next();
+});
+
 export const deviceRouter = router({
  /**
   * Probe whether a specific agent platform (openclaw / hermes) is available
@@ -44,7 +75,7 @@ export const deviceRouter = router({
    )
    .query(async ({ ctx, input }) => {
      const result = await deviceGateway.executeToolCall(
-        { deviceId: input.deviceId, userId: ctx.userId },
+        { deviceId: input.deviceId, userId: ctx.userId, workspaceId: ctx.workspaceId },
        {
          apiName: 'checkPlatformCapability',
          arguments: JSON.stringify({ platform: input.platform }),
@@ -81,6 +112,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -93,6 +125,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -104,6 +137,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -115,10 +149,28 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),

+  /**
+   * List the git worktrees attached to the same repository as a directory on a
+   * remote device, via the device's `listGitWorktrees` RPC. Lets the web/remote
+   * worktree picker mirror the local desktop's, populated over IPC.
+   */
+  listGitWorktrees: deviceProcedure
+    .input(z.object({ deviceId: z.string(), path: z.string() }))
+    .query(async ({ ctx, input }) => {
+      const result = await deviceGateway.listGitWorktrees({
+        deviceId: input.deviceId,
+        path: input.path,
+        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
+      });
+      return result ?? [];
+    }),
+
  /**
   * List the local branches of a directory on a remote device, via the device's
   * `listGitBranches` RPC. Lets the web/remote branch switcher populate the same
@@ -136,6 +188,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? [];
    }),
@@ -160,6 +213,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

@@ -183,6 +237,7 @@ export const deviceRouter = router({
        path: input.path,
        to: input.to,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

@@ -204,6 +259,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

@@ -218,6 +274,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

@@ -232,6 +289,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

@@ -247,6 +305,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -263,6 +322,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -278,6 +338,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? [];
    }),
@@ -294,6 +355,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -310,6 +372,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        scope: input.scope,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -318,24 +381,23 @@ export const deviceRouter = router({
   * Read-only local file preview for a file on a remote device. The web client
   * receives render data, not a `localfile://` URL; saving remains unsupported.
   */
-  getLocalFilePreview: deviceProcedure
+  getLocalFilePreview: workspaceFileProcedure
    .input(
      z.object({
        accept: z.enum(['image']).optional(),
-        deviceId: z.string(),
        path: z.string(),
-        workingDirectory: z.string(),
      }),
    )
-    .query(async ({ ctx, input }) =>
-      deviceGateway.getLocalFilePreview({
+    .query(async ({ ctx, input }) => {
+      return deviceGateway.getLocalFilePreview({
        accept: input.accept,
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
        workingDirectory: input.workingDirectory,
-      }),
-    ),
+      });
+    }),

  /**
   * Project skills (`.agents/skills` / `.claude/skills`) for a directory on a
@@ -349,6 +411,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        scope: input.scope,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -365,9 +428,74 @@ export const deviceRouter = router({
        filePath: input.filePath,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      }),
    ),

+  /**
+   * Move files/folders within a directory on a remote device, via the device's
+   * `moveLocalFiles` RPC. Powers the Files tree's drag-to-move in device mode.
+   */
+  moveProjectFiles: workspaceFileProcedure
+    .input(
+      z.object({
+        items: z.array(z.object({ newPath: z.string(), oldPath: z.string() })),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      return deviceGateway.moveProjectFiles({
+        deviceId: input.deviceId,
+        items: input.items,
+        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
+        workingDirectory: input.workingDirectory,
+      });
+    }),
+
+  /**
+   * Rename a single file/folder in a directory on a remote device, via the
+   * device's `renameLocalFile` RPC.
+   */
+  renameProjectFile: workspaceFileProcedure
+    .input(
+      z.object({
+        newName: z.string(),
+        path: z.string(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      return deviceGateway.renameProjectFile({
+        deviceId: input.deviceId,
+        newName: input.newName,
+        path: input.path,
+        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
+        workingDirectory: input.workingDirectory,
+      });
+    }),
+
+  /**
+   * Save edited content back to a file on a remote device, via the device's
+   * `writeLocalFile` RPC. Powers remote save in the LocalFile editor.
+   */
+  writeProjectFile: workspaceFileProcedure
+    .input(
+      z.object({
+        content: z.string(),
+        path: z.string(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      return deviceGateway.writeProjectFile({
+        content: input.content,
+        deviceId: input.deviceId,
+        path: input.path,
+        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
+        workingDirectory: input.workingDirectory,
+      });
+    }),
+
  /**
   * Check whether a path exists on a remote device and is a directory, via the
   * device's `statPath` RPC. Lets a web client validate a manually-entered
@@ -381,6 +509,7 @@ export const deviceRouter = router({
        deviceId: input.deviceId,
        path: input.path,
        userId: ctx.userId,
+        workspaceId: ctx.workspaceId,
      });
      return result ?? null;
    }),
@@ -399,7 +528,7 @@ export const deviceRouter = router({
    )
    .query(async ({ ctx, input }) => {
      const result = await deviceGateway.executeToolCall(
-        { deviceId: input.deviceId, userId: ctx.userId },
+        { deviceId: input.deviceId, userId: ctx.userId, workspaceId: ctx.workspaceId },
        {
          apiName: 'getAgentProfile',
          arguments: JSON.stringify({ platform: input.platform }),
@@ -424,7 +553,7 @@ export const deviceRouter = router({
  getDeviceSystemInfo: deviceProcedure
    .input(z.object({ deviceId: z.string() }))
    .query(async ({ ctx, input }) => {
-      return deviceGateway.queryDeviceSystemInfo(ctx.userId, input.deviceId);
+      return deviceGateway.queryDeviceSystemInfo(ctx.userId, input.deviceId, ctx.workspaceId);
    }),

  /**
@@ -440,76 +569,171 @@ export const deviceRouter = router({
   * a currently-reachable device during rollout.
   */
  listDevices: deviceProcedure.query(async ({ ctx }): Promise<DeviceListItem[]> => {
-    const [registered, onlineList] = await Promise.all([
-      ctx.deviceModel.query(),
+    const wsId = ctx.workspaceId;
+
+    // Personal devices resolve under the user principal; workspace devices under
+    // the `workspace:<id>` principal (a separate gateway pool). Fetch both.
+    const [personalRows, workspaceRows, personalOnline, workspaceOnline] = await Promise.all([
+      ctx.deviceModel.queryPersonal(),
+      wsId ? ctx.deviceModel.queryWorkspaceDevices() : Promise.resolve([]),
      deviceGateway.queryDeviceList(ctx.userId),
+      wsId ? deviceGateway.queryDeviceList(ctx.userId, wsId) : Promise.resolve([]),
    ]);

    // The gateway already groups by device, exposing live sessions as nested
-    // `channels`. Flatten them into the UI-facing channel shape; fall back to a
-    // single synthetic channel for a legacy gateway that omits the field.
-    const channelsByDevice = new Map<string, DeviceChannel[]>();
-    for (const conn of onlineList) {
-      const channels: DeviceChannel[] =
-        conn.channels && conn.channels.length > 0
-          ? conn.channels.map((c) => ({
-              channel: c.channel ?? null,
-              connectedAt: c.connectedAt,
+    // `channels`. Flatten one connection into the UI-facing channel shape; fall
+    // back to a single synthetic channel for a legacy gateway that omits the field.
+    const toChannels = (conn: DeviceAttachment): DeviceChannel[] =>
+      conn.channels && conn.channels.length > 0
+        ? conn.channels.map((c) => ({
+            channel: c.channel ?? null,
+            connectedAt: c.connectedAt,
+            hostname: conn.hostname ?? null,
+            platform: conn.platform ?? null,
+          }))
+        : [
+            {
+              channel: null,
+              connectedAt: conn.lastSeen,
              hostname: conn.hostname ?? null,
              platform: conn.platform ?? null,
-            }))
-          : [
-              {
-                channel: null,
-                connectedAt: conn.lastSeen,
-                hostname: conn.hostname ?? null,
-                platform: conn.platform ?? null,
-              },
-            ];
-      channelsByDevice.set(conn.deviceId, channels);
-    }
+            },
+          ];

-    const seen = new Set<string>();
+    // Merge a DB-registered set with its live gateway pool into the UI shape.
+    // `scope` tags the group; deviceIds never collide across pools (a personal id
+    // is derived from userId, a workspace id from workspaceId).
+    const buildItems = (
+      rows: Awaited<ReturnType<typeof ctx.deviceModel.queryPersonal>>,
+      onlineList: DeviceAttachment[],
+      scope: DeviceScope,
+    ): DeviceListItem[] => {
+      const channelsByDevice = new Map<string, DeviceChannel[]>();
+      for (const conn of onlineList) channelsByDevice.set(conn.deviceId, toChannels(conn));

-    const fromDb = registered.map((d) => {
-      seen.add(d.deviceId);
-      const channels = channelsByDevice.get(d.deviceId) ?? [];
-      const live = channels[0];
-      return {
-        channels,
-        defaultCwd: d.defaultCwd,
-        deviceId: d.deviceId,
-        friendlyName: d.friendlyName,
-        hostname: d.hostname ?? live?.hostname ?? null,
-        identitySource: d.identitySource,
-        lastSeen: d.lastSeenAt.toISOString(),
-        online: channels.length > 0,
-        platform: d.platform ?? live?.platform ?? null,
-        registered: true,
-        workingDirs: d.workingDirs ?? [],
-      };
-    });
+      const seen = new Set<string>();
+      const fromDb = rows.map((d): DeviceListItem => {
+        seen.add(d.deviceId);
+        const channels = channelsByDevice.get(d.deviceId) ?? [];
+        const live = channels[0];
+        return {
+          channels,
+          defaultCwd: d.defaultCwd,
+          deviceId: d.deviceId,
+          friendlyName: d.friendlyName,
+          hostname: d.hostname ?? live?.hostname ?? null,
+          identitySource: d.identitySource,
+          lastSeen: d.lastSeenAt.toISOString(),
+          online: channels.length > 0,
+          platform: d.platform ?? live?.platform ?? null,
+          registered: true,
+          scope,
+          workingDirs: d.workingDirs ?? [],
+        };
+      });

-    // Online but not yet persisted — transient until the client auto-registers.
-    const ghosts = [...channelsByDevice.entries()]
-      .filter(([deviceId]) => !seen.has(deviceId))
-      .map(([deviceId, channels]) => ({
-        channels,
-        defaultCwd: null,
-        deviceId,
-        friendlyName: null,
-        hostname: channels[0]?.hostname ?? null,
-        identitySource: null,
-        lastSeen: channels[0]?.connectedAt ?? new Date().toISOString(),
-        online: true,
-        platform: channels[0]?.platform ?? null,
-        registered: false,
-        workingDirs: [] as WorkingDirEntry[],
-      }));
+      // Online but not yet persisted — transient until the client auto-registers.
+      const ghosts = [...channelsByDevice.entries()]
+        .filter(([deviceId]) => !seen.has(deviceId))
+        .map(
+          ([deviceId, channels]): DeviceListItem => ({
+            channels,
+            defaultCwd: null,
+            deviceId,
+            friendlyName: null,
+            hostname: channels[0]?.hostname ?? null,
+            identitySource: null,
+            lastSeen: channels[0]?.connectedAt ?? new Date().toISOString(),
+            online: true,
+            platform: channels[0]?.platform ?? null,
+            registered: false,
+            scope,
+            workingDirs: [] as WorkingDirEntry[],
+          }),
+        );

-    return [...fromDb, ...ghosts];
+      return [...fromDb, ...ghosts];
+    };
+
+    return [
+      ...buildItems(personalRows, personalOnline, 'personal'),
+      ...buildItems(workspaceRows, workspaceOnline, 'workspace'),
+    ];
  }),

+  /**
+   * Mint a short-lived connect token for enrolling a WORKSPACE-owned device.
+   * Owner-only (`wsOwnerProcedure`) — the server verifies the caller is an admin
+   * of the workspace, then signs a token carrying the `workspace_id` claim that
+   * the device gateway trusts to route the device to the `workspace:<id>`
+   * principal. The CLI (`lh connect --workspace`) / settings page use this.
+   */
+  mintWorkspaceConnectToken: wsOwnerProcedure.mutation(async ({ ctx }) => {
+    const token = await signWorkspaceDeviceToken(ctx.workspaceId);
+    return { token, workspaceId: ctx.workspaceId };
+  }),
+
+  /**
+   * Enroll the calling machine as a device of the current workspace. Owner-only;
+   * stamps `workspace_id` so the row belongs to the workspace. Used by
+   * `lh connect --workspace` after minting the connect token.
+   */
+  registerWorkspaceDevice: wsOwnerProcedure
+    .use(serverDatabase)
+    .input(
+      z.object({
+        deviceId: z.string().min(1).max(64),
+        hostname: z.string().nullable().optional(),
+        identitySource: z.enum(['machine-id', 'fallback']),
+        platform: z.string().max(20).nullable().optional(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const model = new DeviceModel(ctx.serverDB, ctx.userId, ctx.workspaceId);
+      return model.registerWorkspaceDevice({ ...input, workspaceId: ctx.workspaceId });
+    }),
+
+  /**
+   * Rename / set working dirs of a WORKSPACE device — scoped by `workspace_id`,
+   * owner-gated, so any workspace owner can manage it (not just the enroller).
+   * Mirrors {@link deviceRouter.updateDevice} but for the workspace pool.
+   */
+  updateWorkspaceDevice: wsOwnerProcedure
+    .use(serverDatabase)
+    .input(
+      z.object({
+        defaultCwd: z.string().nullable().optional(),
+        deviceId: z.string(),
+        friendlyName: z.string().max(100).nullable().optional(),
+        workingDirs: z
+          .array(z.object({ path: z.string(), repoType: z.enum(['git', 'github']).optional() }))
+          .max(20)
+          .optional(),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const model = new DeviceModel(ctx.serverDB, ctx.userId, ctx.workspaceId);
+      const { deviceId, workingDirs, ...value } = input;
+      const nextWorkingDirs = workingDirs
+        ? preserveWorkspaceCache(
+            workingDirs,
+            (await model.findWorkspaceDeviceById(deviceId))?.workingDirs ?? [],
+          )
+        : undefined;
+      await model.updateWorkspaceDevice(deviceId, { ...value, workingDirs: nextWorkingDirs });
+      return { success: true };
+    }),
+
+  /** Remove a WORKSPACE device — scoped by `workspace_id`, owner-gated. */
+  removeWorkspaceDevice: wsOwnerProcedure
+    .use(serverDatabase)
+    .input(z.object({ deviceId: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const model = new DeviceModel(ctx.serverDB, ctx.userId, ctx.workspaceId);
+      await model.deleteWorkspaceDevice(input.deviceId);
+      return { success: true };
+    }),
+
  /**
   * Auto-register the calling device (desktop after OIDC login / CLI on first
   * `lh connect`). Upserts on (userId, deviceId); user-owned fields are
@@ -536,7 +760,7 @@ export const deviceRouter = router({
    }),

  status: deviceProcedure.query(async ({ ctx }) => {
-    return deviceGateway.queryDeviceStatus(ctx.userId);
+    return deviceGateway.queryDeviceStatus(ctx.userId, ctx.workspaceId);
  }),

  /** User-editable fields only — never the machine-reported identity columns. */
@@ -0,0 +1,52 @@
+import { TRPCError } from '@trpc/server';
+
+import type { DeviceModel } from '@/database/models/device';
+import { isPathWithinRoot } from '@/server/services/deviceGateway';
+
+/**
+ * Validate that a client-supplied workspace root is actually one the user has
+ * bound to this device.
+ *
+ * The file routes (move / rename / write / preview) receive `workingDirectory`
+ * from the same untrusted browser session that supplies the file paths. The
+ * gateway's `assertPathsWithinWorkspace` only proves the paths sit *inside that
+ * directory* — it never proves the directory itself is legitimate. So a caller
+ * could set `workingDirectory` to `/` (or `C:\`), pass that containment check
+ * trivially, and reach any path on the device.
+ *
+ * To close that hole we re-derive the approved roots from the *server-owned*
+ * device row — the `workingDirs` recent list and `defaultCwd`, both written only
+ * via `device.updateDevice` / the run path, never trusted from this request —
+ * and require the requested root to equal or nest inside one of them before any
+ * RPC is forwarded. The picker upserts every chosen directory into `workingDirs`
+ * (see `useCommitWorkingDirectory`) and run start upserts the bound cwd, so a
+ * legitimately-selected workspace is always present here.
+ */
+export const assertWorkspaceRootApproved = async (
+  deviceModel: DeviceModel,
+  deviceId: string,
+  workingDirectory: string,
+): Promise<void> => {
+  if (!workingDirectory) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: 'A workspace root is required for file operations',
+    });
+  }
+
+  const device = await deviceModel.findByDeviceId(deviceId);
+
+  const approvedRoots = [
+    ...(device?.workingDirs ?? []).map((dir) => dir.path),
+    ...(device?.defaultCwd ? [device.defaultCwd] : []),
+  ].filter((root): root is string => Boolean(root));
+
+  const approved = approvedRoots.some((root) => isPathWithinRoot(root, workingDirectory));
+
+  if (!approved) {
+    throw new TRPCError({
+      code: 'FORBIDDEN',
+      message: 'Working directory is not an approved workspace for this device',
+    });
+  }
+};
@@ -183,6 +183,7 @@ export const documentRouter = router({
        input.documentId,
        editorData,
        input.saveSource,
+        input.lockOwnerId,
      );
    }),

@@ -255,23 +256,27 @@ export const documentRouter = router({

  acquireDocumentLock: documentProcedure
    .use(withScopedPermission('document:update'))
-    .input(z.object({ id: z.string() }))
+    .input(z.object({ id: z.string(), ownerId: z.string().optional() }))
    .mutation(async ({ ctx, input }) => {
-      return ctx.documentService.acquireDocumentLock(input.id);
+      return input.ownerId
+        ? ctx.documentService.acquireDocumentLockWithOwner(input.id, input.ownerId)
+        : ctx.documentService.acquireDocumentLock(input.id);
    }),

  getDocumentLock: documentProcedure
    .use(withScopedPermission('document:update'))
-    .input(z.object({ id: z.string() }))
+    .input(z.object({ id: z.string(), ownerId: z.string().optional() }))
    .query(async ({ ctx, input }) => {
-      return ctx.documentService.getDocumentLock(input.id);
+      return ctx.documentService.getDocumentLock(input.id, input.ownerId);
    }),

  releaseDocumentLock: documentProcedure
    .use(withScopedPermission('document:update'))
-    .input(z.object({ id: z.string() }))
+    .input(z.object({ id: z.string(), ownerId: z.string().optional() }))
    .mutation(async ({ ctx, input }) => {
-      await ctx.documentService.releaseDocumentLock(input.id);
+      if (input.ownerId)
+        await ctx.documentService.releaseDocumentLockWithOwner(input.id, input.ownerId);
+      else await ctx.documentService.releaseDocumentLock(input.id);
    }),

  updateDocument: documentProcedure
--- a/Show More
+++ b/Show More