@qwen-code/qwen-code 0.15.12-preview.0 → 0.15.12-preview.1

package/bundled/qc-helper/docs/features/commands.md

@@ -45,12 +45,11 @@ Commands for adjusting interface appearance and work environment.
 
 Commands specifically for controlling interface and output language.
 
-| Command               | Description                                                                 | Usage Examples             |
-| --------------------- | --------------------------------------------------------------------------- | -------------------------- |
-| `/language`           | View or change language settings                                            | `/language`                |
-| → `ui [language]`     | Set UI interface language                                                   | `/language ui zh-CN`       |
-| → `output [language]` | Set LLM output language                                                     | `/language output Chinese` |
-| → `translate on/off`  | Toggle AI translation for dynamic slash command descriptions (default: off) | `/language translate on`   |
+| Command               | Description                      | Usage Examples             |
+| --------------------- | -------------------------------- | -------------------------- |
+| `/language`           | View or change language settings | `/language`                |
+| → `ui [language]`     | Set UI interface language        | `/language ui zh-CN`       |
+| → `output [language]` | Set LLM output language          | `/language output Chinese` |
 
 - Available built-in UI languages: `zh-CN` (Simplified Chinese), `en-US` (English), `ru-RU` (Russian), `de-DE` (German), `ja-JP` (Japanese), `pt-BR` (Portuguese - Brazil), `fr-FR` (French), `ca-ES` (Catalan)
 - Output language examples: `Chinese`, `English`, `Japanese`, etc.

package/bundled/qc-helper/docs/features/hooks.md

@@ -30,13 +30,14 @@ Hooks are user-defined scripts or programs that are automatically executed by Qw
 
 ## Hook Types
 
-Qwen Code supports three hook executor types:
+Qwen Code supports four hook executor types:
 
 | Type       | Description                                                                                    |
 | :--------- | :--------------------------------------------------------------------------------------------- |
 | `command`  | Execute a shell command. Receives JSON via `stdin`, returns results via `stdout`.              |
 | `http`     | Send JSON as a `POST` request body to a specified URL. Returns results via HTTP response body. |
 | `function` | Directly call a registered JavaScript function (session-level hooks only).                     |
+| `prompt`   | Use an LLM to evaluate hook input and return a decision.                                       |
 
 ### Command Hooks
 
@@ -134,6 +135,102 @@ Function hooks directly call registered JavaScript/TypeScript functions. They ar
 
 **Note**: For most use cases, use **command hooks** or **HTTP hooks** instead, which can be configured in settings files.
 
+### Prompt Hooks
+
+Prompt hooks use an LLM to evaluate hook input and return a decision. This is useful for making intelligent decisions based on context, such as determining whether to allow or block an operation.
+
+**How it works:**
+
+1. The hook input JSON is injected into your prompt using the `$ARGUMENTS` placeholder
+2. The prompt is sent to an LLM (default: your current model)
+3. The LLM returns a JSON response with the decision
+4. Qwen Code processes the decision and continues or blocks execution accordingly
+
+**Configuration:**
+
+| Field           | Type       | Required | Description                                         |
+| :-------------- | :--------- | :------- | :-------------------------------------------------- |
+| `type`          | `"prompt"` | Yes      | Hook type                                           |
+| `prompt`        | `string`   | Yes      | Prompt sent to LLM. Use `$ARGUMENTS` for hook input |
+| `model`         | `string`   | No       | Model to use (defaults to your current model)       |
+| `timeout`       | `number`   | No       | Timeout in seconds, default 30                      |
+| `name`          | `string`   | No       | Hook name (for logging)                             |
+| `description`   | `string`   | No       | Hook description                                    |
+| `statusMessage` | `string`   | No       | Status message displayed during execution           |
+
+**Response Format:**
+
+The LLM must return JSON with the following structure:
+
+```json
+{
+  "ok": true,
+  "reason": "Explanation of the decision",
+  "additionalContext": "Optional context to inject into the conversation"
+}
+```
+
+| Field               | Description                                                                |
+| :------------------ | :------------------------------------------------------------------------- |
+| `ok`                | `true` to allow/continue, `false` to block/stop                            |
+| `reason`            | Required when `ok` is `false`. Shown to the model to explain the block     |
+| `additionalContext` | Optional. Additional context to inject into the conversation when allowing |
+
+**Supported Events:**
+
+Prompt hooks can be used with most hook events, including:
+
+- `PreToolUse` - Evaluate whether to allow a tool call
+- `PostToolUse` - Evaluate tool results and potentially inject context
+- `Stop` - Determine whether to continue or stop
+- `SubagentStop` - Evaluate subagent results
+- `UserPromptSubmit` - Evaluate or enrich user prompts
+
+**Example: Stop Hook**
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "You are evaluating whether Qwen Code should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+When `ok` is `false`, Qwen Code will continue working and use the `reason` as context for the next response.
+
+**Example: PreToolUse Hook**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Evaluate this tool call for security concerns. Tool input: $ARGUMENTS\n\nCheck for:\n- Dangerous commands (rm -rf, curl | sh, etc.)\n- Unauthorized access attempts\n- Data exfiltration patterns\n\nRespond with {\"ok\": true} if safe, or {\"ok\": false, \"reason\": \"concern\"} if blocked.",
+            "model": "sonnet",
+            "timeout": 30,
+            "name": "security-evaluator"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Hook Events
 
 Hooks fire at specific points during a Qwen Code session. Different events support different matchers to filter trigger conditions.
@@ -152,6 +249,8 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | `PreCompact`         | Before conversation compaction            | Trigger (`manual`, `auto`)                                |
 | `Notification`       | When notifications are sent               | Type (`permission_prompt`, `idle_prompt`, `auth_success`) |
 | `PermissionRequest`  | When permission dialog is shown           | Tool name                                                 |
+| `TodoCreated`        | When a new todo item is created           | None (always fires)                                       |
+| `TodoCompleted`      | When a todo item is marked as completed   | None (always fires)                                       |
 
 ### Matcher Patterns
 
@@ -165,6 +264,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | Session Events      | `SessionEnd`                                                           | ✅ Regex        | Reason: `clear`, `logout`, `prompt_input_exit`, etc.     |
 | Notification Events | `Notification`                                                         | ✅ Exact match  | Type: `permission_prompt`, `idle_prompt`, `auth_success` |
 | Compact Events      | `PreCompact`                                                           | ✅ Exact match  | Trigger: `manual`, `auto`                                |
+| Todo Events         | `TodoCreated`, `TodoCompleted`                                         | ❌ No           | N/A                                                      |
 | Prompt Events       | `UserPromptSubmit`                                                     | ❌ No           | N/A                                                      |
 | Stop Events         | `Stop`                                                                 | ❌ No           | N/A                                                      |
 
@@ -754,6 +854,204 @@ Hook output supports three categories of fields:
 }
 ```
 
+#### TodoCreated
+
+**Purpose**: Executed when a new todo item is created via the `todo_write` tool. Allows validation, logging, or blocking of todo creation.
+
+Todo hooks run in two phases:
+
+- `validation`: runs before persistence. Use this phase for validation only; returning `block` or `deny` prevents the write.
+- `postWrite`: runs after persistence. Use this phase for side effects such as logging or syncing; `block` or `deny` is ignored in this phase.
+
+**Event-specific fields**:
+
+```json
+{
+  "todo_id": "unique identifier for the todo item",
+  "todo_content": "content/description of the todo item",
+  "todo_status": "pending | in_progress | completed",
+  "all_todos": "array of all todo items in the current list",
+  "phase": "validation | postWrite"
+}
+```
+
+**Output Options**:
+
+- `decision`: "allow", "block", or "deny"
+- `reason`: human-readable explanation for the decision (required when blocking)
+
+**Blocking Behavior**:
+
+During the `validation` phase, when `decision` is `block` or `deny` (exit code 2), todo creation is prevented. The todo list remains unchanged, and the reason is provided as feedback to the model.
+
+During the `postWrite` phase, the todo has already been persisted. Hooks may still return output, but `block` / `deny` does not undo the write and should not be used for validation.
+
+**Example Output (Allow)**:
+
+```json
+{
+  "decision": "allow",
+  "reason": "Todo content validated successfully"
+}
+```
+
+**Example Output (Block)**:
+
+```json
+{
+  "decision": "block",
+  "reason": "Todo content too short. Minimum 5 characters required."
+}
+```
+
+**Example Hook Script**:
+
+```bash
+#!/bin/bash
+# ~/.qwen/hooks/todo-validator.sh
+# Validates todo content before creation
+
+INPUT=$(cat)
+CONTENT=$(echo "$INPUT" | jq -r '.todo_content')
+
+# Check minimum length
+if [ ${#CONTENT} -lt 5 ]; then
+  echo '{"decision": "block", "reason": "Todo content must be at least 5 characters"}'
+  exit 2
+fi
+
+# Block test-related todos
+if [[ "$CONTENT" =~ "test" ]]; then
+  echo '{"decision": "block", "reason": "Test todos are not allowed in production"}'
+  exit 2
+fi
+
+echo '{"decision": "allow"}'
+exit 0
+```
+
+**Example Configuration**:
+
+```json
+{
+  "hooks": {
+    "TodoCreated": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.qwen/hooks/todo-validator.sh",
+            "name": "todo-validator",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### TodoCompleted
+
+**Purpose**: Executed when a todo item is marked as completed. Allows validation, logging, or blocking of todo completion.
+
+Todo hooks run in two phases:
+
+- `validation`: runs before persistence. Use this phase for validation only; returning `block` or `deny` prevents the write.
+- `postWrite`: runs after persistence. Use this phase for side effects such as logging or syncing; `block` or `deny` is ignored in this phase.
+
+**Event-specific fields**:
+
+```json
+{
+  "todo_id": "unique identifier for the todo item",
+  "todo_content": "content/description of the todo item",
+  "previous_status": "pending | in_progress (status before completion)",
+  "all_todos": "array of all todo items in the current list",
+  "phase": "validation | postWrite"
+}
+```
+
+**Output Options**:
+
+- `decision`: "allow", "block", or "deny"
+- `reason`: human-readable explanation for the decision (required when blocking)
+
+**Blocking Behavior**:
+
+During the `validation` phase, when `decision` is `block` or `deny` (exit code 2), todo completion is prevented. The todo item remains in its previous status, and the reason is provided as feedback to the model.
+
+During the `postWrite` phase, the todo has already been persisted. Hooks may still return output, but `block` / `deny` does not undo the write and should not be used for validation.
+
+**Example Output (Allow)**:
+
+```json
+{
+  "decision": "allow",
+  "reason": "Todo completion approved"
+}
+```
+
+**Example Output (Block)**:
+
+```json
+{
+  "decision": "block",
+  "reason": "Cannot complete this todo until dependent tasks are finished."
+}
+```
+
+**Example Hook Script**:
+
+```bash
+#!/bin/bash
+# ~/.qwen/hooks/todo-completion-validator.sh
+# Validates todo completion conditions
+
+INPUT=$(cat)
+TODO_ID=$(echo "$INPUT" | jq -r '.todo_id')
+ALL_TODOS=$(echo "$INPUT" | jq -r '.all_todos')
+
+# Check if there are incomplete dependent todos (example logic)
+INCOMPLETE_COUNT=$(echo "$ALL_TODOS" | jq '[.[] | select(.status != "completed")] | length')
+
+if [ "$INCOMPLETE_COUNT" -gt 5 ]; then
+  echo '{"decision": "block", "reason": "Too many incomplete todos. Complete other tasks first."}'
+  exit 2
+fi
+
+echo '{"decision": "allow"}'
+exit 0
+```
+
+**Example Configuration**:
+
+```json
+{
+  "hooks": {
+    "TodoCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.qwen/hooks/todo-completion-validator.sh",
+            "name": "completion-validator",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Use Cases**:
+
+- **Logging**: Track todo creation and completion for audit or analytics
+- **Validation**: Enforce content quality standards (minimum length, required keywords)
+- **Workflow Control**: Block completion until prerequisites are met
+- **Integration**: Sync todos with external task management systems (Jira, Trello, etc.)
+
 ## Hook Configuration
 
 Hooks are configured in Qwen Code settings, typically in `.qwen/settings.json` or user configuration files:

package/bundled/qc-helper/docs/features/language.md

@@ -55,22 +55,6 @@ Detection priority:
 3. System locale via JavaScript Intl API
 4. Default: English
 
-### Dynamic Command Translation
-
-Dynamic slash command descriptions from skills, extensions, file commands, and
-MCP prompts can be translated with AI. This is **off by default** to avoid
-unexpected model calls, latency, and token usage.
-
-```bash
-/language translate status  # Show current status
-/language translate on      # Enable AI translation for dynamic descriptions
-/language translate off     # Disable AI translation
-```
-
-Use `/language translate cache refresh` to re-translate cached dynamic
-descriptions after enabling translation, or `/language translate cache clear` to
-remove cached translations.
-
 ## LLM Output Language
 
 The LLM output language controls what language the AI assistant responds in, regardless of what language you type your questions in.
@@ -145,6 +129,29 @@ User directory takes precedence over built-in translations.
 > Contributions are welcome! If you’d like to improve built-in translations or add new languages.
 > For a concrete example, see [PR #1238: feat(i18n): add Russian language support](https://github.com/QwenLM/qwen-code/pull/1238).
 
+### Maintaining `zh-TW` (Traditional Chinese for Taiwan)
+
+`zh-TW` is **not** an automatic OpenCC s2t conversion of `zh.js` — it is a hand-maintained Taiwan-vocabulary translation. When adding or updating keys, please follow the conventions below.
+
+The "CI enforced?" column indicates whether `npm run check-i18n` will fail the build on a violation. Rows marked **No** are style guidance enforced by review only — typically because the offending form has a legitimate non-UI meaning (`文件` can mean "document", `打開` is colloquially fine in Taiwan).
+
+| Avoid                 | Use instead           | CI enforced? | Reason                                                                                                                                                                           |
+| --------------------- | --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 文件 (file)           | 檔案                  | No           | Taiwan term for filesystem files (but `文件` can legitimately mean "document")                                                                                                   |
+| 服務器 / 服务器       | 伺服器                | Yes          | Taiwan term for "server"                                                                                                                                                         |
+| 菜單 / 菜单           | 選單                  | Yes          | Taiwan term for "menu"                                                                                                                                                           |
+| 鏈接 / 链接           | 連結                  | Yes          | Taiwan term for "link" (bare `鏈` is fine — e.g. 區塊鏈)                                                                                                                         |
+| 打開                  | 開啟                  | No           | Taiwan-preferred verb for "open" (UI); `打開` is colloquially common                                                                                                             |
+| 爲 / 啓 / 曆史 / 鏈接 | 為 / 啟 / 歷史 / 連結 | Yes          | Variant Traditional forms from raw OpenCC s2t. Note: `曆` is context-dependent and correct in calendar terms (日曆, 農曆, 西曆); CI only flags the bigram `曆史`, not bare `曆`. |
+
+If you are not a Traditional Chinese speaker and need to bootstrap a value, **do not paste raw OpenCC `s2t` output**: the default s2t profile emits variant Traditional characters (e.g. 爲, 啓) that Taiwan does not use, and never rewrites Mainland-Chinese vocabulary (服務器, 菜單). Prefer `s2twp.json` (Simplified → Taiwan with phrase mapping) as a starting point and then ask a Taiwan-Chinese speaker to review.
+
+The `check-i18n` script (run in CI via `npm run check-i18n`) will fail the build if any of the CI-enforced substrings above end up in a `zh-TW` value. See `scripts/check-i18n.ts → ZH_TW_FORBIDDEN_PATTERNS` for the full list. If a translation legitimately needs to contain a CI-forbidden substring, add its key to `ZH_TW_ALLOWED_EXCEPTIONS` in the same file with a brief justification.
+
+> [!note]
+>
+> The check uses plain substring matching, which does not understand Chinese word boundaries. A bigram pattern can therefore false-positive across compound-word boundaries — for example, `區塊鏈接口` (= `區塊鏈` + `接口`) contains the substring `鏈接` even though neither word is incorrect. If you hit a surprising CI failure of this kind, add the translation key to `ZH_TW_ALLOWED_EXCEPTIONS` rather than removing the pattern.
+
 ### Language Pack Format
 
 ```javascript

package/bundled/qc-helper/docs/qwen-serve.md

@@ -8,9 +8,10 @@ Run Qwen Code as a local HTTP daemon so multiple clients (IDE plugins, web UIs,
 
 ## What it gives you
 
-- **One agent process, many clients** — under the default `sessionScope: 'single'`, every client connecting to the same workspace shares one ACP session. Live cross-client collaboration on the same conversation, the same file diffs, the same permission prompts.
+- **One agent process, many clients** — under the default `sessionScope: 'single'`, every client connecting to the daemon shares one ACP session. Live cross-client collaboration on the same conversation, the same file diffs, the same permission prompts.
 - **Reconnect-safe streaming** — SSE with `Last-Event-ID` reconnect lets a client drop and pick up exactly where it left off (within the ring's replay window).
 - **First-responder permissions** — when the agent asks for permission to run a tool, every connected client sees the request; whichever client answers first wins.
+- **One daemon, one workspace** — each `qwen serve` process binds to exactly one workspace at boot (per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02). Multi-workspace deployments run one daemon per workspace on separate ports (or behind an orchestrator).
 
 ## Quickstart
 
@@ -19,11 +20,11 @@ Run Qwen Code as a local HTTP daemon so multiple clients (IDE plugins, web UIs,
 ```bash
 cd your-project/
 qwen serve
-# → qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge)
+# → qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge, workspace=/path/to/your-project)
 # → qwen serve: bearer auth disabled (loopback default). Set QWEN_SERVER_TOKEN to enable.
 ```
 
-The default bind is `127.0.0.1:4170`. Bearer auth is **off** on loopback so local development "just works".
+The default bind is `127.0.0.1:4170`. Bearer auth is **off** on loopback so local development "just works". The daemon binds to the current working directory; use `--workspace /path/to/dir` to override.
 
 ### 2. Sanity-check it
 
@@ -32,19 +33,23 @@ curl http://127.0.0.1:4170/health
 # → {"status":"ok"}
 
 curl http://127.0.0.1:4170/capabilities
-# → {"v":1,"mode":"http-bridge","features":["health","capabilities","session_create",...]}
+# → {"v":1,"mode":"http-bridge","features":["health","capabilities","session_create",...],"workspaceCwd":"/path/to/your-project"}
 ```
 
+The `workspaceCwd` field surfaces the bound workspace so clients can pre-flight check + omit `cwd` on `POST /session`.
+
 ### 3. Open a session
 
 ```bash
 curl -X POST http://127.0.0.1:4170/session \
   -H 'Content-Type: application/json' \
-  -d '{"cwd":"'"$PWD"'"}'
+  -d '{}'
 # → {"sessionId":"<uuid>","workspaceCwd":"…","attached":false}
 ```
 
-A second client posting to `/session` with the same `cwd` gets `"attached": true` — they're now sharing the agent.
+`cwd` may be omitted — the route falls back to the daemon's bound workspace. Posting a `cwd` that doesn't match the bound workspace returns `400 workspace_mismatch` (the daemon is bound to exactly one workspace; start a separate daemon for a different one).
+
+A second client posting to `/session` (any matching `cwd` or none) gets `"attached": true` — they're now sharing the agent.
 
 ### 4. Subscribe to the event stream (in another terminal first)
 
@@ -94,7 +99,7 @@ Clients then send `Authorization: Bearer $QWEN_SERVER_TOKEN` on every request. `
 
 ```bash
 curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" http://your-host:4170/capabilities
-# → {"v":1,"mode":"http-bridge","features":[...],"modelServices":[]}
+# → {"v":1,"mode":"http-bridge","features":[...],"modelServices":[],"workspaceCwd":"/path/to/your-project"}
 # Wrong token → 401
 ```
 
@@ -102,14 +107,15 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
 
 ## CLI flags
 
-| Flag                    | Default     | Purpose                                                                                                                                                                                                                                                                                                                                             |
-| ----------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--port <n>`            | `4170`      | TCP port. `0` = OS-assigned ephemeral port.                                                                                                                                                                                                                                                                                                         |
-| `--hostname <addr>`     | `127.0.0.1` | Bind interface. Anything beyond loopback requires a token.                                                                                                                                                                                                                                                                                          |
-| `--token <str>`         | —           | Bearer token. Falls back to `QWEN_SERVER_TOKEN` env var (with leading/trailing whitespace stripped — handy for `$(cat token.txt)`).                                                                                                                                                                                                                 |
-| `--max-sessions <n>`    | `20`        | Cap on concurrent live sessions. New `POST /session` requests that would spawn a fresh child return `503` (with `Retry-After: 5`) when the cap is hit; attaches to existing sessions are NOT counted. Set to `0` to disable. Sized for single-user / small-team usage; raise it if your deployment has the RAM/FD headroom (~30–50 MB per session). |
-| `--max-connections <n>` | `256`       | Listener-level TCP connection cap (`server.maxConnections`). Bounds raw socket count irrespective of session count — slow / phantom SSE clients get rejected at accept time once full. Raise alongside `--max-sessions` if your deployment expects many SSE subscribers per session.                                                                |
-| `--http-bridge`         | `true`      | Stage 1 mode: per-session `qwen --acp` child process. Stage 2 native in-process becomes available later.                                                                                                                                                                                                                                            |
+| Flag                    | Default         | Purpose                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--port <n>`            | `4170`          | TCP port. `0` = OS-assigned ephemeral port.                                                                                                                                                                                                                                                                                                         |
+| `--hostname <addr>`     | `127.0.0.1`     | Bind interface. Anything beyond loopback requires a token.                                                                                                                                                                                                                                                                                          |
+| `--token <str>`         | —               | Bearer token. Falls back to `QWEN_SERVER_TOKEN` env var (with leading/trailing whitespace stripped — handy for `$(cat token.txt)`).                                                                                                                                                                                                                 |
+| `--max-sessions <n>`    | `20`            | Cap on concurrent live sessions. New `POST /session` requests that would spawn a fresh child return `503` (with `Retry-After: 5`) when the cap is hit; attaches to existing sessions are NOT counted. Set to `0` to disable. Sized for single-user / small-team usage; raise it if your deployment has the RAM/FD headroom (~30–50 MB per session). |
+| `--workspace <path>`    | `process.cwd()` | Absolute workspace path this daemon binds to (per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02 — 1 daemon = 1 workspace). `POST /session` requests with a mismatched `cwd` return `400 workspace_mismatch`. For multi-workspace deployments, run one `qwen serve` per workspace on separate ports.                                  |
+| `--max-connections <n>` | `256`           | Listener-level TCP connection cap (`server.maxConnections`). Bounds raw socket count irrespective of session count — slow / phantom SSE clients get rejected at accept time once full. Raise alongside `--max-sessions` if your deployment expects many SSE subscribers per session.                                                                |
+| `--http-bridge`         | `true`          | Stage 1 mode: one `qwen --acp` child per daemon (bound to one workspace at boot, per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02); N sessions multiplex onto that child via ACP `newSession()`. Stage 2 native in-process becomes available later.                                                                                 |
 
 > **Sizing the load knobs.** `--max-sessions` is the **new-child** cap.
 > Three other layers also limit load — when sizing for a high-concurrency
@@ -157,13 +163,15 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
 > swallow RSTs may want to lower `server.keepAliveTimeout` via a
 > reverse proxy or accept periodic daemon restarts.
 
-## Multi-session & remote deployment
+## Multi-session & multi-workspace deployment
+
+Per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02, each `qwen serve` process binds to **one workspace** at boot. Within that workspace it multiplexes N sessions onto a single `qwen --acp` child via the agent's native session map — sessions share the child's process / OAuth state / file-read cache / hierarchy-memory parse.
 
-A single `qwen serve` process can manage sessions for any workspace path passed via `cwd` on `POST /session` — under the default `sessionScope: 'single'` it keeps one ACP session per canonicalized workspace, sharing it across every client that posts the same `cwd`. So one daemon will happily host sessions for many workspaces at once.
+To host **multiple workspaces** (one user, several repos; or several users on the same host), run **multiple daemon processes** — one per workspace, each on its own port, supervised by systemd / docker-compose / k8s / a `qwen-coordinator` reference orchestrator. The trade-off is intentional: one workspace per child means `loadSettings(cwd)` / OAuth / MCP server scope stay aligned with the bound directory and don't drift across requests.
 
 > **Subscribe BEFORE posting `modelServiceId` on attach.** When a client `POST /session` with a `modelServiceId` and the workspace already has a session running a different model, the daemon issues an internal `setSessionModel` call — failures are NOT propagated as an HTTP error (the session stays operational on its current model). The visible failure signal is a `model_switch_failed` event on the session's SSE stream. If you call `POST /session` and only THEN open `GET /session/:id/events`, you'll miss the failure event and silently keep talking to the wrong model. Open the SSE stream first, or pass `Last-Event-ID: 0` on subscribe to replay the ring's oldest available event.
 
-To handle multiple **users** (each with their own quota, audit log, sandbox) or to scale beyond one process's reach (cold-start budget, FD count, RSS), you spawn multiple daemon instances behind an external orchestrator. That orchestrator (multi-tenancy / OIDC / Quota / Audit / k8s) is **out of scope** for the qwen-code project — see issue [#3803](https://github.com/QwenLM/qwen-code/issues/3803) "External Reference Architecture" for the design pointers.
+To handle multiple **users** (each with their own quota, audit log, sandbox) or to scale beyond one process's reach (cold-start budget, FD count, RSS), spawn one daemon per workspace per user behind an external orchestrator. That orchestrator (multi-tenancy / OIDC / Quota / Audit / k8s) is **out of scope** for the qwen-code project — see issue [#3803](https://github.com/QwenLM/qwen-code/issues/3803) "External Reference Architecture" for the design pointers.
 
 ## Durability model
 
@@ -255,7 +263,7 @@ Concrete cost at N=5 sessions on the same workspace:
 | Auto-memory learned facts            | shared      | one knowledge base per child |
 | Cold start                           | first only  | <200 ms after first session  |
 
-The bridge keeps **one channel per workspace** (cross-workspace sharing is intentionally not done — different workspaces have different settings/auth scope, and `acpAgent.ts:601` reloads settings per newSession `cwd`, which would interfere). The channel stays alive while at least one session is live; the last `killSession` (or a channel-level crash) kills the child.
+The bridge keeps **one channel per daemon** (one daemon per workspace, per §02). The channel stays alive while at least one session is live; the last `killSession` (or a channel-level crash) kills the child.
 
 **MCP server children** are still per-session today — each session's config can specify different servers, so they're independently spawned. Stage 1.5 follow-up: refcount MCP server children by `(workspace, config-hash)` so identical configs share. Not in scope for this PR.