@qwen-code/qwen-code 0.19.11 → 0.19.12-nightly.20260719.86ad532de

package/bundled/batch/SKILL.md

@@ -126,23 +126,29 @@ You are a worker agent processing a batch of files.
 
 ### Example Invocation Pattern
 
+Set `run_in_background: false` on every worker call so all results return inline
+for aggregation in Step 4.
+
 ```
 <Agent tool call 1>
 description: "Process batch chunk 1/3"
 prompt: "You are a worker agent... [full prompt as above]"
 subagent_type: "general-purpose"
+run_in_background: false
 </Agent tool call 1>
 
 <Agent tool call 2>
 description: "Process batch chunk 2/3"
 prompt: "You are a worker agent... [full prompt as above]"
 subagent_type: "general-purpose"
+run_in_background: false
 </Agent tool call 2>
 
 <Agent tool call 3>
 description: "Process batch chunk 3/3"
 prompt: "You are a worker agent... [full prompt as above]"
 subagent_type: "general-purpose"
+run_in_background: false
 </Agent tool call 3>
 ```
 

package/bundled/qc-helper/docs/configuration/model-providers.md

@@ -237,6 +237,17 @@ This auth type supports not only OpenAI's official API but also any OpenAI-compa
 }
 ```
 
+For a vision model that can also follow the normal Qwen Code agent policy and use tools, opt in to full-turn image routing with both capabilities:
+
+```json
+"capabilities": {
+  "vision": true,
+  "agent": true
+}
+```
+
+When a text-only primary uses that model as its configured vision fallback, the complete image-bearing turn stays on that exact provider, model, and endpoint across tool calls and retries. The next independent turn returns to the primary, and each model request receives only media modalities supported by its target. Omit `agent` (or set it to `false`) to keep the safer Vision Bridge transcription flow.
+
 ### Local Self-Hosted Models (via OpenAI-compatible API)
 
 Most local inference servers (vLLM, Ollama, LM Studio, etc.) provide an OpenAI-compatible API endpoint. Configure them using the `openai` auth type with a local `baseUrl`:

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

@@ -87,7 +87,7 @@ Settings are organized into categories. Most settings should be placed within th
 | `general.gitCoAuthor.commit`               | boolean | Add a Co-authored-by trailer to git commit messages AND attach a per-file AI-attribution git note (`refs/notes/ai-attribution`) for commits made through Qwen Code. Disabling skips both.                                                                                                                                 | `true`      |
 | `general.gitCoAuthor.pr`                   | boolean | Append a Qwen Code attribution line to pull request descriptions when running `gh pr create`.                                                                                                                                                                                                                             | `true`      |
 | `general.defaultFileEncoding`              | enum    | Default encoding for new files. Use `"utf-8"` (default) for UTF-8 without BOM, or `"utf-8-bom"` for UTF-8 with BOM. Only change this if your project specifically requires BOM.                                                                                                                                           | `"utf-8"`   |
-| `general.voice.enabled`                    | boolean | Enable voice dictation in the prompt input. Also togglable with the `/voice` command. Requires a transcription model (`voiceModel`) to be configured.                                                                                                                                                                     | `false`     |
+| `general.voice.enabled`                    | boolean | Enable voice dictation in the prompt input. Also toggleable with the `/voice` command. Requires a transcription model (`voiceModel`) to be configured.                                                                                                                                                                    | `false`     |
 | `general.voice.mode`                       | enum    | How push-to-talk behaves: `"hold"` to talk while the key is held, or `"tap"` to start and tap (or pause) to stop and submit.                                                                                                                                                                                              | `"hold"`    |
 | `general.voice.language`                   | string  | Preferred spoken language for voice transcription (e.g. `"english"`, `"chinese"`). Leave empty to auto-detect.                                                                                                                                                                                                            | `""`        |
 | `general.voice.keytermsFile`               | string  | Path to a custom keyterms file (one term per line, `#` for comments) that biases voice transcription toward domain-specific terms. Relative paths resolve from the workspace root; defaults to `.qwen/voice-keyterms.txt` when present. Read only in trusted workspaces. Only applies to Qwen ASR models (`qwen3-asr-*`). | `""`        |
@@ -139,7 +139,7 @@ Settings are organized into categories. Most settings should be placed within th
 | `ui.disableWorkflowKeywordTrigger`      | boolean          | When `true`, mentioning the word `workflow` in a prompt no longer softly steers the turn toward the Workflow tool (and the Footer `workflow active` indicator is suppressed). Only applies when workflows are enabled.                                                                                                                                                                                                                                                                                                                             | `false`       |
 | `ui.enableUserFeedback`                 | boolean          | Show an optional feedback dialog after conversations to help improve Qwen performance.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `true`        |
 | `ui.compactInline`                      | boolean          | Compact tool display within each group instead of merging across groups. Requires `ui.compactMode` to be enabled. Requires restart.                                                                                                                                                                                                                                                                                                                                                                                                                | `false`       |
-| `ui.useTerminalBuffer`                  | boolean          | Render conversation history in an in-app scrollable viewport instead of the terminal scrollback buffer. Recommended if you see flicker, scroll-storm, or interface freeze on long sessions. Scroll with `Shift+↑/↓` (line), `PgUp`/`PgDn` (page), `Ctrl+Home/End` (top/bottom), or the mouse wheel. Does not use the host terminal scrollback while enabled; hold `Shift` (or `Option` on macOS) while dragging for native text selection.                                                                                                         | `false`       |
+| `ui.useTerminalBuffer`                  | boolean          | Render conversation history in an in-app scrollable viewport instead of the terminal scrollback buffer. Recommended if you see flicker, scroll-storm, or interface freeze on long sessions. Scroll with `Shift+↑/↓` (line), `PgUp`/`PgDn` (page), `Ctrl+Home/End` (top/bottom), or the mouse wheel. Does not use the host terminal scrollback while enabled; drag to select text (double/triple click selects a word/line), or hold `Shift` (or `Option` on macOS) while dragging for the terminal's own selection.                                | `false`       |
 | `ui.hideBuiltinWorktreeIndicator`       | boolean          | Hide the built-in `⎇ worktree-<branch> (<slug>)` line in the Footer. The worktree state is still passed to custom statusline scripts via the stdin payload. Keep at the default unless your custom statusline renders the worktree itself.                                                                                                                                                                                                                                                                                                         | `false`       |
 
 #### ide
@@ -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`                        | 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.maxToolCallsPerTurn`                        | integer | Per-turn tool-call cap (one model turn plus its tool-result continuations; blocking Stop-hook continuations such as `/goal` iterations start a fresh budget). When set explicitly, this value is a hard cap: the turn halts on the next tool call after it is reached (the released behavior). When left unset (default 100), the cap is adaptive: once the turn exceeds 100 it halts only when the model keeps repeating the same call (a stuck loop); a productive turn (diverse calls) continues up to a hard backstop of 1000, which always halts. The adaptive default applies to both the interactive TUI and non-interactive (`-p` / JSON / stream-JSON) core-client runs; the daemon/ACP path always treats the value as a hard cap. Always-on circuit breaker against runaway turns, independent of `model.skipLoopDetection`. 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` |
@@ -547,13 +547,14 @@ LSP server configuration is done through `.lsp.json` files in your project root
 >
 > **Experimental features.** These toggles gate in-development capabilities and may change or be removed in future releases.
 
-| Setting                                | Type    | Description                                                                                                                                                                                                                                                                                                                                                                  | Default |
-| -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `experimental.cron`                    | boolean | Enable in-session cron/loop tools (`cron_create`, `cron_list`, `cron_delete`) so the model can create recurring prompts. Can be disabled via the `QWEN_CODE_DISABLE_CRON=1` environment variable. Requires restart.                                                                                                                                                          | `true`  |
-| `experimental.cronRecurringMaxAgeDays` | number  | Days a recurring cron/loop job lives before auto-expiring (it fires one final time, then is deleted). Set to `0` to disable expiry so jobs run until deleted — useful for long-running daemon deployments. Can be overridden via the `QWEN_CODE_CRON_MAX_AGE_DAYS` environment variable. Requires restart.                                                                   | `7`     |
-| `experimental.agentTeam`               | boolean | Enable agent-team collaboration tools (`team_create`, `task_create`, `task_update`, `send_message`, etc.) for multi-agent coordination. Can also be enabled via `QWEN_CODE_ENABLE_AGENT_TEAM=1`. Requires restart.                                                                                                                                                           | `false` |
-| `experimental.artifact`                | boolean | Enable the Artifact tool, letting the model publish a self-contained HTML page and open it in the browser. Interactive, non-SDK sessions only. `QWEN_CODE_ENABLE_ARTIFACT=1` enables metadata-only `record_artifact` for non-SDK daemon sessions and also enables the Artifact tool in interactive sessions; `QWEN_CODE_DISABLE_ARTIFACT=1` disables both. Requires restart. | `false` |
-| `experimental.emitToolUseSummaries`    | boolean | Generate a short LLM-based label after each tool-call batch completes. See [Tool-Use Summaries](../features/tool-use-summaries). Requires a fast model to be configured (`fastModel`); silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`.                                                                         | `true`  |
+| Setting                                | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                  | Default |
+| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| `experimental.cron`                    | boolean | Enable in-session cron/loop tools (`cron_create`, `cron_list`, `cron_delete`) so the model can create recurring prompts. Can be disabled via the `QWEN_CODE_DISABLE_CRON=1` environment variable. Requires restart.                                                                                                                                                                                          | `true`  |
+| `experimental.todoStopGuard`           | boolean | Allow daemon and ACP sessions to continue after a natural model stop when the current work chain successfully wrote an unfinished top-level Todo list. Adds at most two consecutive primary-model calls without new user input; mid-turn user input starts a fresh two-attempt stage. It is not restored after process restart and is forced off in safe, bare, and Approval `plan` modes. Requires restart. | `false` |
+| `experimental.cronRecurringMaxAgeDays` | number  | Days a recurring cron/loop job lives before auto-expiring (it fires one final time, then is deleted). Set to `0` to disable expiry so jobs run until deleted — useful for long-running daemon deployments. Can be overridden via the `QWEN_CODE_CRON_MAX_AGE_DAYS` environment variable. Requires restart.                                                                                                   | `7`     |
+| `experimental.agentTeam`               | boolean | Enable agent-team collaboration tools (`team_create`, `task_create`, `task_update`, `send_message`, etc.) for multi-agent coordination. Can also be enabled via `QWEN_CODE_ENABLE_AGENT_TEAM=1`. Requires restart.                                                                                                                                                                                           | `false` |
+| `experimental.artifact`                | boolean | Enable artifact tools. Enabled by default. In interactive, non-SDK sessions, the model can publish a self-contained HTML page as an interactive Artifact and open it in the browser. Non-SDK daemon sessions can use metadata-only `record_artifact`. Set this to `false` or use `QWEN_CODE_DISABLE_ARTIFACT=1` to disable both. Requires restart.                                                           | `true`  |
+| `experimental.emitToolUseSummaries`    | boolean | Generate a short LLM-based label after each tool-call batch completes. See [Tool-Use Summaries](../features/tool-use-summaries). Requires a fast model to be configured (`fastModel`); silently skipped otherwise. Can be overridden per-session with `QWEN_CODE_EMIT_TOOL_USE_SUMMARIES=0` or `=1`.                                                                                                         | `true`  |
 
 #### mcpServers
 

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

@@ -92,23 +92,37 @@ Controls how conversation sessions are managed:
 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.
+- `记住：默认使用 staging 环境` is the deterministic form and saves exactly one
+  scalar entry for the current chat or thread.
+- To save several separate facts in one request, use a natural phrase routed
+  through the classifier. For example:
+  `请记住这三条约定：使用 staging；发布前测试；优先中文回复` creates entries
+  that you can manage independently. Exact duplicate facts are skipped and
+  reported without creating another entry. Requests containing credential-like
+  text are rejected; remove secrets and save the non-sensitive facts separately.
 - `查看记忆` 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.
+  Natural updates and removals first show the proposed change. Confirm an
+  update with `确认更新记忆` or `confirm memory update`, or a removal with
+  `确认删除记忆` or `confirm memory removal`, within 60 seconds. Exact-ID
+  updates and removals remain immediate and do not need 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.
+is no pending selection for an ambiguous result: 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.
+
+Pending update, removal, and clear confirmations apply only to the sender and
+chat or thread that created them. A newer clear, natural update, or natural
+removal proposal replaces an older pending one for that sender and target.
+Pending confirmations are discarded when the channel process restarts.
 
 The legacy slash aliases `/remember-channel`, `/channel-memory`, and
 `/forget-channel` have been removed. They are no longer channel-memory
@@ -130,10 +144,9 @@ 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.
+Channel memory does not automatically learn facts from normal conversation 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
 
@@ -160,7 +173,7 @@ When `senderPolicy` is set to `"pairing"`, unknown senders go through an approva
 qwen channel pairing approve my-channel VEQDDWXJ
 ```
 
-Once approved, the user's ID is saved to `~/.qwen/channels/<name>-allowlist.json` and all future messages go through normally.
+Once approved, the user's ID is saved to the channel's workspace-scoped allowlist (`~/.qwen/channels/<workspace-scope>/<name>-allowlist.json`) and all future messages go through normally. Pairing state is scoped per workspace, so two workspaces using the same channel name keep separate approvals.
 
 ### Pairing CLI Commands
 
@@ -172,13 +185,15 @@ qwen channel pairing list my-channel
 qwen channel pairing approve my-channel <CODE>
 ```
 
+Run these from the channel's workspace directory (or pass `--cwd <dir>`) — pairing state is stored per workspace.
+
 ### Pairing Rules
 
 - Codes are 8 characters, uppercase, using an unambiguous alphabet (no `0`/`O`/`1`/`I`)
 - Codes expire after 1 hour
 - Maximum 3 pending requests per channel at a time — additional requests are ignored until one expires or is approved
 - Users listed in `allowedUsers` in `settings.json` always skip pairing
-- Approved users are stored in `~/.qwen/channels/<name>-allowlist.json` — treat this file as sensitive
+- Approved users are stored per workspace in `~/.qwen/channels/<workspace-scope>/<name>-allowlist.json` — treat this file as sensitive
 
 ## Group Chats
 
@@ -473,6 +488,48 @@ Example channel config:
 
 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.
 
+Daemon-managed DingTalk, Feishu, Telegram, and WeCom channels dynamically observe contacts from authorized inbound messages. List contacts observed in the primary workspace during the default seven-day freshness window:
+
+```bash
+curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
+  http://127.0.0.1:4170/workspace/channel/observed-contacts
+```
+
+Use `GET /workspaces/:workspace/channel/observed-contacts` to select another registered, trusted workspace. Add `?freshWithinSeconds=N` to choose a window from one second through 365 days. The daemon advertises this API with the `workspace_channel_observed_contacts` capability.
+
+The response returns complete platform IDs and labels. Group labels use names already present in accepted inbound messages when available: DingTalk supplies `conversationTitle`, and Telegram supplies `chat.title`. Feishu and WeCom group labels currently fall back to their complete IDs; no platform directory or group-detail API is queried. Topic labels also fall back to complete IDs. Each `lastObservedAt` is a canonical ISO 8601 UTC timestamp with millisecond precision; clients can convert it to the user's local time zone for display. Top-level `users` contains users observed in direct messages. `groups` contains observed group conversations, `groups[].users` contains users observed in each group, and `groups[].topics[].users` contains users observed in Feishu or Telegram topics:
+
+```json
+{
+  "users": [
+    {
+      "channelName": "feishu-main",
+      "label": "Example User",
+      "id": "ou_complete_user_id",
+      "lastObservedAt": "2026-07-17T08:00:00.000Z"
+    }
+  ],
+  "groups": [
+    {
+      "channelName": "feishu-main",
+      "label": "oc_complete_chat_id",
+      "id": "oc_complete_chat_id",
+      "lastObservedAt": "2026-07-17T08:05:00.000Z",
+      "users": [
+        {
+          "label": "Example User",
+          "id": "ou_complete_user_id",
+          "lastObservedAt": "2026-07-17T08:05:00.000Z"
+        }
+      ],
+      "topics": []
+    }
+  ]
+}
+```
+
+These nested users are observed participants, not authoritative group membership. Only messages that pass direct/group, mention, sender, and pairing gates are recorded. Repeated observations refresh labels and timestamps; passive observation cannot detect a leave or deletion until the relationship becomes stale. Message content is never stored. The bounded registry lives under `$QWEN_HOME/channels/daemon/<workspaceHash>/observed-contacts.json`, outside the workspace checkout and partitioned per workspace. Its 500-observation limit is shared by all channels and conversations in that workspace, and observations older than 365 days are removed on the next accepted write. If the registry becomes malformed or uses an unsupported version, delete that file to reset it; accepted traffic recreates it. Webhook configuration and delivery are unchanged.
+
 Start `qwen serve` with the channel worker enabled:
 
 ```bash

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -14,16 +14,16 @@ Subagents are independent AI assistants that:
 
 ## Fork Subagent
 
-In addition to named subagents, Qwen Code supports **forking** — selected explicitly with `subagent_type: "fork"` (available in interactive sessions). A fork inherits the parent's full conversation context and runs detached in the background. Omitting `subagent_type` does **not** fork; it launches the general-purpose subagent, which runs to completion and returns its result inline.
+In addition to named subagents, Qwen Code supports **forking** — selected explicitly with `subagent_type: "fork"` (available in interactive sessions). A fork inherits the parent's full conversation context and runs detached in the background. Omitting `subagent_type` does **not** fork; it launches the general-purpose subagent. Top-level named subagents run in the background by default and deliver their results through completion notifications. Set `run_in_background: false` when the current turn must wait for the result inline.
 
 ### How Fork Differs from Named Subagents
 
-|               | Named Subagent                    | Fork Subagent                                         |
-| ------------- | --------------------------------- | ----------------------------------------------------- |
-| Context       | Starts fresh, no parent history   | Inherits parent's full conversation history           |
-| System prompt | Uses its own configured prompt    | Uses parent's exact system prompt (for cache sharing) |
-| Execution     | Blocks the parent until done      | Runs in background, parent continues immediately      |
-| Use case      | Specialized tasks (testing, docs) | Parallel tasks that need the current context          |
+|               | Named Subagent                                                 | Fork Subagent                                         |
+| ------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
+| Context       | Starts fresh, no parent history                                | Inherits parent's full conversation history           |
+| System prompt | Uses its own configured prompt                                 | Uses parent's exact system prompt (for cache sharing) |
+| Execution     | Background by default; supports an explicit foreground opt-out | Always detached; parent continues immediately         |
+| Use case      | Specialized tasks (testing, docs)                              | Parallel tasks that need the current context          |
 
 ### When Fork is Used
 
@@ -61,7 +61,7 @@ Fork children cannot create further forks. This is enforced at runtime — if a
 1. **Configuration**: You create Subagents configurations that define their behavior, tools, and system prompts
 2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents — or fork itself (`subagent_type: "fork"`) when it wants to inherit the full conversation context and discard the intermediate output
 3. **Execution**: Subagents work independently, using their configured tools to complete tasks
-4. **Results**: They return results and execution summaries back to the main conversation
+4. **Results**: Background runs notify the main conversation when they finish; foreground opt-outs return results inline
 
 ## Getting Started
 

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

@@ -181,8 +181,8 @@ The `agent` tool accepts an optional `isolation: "worktree"` parameter. When set
 
 Two constraints:
 
-- `isolation: "worktree"` requires a `subagent_type` — forked sub-agents (no `subagent_type`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
-- Background agents (`run_in_background: true`) work fine with isolation; the cleanup runs when the agent reports completion.
+- `isolation: "worktree"` requires a non-fork `subagent_type` — forked sub-agents (`subagent_type: "fork"`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
+- Agents using `isolation: "worktree"` follow the default background behavior; the cleanup runs when the agent reports completion. Set `run_in_background: false` for an inline result. Caller-owned `working_dir` launches remain foreground by default because their lifecycle is managed externally.
 
 ### Automatic Stale Cleanup
 

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.