@qwen-code/qwen-code 0.18.0-preview.2 → 0.18.1-nightly.20260616.a68b2e1e7

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

@@ -18,14 +18,21 @@ Slash commands are used to manage Qwen Code sessions, interface, and basic behav
 
 These commands help you save, restore, and summarize work progress.
 
-| Command     | Description                                               | Usage Examples                       |
-| ----------- | --------------------------------------------------------- | ------------------------------------ |
-| `/init`     | Analyze current directory and create initial context file | `/init`                              |
-| `/summary`  | Generate project summary based on conversation history    | `/summary`                           |
-| `/compress` | Replace chat history with summary to save Tokens          | `/compress`                          |
-| `/resume`   | Resume a previous conversation session                    | `/resume`                            |
-| `/recap`    | Generate a one-line session recap now                     | `/recap`                             |
-| `/restore`  | Restore files to state before tool execution              | `/restore` (list) or `/restore <ID>` |
+| Command          | Description                                                              | Usage Examples                                                |
+| ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `/init`          | Analyze current directory and create initial context file                | `/init`                                                       |
+| `/summary`       | Generate project summary based on conversation history                   | `/summary`                                                    |
+| `/compress`      | Replace chat history with summary to save Tokens                         | `/compress`                                                   |
+| `/compress-fast` | Fast compression without AI — strips old tool outputs and thinking parts | `/compress-fast`                                              |
+| `/resume`        | Resume a previous conversation session                                   | `/resume`                                                     |
+| `/recap`         | Generate a one-line session recap now                                    | `/recap`                                                      |
+| `/restore`       | Revert project files to the checkpoint before a tool call ran            | `/restore` (list) or `/restore <ID>`                          |
+| `/delete`        | Delete a previous session                                                | `/delete`                                                     |
+| `/branch`        | Fork the current conversation into a new session                         | `/branch`                                                     |
+| `/fork`          | Spawn a background agent that inherits the full conversation             | `/fork <directive>`                                           |
+| `/rewind`        | Rewind conversation to a previous turn                                   | `/rewind` or `/rollback`                                      |
+| `/export`        | Export session history to file                                           | `/export html`, `/export md`, `/export json`, `/export jsonl` |
+| `/rename`        | Rename or tag the current session                                        | `/rename My Feature` or `/tag`                                |
 
 ### 1.2 Interface and Workspace Control
 
@@ -43,6 +50,7 @@ Commands for adjusting interface appearance and work environment.
 | `/editor`            | Open dialog to select supported editor                                                                                                                                            | `/editor`                               |
 | `/statusline`        | Open interactive [status line](./status-line.md) preset dialog                                                                                                                    | `/statusline`                           |
 | `/statusline <text>` | Generate a command-mode [status line](./status-line.md) via agent                                                                                                                 | `/statusline show model and git branch` |
+| `/terminal-setup`    | Configure terminal keybindings for multiline input                                                                                                                                | `/terminal-setup`                       |
 
 ### 1.3 Language Settings
 
@@ -71,6 +79,7 @@ Commands for managing AI tools and models.
 | →`plan`          | Analysis only, no execution                   | Secure review                                 |
 | →`default`       | Require approval for edits                    | Daily use                                     |
 | →`auto-edit`     | Automatically approve edits                   | Trusted environment                           |
+| →`auto`          | Classifier-evaluated approval                 | Autonomous sessions with safety guardrails    |
 | →`yolo`          | Automatically approve all                     | Quick prototyping                             |
 | `/model`         | Switch model used in current session          | `/model`                                      |
 | `/model --fast`  | Set a lighter model for prompt suggestions    | `/model --fast qwen3-coder-flash`             |
@@ -79,6 +88,14 @@ Commands for managing AI tools and models.
 | `/remember`      | Save a durable memory                         | `/remember Prefer terse responses`            |
 | `/forget`        | Remove matching entries from auto-memory      | `/forget <query>`                             |
 | `/dream`         | Manually run auto-memory consolidation        | `/dream`                                      |
+| `/hooks`         | Manage Qwen Code hooks                        | `/hooks`, `/hooks list`                       |
+| `/permissions`   | Manage permission rules                       | `/permissions`                                |
+| `/agents`        | Manage subagents                              | `/agents manage`, `/agents create`            |
+| `/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`                                      |
+| `/lsp`           | Show LSP server status                        | `/lsp`                                        |
+| `/trust`         | Manage folder trust settings                  | `/trust`                                      |
 
 ### 1.5 Built-in Skills
 
@@ -192,7 +209,7 @@ progress; otherwise it waits for the current turn to finish and then fires).
 Unlike the manual command, the auto-trigger is fully silent on failure: if
 generation errors or there is nothing to summarize, no message is added to
 the history. Controlled by the `general.showSessionRecap` setting
-(default: `true`); the manual `/recap` command always works regardless of
+(default: `false`); the manual `/recap` command always works regardless of
 this setting.
 
 **Example:**
@@ -209,8 +226,8 @@ this setting.
 >
 > Configure a fast model via `/model --fast <model>` (e.g.
 > `qwen3-coder-flash`) to make `/recap` fast and cheap. Set
-> `general.showSessionRecap` to `false` to opt out of the auto-trigger
-> while keeping the manual command available.
+> `general.showSessionRecap` to `true` to enable the auto-trigger; the
+> manual `/recap` command always works regardless of this setting.
 
 ### 1.8 Diff Viewer (`/diff`)
 
@@ -278,6 +295,11 @@ Commands for obtaining information and performing system settings.
 | `/stats tools`  | Show per-tool call counts                                                                                                                                                                                                                                                                       | `/stats tools`                   |
 | `/settings`     | Open settings editor                                                                                                                                                                                                                                                                            | `/settings`                      |
 | `/auth`         | Change authentication method                                                                                                                                                                                                                                                                    | `/auth`                          |
+| `/doctor`       | Run installation and environment diagnostics                                                                                                                                                                                                                                                    | `/doctor`, `/doctor memory`      |
+| `/docs`         | Open full Qwen Code documentation in browser                                                                                                                                                                                                                                                    | `/docs`                          |
+| `/ide`          | Manage IDE integration                                                                                                                                                                                                                                                                          | `/ide status`, `/ide install`    |
+| `/insight`      | Generate programming insights from chat history                                                                                                                                                                                                                                                 | `/insight`                       |
+| `/setup-github` | Set up GitHub Actions                                                                                                                                                                                                                                                                           | `/setup-github`                  |
 | `/bug`          | Submit issue about Qwen Code                                                                                                                                                                                                                                                                    | `/bug Button click unresponsive` |
 | `/copy`         | Copy AI output to clipboard (`/copy N` = Nth-last AI message)                                                                                                                                                                                                                                   | `/copy` or `/copy 2`             |
 | `/quit`         | Exit Qwen Code immediately                                                                                                                                                                                                                                                                      | `/quit` or `/exit`               |

package/bundled/qc-helper/docs/features/dual-output.md

@@ -199,10 +199,10 @@ wrappers that throw away stdout anyway.
 
 ## Quick start
 
-Run Qwen Code with all three channels enabled:
+Run Qwen Code with both channels enabled using regular files:
 
 ```bash
-mkfifo /tmp/qwen-events.jsonl /tmp/qwen-input.jsonl
+touch /tmp/qwen-events.jsonl /tmp/qwen-input.jsonl
 qwen \
   --json-file /tmp/qwen-events.jsonl \
   --input-file /tmp/qwen-input.jsonl
@@ -211,7 +211,7 @@ qwen \
 In a second terminal, tail the event stream:
 
 ```bash
-cat /tmp/qwen-events.jsonl
+tail -f /tmp/qwen-events.jsonl
 ```
 
 In a third terminal, push a prompt into the running TUI:
@@ -223,6 +223,33 @@ echo '{"type":"submit","text":"Explain this repo"}' >> /tmp/qwen-input.jsonl
 The prompt appears in the TUI exactly as if the user typed it, and the
 streaming response is mirrored on `/tmp/qwen-events.jsonl`.
 
+### Using FIFOs (named pipes) for event output
+
+FIFOs deliver lower latency than regular files (no disk I/O) and work
+well when both sides are on the same host. The bridge opens FIFOs with
+`O_RDWR | O_NONBLOCK`, so it **does not block** even if no reader is
+connected yet — events are buffered in the kernel pipe buffer until a
+reader attaches.
+
+> **Note:** `--input-file` requires a regular file (not a FIFO) because
+> the watcher relies on `stat.size` to detect new data, which is always
+> 0 for FIFOs.
+
+```bash
+mkfifo /tmp/qwen-events.jsonl
+touch /tmp/qwen-input.jsonl
+qwen \
+  --json-file /tmp/qwen-events.jsonl \
+  --input-file /tmp/qwen-input.jsonl
+# TUI starts immediately — no need to start a reader first.
+
+# In a second terminal, connect whenever ready:
+cat /tmp/qwen-events.jsonl
+```
+
+If no reader ever connects, the bridge auto-disables once the internal
+buffer exceeds 1 MB. The TUI continues running normally.
+
 ## Output event schema
 
 Events are emitted as JSON Lines (one object per line). The schema is the same
@@ -325,6 +352,13 @@ polling — events are written synchronously as the TUI emits them.
 - **Consumer disconnect.** If the reader on the other side of the channel
   goes away (`EPIPE`), the bridge silently disables itself and the TUI
   keeps running. No retry.
+- **FIFO buffer overflow.** When writing to a FIFO with no reader
+  attached, events buffer in the kernel pipe (~64 KB on Linux) and the
+  Node.js WriteStream. Once the pipe is full or the internal buffer
+  exceeds 1 MB, the bridge disables itself and closes the fd. No
+  `session_end` is emitted in this case — consumers should treat a
+  closed stream without `session_end` as an abnormal termination. The
+  TUI continues running normally.
 - **Adapter exception.** Any exception thrown while emitting an event is
   caught, logged, and disables the bridge. The TUI is never crashed by a
   dual-output failure.

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

@@ -32,7 +32,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 (enabled by default)
+- The feature is enabled in settings (disabled by default — set `ui.enableFollowupSuggestions` to `true` to turn it on)
 
 Suggestions will not appear in non-interactive mode (e.g., headless/SDK mode).
 
@@ -72,7 +72,7 @@ These settings can be configured in `settings.json`:
 
 | Setting                        | Type    | Default | Description                                                        |
 | ------------------------------ | ------- | ------- | ------------------------------------------------------------------ |
-| `ui.enableFollowupSuggestions` | boolean | `true`  | Enable or disable followup suggestions                             |
+| `ui.enableFollowupSuggestions` | boolean | `false` | 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/skills.md

@@ -118,9 +118,35 @@ Notes:
 
 - Globs are matched relative to the project root with [picomatch](https://github.com/micromatch/picomatch); files outside the project root never trigger activation.
 - A path-gated Skill **stays activated for the rest of the session** once a matching file is touched. A new session, or a `refreshCache` triggered by editing any Skill file, resets activations.
-- `paths:` only gates **model** discovery, and only at the SkillTool listing level. You can always invoke a path-gated Skill yourself via `/<skill-name>` or the `/skills` picker — that user path runs the Skill body regardless of activation state. The model side, however, stays gated until a matching file is touched: a slash invocation does **not** unlock model-side activation, so if you want the model to chain off your invocation (call `Skill { skill: ... }` itself), also access a file matching the skill's `paths:` first.
+- `paths:` only gates **model** discovery, and only at the SkillTool listing level. Unless `user-invocable: false` is set, you can always invoke a path-gated Skill yourself via `/<skill-name>` or the `/skills` picker — that user path runs the Skill body regardless of activation state. The model side, however, stays gated until a matching file is touched: a slash invocation does **not** unlock model-side activation, so if you want the model to chain off your invocation (call `Skill { skill: ... }` itself), also access a file matching the skill's `paths:` first.
 - Combining `paths:` with `disable-model-invocation: true` is allowed but the gate has no effect — the Skill is hidden from the model regardless, so path activation never advertises it.
 
+### Optional: control user and model invocation
+
+Skills are user-invocable by default. To hide a Skill from direct slash-command use while keeping it available for model invocation, set `user-invocable: false`:
+
+```yaml
+---
+name: model-only-helper
+description: Helper the model can call when appropriate
+user-invocable: false
+---
+```
+
+This removes the Skill from `/<skill-name>` invocation and `/skills` picker results. It does not hide the Skill from the model.
+
+To hide a Skill from model invocation while keeping direct user invocation available, set `disable-model-invocation: true`:
+
+```yaml
+---
+name: manual-helper
+description: Helper you invoke manually
+disable-model-invocation: true
+---
+```
+
+You can combine both fields, but then the Skill is not reachable through the normal user or model invocation paths.
+
 ## Add supporting files
 
 Create additional files alongside `SKILL.md`:
@@ -170,9 +196,9 @@ To view available Skills, ask Qwen Code directly:
 What Skills are available?
 ```
 
-> **Heads up — model vs. user view.** Asking the model only surfaces Skills the model can currently see. If a Skill uses `paths:` (see "Optional: gate a Skill on file paths" above), it stays out of that listing until a matching file has been touched. The full set is always visible to you via the `/skills` slash command and on disk.
+> **Heads up — model vs. user view.** Asking the model only surfaces Skills the model can currently see. If a Skill uses `paths:` (see "Optional: gate a Skill on file paths" above), it stays out of that listing until a matching file has been touched. The `/skills` slash command shows Skills you can invoke directly; Skills with `user-invocable: false` remain visible on disk and may still be visible to the model.
 
-Or browse the full list with the slash command (always shows every Skill, including path-gated ones that have not activated yet):
+Or browse the user-invocable list with the slash command (including path-gated Skills that have not activated yet):
 
 ```text
 /skills

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

@@ -135,7 +135,7 @@ Subagents are configured using Markdown files with YAML frontmatter. This format
 name: agent-name
 description: Brief description of when and how to use this agent
 model: inherit # Optional: inherit, fast, modelId, or authType:modelId
-approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo
+approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo, bubble
 tools:         # Optional: allowlist of tools
   - tool1
   - tool2
@@ -202,6 +202,7 @@ Use the optional `approvalMode` frontmatter field to control how a subagent's to
 - `plan`: Analyze-only mode — the agent plans but does not execute changes
 - `auto-edit`: Tools are auto-approved without prompting (recommended for most agents)
 - `yolo`: All tools auto-approved, including potentially destructive ones
+- `bubble`: Background-agent tool approvals are surfaced in the parent session
 
 If you omit this field, the subagent's permission mode is determined automatically:
 
@@ -282,13 +283,15 @@ can drop a CC agent file into `.qwen/agents/` and have the supported fields
 parse identically. Optional fields with invalid values are silently dropped
 at parse time rather than rejected — the same lenient posture CC uses.
 
-| Field            | Type             | Notes                                                                                                                                                                                                                                         |
-| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                        |
-| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins.                                                                                                                       |
-| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy qwen sentinel `auto` is also preserved for backward compatibility. Other values are silently dropped on parse. |
+| Field            | Type             | Notes                                                                                                                                                                                                                                                                            |
+| ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `permissionMode` | enum string      | `acceptEdits`, `auto`, `bypassPermissions`, `default`, `dontAsk`, `plan`. Mapped to `approvalMode` at parse time; when both are set, the explicit `approvalMode` wins.                                                                                                           |
+| `maxTurns`       | positive integer | Caps the agent's turn budget. Wired into `runConfig.max_turns` at runtime; when both are set, the top-level field wins. The legacy nested value is pruned from the on-disk file on save to avoid two sources of truth.                                                           |
+| `color`          | enum string      | Display color. Allowlist: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan` (mirrors CC's `_Y`). The legacy qwen sentinel `auto` is preserved for backward compatibility. Other values are silently dropped on parse.                                         |
+| `mcpServers`     | record of specs  | Per-agent MCP server overrides. Merged with the session-level MCP server set when the agent spawns; on key collision the agent's spec wins (matching CC's `scope: 'agent'` semantics). Malformed entries are dropped per-key with a warning rather than failing the whole agent. |
+| `hooks`          | record of arrays | Per-agent hooks. Keys are CC hook event names (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, …); values are arrays of `{ matcher?, hooks: [...] }` definitions in the same shape as `settings.json`'s `hooks` field. Registered while the agent runs, removed when it stops.  |
 
-Example:
+Example with all of the above:
 
 ```
 ---
@@ -301,6 +304,17 @@ tools:
   - read_file
   - grep_search
   - glob
+mcpServers:
+  filesystem:
+    type: stdio
+    command: node
+    args: [/usr/local/lib/mcp-fs/server.js]
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: echo "review-agent about to run a shell command"
 ---
 
 You are a code reviewer. Analyze the code thoroughly and report findings
@@ -308,11 +322,19 @@ ordered by severity.
 ```
 
 The remaining CC frontmatter fields — `effort`, `skills`, `initialPrompt`,
-`memory`, `isolation`, `mcpServers`, `hooks` — are documented in the
-declarative-agent design doc and land in follow-up PRs once the prerequisite
-infrastructure exists (`effort` needs a model-layer parameter; `memory`
-needs a scoped memory subsystem; `mcpServers` / `hooks` need a nested-aware
-YAML parser; `--agent` CLI flag enables `initialPrompt`; etc.).
+`memory`, `isolation` — are documented in the declarative-agent design doc
+and land in follow-up PRs once the prerequisite infrastructure exists
+(`effort` needs a model-layer parameter; `memory` needs a scoped memory
+subsystem; `--agent` CLI flag enables `initialPrompt`; etc.).
+
+> **`hooks` v1 limitation.** While a subagent declaring `hooks` is running,
+> its hook entries fire for every matching event in the session, not only
+> for that subagent's own tool calls. If two subagents with different
+> per-agent hook sets run concurrently, both sets fire for both agents.
+> Per-agent scope filtering at hook-firing time is left to a follow-up;
+> for v1, prefer per-agent hooks that are safe to fire globally for the
+> duration of the agent's run (e.g. logging) over hooks that mutate
+> behavior.
 
 #### Example Usage
 

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

@@ -0,0 +1,221 @@
+# Local launch templates for `qwen serve` (v0.16-alpha)
+
+Reference templates for running `qwen serve` as a long-lived background process on a developer workstation. Pairs with the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) — local-only, single-user, BYO bearer token. Containerized / multi-host / TLS-fronted deployments defer to v0.16.x.
+
+> **Audience**: dogfooding developers who want the daemon up across reboots, with logs going somewhere durable, and a clean `restart-on-failure` story. If you only need the daemon for the duration of a single shell session, plain `qwen serve` (foreground, Ctrl-C to stop) is fine.
+
+## Generate a bearer token (once)
+
+```bash
+openssl rand -hex 32 > ~/.qwen-serve-token  # user-managed, NOT a built-in path
+chmod 600 ~/.qwen-serve-token
+export QWEN_SERVER_TOKEN="$(cat ~/.qwen-serve-token)"
+```
+
+The path / filename is yours to choose; v0.16-alpha does not auto-generate or auto-locate a token file (deferred to v0.16.x). See the [Authentication](./qwen-serve.md#authentication) section of the user guide for the canonical BYO setup.
+
+> **Scope this `export` to the current shell session only.** Don't add it to `~/.bashrc` / `~/.zshrc` — a profile-level export exposes the bearer token to every process spawned from that shell (IDE subprocesses, browser debuggers, `npm` scripts from unrelated projects). For long-running setups, use the systemd `EnvironmentFile=` / launchd `EnvironmentVariables` mechanisms below — both scope the token to just the daemon process.
+
+The daemon reads the bearer token from either `--token <value>` on the CLI or the `QWEN_SERVER_TOKEN` env var (whitespace stripped from both). The TypeScript SDK's `DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` when no `token` option is passed (PR 27 fallback — clients with the env var set never need to thread the value through their script).
+
+One shell-level `export` covers both server boot and SDK client construction (just keep it scoped to the session, per the note above).
+
+## 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`.
+
+`~/.config/systemd/user/qwen-serve.service`:
+
+```ini
+[Unit]
+Description=Qwen Code daemon (loopback HTTP + SSE)
+After=network.target
+
+[Service]
+Type=simple
+# Replace with your project; %h expands to $HOME under user units.
+WorkingDirectory=%h/your-project
+# 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
+# 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
+# the user-owned secret file you already created with `chmod 600`.
+EnvironmentFile=%h/.qwen-serve-token-env
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+```
+
+Build the env file once (the token file from the setup step holds the raw value; this wraps it in `KEY=value` form so systemd reads it as an env assignment):
+
+```bash
+echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
+chmod 600 ~/.qwen-serve-token-env
+```
+
+Manage:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now qwen-serve.service
+loginctl enable-linger "$(whoami)"               # keep the user manager running after logout / across reboot
+journalctl --user -u qwen-serve -f               # tail logs
+systemctl --user restart qwen-serve.service     # after token rotation
+systemctl --user disable --now qwen-serve.service
+```
+
+Without `loginctl enable-linger`, the user-level systemd instance shuts down when the user logs out and only restarts on next login — on a headless dev box the daemon would not survive an SSH session ending. `enable-linger` is what makes "across reboots" actually work.
+
+**System-wide alternative** (shared dev hosts, less common): drop the unit at `/etc/systemd/system/qwen-serve@.service` with `User=%i`, manage via `sudo systemctl enable --now qwen-serve@<username>.service`. Same `[Service]` body otherwise — but world-readable `Environment=` exposure is even more problematic at this level, so always use `EnvironmentFile=` pointing at the user's `chmod 600` file. Pick user-level + linger for single-user workstations.
+
+## macOS: launchd user agent
+
+> **Find your `qwen` binary first.** Same constraint as systemd — `ProgramArguments` must hold an **absolute path**. Run `which qwen` to discover it. Common locations on macOS: `/opt/homebrew/bin/qwen` (Homebrew on Apple Silicon), `/usr/local/bin/qwen` (Homebrew on Intel, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.volta/bin/qwen` (Volta). Substitute below where the template shows `/PATH/TO/qwen`.
+
+`~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.qwenlm.qwen-serve</string>
+  <key>ProgramArguments</key>
+  <array>
+    <!-- Run `which qwen` to find the absolute path; launchd does NOT read $PATH. -->
+    <string>/PATH/TO/qwen</string>
+    <string>serve</string>
+    <string>--hostname</string>
+    <string>127.0.0.1</string>
+    <string>--port</string>
+    <string>4170</string>
+  </array>
+  <!-- launchd does NOT expand `~` or `$HOME` — use absolute paths. -->
+  <key>WorkingDirectory</key>
+  <string>/Users/YOUR-USERNAME/your-project</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <!-- DO NOT COMMIT this file with a real token. Also chmod 600 the
+         plist itself so the inlined token is not world-readable. -->
+    <key>QWEN_SERVER_TOKEN</key>
+    <string>PASTE-YOUR-TOKEN-HERE</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <!-- Restart only on non-zero exits (matches systemd Restart=on-failure).
+       A bare `<true/>` would respawn even after a clean SIGTERM, making
+       `kill <pid>` impossible to use as a stop signal — operator would
+       have to `launchctl unload`. SuccessfulExit=false fixes that. -->
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <!-- Throttle restart storms on persistent failures (mirrors systemd
+       RestartSec=5; launchd's default would respawn every <1s). -->
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <!-- Log into the user's Library, not /tmp. /tmp is world-writable
+       (symlink-attack risk on shared workstations) and gets cleaned by
+       periodic-daily after 3 days; `~/Library/Logs/qwen-serve/` is
+       user-scoped and survives. launchd truncates these on every
+       `load`, so the unload→load token-rotation cycle wipes prior
+       diagnostic logs — back them up if you need post-incident
+       inspection. -->
+  <key>StandardOutPath</key>
+  <string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/err.log</string>
+</dict>
+</plist>
+```
+
+Manage:
+
+```bash
+mkdir -p ~/Library/Logs/qwen-serve                                       # first time only
+chmod 600 ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist             # plist holds the inline token
+launchctl load   ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist
+launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist      # to stop
+tail -f ~/Library/Logs/qwen-serve/out.log ~/Library/Logs/qwen-serve/err.log
+```
+
+After editing the plist (e.g., rotating the token) you must `unload` then `load` again — `launchctl` does not auto-reload on plist changes the way `systemd daemon-reload` does. Note: each `load` truncates the log files, so save them off if you're investigating an incident before rotating.
+
+## tmux session (interactive supervision)
+
+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 attach -t qwen-serve   # see live logs; Ctrl-b d to detach
+tmux kill-session -t qwen-serve
+```
+
+`tmux new -d` inherits the parent shell's environment, so `QWEN_SERVER_TOKEN` flows through automatically. Best when you want to occasionally watch the daemon's stdout (auth warnings, MCP discovery progress, slow-client warnings) without committing to a service unit. Survives terminal close but not host reboot.
+
+## nohup one-liner (quick + dirty)
+
+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 &
+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.
+
+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.
+
+## Verifying the daemon is up
+
+```bash
+curl http://127.0.0.1:4170/health                                   # → {"status":"ok"}
+curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
+  http://127.0.0.1:4170/capabilities | jq .protocolVersions         # daemon's feature set
+```
+
+When auth is configured (i.e., the daemon was started with `--token` / `QWEN_SERVER_TOKEN` set, OR `--require-auth=true`), every route except `/health` on loopback binds requires `Authorization: Bearer <token>`. If you started the daemon without a token on the loopback default (the `qwen serve` zero-config path), neither call requires a header. The templates above all configure a token, so the `Authorization` header is needed in practice. If `/capabilities` returns `401`, the unit / plist token doesn't match the env-exported token your `curl` is using.
+
+## Token rotation
+
+1. Generate a new token + write the env file the unit references:
+   ```bash
+   openssl rand -hex 32 > ~/.qwen-serve-token
+   chmod 600 ~/.qwen-serve-token
+   echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
+   chmod 600 ~/.qwen-serve-token-env
+   ```
+   (For the launchd / nohup / tmux templates: edit the plist's `<string>` value or re-`export QWEN_SERVER_TOKEN`. Don't forget `chmod 600` on the plist if you regenerate it.)
+2. Restart the daemon:
+   - **systemd**: `systemctl --user restart qwen-serve.service`
+   - **launchd**: `launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist && launchctl load ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`
+   - **tmux / nohup**: `kill <pid>` then re-run with the new token in env
+3. Update any client SDKs / scripts. The TypeScript SDK's `DaemonClient` reads `QWEN_SERVER_TOKEN` automatically (PR 27 fallback) — re-`export` the new value in any client shell and reconstruct the client.
+
+## Restart and crash behavior
+
+Service-manager restart semantics differ across the templates:
+
+- **systemd `Restart=on-failure`** — restart only on non-zero exit / signal. A clean SIGTERM (`systemctl stop`) does **not** trigger a restart loop.
+- **launchd `KeepAlive` with `SuccessfulExit=false`** (the template above) — matches systemd behavior. A bare `<true/>` would have respawned even after a clean exit. `ThrottleInterval=10` rate-limits restart storms on persistent failures, mirroring systemd's `RestartSec=5`.
+- **tmux / nohup** — no automatic restart. A daemon crash leaves you with a dead PID until you re-run.
+
+Within a **single daemon process lifetime**, client disconnects recover via SSE `Last-Event-ID` resume per the [Durability model](./qwen-serve.md#durability-model) section of the user guide — the replay ring is in-memory.
+
+A daemon **restart** drops all in-memory sessions; clients reconnect and start fresh. Cross-restart durability of session content (prompts, tool calls, conversation history) is **NOT** in v0.16-alpha.
+
+## 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.
+- **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.
+
+See the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) callout in the main user guide for the full deferred-features list, and [#4175](https://github.com/QwenLM/qwen-code/issues/4175) for the v0.16-alpha rollout tracking issue.