@qwen-code/qwen-code 0.18.2 → 0.18.3-nightly.20260621.6b2f800ab

package/bundled/qc-helper/docs/extension/introduction.md

@@ -18,6 +18,16 @@ You can manage extensions at runtime within the interactive CLI using `/extensio
 | `/extensions install <source>`        | Install an extension from a git URL, local path, npm package, or marketplace |
 | `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser            |
 
+#### The interactive extension manager
+
+Running `/extensions` (or `/extensions manage`) opens an interactive manager with three tabs. Press `Tab` or the `←`/`→` arrows to switch between them.
+
+- **Discover** — browse plugins from your configured marketplace sources. Type to search, `Enter` to view a plugin's details, and install it (you'll be asked to choose an install scope). Press `Ctrl+R` to re-fetch the listings, and `Esc` to go back.
+- **Installed** — your installed extensions, grouped by scope (**User level**, **Project level**, and favorites). Use `↑`/`↓` to navigate, `Space` to enable/disable an extension, `f` to favorite it, and `Enter` to open its details. MCP servers bundled by an extension appear nested under their parent extension with live connection status; you can enable or disable each server individually from there.
+- **Sources** — manage the marketplace sources that feed the Discover tab. Use `↑`/`↓` to navigate, `Enter` to select a source, and `d` to remove one. These are the same sources managed by the `qwen extensions sources` CLI commands described below.
+
+Changes made here hot-reload immediately, without restarting Qwen Code.
+
 ### CLI Extension Management
 
 You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.
@@ -133,6 +143,34 @@ qwen extensions install /path/to/your/extension
 
 Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
 
+#### Choosing an install scope
+
+By default, an installed extension is enabled globally (user scope). Pass `--scope project` to enable it only for the current workspace:
+
+```bash
+qwen extensions install <source> --scope project
+```
+
+`--scope workspace` is accepted as an alias of `--scope project`. This matches the scope choice offered when installing from the `/extensions manage` Discover tab.
+
+### Managing marketplace sources
+
+Marketplace sources (Claude plugin marketplaces) power the Discover tab in `/extensions manage`. You can manage them from the CLI as well:
+
+```bash
+# Add a marketplace (owner/repo, git URL, https URL to marketplace.json, or local path)
+qwen extensions sources add <source>
+
+# List configured marketplaces
+qwen extensions sources list
+
+# Re-fetch a marketplace's plugin listing
+qwen extensions sources update <name>
+
+# Remove a marketplace
+qwen extensions sources remove <name>
+```
+
 ### Uninstalling an extension
 
 To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:

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

@@ -52,6 +52,8 @@ If you are in Normal Mode, **Shift+Tab** (or **Tab** on Windows) first switches
 
 The `/plan` command provides a quick shortcut for entering and exiting Plan Mode:
 
+Regular planning requests do not switch modes by themselves. If you want the read-only Plan Mode workflow, use `/plan`, the keyboard shortcut, or set the approval mode to `plan` explicitly.
+
 ```bash
 /plan                          # Enter plan mode
 /plan refactor the auth module # Enter plan mode and start planning

package/bundled/qc-helper/docs/features/channels/_meta.ts

@@ -4,5 +4,6 @@ export default {
   weixin: 'WeChat',
   dingtalk: 'DingTalk',
   feishu: 'Feishu',
+  qqbot: 'QQ Bot',
   plugins: 'Plugins',
 };

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

@@ -1,6 +1,6 @@
 # Channels
 
-Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, WeChat, or DingTalk, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI.
+Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, WeChat, QQ, or DingTalk, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI.
 
 ## How It Works
 
@@ -15,7 +15,7 @@ All channels share one agent process with isolated sessions per user. Each chann
 
 ## Quick Start
 
-1. Set up a bot on your messaging platform (see channel-specific guides: [Telegram](./telegram), [WeChat](./weixin), [DingTalk](./dingtalk))
+1. Set up a bot on your messaging platform (see channel-specific guides: [Telegram](./telegram), [WeChat](./weixin), [QQ Bot](./qqbot), [DingTalk](./dingtalk))
 2. Add the channel configuration to `~/.qwen/settings.json`
 3. Run `qwen channel start` to start all channels, or `qwen channel start <name>` for a single channel
 
@@ -49,7 +49,7 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 
 | Option                   | Required | Description                                                                                                                                    |
 | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`                   | Yes      | Channel type: `telegram`, `weixin`, `dingtalk`, or a custom type from an extension (see [Plugins](./plugins))                                  |
+| `type`                   | Yes      | Channel type: `telegram`, `weixin`, `qq`, `dingtalk`, `feishu`, or a custom type from an extension (see [Plugins](./plugins))                  |
 | `token`                  | Telegram | Bot token. Supports `$ENV_VAR` syntax to read from environment variables. Not needed for WeChat or DingTalk                                    |
 | `clientId`               | DingTalk | DingTalk AppKey. Supports `$ENV_VAR` syntax                                                                                                    |
 | `clientSecret`           | DingTalk | DingTalk AppSecret. Supports `$ENV_VAR` syntax                                                                                                 |
@@ -292,7 +292,7 @@ Channels support slash commands. These are handled locally (no agent round-trip)
 
 All other slash commands (e.g., `/compress`, `/summary`) are forwarded to the agent.
 
-These commands work on all channel types (Telegram, WeChat, DingTalk).
+These commands work on all channel types (Telegram, WeChat, QQ, DingTalk).
 
 ## Running
 

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

@@ -0,0 +1,179 @@
+# QQ Bot (QQ机器人)
+
+This guide covers setting up a Qwen Code channel on QQ via the official QQ Bot Open Platform API.
+
+## Prerequisites
+
+- A QQ account (mobile app for scanning the QR code)
+
+## Setup
+
+### QR Code Login
+
+Start the channel — the first time it will show a QR code. Scan it with your QQ app to activate. No developer account or manual registration needed. Credentials are saved and reused automatically.
+
+```json
+{
+  "channels": {
+    "my-qq": {
+      "type": "qq"
+    }
+  }
+}
+```
+
+```bash
+qwen channel start my-qq
+# Scan the QR code in the terminal with your QQ app
+```
+
+### Manual Configuration (Developer Portal)
+
+You can also use credentials from the [QQ Bot Open Platform](https://q.qq.com/) developer portal if you already have an app registered there:
+
+```json
+{
+  "channels": {
+    "my-qq": {
+      "type": "qq",
+      "appID": "YOUR_APP_ID",
+      "appSecret": "$QQ_APP_SECRET"
+    }
+  }
+}
+```
+
+Set the secret as an environment variable:
+
+```bash
+export QQ_APP_SECRET=<your-app-secret>
+```
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "my-qq": {
+      "type": "qq",
+      "appID": "YOUR_APP_ID",
+      "appSecret": "$QQ_APP_SECRET",
+      "sandbox": false,
+      "senderPolicy": "open",
+      "sessionScope": "user",
+      "cwd": "/path/to/your/project",
+      "instructions": "你是一个通过 QQ Bot 对话的 AI 助手。回复控制在 2000 字符以内。",
+      "blockStreaming": "on",
+      "groupPolicy": "disabled",
+      "groups": {
+        "*": { "requireMention": true }
+      }
+    }
+  }
+}
+```
+
+### QQ-Specific Options
+
+| Option      | Default | Description                                                                       |
+| ----------- | ------- | --------------------------------------------------------------------------------- |
+| `appID`     | —       | QQ Bot AppID from developer portal. If omitted, QR code login is used.            |
+| `appSecret` | —       | QQ Bot AppSecret. Supports `$ENV_VAR` syntax. If omitted, QR code login is used.  |
+| `sandbox`   | `false` | Set to `true` to use the QQ sandbox API environment (`sandbox.api.sgroup.qq.com`) |
+
+All standard channel options (see [Channel Overview](./overview#options)) are also supported:
+`senderPolicy`, `allowedUsers`, `sessionScope`, `cwd`, `instructions`, `groupPolicy`, `groups`, `dispatchMode`, `blockStreaming`, `blockStreamingChunk`, `blockStreamingCoalesce`.
+
+## Running
+
+```bash
+# Start only the QQ channel
+qwen channel start my-qq
+
+# Or start all configured channels together
+qwen channel start
+```
+
+Open QQ and send a message to your bot. You should see the response arrive in your chat.
+
+## Group Chats
+
+To use the bot in QQ groups:
+
+1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
+2. Add the bot to a QQ group via the QQ Bot Open Platform dashboard or by having a group admin invite it
+3. Group members must **@mention** the bot to trigger a response
+
+QQ Bot API V2 only delivers group messages that @mention the bot — the bot does not see all group messages. By default, `requireMention` is `true` and should be left that way for QQ.
+
+See [Group Chats](./overview#group-chats) for full details on group policies and mention gating.
+
+## Markdown Support
+
+The QQ Bot channel supports Markdown formatting (`msg_type=2`). The agent's Markdown responses are sent as-is, and QQ renders them with rich formatting (bold, italic, code blocks, links, lists).
+
+If the QQ server rejects a Markdown message for any reason, the channel automatically retries it as plain text — so your messages always go through even if the bot's Markdown capability is restricted server-side.
+
+This is the opposite of the WeChat channel, which strips all Markdown. You can let the agent use full Markdown with the QQ channel.
+
+## Token Management
+
+Access tokens expire after approximately 2 hours. The channel automatically refreshes them at 80% of their TTL (typically ~1.6 hours). If a refresh fails, it retries after 60 seconds.
+
+Token refresh continues across WebSocket reconnects — the channel never goes offline due to an expired token as long as the AppID and AppSecret remain valid.
+
+## Connection Resilience
+
+- **Auto-reconnect:** On WebSocket disconnect, the channel retries with exponential backoff (up to 20 attempts, max 30 seconds between retries)
+- **Session resume:** If the WebSocket drops briefly, the channel uses QQ's `RESUME` opcode to restore the session without losing in-flight messages
+- **Cross-server context continuation:** Chat sessions and routing state are persisted to disk. If the daemon restarts, conversations continue from where they left off
+- **Heartbeat monitoring:** HEARTBEAT_ACK timeouts are detected and force a reconnection to avoid zombie connections
+- **Message deduplication:** Replayed messages after a reconnect are detected and skipped
+
+## Tips
+
+- **Use Markdown freely** — Unlike WeChat, QQ renders Markdown natively. Bold, code blocks, lists, and links all work.
+- **Keep responses under 2000 characters** — Longer responses are automatically split into chunks. Adding a length hint to your instructions helps the agent stay concise.
+- **Sandbox for testing** — Set `"sandbox": true` to use the sandbox API during development. No production messages will be affected.
+- **Restrict access** — Use `senderPolicy: "allowlist"` for a fixed set of QQ users, or `"pairing"` to approve new users from the CLI. See [DM Pairing](./overview#dm-pairing) for details.
+
+## Key Differences from Telegram
+
+| Area             | QQ Bot                                      | Telegram                                      |
+| ---------------- | ------------------------------------------- | --------------------------------------------- |
+| Authentication   | QR code login or AppID/AppSecret            | Static bot token from BotFather               |
+| Markdown         | Native QQ Markdown with plaintext fallback  | HTML-formatted from agent Markdown            |
+| Token lifecycle  | 2h TTL, auto-refresh at 80%                 | Permanent bot token                           |
+| Group messages   | Only @mention messages are delivered to bot | Bot sees all messages (with privacy mode off) |
+| Typing indicator | Not available (QQ API limitation)           | "Working..." message                          |
+| Sandbox mode     | Supported for testing                       | Not available                                 |
+
+## Troubleshooting
+
+### Bot doesn't respond
+
+- Check the terminal output for errors
+- Verify the channel is running (`qwen channel status`)
+- If using `senderPolicy: "allowlist"`, make sure your QQ user ID is in `allowedUsers`
+- On first start, a QR code will appear in the terminal — scan it with your QQ app
+
+### Bot doesn't respond in groups
+
+- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
+- **You must @mention the bot** — QQ only delivers messages that tag the bot
+- Verify the bot has been added to the group
+
+### QR code login is stuck
+
+- The QR code is displayed in the terminal. Scan it with your QQ mobile app (Me → Scan)
+- If the QR code expires (typically after a few minutes), restart the channel to get a new one
+
+### Markdown messages appear as plain text
+
+- The QQ server may have rejected the Markdown message and the channel silently fell back to plain text. Check the terminal for `"Markdown rejected"` log messages
+- This is unusual on the QQ Bot Open Platform but can happen if the bot's Markdown capability is restricted server-side
+
+### Token expired after long downtime
+
+- If the channel is offline for more than 2 hours, the access token will have expired. The channel fetches a fresh token on reconnect — no action needed
+- If the AppSecret itself is invalid (e.g., rotated in the developer portal), update the `appSecret` field or delete `~/.qwen/channels/<name>-credentials.json` to re-trigger QR code login

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

@@ -94,6 +94,7 @@ Commands for managing AI tools and models.
 | `/arena`         | Manage Arena sessions                         | `/arena start`, `/arena status`               |
 | `/goal`          | Set a goal — keep working until condition met | `/goal <condition>`, `/goal clear`            |
 | `/tasks`         | List background tasks                         | `/tasks`                                      |
+| `/workflows`     | Inspect workflow runs                         | `/workflows`, `/workflows <runId>`            |
 | `/lsp`           | Show LSP server status                        | `/lsp`                                        |
 | `/trust`         | Manage folder trust settings                  | `/trust`                                      |
 
@@ -526,3 +527,51 @@ Requirements:
 | Shell Escaping         | Prevent command injection  | Automatic processing   |
 | Execution Confirmation | Avoid accidental execution | Dialog confirmation    |
 | Error Reporting        | Help diagnose issues       | View error information |
+
+## 5. CLI Subcommands
+
+These commands are run from the shell as `qwen <subcommand>` before starting an interactive session.
+
+### Session Management
+
+| Command              | Description                       | Usage Examples                                               |
+| -------------------- | --------------------------------- | ------------------------------------------------------------ |
+| `qwen sessions list` | List recent conversation sessions | `qwen sessions list`, `qwen sessions list --json --limit 50` |
+
+#### `qwen sessions list`
+
+Lists your recent Qwen Code sessions with metadata.
+
+**Flags:**
+
+| Flag      | Type    | Default | Description                                     |
+| --------- | ------- | ------- | ----------------------------------------------- |
+| `--json`  | boolean | `false` | Output as JSON Lines (one JSON object per line) |
+| `--limit` | number  | `20`    | Maximum number of sessions to show              |
+
+**Human-readable output (default):**
+
+A table with columns: SESSION ID, STARTED (UTC timestamp), TITLE, BRANCH, PROMPT.
+
+**JSON output (`--json`):**
+
+Outputs JSON Lines on stdout. Each line is a JSON object with fields:
+
+```
+sessionId, startTime, mtime, prompt, gitBranch, customTitle, titleSource, filePath, cwd
+```
+
+The "has more sessions" hint is emitted via stderr so piping to `jq` remains safe.
+
+**Examples:**
+
+```bash
+# Show last 20 sessions (default)
+qwen sessions list
+
+# Show last 50 sessions
+qwen sessions list --limit 50
+
+# Output as JSON for scripting
+qwen sessions list --json | jq .
+```

package/bundled/qc-helper/docs/features/followup-suggestions.md

@@ -1,12 +1,12 @@
 # Followup Suggestions
 
-Qwen Code can predict what you want to type next and show it as ghost text in the input area. This feature uses an LLM call to analyze the conversation context and generate a natural next step suggestion.
+Qwen Code can predict what you want to type next and show it as placeholder text in the input area. This feature uses an LLM call to analyze the conversation context and generate a natural next step suggestion.
 
 This feature works end-to-end in the CLI. In the WebUI, the hook and UI plumbing are available, but host applications must trigger suggestion generation and wire the followup state for suggestions to appear.
 
 ## How It Works
 
-After Qwen Code finishes responding, a suggestion appears as dimmed text in the input area after a short delay (~300ms). For example, after fixing a bug, you might see:
+After Qwen Code finishes responding, a suggestion appears as dimmed placeholder text in the input area after a short delay (~300ms). For example, after fixing a bug, you might see:
 
 ```
 > run the tests
@@ -19,10 +19,12 @@ The suggestion is generated by sending the conversation history to the model, wh
 | Key           | Action                                           |
 | ------------- | ------------------------------------------------ |
 | `Tab`         | Accept the suggestion and fill it into the input |
-| `Enter`       | Accept the suggestion and submit it immediately  |
+| `Enter`       | Accept the suggestion and fill it into the input |
 | `Right Arrow` | Accept the suggestion and fill it into the input |
 | Any typing    | Dismiss the suggestion and type normally         |
 
+`Enter` fills the input rather than submitting, so accepting a suggested slash command (e.g. `/clear`) never auto-executes — you submit it yourself with a second `Enter`.
+
 ## When Suggestions Appear
 
 Suggestions are generated when all of the following conditions are met:
@@ -32,7 +34,7 @@ Suggestions are generated when all of the following conditions are met:
 - There are no errors in the most recent response
 - No confirmation dialogs are pending (e.g., shell confirmation, permissions)
 - The approval mode is not set to `plan`
-- The feature is enabled in settings (disabled by default — set `ui.enableFollowupSuggestions` to `true` to turn it on)
+- The feature is enabled (on by default — set `ui.enableFollowupSuggestions` to `false` to turn it off)
 
 Suggestions will not appear in non-interactive mode (e.g., headless/SDK mode).
 
@@ -44,7 +46,7 @@ Suggestions are automatically dismissed when:
 
 ## Fast Model
 
-By default, suggestions use the same model as your main conversation. For faster and cheaper suggestions, configure a dedicated fast model:
+By default, suggestions use the same model as your main conversation. For lower-latency suggestions, configure a dedicated fast model:
 
 ### Via command
 
@@ -64,6 +66,8 @@ Or use `/model --fast` (without a model name) to open a selection dialog.
 
 The fast model is used for prompt suggestions and speculative execution. When not configured, the main conversation model is used as fallback.
 
+> **Cost note:** A fast model lowers latency, but it does not always lower cost. Suggestion generation reuses your conversation's prefix cache (via `ui.enableCacheSharing`, on by default) — but a prefix cache is per-model. Pointing `fastModel` at a different model forks to a separate cache, so the whole conversation history is re-billed as uncached input on the fast model. On long conversations, the default (main model + shared cache) can be **cheaper** than a fast model, since most of the history is billed at the discounted cached rate. Set `fastModel` when latency matters more than per-turn cost.
+
 Thinking/reasoning mode is automatically disabled for all background tasks (suggestion generation and speculation), regardless of your main model's thinking configuration. This avoids wasting tokens on internal reasoning that isn't needed for these tasks.
 
 ## Configuration
@@ -72,7 +76,7 @@ These settings can be configured in `settings.json`:
 
 | Setting                        | Type    | Default | Description                                                        |
 | ------------------------------ | ------- | ------- | ------------------------------------------------------------------ |
-| `ui.enableFollowupSuggestions` | boolean | `false` | Enable or disable followup suggestions                             |
+| `ui.enableFollowupSuggestions` | boolean | `true`  | Enable or disable followup suggestions                             |
 | `ui.enableCacheSharing`        | boolean | `true`  | Use cache-aware forked queries to reduce cost (experimental)       |
 | `ui.enableSpeculation`         | boolean | `false` | Speculatively execute suggestions before submission (experimental) |
 | `fastModel`                    | string  | `""`    | Model for prompt suggestions and speculative execution             |

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

@@ -384,7 +384,8 @@ Hook output supports three categories of fields:
   "permission_mode": "default | plan | auto_edit | yolo",
   "tool_name": "name of the tool being executed",
   "tool_input": "object containing the tool's input parameters",
-  "tool_use_id": "unique identifier for this tool use instance"
+  "tool_use_id": "unique identifier for this tool use instance (internal format, e.g., toolu_xxx)",
+  "tool_call_id": "original API call ID from the LLM provider (e.g., call_xxx for OpenAI/Qwen) (optional)"
 }
 ```
 
@@ -422,7 +423,8 @@ Hook output supports three categories of fields:
   "tool_name": "name of the tool that was executed",
   "tool_input": "object containing the tool's input parameters",
   "tool_response": "object containing the tool's response",
-  "tool_use_id": "unique identifier for this tool use instance"
+  "tool_use_id": "unique identifier for this tool use instance (internal format, e.g., toolu_xxx)",
+  "tool_call_id": "original API call ID from the LLM provider (e.g., call_xxx for OpenAI/Qwen) (optional)"
 }
 ```
 
@@ -453,7 +455,8 @@ Hook output supports three categories of fields:
 ```json
 {
   "permission_mode": "default | plan | auto_edit | yolo",
-  "tool_use_id": "unique identifier for the tool use",
+  "tool_use_id": "unique identifier for the tool use (internal format, e.g., toolu_xxx)",
+  "tool_call_id": "original API call ID from the LLM provider (e.g., call_xxx for OpenAI/Qwen) (optional)",
   "tool_name": "name of the tool that failed",
   "tool_input": "object containing the tool's input parameters",
   "error": "error message describing the failure",

package/bundled/qc-helper/docs/features/status-line.md

@@ -88,8 +88,8 @@ Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
 | `model`                |         | Current model name without reasoning level                         |
 | `git-branch`           | Yes     | Current Git branch name (hidden when not in a git repo)            |
 | `context-remaining`    | Yes     | Percentage of context window remaining (e.g. `Context 65.7% left`) |
-| `total-input-tokens`   |         | Total input tokens used in session (e.g. `30.0k in`)               |
-| `total-output-tokens`  |         | Total output tokens used in session (e.g. `5.0k out`)              |
+| `total-input-tokens`   |         | Cumulative input tokens used in session (e.g. `30.0k total in`)    |
+| `total-output-tokens`  |         | Cumulative output tokens used in session (e.g. `5.0k total out`)   |
 | `current-dir`          | Yes     | Current working directory                                          |
 | `project-name`         |         | Project name (basename of working directory)                       |
 | `pull-request-number`  |         | Open PR number for the current branch (requires `gh` CLI)          |
@@ -103,6 +103,8 @@ Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
 
 Items marked **Default** are pre-selected when you first open the `/statusline` dialog.
 
+`total-input-tokens` and `total-output-tokens` are session totals. They add up token usage across turns, so input tokens can grow quickly because each new model request includes the current conversation context again. Use `used-tokens` when you want the current prompt size instead of cumulative session spend.
+
 ### Example output
 
 With the default items, the status line looks like:

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

@@ -10,6 +10,7 @@ Run Qwen Code as a local HTTP daemon so multiple clients (IDE plugins, web UIs,
 
 ## What it gives you
 
+- **Built-in Web Shell UI** — `qwen serve` serves the browser-based Web Shell at its root (`http://127.0.0.1:4170/`) out of the box; run `qwen serve --open` to launch it in your browser automatically. It is served on the same origin as the API, so no second port or reverse proxy is needed. Pass `--no-web` for an API-only daemon.
 - **One agent process, many clients** — under the default `sessionScope: 'single'`, every client connecting to the daemon shares one ACP session. Live cross-client collaboration on the same conversation, the same file diffs, the same permission prompts.
 - **Reconnect-safe streaming** — SSE with `Last-Event-ID` reconnect lets a client drop and pick up exactly where it left off (within the ring's replay window).
 - **First-responder permissions** — when the agent asks for permission to run a tool, every connected client sees the request; whichever client answers first wins.
@@ -63,6 +64,8 @@ qwen serve
 
 The default bind is `127.0.0.1:4170`. Bearer auth is **off** on loopback so local development "just works". The daemon binds to the current working directory; use `--workspace /path/to/dir` to override.
 
+**Open the Web Shell UI.** Browse to `http://127.0.0.1:4170/` (or start the daemon with `qwen serve --open` to launch it automatically) for the full browser terminal — chat, diffs, tool calls, and permission prompts. The UI is served at the daemon root on the same origin as the API. The rest of this guide uses raw HTTP so you can script against the API directly.
+
 ### 2. Sanity-check it
 
 ```bash
@@ -161,7 +164,7 @@ curl -N http://127.0.0.1:4170/session/$SESSION_ID/events
 The `data:` line is the **full event envelope** — `{id?, v, type, data, originatorClientId?}` — JSON-stringified on a single line. The ACP payload (the `sessionUpdate` block in this example) sits under `data` inside that envelope. The SSE-level `id:` / `event:` lines are convenience for EventSource clients; the same values appear inside the JSON envelope so raw-`fetch` consumers get them too.
 
 Open this **before** sending the prompt — the SSE replay buffer holds the
-last 4000 events so a late subscriber can catch up via `Last-Event-ID`,
+last 8000 events so a late subscriber can catch up via `Last-Event-ID`,
 but for the simple "watch a single prompt" case it's easiest to subscribe
 first and let it stream live.
 
@@ -230,6 +233,8 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
 | `--mcp-budget-mode <m>`                 | `warn` / `off`  | How `--mcp-client-budget` is enforced. `warn` (default when budget set): no refusal, snapshot's `budgets[0].status` flips to `warning` at ≥75% of budget. `enforce`: connects past the cap are refused, per-server cell shows `disabledReason: 'budget'`, deterministic by `mcpServers` declaration order. `off` (default when budget unset): pure observability. Boot rejects `enforce` without a budget.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `--http-bridge`                         | `true`          | Stage 1 mode: one `qwen --acp` child per daemon (bound to one workspace at boot, per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02); N sessions multiplex onto that child via ACP `newSession()`. Stage 2 native in-process becomes available later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `--allow-origin <pat>`                  | —               | T2.4 ([#4514](https://github.com/QwenLM/qwen-code/issues/4514)). Cross-origin allowlist for browser webui clients. Repeatable. Each value is `*` (any origin — boot refuses if no bearer token is configured; `--require-auth` on loopback is recommended so `/health` and `/demo` are also bearer-gated, since both are pre-auth on loopback by default) or a canonical URL origin (`<scheme>://<host>[:<port>]`, no trailing slash / path / userinfo / query). **Subdomain wildcards (`https://*.example.com`) are intentionally unsupported** — list each subdomain explicitly, or use `*` with a configured token (and `--require-auth` for full hardening). Matched origins receive CORS response headers (`Access-Control-Allow-Origin`, `Vary: Origin`, methods, headers, max-age, and exposed `Retry-After`); unmatched origins still get a 403 with the same envelope as today's wall. `Origin: null` (sandboxed iframes, file:// docs) is always rejected, even under `*`. Pre-flight via `caps.features.allow_origin`. Loopback self-origin hits are unaffected. |
+| `--web` / `--no-web`                    | `true`          | Serve the built Web Shell SPA at the daemon root (`GET /`, `/assets/*`, and SPA deep-link fallback). The static shell is registered **before** the bearer-auth gate — a browser can't attach a token to a `<script>` subresource or an address-bar navigation, the shell carries no secrets, and every API route stays token-gated regardless. On non-loopback binds a one-line stderr warning notes the UI is reachable without auth. Use `--no-web` for an API-only daemon. No effect when the build omits the Web Shell assets (the daemon logs a breadcrumb and runs API-only).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--open`                                | `false`         | After the listener is up, open the Web Shell in your default browser at the daemon URL (with `#token=` appended as a URL fragment when a token is configured — a fragment is never sent to the server, keeping the token out of access logs and Referer headers). No-op with `--no-web`, or in headless / CI / SSH environments where no browser is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 > **Sizing the load knobs.** `--max-sessions` is the **new-child** cap.
 > Three other layers also limit load — when sizing for a high-concurrency
@@ -357,7 +362,7 @@ for await (const event of session.events()) {
 
 Pre-flight `caps.features.session_load` / `caps.features.session_resume` before calling — older daemons return `404`. `unstable_session_resume` is still advertised as a deprecated compatibility alias. Concurrent same-action requests for the same id coalesce; cross-action races (a `load` racing a `resume`) get `409 restore_in_progress` with `Retry-After: 5`. See the [protocol reference](../developers/qwen-serve-protocol.md) for the full error envelope.
 
-Note: history replay is bounded by the SSE ring (default 4000 frames). Long histories with chatty turns can exceed that — earliest frames are dropped silently. For very long sessions, prefer `resume` and rely on the client's local persisted UI.
+Note: history replay is bounded by the SSE ring (default 8000 frames). Long histories with chatty turns can exceed that — earliest frames are dropped silently. For very long sessions, prefer `resume` and rely on the client's local persisted UI.
 
 ## Durability model
 
@@ -365,7 +370,7 @@ Note: history replay is bounded by the SSE ring (default 4000 frames). Long hist
 
 - A child process crash publishes `session_died` and removes the live session from the daemon's maps. The persisted on-disk session **can** be reloaded via `POST /session/:id/load` if a fresh agent child is spawnable.
 - A daemon restart loses every in-flight live session. The persisted sessions remain on disk and can be loaded against a new daemon process, subject to the same workspace binding rules.
-- Long client disconnects (>5 min on a chatty turn) can outrun the SSE replay ring (default 4000 frames) — `Last-Event-ID` reconnect succeeds but state may be incoherent. For mobile / flaky-network clients, plan to re-open SSE on long drops or call `POST /session/:id/load` to replay from disk.
+- Long client disconnects (>5 min on a chatty turn) can outrun the SSE replay ring (default 8000 frames) — `Last-Event-ID` reconnect succeeds but state may be incoherent. For mobile / flaky-network clients, plan to re-open SSE on long drops or call `POST /session/:id/load` to replay from disk.
 - File operations (`writeTextFile`) are atomic across crashes (write-then-rename); they aren't atomic across daemon restarts in the sense of replaying — the file write either landed or it didn't.
 
 If your integration needs server-side cross-restart durability beyond what `session/load` covers (e.g. server-managed retry queues), you still need application-level state recovery. Don't hold long-running, restart-sensitive state inside the daemon's session.
@@ -383,7 +388,7 @@ Stage 1's contract is sized for prototyping. Per [#3889 chiga0 downstream-consum
 
 3. ~~**Client-initiated heartbeat path**~~ — shipped via [#4175](https://github.com/QwenLM/qwen-code/issues/4175) PR 9. `POST /session/:id/heartbeat` records last-seen timestamps on the daemon (capability tag `client_heartbeat`); SDK helpers are `DaemonClient.heartbeat()` / `DaemonSessionClient.heartbeat()`.
 4. **`permission_already_resolved` event** when a vote loses the first-responder race — currently UIs have to infer state from a `404`.
-5. **Larger / per-session-configurable replay ring** — default 4000 covers short drops; mobile / chatty-turn workloads need 8000+ or per-session config.
+5. ~~**Larger replay ring**~~ — bumped to 8000. **Per-session-configurable ring** still open — mobile / chatty-turn workloads may need per-session overrides.
 6. **`slow_client_warning` event before `client_evicted`** — soft backpressure so well-behaved slow clients can self-throttle (trim render depth, drop chunks) before being terminated.
 
 **Integration ergonomics:**

package/bundled/qc-helper/docs/reference/keyboard-shortcuts.md

@@ -51,11 +51,11 @@ This document lists the available keyboard shortcuts in Qwen Code.
 
 ## Suggestions
 
-| Shortcut        | Description                            |
-| --------------- | -------------------------------------- |
-| `Down Arrow`    | Navigate down through the suggestions. |
-| `Tab` / `Enter` | Accept the selected suggestion.        |
-| `Up Arrow`      | Navigate up through the suggestions.   |
+| Shortcut                | Description                            |
+| ----------------------- | -------------------------------------- |
+| `Down Arrow` / `Ctrl+N` | Navigate down through the suggestions. |
+| `Tab` / `Enter`         | Accept the selected suggestion.        |
+| `Up Arrow` / `Ctrl+P`   | Navigate up through the suggestions.   |
 
 ## Radio Button Select
 
@@ -83,6 +83,12 @@ Active only when `ui.useTerminalBuffer` is enabled (Settings → UI → Virtuali
 
 When `ui.useTerminalBuffer` is on, the terminal forwards mouse events to qwen-code so the wheel can drive the in-app viewport. As a side effect, **native click-and-drag text selection is consumed by the program** — hold `Shift` (or `Option` on macOS Terminal / iTerm) while dragging to bypass mouse capture and select text the usual way.
 
+### tmux trackpad scrolling
+
+Inside tmux, some terminals translate trackpad or wheel gestures into plain `Up Arrow` and `Down Arrow` sequences before qwen-code sees them. Those bytes are identical to real arrow-key presses, so qwen-code cannot tell whether you meant to scroll the viewport or navigate prompt history.
+
+If trackpad scrolling changes the prompt history in tmux, enable `ui.useTerminalBuffer`; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
+
 ## IDE Integration
 
 | Shortcut | Description                       |

package/bundled/qc-helper/docs/support/troubleshooting.md

@@ -85,6 +85,11 @@ This guide provides solutions to common issues and debugging tips, including top
   - **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded from project `.env` files to prevent interference with the CLI behavior.
   - **Solution:** Use a `.qwen/.env` file instead, or configure the `advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer variables.
 
+- **Trackpad scrolling in tmux changes prompt history instead of scrolling the conversation**
+  - **Issue:** In a tmux session, trackpad or wheel scrolling may cycle through previous prompts, similar to pressing `Up Arrow` or `Down Arrow`.
+  - **Cause:** tmux can translate wheel gestures into plain arrow-key sequences. Those sequences are indistinguishable from real arrow-key presses by the time qwen-code receives them.
+  - **Solution:** Enable `ui.useTerminalBuffer`; then use `Shift+Up` / `Shift+Down`, or the mouse wheel when tmux forwards wheel events to the app. If you prefer host scrollback, adjust your tmux mouse bindings for wheel events.
+
 ## IDE Companion not connecting
 
 - Ensure VS Code has a single workspace folder open.