@qwen-code/qwen-code 0.19.10 → 0.19.11-nightly.20260717.f8e6e8931

package/bundled/qc-helper/docs/configuration/settings.md

@@ -163,7 +163,7 @@ Settings are organized into categories. Most settings should be placed within th
 | `model.reasoningEffort`                            | enum    | How hard reasoning-capable models think, applied across all providers. Set with the [`/effort`](../features/commands) command (`low`, `medium`, `high`, `xhigh`, `max`). Each provider maps and clamps this to what the active model supports (e.g. Gemini caps at `high`; Anthropic clamps tiers a model lacks). Leave unset to use the model/provider default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `undefined` |
 | `model.baseUrl`                                    | string  | Persisted automatically by the model picker to disambiguate when multiple `modelProviders` entries share the same model id. Not intended to be set by hand — use the `/model` picker or a `modelProviders` entry instead; a stale hand-edited value can silently route requests to a different same-id provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `undefined` |
 | `model.sessionTokenLimit`                          | number  | Maximum recorded prompt token count allowed before sending the next message. `-1` means unlimited; `0` is also treated as unlimited (unlike `model.maxToolCalls`, where `0` disallows all calls). When the recorded prompt count exceeds the limit, the next send is dropped (the session is not aborted).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `-1`        |
-| `model.maxSessionTurns`                            | number  | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `-1`        |
+| `model.maxSessionTurns`                            | integer | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `-1`        |
 | `model.maxWallTimeSeconds`                         | number  | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `-1`        |
 | `model.maxToolCalls`                               | number  | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `-1`        |
 | `model.maxSubagentDepth`                           | number  | Maximum sub-agent nesting depth (1-based levels: a top-level sub-agent is level 1). `1` keeps sub-agents available but disables nesting — the pre-nesting behavior. Values clamp to the range 1–100; non-finite values fall back to the default. Teammates, forks, and workflow-spawned agents never nest regardless of this setting. Overridable via `--max-subagent-depth`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `5`         |
@@ -175,7 +175,7 @@ Settings are organized into categories. Most settings should be placed within th
 | `model.chatCompression.screenshotTriggerThreshold` | number  | Tool-returned image count at or above which the screenshot trigger fires (only when `enableScreenshotTrigger`). Compaction resets the count — surviving images are re-embedded as top-level parts, which the trigger doesn't count — so it won't immediately re-fire. Env override: `QWEN_COMPACT_SCREENSHOT_THRESHOLD`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `20`        |
 | `model.skipNextSpeakerCheck`                       | boolean | Skip the next speaker check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `true`      |
 | `model.skipLoopDetection`                          | boolean | Disables streaming loop detection checks. Defaults to `true` (loop detection is skipped) to avoid false positives interrupting legitimate workflows. Set to `false` to re-enable streaming loop detection — useful as a guardrail in headless / non-interactive runs where stuck repetition can otherwise waste budget.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `true`      |
-| `model.maxToolCallsPerTurn`                        | number  | Hard cap on tool calls within a single turn (one model turn plus its tool-result continuations; blocking Stop-hook continuations such as `/goal` iterations start a fresh budget). Always-on circuit breaker against runaway turns, independent of `model.skipLoopDetection`; the pattern-based loop detectors fire long before this cap, which only bounds total volume. Set to `0` or a negative value to disable the cap. Choosing "Disable loop detection for this session" in the loop-detected dialog also suppresses it for the rest of the session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `100`       |
+| `model.maxToolCallsPerTurn`                        | integer | Hard cap on tool calls within a single turn (one model turn plus its tool-result continuations; blocking Stop-hook continuations such as `/goal` iterations start a fresh budget). Always-on circuit breaker against runaway turns, independent of `model.skipLoopDetection`; the pattern-based loop detectors fire long before this cap, which only bounds total volume. Set to `0` or a negative value to disable the cap. Choosing "Disable loop detection for this session" in the loop-detected dialog also suppresses it for the rest of the session.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `100`       |
 | `model.skipStartupContext`                         | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false`     |
 | `model.enableOpenAILogging`                        | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`     |
 | `model.openAILoggingDir`                           | string  | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `undefined` |
@@ -258,9 +258,9 @@ The `extra_body` field allows you to add custom parameters to the request body s
 
 #### visionModel
 
-| Setting       | Type   | Description                                                                                                                                                                                                                        | Default |
-| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `visionModel` | string | Image-capable model used as the vision bridge: when a text-only main model receives an image, it is transcribed by this model first. Leave empty to auto-pick a same-provider vision model. Can also be set via `/model --vision`. | `""`    |
+| Setting       | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                         | Default |
+| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `visionModel` | string | Image-capable model used as the vision bridge: when a text-only main model receives an image, or `read_file` needs the bounded PDF visual fallback, it is transcribed by this model first. Setting this explicitly authorizes bridge calls to that model even when it uses another provider; the tool display discloses the endpoint. Leave empty to auto-pick a same-provider vision model. Can also be set via `/model --vision`. | `""`    |
 
 #### visionBridgeTimeoutMs
 
@@ -320,12 +320,13 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
 | `tools.sandboxImage`                  | string            | Sandbox image URI used by Docker/Podman when `--sandbox-image` and `QWEN_SANDBOX_IMAGE` are not set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.shell.enableInteractiveShell`  | boolean           | Use `node-pty` for an interactive shell experience. Fallback to `child_process` still applies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `true`      |                                                                                                                                                                                                                                                                                                                             |
 | `tools.shell.defaultTimeoutMs`        | number            | Default timeout, in milliseconds, for foreground shell commands started by the agent. A per-call timeout on the shell tool overrides this. When unset, foreground commands time out after 120000 ms (2 minutes). Set to 0 to disable the timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `undefined` |                                                                                                                                                                                                                                                                                                                             |
+| `tools.shell.heartbeatIntervalMs`     | number            | Interval, in milliseconds, between liveness heartbeats emitted while a foreground shell command produces no output. Heartbeats are forwarded to ACP clients and stream-json consumers so they can tell a silent command from a dead session. When unset, heartbeats fire every 10000 ms (10 seconds). Set to 0 to disable heartbeats.                                                                                                                                                                                                                                                                                                                                                                                                                | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.core`                          | array of strings  | **Deprecated.** Will be removed in next version. Use `permissions.allow` + `permissions.deny` instead. Restricts built-in tools to an allowlist. All tools not in the list are disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.exclude`                       | array of strings  | **Deprecated.** Use `permissions.deny` instead. Tool names to exclude from discovery. Automatically migrated to the `permissions` format on first load.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.disabled`                      | array of strings  | Tool names hidden from the registry entirely. Unlike `permissions.deny` (which blocks calls at runtime), disabled tools are never registered, so they do not appear in `/tools` and cannot be discovered or called by the model. For example, `["enter_plan_mode"]` prevents the model from switching into plan mode on its own. Merged as a union across scopes.                                                                                                                                                                                                                                                                                                                                                                                    | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.visible`                       | array of strings  | Deferred tool names made visible at startup without requiring `tool_search`. Listed tools appear alongside core tools in the initial session. Merged as a union across scopes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.allowed`                       | array of strings  | **Deprecated.** Use `permissions.allow` instead. Tool names that bypass the confirmation dialog. Automatically migrated to the `permissions` format on first load.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `undefined` |                                                                                                                                                                                                                                                                                                                             |
-| `tools.approvalMode`                  | string            | Sets the default approval mode for tool usage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `default`   | Possible values: `plan` (analyze only, do not modify files or execute commands), `default` (require approval before file edits or shell commands run), `auto-edit` (automatically approve file edits), `auto` (LLM classifier auto-approves safe actions, blocks risky ones), `yolo` (automatically approve all tool calls) |
+| `tools.approvalMode`                  | string            | Sets the default approval mode for tool usage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `auto`      | Possible values: `plan` (analyze only, do not modify files or execute commands), `default` (require approval before file edits or shell commands run), `auto-edit` (automatically approve file edits), `auto` (LLM classifier auto-approves safe actions, blocks risky ones), `yolo` (automatically approve all tool calls) |
 | `tools.discoveryCommand`              | string            | Command to run for tool discovery.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.callCommand`                   | string            | Defines a custom shell command for calling a specific tool that was discovered using `tools.discoveryCommand`. The shell command must meet the following criteria: It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as first command line argument. It must read function arguments as JSON on `stdin`, analogous to [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). It must return function output as JSON on `stdout`, analogous to [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). | `undefined` |                                                                                                                                                                                                                                                                                                                             |
 | `tools.useRipgrep`                    | boolean           | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `true`      |                                                                                                                                                                                                                                                                                                                             |

package/bundled/qc-helper/docs/features/approval-mode.md

@@ -19,9 +19,9 @@ Qwen Code offers five distinct permission modes that allow you to flexibly contr
 ### Quick Reference Guide
 
 - **Start in Plan Mode**: Great for understanding before making changes
-- **Work in Ask Permissions Mode**: The balanced choice for most development work
+- **Auto Mode (default)**: The default out-of-the-box experience — an LLM classifier auto-approves safe actions and blocks risky ones, minimizing interruptions while keeping a safety net
+- **Switch to Ask Permissions**: When you want manual approval for every file edit and shell command
 - **Switch to Auto-Edit**: When you're making lots of safe code changes
-- **Try Auto Mode**: When you want fewer interruptions but still want safety on shell commands and network calls — an LLM classifier evaluates each call
 - **Use YOLO sparingly**: Only for trusted automation in controlled environments
 
 > [!tip]

package/bundled/qc-helper/docs/features/channels/dingtalk.md

@@ -81,6 +81,36 @@ qwen channel start
 
 Open DingTalk and send a message to the bot. You should see a 👀 emoji reaction appear while the agent processes, followed by the response.
 
+## Daemon Webhook Delivery
+
+When the channel runs under `qwen serve`, authenticated external Webhook events can trigger unattended agent tasks and deliver the final Markdown response to either a DingTalk user or group. Use the existing Webhook target fields; no separate channel type is required:
+
+```json
+{
+  "webhooks": {
+    "sources": {
+      "manual-test": {
+        "secretEnv": "QWEN_CHANNEL_DINGTALK_TEST_SECRET",
+        "targets": {
+          "operator": {
+            "chatId": "DINGTALK_USER_ID",
+            "senderId": "webhook:manual-test",
+            "isGroup": false
+          },
+          "team": {
+            "chatId": "OPEN_CONVERSATION_ID",
+            "senderId": "webhook:manual-test",
+            "isGroup": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Every target must set `isGroup` explicitly. For a direct message, `chatId` is the recipient's DingTalk user ID. For a group message, `chatId` is the group's `openConversationId`. Thread targets and incoming robot Webhook URLs are not supported for proactive delivery. See [Webhook-triggered tasks](./overview#webhook-triggered-tasks) for the complete channel configuration and request format.
+
 ## Group Chats
 
 DingTalk bots work in both DM and group conversations. To enable group support:

package/bundled/qc-helper/docs/features/channels/overview.md

@@ -89,20 +89,51 @@ Controls how conversation sessions are managed:
 
 ### Channel Memory
 
-Channel memory lets accepted channel senders save stable context for one chat or thread. Qwen Code injects that memory when a fresh channel session starts, including after `/clear`.
-
-Natural-language examples:
-
-- `记住：默认使用 staging 环境` saves memory for the current chat or thread.
-- `你记一下以后回复前要说 1122` saves the extracted durable memory.
-- `你现在都记住了什么` shows saved memory for the current chat or thread.
-- `把这个聊天的记忆清空` starts the clear flow; `确认清空记忆` confirms it.
-
-Channel memory follows the channel access gates. Any message accepted by `senderPolicy`, `dmPolicy`, `groupPolicy`, group settings, pairing, and mention requirements can read, write, or clear memory for that chat or thread.
-
-In open groups, any accepted member can update shared channel memory for that group. Use `allowlist` or `pairing` policies when memory should be limited to trusted senders.
-
-Memory is keyed to the current chat or thread, so it is not injected into `single` session scope, where every chat shares one channel-wide agent session.
+Channel memory stores durable context for one chat or thread. Entries have stable
+IDs, so a list response can be used for deterministic follow-up operations.
+
+- `记住：默认使用 staging 环境` saves a new entry for the current chat or
+  thread.
+- `查看记忆` lists entries and their stable IDs. Use `查看第 2 页记忆` to view
+  a later page, `查看记忆 <id>` to view one entry, or a natural filtered
+  request such as `只看中文偏好` to list the matching entries.
+- `查看刚才那条记忆`, `把关于 staging 的记忆改成默认使用 production`, and
+  `忘掉刚才那条` work when the natural reference resolves to exactly one entry.
+  `把 <id> 改成默认使用 production` updates that entry immediately, and
+  `忘掉 <id>` removes it immediately. Neither operation needs confirmation.
+- `清空记忆` starts the clear-all confirmation flow; `确认清空记忆` completes
+  it.
+
+When a natural inspect, update, or removal request matches multiple entries,
+the bot returns the candidate IDs and previews without changing memory. There
+is no pending selection or confirmation state: retry the request with one exact
+ID, such as `忘掉 m-a31f0d82c7e4`. Exact-ID operations remain the deterministic
+fast path. A natural request with no match reports that no entry matched.
+
+The legacy slash aliases `/remember-channel`, `/channel-memory`, and
+`/forget-channel` have been removed. They are no longer channel-memory
+commands.
+
+Channel memory follows the channel access gates. Any message accepted by
+`senderPolicy`, `dmPolicy`, `groupPolicy`, group settings, pairing, and mention
+requirements can read, write, update, or clear memory for that chat or thread.
+Accepted members of the same group share that group's target store. Use
+`allowlist` or `pairing` policies when group memory should be limited to trusted
+senders.
+
+Existing legacy `CHANNEL.md` memory is migrated automatically to structured
+`CHANNEL.json` storage on the first mutation. Structured memory persists across
+standalone channel and daemon-managed channel restarts, and is injected when a
+fresh target-scoped session starts, including after `/clear`.
+
+Memory remains keyed to the current chat or thread. It is not injected into a
+`sessionScope: single` session, because that session is shared across the whole
+channel rather than scoped to one target.
+
+Channel memory does not automatically learn facts from normal conversation,
+extract multiple entries from one request, or accept `第一个` as confirmation
+for an ambiguous natural reference. Use a clear remember request and an exact
+entry ID when a natural reference is ambiguous.
 
 ### Token Security
 
@@ -421,7 +452,12 @@ Example channel config:
           "github-ci": {
             "secretEnv": "QWEN_CHANNEL_GITHUB_CI_SECRET",
             "targets": {
-              "default": {
+              "operator": {
+                "chatId": "DINGTALK_USER_ID",
+                "senderId": "webhook:github-ci",
+                "isGroup": false
+              },
+              "team": {
                 "chatId": "OPEN_CONVERSATION_ID",
                 "senderId": "webhook:github-ci",
                 "isGroup": true
@@ -435,7 +471,7 @@ Example channel config:
 }
 ```
 
-For DingTalk, `chatId` must be the group `openConversationId`; other adapters may require their own proactive target shape.
+For DingTalk, set `isGroup` explicitly on every target. A direct-message target uses the DingTalk user ID as `chatId` with `isGroup: false`; a group target uses the group `openConversationId` with `isGroup: true`. Other adapters may require their own proactive target shape.
 
 Start `qwen serve` with the channel worker enabled:
 
@@ -451,7 +487,7 @@ curl -X POST "http://127.0.0.1:4170/channels/dingtalk-main/webhooks/github-ci" \
   -H "Content-Type: application/json" \
   -d '{
     "eventType": "push",
-    "targetRef": "default",
+    "targetRef": "operator",
     "title": "CI pipeline finished",
     "payload": {
       "targetRef": "refs/heads/main",

package/bundled/qc-helper/docs/features/channels/wecom.md

@@ -39,10 +39,7 @@ Add the channel to `~/.qwen/settings.json`:
       "sessionScope": "user",
       "cwd": "/path/to/your/project",
       "instructions": "You are a concise coding assistant responding via WeCom.",
-      "groupPolicy": "open",
-      "groups": {
-        "*": { "requireMention": true }
-      }
+      "groupPolicy": "open"
     }
   }
 }
@@ -82,9 +79,13 @@ Open WeCom and send a message to the intelligent robot.
 - `pairing`: users must pair before using the bot.
 - `open`: anyone who can message the robot can use it.
 
-For groups, set `groupPolicy` to `"allowlist"` or `"open"`. By default, group messages require a mention through `"requireMention": true`.
+For groups, set `groupPolicy` to `"allowlist"` or `"open"`. WeCom only delivers group messages that mention the intelligent robot, so every delivered group callback is treated as mentioned. The `requireMention` setting cannot enable responses to unmentioned group messages because those messages are not delivered to the bot.
 
-When the WeCom SDK includes explicit mention metadata, Qwen Code uses it for this gate. If no mention metadata is present, the channel treats delivered group messages as unmentioned. Set `"requireMention": false` only if you want to rely on WeCom-side delivery scoping instead.
+### Group Mention Compatibility
+
+Earlier Qwen Code versions also applied the generic `requireMention` gate after WeCom delivered a group callback. Because the callback does not include separate mention metadata, `requireMention: true`—including the default value—could reject every delivered group message and make group chat appear nonfunctional.
+
+Qwen Code now relies on WeCom's mention-scoped delivery and does not apply a second mention decision. Existing WeCom configurations containing either `requireMention: true` or `requireMention: false` remain valid and do not produce configuration errors. Both values have the same behavior for WeCom, so the field can be removed. Other settings in the same group entry, such as `dispatchMode`, continue to apply. `groupHistoryLimit` remains accepted but cannot collect new WeCom history because unmentioned group messages are not delivered.
 
 ## Images and Files
 
@@ -109,7 +110,7 @@ For safety, local image paths must be inside the channel file directory under th
 ### Bot does not respond in groups
 
 - Check `groupPolicy`.
-- Mention the bot unless the group config sets `"requireMention": false`.
+- Mention the bot in the group.
 - Confirm the robot has been added to the group.
 
 ### Self-built application credentials do not work

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

@@ -114,6 +114,8 @@ Priority order (highest to lowest):
 
 `settings.env.QWEN_SANDBOX_IMAGE` also works as a generic env injection mechanism, but `tools.sandboxImage` is the preferred persistent setting.
 
+Custom images are user-managed. Rebuild them with an up-to-date Qwen Code installation to receive the safe update handoff; older images may still use their original in-process updater.
+
 ### macOS Seatbelt profiles
 
 Built-in profiles (set via `SEATBELT_PROFILE` env var):

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

@@ -20,6 +20,34 @@ The daemon reads the bearer token from either `--token <value>` on the CLI or th
 
 One shell-level `export` covers both server boot and SDK client construction (just keep it scoped to the session, per the note above).
 
+## Workspace lifecycle and process boundaries
+
+One daemon can host several isolated workspace runtimes under the same listener.
+Repeat `--workspace` with absolute directories to create explicit startup
+runtimes; the first is primary. Primary and other explicit startup/static
+runtimes cannot be removed without restarting the process.
+
+Additional workspaces can also be registered while the daemon is running
+through `POST /workspaces`. Pass `persist: true` to retain a dynamic secondary
+in the user-level registration store so it is restored on the next start.
+Untrusted registrations remain visible for diagnostics, bounded file reads,
+and declared persisted reads but cannot start ACP. Dynamic and
+persisted-restored secondaries are removable: a normal removal refuses while
+the runtime is busy, while a forced removal requests termination of active
+resources and commits logical removal before the same cwd can be re-added.
+Cleanup is bounded and best-effort after the persistence commit point; failures
+are logged rather than restoring the removed runtime.
+
+Runtime isolation covers cwd, environment overlay, filesystem/trust boundary,
+workspace services, bridge, Voice lease state, channel worker, and the ACP/MCP
+resource boundary. Production attempts to preheat the primary ACP child and
+retries on first use after failure; trusted secondaries start theirs on demand,
+and untrusted secondaries do not start ACP.
+Authentication, HTTP rate limits, listener and Voice admission caps,
+total-session admission, metrics, shutdown, and the process fault radius remain
+daemon-global. Run separate daemons when those process-level boundaries must be
+independent.
+
 ## Linux: systemd user unit
 
 > **Find your `qwen` binary first.** The unit file's `ExecStart=` must hold an **absolute path** — service managers don't read your shell's `PATH`. Run `which qwen` to discover it. Common locations: `/usr/local/bin/qwen` (Linuxbrew, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.fnm/aliases/default/bin/qwen` (fnm), `~/.volta/bin/qwen` (Volta). Substitute the actual path everywhere the templates below show `/PATH/TO/qwen`.
@@ -34,9 +62,9 @@ After=network.target
 [Service]
 Type=simple
 # Replace with your project; %h expands to $HOME under user units.
-WorkingDirectory=%h/your-project
+WorkingDirectory=%h/project-a
 # Run `which qwen` to find the absolute path. systemd does NOT read $PATH.
-ExecStart=/PATH/TO/qwen serve --hostname 127.0.0.1 --port 4170
+ExecStart=/PATH/TO/qwen serve --hostname 127.0.0.1 --port 4170 --workspace %h/project-a --workspace %h/project-b
 # Read the bearer token from a chmod 600 file rather than inlining it
 # in the unit. `Environment=` would expose the token in the unit file
 # (typically 644 = world-readable). EnvironmentFile keeps the token in
@@ -95,10 +123,14 @@ Without `loginctl enable-linger`, the user-level systemd instance shuts down whe
     <string>127.0.0.1</string>
     <string>--port</string>
     <string>4170</string>
+    <string>--workspace</string>
+    <string>/Users/YOUR-USERNAME/project-a</string>
+    <string>--workspace</string>
+    <string>/Users/YOUR-USERNAME/project-b</string>
   </array>
   <!-- launchd does NOT expand `~` or `$HOME` — use absolute paths. -->
   <key>WorkingDirectory</key>
-  <string>/Users/YOUR-USERNAME/your-project</string>
+  <string>/Users/YOUR-USERNAME/project-a</string>
   <key>EnvironmentVariables</key>
   <dict>
     <!-- DO NOT COMMIT this file with a real token. Also chmod 600 the
@@ -153,7 +185,7 @@ After editing the plist (e.g., rotating the token) you must `unload` then `load`
 Assumes `QWEN_SERVER_TOKEN` is already exported in your shell (see the setup section above):
 
 ```bash
-tmux new -d -s qwen-serve "cd ~/your-project && qwen serve --hostname 127.0.0.1"
+tmux new -d -s qwen-serve "qwen serve --hostname 127.0.0.1 --workspace /absolute/path/project-a --workspace /absolute/path/project-b"
 tmux attach -t qwen-serve   # see live logs; Ctrl-b d to detach
 tmux kill-session -t qwen-serve
 ```
@@ -165,11 +197,14 @@ tmux kill-session -t qwen-serve
 Assumes `QWEN_SERVER_TOKEN` is already exported in your shell:
 
 ```bash
-nohup bash -c 'cd ~/your-project && qwen serve --hostname 127.0.0.1' > qwen-serve.log 2>&1 &
+nohup qwen serve --hostname 127.0.0.1 \
+  --workspace /absolute/path/project-a \
+  --workspace /absolute/path/project-b \
+  > qwen-serve.log 2>&1 &
 echo $!  # daemon PID; capture if you want to `kill` cleanly later
 ```
 
-The wrapping `bash -c '...'` ensures the daemon binds to `~/your-project` rather than wherever you happened to run the command. Without that `cd`, `qwen serve` defaults to `process.cwd()` and a `POST /session` from a client expecting your project workspace returns `400 workspace_mismatch` — silent foot-gun.
+Explicit absolute `--workspace` values keep the daemon independent of the shell's current directory. A client should select one of the advertised `capabilities.workspaces[]` entries and pass its cwd when creating a session.
 
 OK for one-off "let me run this in the background while I poke at the API" workflows. **Not recommended** for anything beyond a single session — no restart-on-crash, log file grows unbounded, no clean way to find the daemon if you forget the PID. Prefer tmux for interactive supervision or systemd / launchd for anything you want to outlast a reboot.
 
@@ -214,7 +249,7 @@ A daemon **restart** drops all in-memory sessions; clients reconnect and start f
 ## Out of scope (defers to v0.16.x or later)
 
 - **Containerized deployment** — Dockerfile, docker-compose, Kubernetes manifests, nginx + TLS reverse proxy, multi-instance token isolation. Defers to v0.16.x once an enterprise pilot is committed; the doc would otherwise rot from no-one-validating.
-- **Cross-host federation / multi-daemon coordination on one host** — `1 daemon = 1 workspace × N sessions` is enforced. Instance-path token keying + stale-token cleanup defer to v0.16.x.
+- **Cross-host federation / multi-daemon coordination on one host** — one daemon can host multiple registered workspace runtimes, but daemons do not coordinate. Instance-path token keying + stale-token cleanup defer to v0.16.x.
 - **Auto-generated daemon tokens** — alpha is BYO-token. Auto-gen + token-store infrastructure defers to v0.16.x.
 - **Windows native service** (`nssm`, Service Control Manager wrapper) — for now use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) and follow the systemd section above.