@qwen-code/qwen-code 0.23.1-preview.2 → 0.23.2-nightly.20260909.2e212144d3

package/README.md

@@ -7,7 +7,7 @@
 
 <a href="https://trendshift.io/repositories/15287" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15287" alt="QwenLM%2Fqwen-code | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
-**The open-source AI coding agent that lives in your terminal.**
+**The open-source AI coding agent for your terminal, editor, desktop, browser, and chat.**
 
 <a href="https://qwenlm.github.io/qwen-code-docs/zh/users/overview">中文</a> |
 <a href="https://qwenlm.github.io/qwen-code-docs/de/users/overview">Deutsch</a> |
@@ -19,12 +19,14 @@
 
 </div>
 
+![Qwen Code in the terminal, desktop app, browser, editor, and chat, with VS Code, Zed, JetBrains, Telegram, DingTalk, WeChat, and Feishu integrations](https://img.alicdn.com/imgextra/i3/O1CN01l5GyhGuOPGC3XHtt_!!6000000005884-2-tps-1742-903.png)
+
 ## Why Qwen Code?
 
 - **Agentic out of the box** — Auto-Memory, Auto-Skills, SubAgents, Agent Teams, and MCP. Dynamic workflows, zero setup.
 - **Open-source, inside and out** — The framework and the Qwen models are open-source. They evolve together. No vendor lock-in.
 - **Multi-protocol** — Supports OpenAI, Anthropic, Gemini, and Qwen APIs. Any third-party provider or local model (Ollama / vLLM). Switch at runtime.
-- **Beyond the terminal** — IDE plugins, Desktop app, daemon mode, SDKs, and IM bots (Telegram / DingTalk / WeChat / Feishu).
+- **Beyond the terminal** — IDE plugins, Desktop app, Web UI, SDKs, and chat integrations (Telegram / DingTalk / WeChat / Feishu).
 
 > [!TIP]
 > Qwen Code is actively iterating on itself — using its own agent and models to file issues, submit PRs, review code, and run tests. Powered by the community, driven by AI.
@@ -64,27 +66,45 @@ brew install qwen-code
 
 ## Quick Start
 
+Open a terminal in your project and start Qwen Code:
+
 ```bash
-qwen          # Launch interactive terminal UI
-# Inside the session:
-/auth         # Configure your provider and API key
+cd /path/to/your-project
+qwen
+```
+
+Inside the session, run `/auth` to configure your provider and API key. Then try:
+
+```text
+Explain this repository and show me where to start.
 ```
 
 See the [Authentication Guide](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/) and [Settings Reference](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/) for detailed setup.
 
-![Qwen Code](https://img.alicdn.com/imgextra/i2/O1CN01K0nwj41RM1Il8kB0t_!!6000000002096-2-tps-1544-1060.png)
+<details>
+<summary>See the terminal interface</summary>
+
+![Qwen Code terminal interface](https://img.alicdn.com/imgextra/i2/O1CN01K0nwj41RM1Il8kB0t_!!6000000002096-2-tps-1544-1060.png)
+
+</details>
 
 ## How to Use Qwen Code
 
-| Mode            | Command         | Use Case                                                                                                                                                                                                                                        |
-| --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Interactive** | `qwen`          | Terminal UI with rich rendering, `@file` references, slash commands                                                                                                                                                                             |
-| **Headless**    | `qwen -p "..."` | Scripts, CI/CD, batch processing — no UI                                                                                                                                                                                                        |
-| **IDE**         | —               | [VS Code](https://qwenlm.github.io/qwen-code-docs/en/users/integration-vscode/), [Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/), [JetBrains](https://qwenlm.github.io/qwen-code-docs/en/users/integration-jetbrains/) |
-| **Desktop**     | —               | [Qwen Code Desktop](https://github.com/QwenLM/qwen-code/releases/tag/desktop-latest) — GUI for macOS, Windows, Linux                                                                                                                            |
-| **Daemon**      | `qwen serve`    | Shared agent session over HTTP+SSE (ACP). Multiple clients, one agent. _(experimental)_ [Docs](https://qwenlm.github.io/qwen-code-docs/en/users/qwen-serve)                                                                                     |
-| **SDK**         | —               | [TypeScript](./packages/sdk-typescript/README.md), [Python](./packages/sdk-python/README.md), [Java](./packages/sdk-java/qwencode/README.md)                                                                                                    |
-| **IM Bot**      | `qwen channel`  | Connect to Telegram, DingTalk, WeChat, or Feishu                                                                                                                                                                                                |
+Choose the interface that fits your workflow:
+
+| Interface    | Get started                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Terminal** | Run `qwen` in your project — see [Quick Start](#quick-start).                                                                                                                                                                                                                                                                                                                                             |
+| **Desktop**  | [Download Qwen Code Desktop](https://github.com/QwenLM/qwen-code/releases/tag/desktop-latest) for macOS, Windows, and Linux.                                                                                                                                                                                                                                                                              |
+| **Web**      | Run `qwen serve --open` to open the [Web UI](https://qwenlm.github.io/qwen-code-docs/en/users/qwen-serve/) in your browser. _(experimental)_                                                                                                                                                                                                                                                              |
+| **Editor**   | Set up [VS Code](https://qwenlm.github.io/qwen-code-docs/en/users/integration-vscode/), [Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/), or [JetBrains](https://qwenlm.github.io/qwen-code-docs/en/users/integration-jetbrains/).                                                                                                                                                |
+| **Chat**     | Connect [Telegram](https://qwenlm.github.io/qwen-code-docs/en/users/features/channels/telegram/), [DingTalk](https://qwenlm.github.io/qwen-code-docs/en/users/features/channels/dingtalk/), [WeChat](https://qwenlm.github.io/qwen-code-docs/en/users/features/channels/weixin/), or [Feishu](https://qwenlm.github.io/qwen-code-docs/en/users/features/channels/feishu/), then run `qwen channel start`. |
+
+For automation and custom integrations:
+
+- **Headless** — Run `qwen -p "..."` in scripts, CI/CD, or batch jobs.
+- **SDKs** — Build with [TypeScript](./packages/sdk-typescript/README.md), [Python](./packages/sdk-python/README.md), or [Java](./packages/sdk-java/qwencode/README.md).
+- **Daemon** — Run `qwen serve` to connect clients over HTTP + SSE (ACP). _(experimental)_ [Daemon guide](https://qwenlm.github.io/qwen-code-docs/en/users/qwen-serve/).
 
 <details>
 <summary>SDK example (Python)</summary>

package/bundled/computer-use/SKILL.md

@@ -3,163 +3,236 @@ name: computer-use
 description: Control local desktop applications through Computer Use for tasks that require reading or operating app UI. Prefer purpose-built connectors, APIs, or CLIs when available.
 ---
 
-# Computer Use with the CUA SDK
+## node_repl + @qwen-code/cua-sdk (Computer Use)
 
-- Prefer a dedicated connector or API. Use Computer Use only for UI state or
-  interactions the dedicated interface does not expose.
-- Perform Computer Use through `node_repl` and the typed `ComputerUse` API.
-  Do not use generic `callTool`, direct driver imports, AppleScript, JXA, or
-  synthesized-input utilities.
-- Observe the exact current window before acting. Prefer current element tokens
-  over screenshot coordinates; use coordinates only when accessibility is
-  incomplete and the screenshot provides the target.
-- Treat an action result as delivery evidence, not task completion. Decide from
-  fresh state and require stable postcondition evidence.
+- Use `node_repl` (JavaScript) for all Computer Use actions.
+- Do not use other technologies besides `node_repl` for computer interactions, unless specifically requested by the user (e.g. AppleScript, `osascript`, JXA, System Events, synthesized input).
+- Prefer a dedicated plugin or skill when it can complete the task; use Computer Use for app interactions that are not exposed through a more specific interface.
+- `node_repl` state is persistent across calls.
+- For text output, use `nodeRepl.write(...)`. `nodeRepl.write(...)` takes a string. If you would like to read a whole object, wrap it with `JSON.stringify(...)`.
 
-## Setup
+## Bootstrap
 
-If `node_repl` is unavailable, run these commands yourself:
+If `node_repl` is unavailable, run:
 
 ```bash
-qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.2
-npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.3
+qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.3
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.5
 ```
 
-Tell the user to restart Qwen Code, then stop. If only the SDK import is
-missing, run the second command and retry.
+Tell the user to restart Qwen Code, then stop. If only the SDK import is missing,
+run the second command and retry.
 
-Create one persistent client per REPL kernel:
+Import the `ComputerUse` API directly once per fresh `node_repl` session:
 
 ```js
 globalThis.computer = await (
   await import('@qwen-code/cua-sdk/computer-use')
 ).ComputerUse.create();
-globalThis.cuaRevisions ??= new Map();
 ```
 
-## Target and observe
+## API surface
 
-Use `listApps({signal:nodeRepl.signal})` and filter in JavaScript; print only
-likely matches. After selecting a real PID, call
-`listWindows({pid,signal:nodeRepl.signal})` and choose from returned
-metadata. Never guess a PID, window ID, element token, or coordinate. If the
-app is not running, start it with ordinary Node.js process APIs and refresh the
-lists.
+```ts
+type WindowTarget = { pid: number; windowId: number };
+type ElementTarget = {
+  pid: number;
+  windowId?: number;
+  elementToken: string;
+};
+type CoordinateTarget = WindowTarget & { x: number; y: number };
+type PointOrElementTarget = CoordinateTarget | ElementTarget;
+type ExactActionTarget = WindowTarget | ElementTarget;
+type DeliveryOptions = { deliveryMode?: DeliveryMode };
+
+type ComputerUse = {
+  click: (
+    args: PointOrElementTarget &
+      DeliveryOptions & { button?: MouseButton; count?: number },
+  ) => Promise<object>;
+  doubleClick: (
+    args: PointOrElementTarget & DeliveryOptions,
+  ) => Promise<object>;
+  rightClick: (
+    args: PointOrElementTarget & DeliveryOptions & { modifier?: string[] },
+  ) => Promise<object>;
+  drag: (
+    args: WindowTarget &
+      DeliveryOptions & {
+        fromX: number;
+        fromY: number;
+        toX: number;
+        toY: number;
+      },
+  ) => Promise<object>;
+  observeWindow: (
+    args: WindowTarget & { disableDiff?: boolean; includeScreenshot?: boolean },
+  ) => Promise<WindowObservation>;
+  listApps: () => Promise<Array<App>>;
+  listWindows: (args: { pid: number }) => Promise<Array<Window>>;
+  performSecondaryAction: (
+    args: ElementTarget & { action: string },
+  ) => Promise<object>;
+  pressKey: (
+    args: ExactActionTarget &
+      DeliveryOptions & { key: string; modifiers?: string[] },
+  ) => Promise<object>;
+  hotkey: (
+    args: ExactActionTarget & DeliveryOptions & { keys: string[] },
+  ) => Promise<object>;
+  scroll: (
+    args: PointOrElementTarget &
+      DeliveryOptions & { direction: Direction; amount?: number },
+  ) => Promise<object>;
+  setValue: (args: ElementTarget & { value: string }) => Promise<object>;
+  typeText: (
+    args: ExactActionTarget & DeliveryOptions & { text: string },
+  ) => Promise<object>;
+  close: () => Promise<void>;
+};
+
+type App = {
+  name?: string;
+  bundle_id?: string;
+  pid?: number;
+  running?: boolean;
+  launch_path?: string;
+};
 
-Maintain one revision cursor per window surface. The first observation has no
-base; later observations use only the last revision actually consumed for that
-same surface:
+type Window = {
+  window_id: number;
+  title?: string;
+  is_on_screen?: boolean;
+  on_current_space?: boolean;
+};
 
-```js
-globalThis.observeCuaWindow = async (target, options = {}) => {
-  const key = `${target.pid}:${target.windowId}`;
-  const state = await computer.observeWindow({
-    ...target,
-    ...options,
-    baseRevisionId: cuaRevisions.get(key),
-    signal: nodeRepl.signal,
-  });
-  if (state.revisionId) cuaRevisions.set(key, state.revisionId);
-  return state;
+type WindowObservation = {
+  pid: number;
+  windowId: number;
+  mode: 'full' | 'diff' | 'no_change';
+  resyncReason?: string;
+  text: string;
+  elements: Array<Element>;
+  screenshot?: Screenshot;
 };
+
+type Element = {
+  element_token?: string;
+  role?: string;
+  label?: string;
+  automation_id?: string;
+  value?: unknown;
+  actions?: string[];
+};
+
+type Screenshot = {
+  images: Array<{ mimeType: string; dataBase64: string }>;
+};
+
+type Direction = 'up' | 'down' | 'left' | 'right';
+type MouseButton = 'left' | 'right' | 'middle';
+type DeliveryMode = 'background' | 'foreground';
+```
+
+## Workflow
+
+### 1. Initialize
+
+Start by getting the state for the app and window you want to use. When the task
+names an app, filter for that name directly:
+
+```js
+var apps = await computer.listApps();
+var matches = apps.filter(
+  (app) => app.name === 'Target App' || app.bundle_id === 'com.example.target',
+);
+nodeRepl.write(JSON.stringify(matches));
+
+var windows = await computer.listWindows({ pid: matches[0].pid });
+var target = { pid: matches[0].pid, windowId: windows[0].window_id };
+var state = await computer.observeWindow(target);
+nodeRepl.write(state.text); // This will return the accessibility tree
 ```
 
-Use accessibility text for efficient decisions. Request a screenshot when the
-tree is incomplete, visual layout matters, or action evidence conflicts with
-the tree. Emit only decision-relevant images:
+If you cannot identify an app from the task, prior context, or builtin apps,
+start by discovering the available apps:
 
 ```js
-for (const image of state.screenshot?.images ?? []) {
-  if (image?.dataBase64 && image?.mimeType) {
-    await nodeRepl.emitImage(
-      `data:${image.mimeType};base64,${image.dataBase64}`,
-    );
-  }
-}
+var apps = await computer.listApps();
+nodeRepl.write(JSON.stringify(apps));
 ```
 
-If the SDK explicitly reports a missing/invalid base or a stale lineage,
-perform one observation with `forceFull: true`, replace that surface's cursor,
-then resume the normal helper. Do not make full observations the default.
+After performing one or more UI actions, call `observeWindow(...)` before
+deciding what to do next. This keeps you in the current UI state. Read the
+current actionable `element_token` values from `state.elements`; tokens for
+unchanged elements remain valid across `diff` and `no_change` observations.
 
-## Act and verify
+For token efficiency, when appropriate, the accessibility tree will be returned
+as a diff from the most previous accessibility tree, listing only the elements
+that were removed, added, or changed. Prefer this default diff output; pass
+`disableDiff: true` only when you need a fresh full accessibility tree. If you
+disregard the text from a previous call to `observeWindow`, such as when you only
+emit the screenshot, get the full tree next time you inspect AX text.
+`state.elements` remains the current full actionable element list when
+`state.text` is a diff or reports no change.
 
-Choose the narrowest action supported by current state. Pass an observed
-`element_token` as `elementToken`. Use `performSecondaryAction` only when that
-exact action appears in the element's current `actions` list.
+### 2. Actions using app
 
-Before acting, state a concrete observable postcondition. For postconditions
-expressible as window or element state, use `actAndVerify` with `verifyState`:
+Perform one or more actions, and then fetch the latest state:
 
 ```js
-try {
-  globalThis.lastCuaOutcome = await computer.actAndVerify({
-    action: () =>
-      computer.setValue({
-        ...target,
-        elementToken,
-        value: expectedValue,
-        signal: nodeRepl.signal,
-      }),
-    verify: () =>
-      computer.verifyState({
-        ...target,
-        expect: [
-          {
-            element: {
-              selector: { role: expectedRole, label_contains: expectedLabel },
-              value_equals: expectedValue,
-            },
-          },
-        ],
-        stableSamples: 2,
-        signal: nodeRepl.signal,
-      }),
-  });
-  nodeRepl.write(JSON.stringify(lastCuaOutcome));
-} catch (error) {
-  nodeRepl.write(JSON.stringify(error?.details ?? { message: String(error) }));
-  throw error;
-}
+await computer.click({ pid: target.pid, elementToken });
+await computer.setValue({ pid: target.pid, elementToken, value: 'openai.com' });
+await computer.pressKey({ ...target, key: 'Enter' });
+await computer.typeText({ ...target, text: 'hello' });
+await computer.scroll({
+  pid: target.pid,
+  elementToken,
+  direction: 'down',
+  amount: 1,
+});
+await computer.performSecondaryAction({
+  pid: target.pid,
+  elementToken,
+  action: 'Show Menu',
+});
+nodeRepl.write((await computer.observeWindow(target)).text);
 ```
 
-`verifyState.expect` accepts one to eight AND-combined predicates:
+Notes:
 
-- `{window:{exists, bounds?}}`
-- `{element:{selector:{role?, label_contains?}, exists:true?,
-value_equals?, enabled?, selected?}}`
+- Prefer `element_token`-based actions over coordinate actions. If AX actions or AX text are unavailable or behave unexpectedly, switch to screenshots, coordinate clicks, and key presses.
+- `doubleClick` and `rightClick` invoke their dedicated SDK actions; `rightClick` also accepts optional modifiers.
+- If the UI is not behaving as expected, try fetching the latest `observeWindow(...)` state to make sure you have the latest context.
+- Prefer using accessibility text over screenshots for efficiency, but if the interface is not fully working or not providing enough context, make sure to fetch a screenshot to get more context. The accessibility interface may be incomplete in some applications, so a screenshot helps fully understand what is going on.
+- `performSecondaryAction` invokes an accessibility action that an element exposes besides a normal click, such as expanding a disclosure row, showing a menu, incrementing a control, or cancelling something. It requires an action actually exposed for that element in the accessibility text. Do not guess action names.
+- `pressKey` presses one key and accepts optional modifiers; `hotkey` sends a key combination such as `{ keys: ['ctrl', 'c'] }`. Single-key examples include `"a"`, `"Enter"`, `"Tab"`, and `"Up"`.
+- Take care when passing strings containing `\n` or `\r` to `typeText`, as it simulates pressing the return key. Many apps with message composers or forms will respond by sending the message or submitting the form rather than inserting a newline.
+- The SDK targets an exact PID and window ID. If an action opens a dialog, menu, or new window, call `listWindows({ pid })` again and select the current window before continuing.
 
-Element absence is not provable. `unknown` and `stable:false` are not success.
-When the postcondition is visual or unsupported, observe the exact window
-again with a screenshot and inspect the fresh result before deciding. If state
-is unexpected, observe again rather than repeating the action blindly.
+## Reading screenshots
 
-Read every action result. `effect` is `confirmed`, `partial`, `unverifiable`,
-`suspected_noop`, or `refused`; `route`, `delivery`, `evidence`, `escalation`,
-and `operation` explain what actually happened. A committed operation can
-still have `cancellationRequested:true`, so it still requires verification.
-Follow an advertised escalation only after fresh state shows it is needed.
+Request a screenshot with the observation, read its accessibility text, and
+emit each returned image:
 
-## Interaction details
+`includeScreenshot: true` is the parameter that requests a screenshot.
 
-- After navigation, dialogs, menus, or other surface changes, refresh the
-  relevant window list and observe the new exact surface.
-- Use returned state to determine text-field behavior; do not assume typing
-  replaces existing text. Use the platform-appropriate select-all action when
-  replacement is required.
-- Prefer background delivery. Use `deliveryMode:'foreground'` only when the
-  action result or fresh state shows the background route is unavailable or
-  ineffective.
-- Stop as soon as the requested postcondition is stably satisfied. Do not add
-  extra cleanup actions that could undo the result.
+```js
+var state = await computer.observeWindow({
+  ...target,
+  includeScreenshot: true,
+});
+nodeRepl.write(state.text);
+for (const image of state.screenshot?.images ?? []) {
+  await nodeRepl.emitImage(`data:${image.mimeType};base64,${image.dataBase64}`);
+}
+```
 
-## Finish
+When all Computer Use work is complete:
 
 ```js
 await computer.close();
 globalThis.computer = undefined;
-globalThis.cuaRevisions = undefined;
-globalThis.observeCuaWindow = undefined;
 ```
 
-Reset the REPL only when no other persistent state is needed.
+Reset the Node REPL only when no other persistent state is needed.

package/bundled/goal-draft/SKILL.md

@@ -13,7 +13,7 @@ allowedTools:
 
 You are already inside the loaded `goal-draft` skill — do not call the `skill` tool to invoke it again; start with Step 0.
 
-You are drafting the text for `/goal set`. You are NOT doing the work the goal describes. Do not edit files, do not run the checks, do not start on the task. The only deliverable is the objective text and the `/goal set` line the user can run.
+You are drafting the text for `/goal set`. You are NOT doing the work the goal describes. Do not edit files, do not run the checks, do not start on the task. Deliver a concise objective for approval or a command the user can run; if essential information is missing, deliver only a draft marked "Needs clarification".
 
 ## How Goals are judged (why the format below matters)
 
@@ -32,12 +32,14 @@ Say no, briefly, when the request is a normal one-shot task, needs a design or p
 
 ## Step 1 — check the active Goal
 
-Call `get_goal`. If a Goal is active, ask whether to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). Never draft a second concurrent goal.
+Call `get_goal`. If a Goal is active, preserve the user's explicit choice to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). If that choice is unclear, include it in Step 3's single round of questions; do not choose on the user's behalf. Never draft a second concurrent goal.
 
 ## Step 2 — ground the draft in the workspace
 
 Before asking anything, verify what you can with `read_file`, `glob`, and `grep_search`: that named files and packages exist, and what the real check commands are (`package.json` scripts, `Makefile`, CI workflow, test config). Use those exact commands in "Done when". Never invent paths, IDs, or commands; write `<TODO: …>` for anything you cannot confirm.
 
+Read only what is needed to establish the scope and verification path. Stop exploring once those are grounded; do not audit the implementation, reproduce failures, run builds or tests, install dependencies, or start services while drafting. A requested new output file is a proposed destination, not evidence that the file already exists.
+
 ## Step 3 — at most one round of questions
 
 Ask with `ask_user_question`, 1–3 questions in one call, each with options and a recommended default. Ask only when the answer changes the check, the scope, or the budget. Typical questions:
@@ -54,7 +56,7 @@ Rules for the questions:
 - Only ask things only the user can answer: what counts as done, what is off limits, how long to try.
 - If you cannot find a concrete way to verify the outcome, you MUST ask, offering 2–3 candidate checks. Do not skip this and do not invent one.
 
-If you cannot ask (headless, or a client without prompts), take the recommended default and mark it `[ASSUMPTION]` in Context.
+If you cannot ask (headless, or a client without prompts), use a recommended default only for nonessential choices and mark it `[ASSUMPTION]` in Context. An unknown success criterion, unverified command or input path, or unresolved edit-versus-replace choice stays `<TODO: …>`; do not invent an answer just to finish the hand-off. If essential information is still missing after the single question round, keep the draft incomplete rather than starting another round.
 
 ## Step 4 — draft the objective
 
@@ -64,7 +66,7 @@ Use exactly these labels, in this order. Keep the whole objective on one line wh
 Outcome: <one sentence: what is true when done>
 Done when: 1) <command> exits 0 and its output shows <…> (paste that line); 2) <file/state assertion provable via read or grep>; 3) …
 Must not: <files not to touch; tests/thresholds not to weaken; irreversible actions not to take>
-Budget: stop as blocked after <N> turns (default 20) or <M> minutes without measurable progress
+Budget: <user's stopping agreement; otherwise stop as blocked after 20 turns, and mark that default [ASSUMPTION] in Context>
 On block: propose blocked with the exact blocker and the decision a human must make; never claim completion without evidence for every Done-when item
 Context: <only facts the agent cannot derive: paths, branch, environment, earlier decisions>
 ```
@@ -72,19 +74,24 @@ Context: <only facts the agent cannot derive: paths, branch, environment, earlie
 Rules of thumb:
 
 - One Outcome. Several outcomes = several goals, or a checklist file plus a single "every item in `<file>` is checked" goal.
+- Usually 3–5 Done-when checks suffice; use fewer when enough. Do not add checks just to reach a count, and preserve explicit user requirements.
 - Every Done-when item is binary, and at least one is tool-observable (a command with an exit code or output line, a file that exists, a grep that matches).
+- For audits and exploratory work, agree on bounded coverage and require evidence for each conclusion. Zero defects is a valid result: never require a positive defect count. Do not invent minimum scenario counts, evidence-file counts, or exploration-round quotas; include them only when the user requested them.
 - Prefer "the smallest safe change in `<scope>`" over open-ended refactors.
 - Put anything that must not change on the way into Must not — this is what stops the loop from deleting a failing test to "pass".
 - Keep it short: everything the agent can derive from the workspace stays out. Aim for under ~1200 characters.
+- `Budget` is a stopping agreement for the model, not a runtime-enforced turn or wall-clock limit. Do not claim that writing it configures a timer or changes the Goal token budget. Preserve a user-specified budget; otherwise mark the default `[ASSUMPTION]` in Context.
+
+For example, an audit's Done-when checks can require a report covering the agreed scenarios, observed results and evidence for each scenario, and reproduction steps for each confirmed defect (or an explicit "no confirmed defects" result). Ground the scenarios and report destination before offering the objective for use.
 
 ### Weak → strong
 
-| Weak                          | Strong                                                                                                                                                                                                                                                                                                                                                                                           |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| make checkout faster          | Outcome: checkout API p95 is below 250 ms on the documented slow path. Done when: 1) `npm run bench:checkout` exits 0 and prints a p95 below 250 (paste the line); 2) `npm test` exits 0. Must not: change the benchmark, skip tests, touch files outside `src/checkout`. Budget: stop as blocked after 20 turns. On block: report the measured p95 and what blocks it.                          |
-| keep handling the PR comments | Outcome: every unresolved review thread on PR #123 is fixed or answered. Done when: 1) the review-threads query shows zero unresolved threads (paste the count); 2) CI on the head commit is green (paste the check summary). Must not: force-push, resolve a thread without replying to it. Budget: stop as blocked after 30 turns. On block: list the threads that need a maintainer decision. |
-| clean up the auth module      | Not a goal — "clean" has no check. Ask what would be observable (zero lint warnings in `src/auth`? a file count? a coverage threshold?) or offer a refactor plan instead.                                                                                                                                                                                                                        |
-| get the release out           | Not a goal as written — publishing is irreversible. Either narrow it to a checkable pre-release state (tag exists, changelog entry present, `npm run release:dry-run` exits 0) and put "do not publish" in Must not, or leave publishing to a human.                                                                                                                                             |
+| Weak                          | Strong                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| make checkout faster          | Outcome: checkout API p95 is below 250 ms on the documented slow path. Done when: 1) `npm run bench:checkout` exits 0 and prints a p95 below 250 (paste the line); 2) `npm test` exits 0. Must not: change the benchmark, skip tests, touch files outside `src/checkout`. Budget: stop as blocked after 20 turns. On block: report the measured p95 and what blocks it. Context: [ASSUMPTION] the 20-turn budget is the drafter's default, not the user's. |
+| keep handling the PR comments | Outcome: every unresolved review thread on PR #123 is fixed or answered. Done when: 1) the review-threads query shows zero unresolved threads (paste the count); 2) CI on the head commit is green (paste the check summary). Must not: force-push, resolve a thread without replying to it. Budget: stop as blocked after 30 turns. On block: list the threads that need a maintainer decision.                                                           |
+| clean up the auth module      | Not a goal — "clean" has no check. Ask what would be observable (zero lint warnings in `src/auth`? a file count? a coverage threshold?) or offer a refactor plan instead.                                                                                                                                                                                                                                                                                  |
+| get the release out           | Not a goal as written — publishing is irreversible. Either narrow it to a checkable pre-release state (tag exists, changelog entry present, `npm run release:dry-run` exits 0) and put "do not publish" in Must not, or leave publishing to a human.                                                                                                                                                                                                       |
 
 ## Step 5 — self-check, then hand off
 
@@ -96,18 +103,21 @@ Check every line before printing:
 4. No "after the user confirms/approves" as a completion condition — that belongs in On block as a decision a human must make.
 5. Budget or On block is present.
 6. Exactly one Outcome.
-7. Every path and command in Context was verified in the workspace or is marked `<TODO>`.
+7. Every path and command in Context was verified in the workspace; an unverified path or command is essential and stays `<TODO: …>`.
 8. Under ~1200 characters.
 9. Irreversible actions (push, delete, publish) are listed in Must not, or the user explicitly allowed them.
+10. No invented coverage quotas, required defect findings, or claims that a prose budget is enforced by the runtime; an unrequested default Budget is marked `[ASSUMPTION]` in Context.
+
+**If an essential item remains unresolved — an unknown success criterion, an unverified command or input path, or an unresolved edit-versus-replace choice (each written as `<TODO: …>`) —**, print only a draft marked "Needs clarification" (in the user's language) and briefly list what is missing. Do not call `propose_goal` or print a runnable `/goal set` or `/goal edit` line. Stop here; the ready-objective hand-off below does not apply.
 
 Then hand off, and nothing else:
 
 **If the `propose_goal` tool is available and no Goal is active**, call it with the objective on one line. The user approves or declines it in a dialog; only their approval sets the Goal. If they decline you will not be told why: stop, do not ask about it, and do not propose the same or a reworded objective again. After approval, acknowledge it in one sentence and end the turn — the Goal runtime starts the first Goal turn on its own.
 
-**Otherwise** (headless, the tool is disabled, or a Goal is active), print:
+**Otherwise** (Web Shell or another ACP client, headless, the tool is disabled, or a Goal is active), print:
 
 1. The objective in a fenced code block.
 2. One line the user can run as-is: `/goal set <objective on one line>` (or `/goal edit …` when tightening the active goal). Print it as plain text with no code markers, so it can be copied verbatim.
-3. One sentence on what you assumed (`[ASSUMPTION]` / `<TODO>` items), if any.
+3. One sentence explaining that the draft has not been applied and the user must run the command to apply it; include any `[ASSUMPTION]` items. Do not promise a dialog in Web Shell or other ACP sessions.
 
 Do not run /goal yourself. Do not begin the task. Stop and wait for the user.

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

@@ -16,6 +16,7 @@ export default {
   'integration-github-action': 'GitHub Actions',
   'qwen-serve': 'Daemon mode (qwen serve)',
   'qwen-serve-deploy-local': 'Daemon mode — local launch templates',
+  'conversations-recovery': 'Conversations writer locks and recovery',
   'Code with Qwen Code': {
     type: 'separator',
     title: 'Code with Qwen Code', // Title is optional

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

@@ -2,7 +2,7 @@
 
 Qwen Code's first-run `/auth` menu has three top-level options. Pick the one that matches how you want to run the CLI:
 
-- **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key).
+- **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key). Token Plan and Standard API Key also enable the built-in [`web_search` tool](../../developers/tools/web-search.md) with no extra setup.
 - **Third-party Providers**: choose a built-in provider and connect with an API key (DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty).
 - **Custom Provider**: manually connect a local server, proxy, or unsupported provider — supports OpenAI, Anthropic, Gemini, and other compatible endpoints.