@qwen-code/qwen-code 0.23.3 → 0.23.4

package/bundled/qc-helper/docs/extension/getting-started-extensions.md

@@ -248,6 +248,8 @@ Subagents are specialized AI assistants for specific tasks.
 
 After restarting Qwen Code, your custom skills will be available via `/skills` and subagents via `/agents manage`.
 
+An extension skill is registered under its owner's name: the skill above becomes `my-first-extension:code-analyzer`, so you run it as `/my-first-extension:code-analyzer`. `skills.disabled` can block it under either that name or the plain `code-analyzer` you authored; `skills.enabled` opts it back in under the prefixed name only. See [Extension Skills](../features/skills.md#extension-skills).
+
 ## Step 6: Add a Custom `QWEN.md`
 
 You can provide persistent context to the model by adding a `QWEN.md` file to your extension. This is useful for giving the model instructions on how to behave or information about your extension's tools. Note that you may not always need this for extensions built to expose commands and prompts.

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

@@ -364,15 +364,21 @@ Extensions can provide custom skills by placing skill files in a `skills/` subdi
 
 **Example**
 
+An extension named `gcp` with the following structure:
+
 ```
-.qwen/extensions/my-extension/
+.qwen/extensions/gcp/
 ├── qwen-extension.json
 └── skills/
     └── pdf-processor/
-        └── SKILL.md
+        └── SKILL.md   # frontmatter: name: pdf-processor
 ```
 
-The skill will be available via the `/skills` command when the extension is active.
+provides one skill, registered as `gcp:pdf-processor` — the extension's `name`, a colon, then the name the `SKILL.md` authors. Run it with `/gcp:pdf-processor`; `/skills` lists it and labels it with the extension's display name, falling back to its `name` when the manifest declares none.
+
+Unlike the extension's custom commands, which are named after their files (`/deploy` and `/gcs:sync` above, and prefixed only when one collides — see Conflict resolution below), an extension skill always carries its owner: two extensions that both ship a `pdf-processor` give you two skills instead of one shadowing the other. The prefix is added as the skill loads, so the `name` in your `SKILL.md` is never rewritten on disk.
+
+Settings that name skills treat the two spellings asymmetrically: `skills.disabled` blocks a skill under either name, while `skills.enabled` opts it in under the prefixed name only. See [Extension Skills](../features/skills.md#extension-skills).
 
 ### Custom subagents
 

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

@@ -8,6 +8,7 @@ export default {
   'terminal-images': 'Terminal Images',
   'sub-agents': 'SubAgents',
   'multi-agent-coordination': 'Multi-Agent Coordination',
+  'agent-board': 'Agent Board',
   arena: 'Agent Arena',
   skills: 'Skills',
   memory: 'Memory',

package/bundled/qc-helper/docs/features/agent-board.md

@@ -0,0 +1,89 @@
+# Agent Board
+
+Agent Board lets independently started agents share work through files on the
+same machine. It does not start, join, monitor, or send input to agent processes.
+
+It is a low-level interoperability surface, not the Qwen Agent Team scheduler or
+the cross-session messaging transport. A task owner is only a recorded label;
+it does not start or wake a Qwen Code, Codex, or other agent process.
+
+> Experimental. The on-disk format may change between releases.
+
+## Use a board
+
+Every command names the board explicitly. Every command that changes the board
+also declares the actor with `--as`.
+
+```bash
+qwen board task "check the API response" --board orders --as api
+qwen board show --board orders
+```
+
+The first command prints a task id. Another agent can claim and complete it:
+
+```bash
+qwen board claim <task-id> --board orders --as web
+qwen board done <task-id> --board orders --as web --note "status is numeric"
+```
+
+`--as` is a label recorded with the action, not authentication. There is no
+membership list, join command, heartbeat, or reserved participant name.
+
+Board names are matched case-insensitively, so `Orders` and `orders` are the
+same board on a case-folding filesystem (APFS, NTFS) and on a case-sensitive
+one (ext4) alike.
+
+## Ask a question
+
+```bash
+qwen board ask web "does the client parse status as text?" \
+  --board orders --as api --wait
+```
+
+The receiver uses the same label when answering or declining:
+
+```bash
+qwen board answer <ask-id> "yes" --board orders --as web
+qwen board decline <ask-id> "not my area" --board orders --as web
+```
+
+With `--wait`, exit code `0` means answered, `2` declined, `3` the ask's TTL
+expired, and `4` the local wait ended while the ask was still open. `--timeout`
+sets the local wait in seconds; `--ttl` sets the ask lifetime in seconds.
+
+Expiry is derived on read, never written back. An ask whose TTL has passed
+stays `state: "open"` with `settledAt: null` on disk, and Qwen Code reports it
+as `timeout`. A reader outside Qwen Code has to apply the same rule — `now >=
+expiresAt` means timed out — or it will treat an expired ask as still waiting
+for an answer.
+
+## Machine-readable output
+
+Add `--json` to receive JSON without ANSI formatting:
+
+```bash
+qwen board show --board orders --as web --json
+```
+
+Passing `--as` to `show` filters tasks to that owner and asks to or from that
+actor.
+
+## Housekeeping
+
+Settled records remain until explicitly pruned:
+
+```bash
+qwen board prune --board orders --as human --older-than 7
+```
+
+The cutoff is in days. Pruning rechecks each record while holding its lock, so
+an item changed after the scan is not deleted from stale information.
+
+## Limits
+
+- Boards live under `~/.qwen/boards/` and are scoped to the current OS user.
+- Nothing is pushed into an agent. Each participant chooses when to read.
+- Board text is untrusted data and is never automatically executed.
+- Multiple agents writing the same checkout is not supported.
+- Slash commands, footer polling, fleet/tmux orchestration, and remote boards
+  are not part of this first version.

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

@@ -111,26 +111,6 @@ Background Agent output is sent as soon as each response segment is available.
 Every message is labeled with the Agent name so concurrent work remains
 attributable.
 
-To buffer each Agent's notification turn and send it as one labeled message,
-enable aggregation for the DingTalk channel in `settings.json`:
-
-```json
-{
-  "channels": {
-    "my-dingtalk": {
-      "type": "dingtalk",
-      "clientId": "$DINGTALK_CLIENT_ID",
-      "clientSecret": "$DINGTALK_CLIENT_SECRET",
-      "aggregateBackgroundAgentResponses": true
-    }
-  }
-}
-```
-
-Aggregation is disabled by default. A partial labeled message is sent if the
-Agent turn is interrupted, fails before producing a final response, or does
-not finish within ten minutes.
-
 ## Running
 
 ```bash
@@ -186,6 +166,8 @@ By default, the bot requires an @mention in group chats (`requireMention: true`)
 
 Set `"atSender": true` to have the bot @mention the member whose group message triggered its response. It is off by default and only applies to agent replies with a DingTalk staff ID. Replies are sent as DingTalk markdown whether or not they carry a mention; the mention prefix is included in the first message chunk.
 
+Qwen Code preserves the text content supplied by DingTalk when constructing the canonical message; it does not remove a leading mention itself. When DingTalk omits the bot mention from a plain-text callback, a body such as `/clear` or `!command` still begins with that command marker and follows the normal local-command rules. When the callback retains a leading bot mention, as rich-text callbacks can, `@Bot /clear` and `@Bot !command` remain ordinary agent input because the canonical text does not begin with `/` or `!`. `isInAtList` continues to determine whether the group message addressed the bot.
+
 ### Finding a Group's Conversation ID
 
 DingTalk uses `conversationId` to identify groups. You can find it in the channel service logs when someone sends a message in the group — look for the `conversationId` field in the log output.
@@ -225,7 +207,7 @@ The multi-line layout above is what the agent sees in a 1:1 chat. In a group the
 
 - **Use DingTalk markdown-aware instructions** — DingTalk supports headings, bold text, links, code blocks, and tables. Keep tables compact because narrow screens may scroll horizontally.
 - **Restrict access** — In an organization context, `senderPolicy: "open"` may be acceptable. For tighter control, use `"allowlist"` or `"pairing"`. See [DM Pairing](./overview#dm-pairing) for details.
-- **Referenced messages** — Quoting (replying to) a user message includes the quoted text as context for the agent. If the quoted message is a picture, file, audio, or video message, the bot downloads and attaches it the same way as when sent directly. Quoting bot responses is not yet supported.
+- **Referenced messages** — Quoting (replying to) a user message includes the quoted text as context for the agent. Rich-text quotes preserve their text order and attach embedded pictures. If the quoted message is a picture, file, audio, or video message, the bot downloads and attaches it the same way as when sent directly. Quoting bot responses is not yet supported.
 
 ## Troubleshooting
 

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

@@ -67,7 +67,7 @@ without interactive confirmations:
 YOLO mode auto-approves every tool call. Use it only for a trusted bot account
 and workspace.
 
-`senderPolicy` and `groupPolicy` default to `pairing` for a newly managed DWS channel. Approve a user or group with the code returned by the channel:
+`senderPolicy` and `groupPolicy` default to `pairing` for a newly managed DWS channel. `dmPolicy` defaults to `open`, including existing configurations that omit it. Approve a user or group with the code returned by the channel:
 
 ```bash
 qwen channel pairing approve dws-work CODE
@@ -75,6 +75,10 @@ qwen channel pairing approve dws-work CODE
 
 `senderPolicy` controls direct-message senders, document-notification authors, native-todo creators, and senders in `open` or `allowlist` groups. `groupPolicy` controls group conversations. An approved pairing group follows the shared channel behavior and authorizes its members; open and allowlist groups must also pass `senderPolicy`.
 
+Group and direct-message access can be configured independently. For a group-only channel, set `dmPolicy: "disabled"` and choose an enabled `groupPolicy`. For a direct-message-only channel, set `groupPolicy: "disabled"` and `dmPolicy: "open"`. Direct-message access also controls document notifications. Native todo polling remains controlled separately by `watchTodos`.
+
+Disabled chat sources are not subscribed to or polled, and their messages cannot start new tasks through late callbacks or persisted replay. Pending work and history cursors are retained: after re-enabling a source, the existing recovery mechanism may process older messages, including messages from the disabled interval. Sender authorization, group pairing, and mention requirements still apply.
+
 `groups` controls mention behavior. A concrete group ID overrides `"*"`. With `requireMention: true`, only an @ message wakes the channel. With `requireMention: false`, ordinary messages are also received after the group and sender policies pass.
 
 Group mentions use the real-time personal event stream first. The channel also checks recent `@` message history every five seconds, so mentions from external groups are recovered when DingTalk omits them from the personal event stream. Messages are deduplicated by conversation and message ID across both paths.

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

@@ -63,7 +63,6 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 | `allowedUsers`      | No               | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies)                                                                                                                                    |
 | `sessionScope`      | No               | How sessions are scoped: `user` (default), `chat_thread`, or `single`. Legacy `thread` remains compatible when already configured but is not offered for new Web Shell configurations                                   |
 | `multiSession`      | No               | Retain up to eight owner-scoped named tasks in one chat. Requires daemon-managed mode, `sessionScope: "user"`, no webhooks or group-history backfill, and no enabled Channel loops                                      |
-| `messagePrefix`     | No               | Only dispatch user messages that begin with this exact, case-sensitive prefix after any leading `@mentions`; the prefix and following whitespace are removed before dispatch                                            |
 | `cwd`               | No               | Working directory for the agent. Defaults to the current directory                                                                                                                                                      |
 | `approvalMode`      | No               | Tool approval mode for channel sessions. Unattended webhook tasks require `yolo`; the setting applies to every session on the channel                                                                                   |
 | `instructions`      | No               | Custom instructions prepended to the first message of each session                                                                                                                                                      |
@@ -74,10 +73,6 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 | `groups`            | No               | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats)                                                                                                                      |
 | `dispatchMode`      | No               | What happens when you send a message while the bot is busy: `steer` (default), `collect`, or `followup`. See [Dispatch Modes](#dispatch-modes)                                                                          |
 
-When `messagePrefix` is set, every user-authored message must begin with the prefix and a non-empty payload, for example `/review inspect #123`. Only the prefix and the mentions ahead of it are removed; a mention the user typed after the prefix reaches the agent unchanged. Shared and agent commands use the same rule (`/review /help`, `/review /clear`, and so on). Telegram's registered command-menu actions remain available without the prefix — unless the configured prefix is itself one of them, in which case the prefix wins and that command has to be sent prefixed too (`/new /new`). Attachments need a matching caption when the platform supports one; captionless Telegram, Feishu, WeChat, DingTalk and WeCom media messages continue to run, and their placeholder text is never quoted back as group history. Native todos, webhooks, and provider-generated assignment or review-request events also continue to run without a prefix because they are system events rather than chat messages.
-
-Two behaviours are deliberate and worth knowing before you turn the prefix on. A voice message whose transcript DingTalk or WeCom fills in counts as text the user spoke, so it must carry the prefix like any other message and is dropped otherwise — only an untranscribed voice note runs as captionless media. And the prefix is checked before pairing, so first contact from an unknown sender or an unapproved group has to carry the prefix as well; without that ordering every unprefixed message in a busy group would draw a pairing reply, which is exactly the noise the prefix exists to suppress. Tell new users the prefix out of band, or leave pairing channels unprefixed.
-
 ### Sender Policy
 
 Controls who can interact with the bot:
@@ -524,7 +519,11 @@ qwen channel status --daemon-url http://127.0.0.1:4170 --token secret
 qwen channel stop --daemon-url http://127.0.0.1:4170 --token secret
 ```
 
-This mode starts workspace-grouped channel worker processes owned by `qwen serve`. Workers connect back to the daemon through the SDK and use the same channel adapters. They are separate from the daemon process, so a channel adapter crash does not crash the daemon. A daemon started without `--channel` does not load channel adapters or reserve the channel-service PID lease until the first `qwen channel set`.
+This mode starts workspace-grouped channel worker processes owned by `qwen serve`. Workers connect back to the daemon through the SDK and use the same channel adapters. They are separate from the daemon process, so a channel adapter crash does not crash the daemon. An explicit `--channel` selection takes precedence and fails daemon startup if it cannot become ready. On a flagless boot, the trusted primary workspace's `serve.channels` setting is restored. Secondary workspaces do not independently restore their own `serve.channels`. Without either source, the daemon does not load channel adapters or reserve the lease until the first `qwen channel set`.
+
+Automatic restore skips invalid startup settings and validation or lease failures that occur before workers start, while preserving unrelated settings. After a worker startup fails, the daemon continues only once cleanup succeeds. A global runtime startup timeout or an unconfirmed worker stop still follows the normal startup-failure path; the service lease remains held while worker termination is unconfirmed. Check the daemon log for messages identifying `serve.channels` when a channel does not restore.
+
+Stored startup names must be non-empty, have no leading or trailing whitespace, and contain no unsafe control or invisible characters. Invalid entries are skipped individually and logged by their array index. Startup does not rename instances or rewrite the configuration. The channel startup toggle reflects the saved setting; runtime state shows whether the channel is running.
 
 `qwen serve --channel` is not the same service as `qwen channel start`. Standalone `qwen channel start` still uses the ACP-backed channel service and can run channel configs with different `cwd` values. Daemon-managed channels require every selected channel's `cwd` to resolve to a workspace registered by the daemon. In multi-workspace mode, a selection replacement keeps workers for workspaces whose ordered channel list did not change; `all` remains primary-workspace-only.
 

package/bundled/qc-helper/docs/features/code-review.md

@@ -133,7 +133,7 @@ A **source** file that is largely rewritten (an existing file of 300+ lines that
 
 The checklist is split three ways on purpose. Handing one agent all eight checks over a 2 400-line file gets one of them done properly; three agents with two or three checks each get all of them done. Chunk agents do not substitute for this — on PR #6457 they held every one of these defects inside their assigned territory and reported none. What they lacked was not the lines but the question.
 
-Findings are verified in **sharded batches** (at most 8 findings per verification agent, all launched together). A verifier may reject a Critical only by quoting the code that contradicts it (or when the diff's own comments document the flagged behavior as deliberate); anything less certain is downgraded to low confidence rather than deleted — a silently rejected Critical is invisible to every later stage, while a downgraded one still reaches a human. The bar applies to the shape of every rejection: it must be constructible from the code — quote the line the finding misreads, prove the claimed state impossible from a type, constant, or invariant, cite the in-diff guard that covers the trigger, or match a pure-style change with no observable effect — or otherwise match an exclusion criterion — and "too speculative" is never one of them. A finding whose failure scenario names a state the code does not exclude is plausible by default: a concurrency race, nil/undefined on a rare-but-reachable path, a falsy zero or empty collection treated as missing, an off-by-one on an unexcluded boundary, a retry storm or partial failure, a regex or allowlist that lost an anchor. A rejection that constructs none of the four grounds downgrades instead of dropping. After verification, **iterative reverse audit** hunts for gaps, fanned out one auditor per chunk per round, each with the cumulative finding list. The loop stops after **two consecutive dry rounds** (or at the plan's round cap — reported as such rather than as convergence). That cap follows the diff's topology: **10** on a small diff, where a round is a single auditor; **5** on a chunked one, where it is one auditor per chunk; and **3** on a huge diff (≥ 3000 effective lines) _when the run has a deadline_, because five ~90-minute rounds do not fit a six-hour CI ceiling and a review killed mid-flight posts nothing — with no deadline a huge diff keeps the chunked cap of 5. An operator can lower whichever cap applies for every review with the `review.reverseAuditRounds` setting; it can never raise one. One dry round is not evidence of convergence, and reverse-audit findings are verified like any other.
+Findings are verified in **sharded batches** (at most 8 findings per verification agent, all launched together). A verifier may reject a Critical only by quoting the code that contradicts it (or when the diff's own comments document the flagged behavior as deliberate); anything less certain is downgraded to low confidence rather than deleted — a silently rejected Critical is invisible to every later stage, while a downgraded one still reaches a human. The bar applies to the shape of every rejection: it must be constructible from the code — quote the line the finding misreads, prove the claimed state impossible from a type, constant, or invariant, cite the in-diff guard that covers the trigger, or match a pure-style change with no observable effect — or otherwise match an exclusion criterion — and "too speculative" is never one of them. A finding whose failure scenario names a state the code does not exclude is plausible by default: a concurrency race, nil/undefined on a rare-but-reachable path, a falsy zero or empty collection treated as missing, an off-by-one on an unexcluded boundary, a retry storm or partial failure, a regex or allowlist that lost an anchor. A rejection that constructs none of the four grounds downgrades instead of dropping. After verification, **iterative reverse audit** hunts for gaps, fanned out one auditor per chunk per round, each with the cumulative finding list. The loop stops after **two consecutive dry rounds** (or at the plan's round cap — reported as such rather than as convergence). That cap follows the diff's topology: **10** on a small diff, where a round is a single auditor; **5** on a chunked one, where it is one auditor per chunk; and **3** on a huge diff (≥ 3000 effective lines) _when the run has an explicit deadline_ (CI's, or `--deadline` at capture), because five ~90-minute rounds do not fit a six-hour CI ceiling and a review killed mid-flight posts nothing — under the plan's default wall a huge diff keeps the chunked cap of 5. Capture prices the tier from the clock it sees and records it; a reader may only lower a recorded value inside its band (a plan captured under CI's epoch keeps 3 in a continuation resumed without that epoch; one captured with no clock is cut to 3 if the run later gains one), and a value outside the band falls back to the tier. An operator can lower whichever cap applies for every review with the `review.reverseAuditRounds` setting; it can never raise one. One dry round is not evidence of convergence, and reverse-audit findings are verified like any other.
 
 ## Severity Levels
 
@@ -414,9 +414,9 @@ The exit code is the contract a gate should read:
 
 `--resume` continues an interrupted review of the same PR instead of starting over — when a long local run dies part-way (a dropped connection, a timeout, a killed terminal), the retry would otherwise re-fetch, re-chunk and re-launch agents whose work is already on disk. It is safe to pass unconditionally on a retry: `fetch-pr` rules on the on-disk state itself (worktree still at the fetched SHA and clean, diff bytes unchanged, PR head unmoved, resume cap unspent) and silently falls back to a fresh review whenever anything no longer matches, so the flag never fails a run that could start over. When the current invocation has only the built-in target default, a continuation stays pinned to the interrupted run's recorded effort. An explicit `--effort`, a project-remembered level, the operator `review.effort` setting, or an effective `--comment` supplies a required level; a mismatch refuses the resume and runs fresh at that level. PR targets only (a local review's diff is captured from a live working tree, which has no stable interrupted state to continue). Resume is a **local convenience**: the repository's own CI review workflow does **not** resume — each retry re-runs fresh, because a CI attempt runs no-sandbox and its worktree is deleted on exit, leaving no interrupted state to continue.
 
-A time-budgeted run can also export a **soft** deadline so the review stops its open-ended reverse-audit loop while there is still time to verify, compose and post: `QWEN_REVIEW_DEADLINE_EPOCH` is the Unix-seconds moment the run will be killed, and `QWEN_REVIEW_DEADLINE_RESERVE_SECONDS` (default 3600; `0` keeps only the round estimate) is the tail that must remain for the last round's verification, `compose-review` and submission. When the remaining budget no longer fits another round plus that tail, the round builder refuses to build it, and the composed verdict discloses the truncated audit (an otherwise-Approve verdict is capped at Comment). A missing or malformed deadline leaves the review ungated — the outer timeout still bounds the run.
+A time-budgeted run can also export a **soft** deadline so the review stops its open-ended reverse-audit loop while there is still time to verify, compose and post: `QWEN_REVIEW_DEADLINE_EPOCH` is the Unix-seconds moment the run will be killed, and `QWEN_REVIEW_DEADLINE_RESERVE_SECONDS` (default 4800; `0` keeps only the round estimate) is the tail that must remain for the last round's verification, `compose-review` and submission. When the remaining budget no longer fits another round plus that tail, the round builder refuses to build it, and the composed verdict discloses the truncated audit (an otherwise-Approve verdict is capped at Comment). Without that variable the review uses the wall its plan recorded at capture: `--deadline <minutes>` on `qwen review fetch-pr` / `capture-local` / `plan-diff`, or by default **8 hours** on a small (Step 3A) diff, **12** on a large (3B) one and **16** on a huge one. That default is a liveness bound — sized above what a healthy run at the round cap spends — so it ends a loop that has stopped converging and leaves a run that keeps working untouched; it is charged in elapsed time, idle included, so a session left overnight spends it, and because the next round is priced from the previous round's admission, a multi-hour pause between rounds can stop a run with time still on the wall (a `--resume` from a new session restarts both the wall and the pricing; **Review Deadline** below gives the ceilings). It stops the loop at the next round admission or verify build; it does not interrupt a build already running. A plan-recorded wall keeps a third of itself (capped at 4800 seconds, floored at the compose floor) as the tail reserve unless the reserve variable is set; a `--deadline` that cannot hold a convergence (two rounds plus that reserve — at or under ninety minutes, or more when the shell's reserve or compose-floor overrides raise the bar; that second leg is skipped while the environment exports a well-formed epoch, since the flag is inert then, and the wall it records is priced again in whatever shell a later env-less `--resume` runs in) is refused up front, and a wall just above it can still stop before round 1 once the fan-out and verification have spent it. When the wall can no longer admit a rebuild the coverage check would otherwise prescribe (a reverse-audit round, or a verifier shard under the compose floor), `compose-review` withholds that `FIX:` line and prints a `NOTE:` line saying so, with the gate's arithmetic; the gap is still disclosed in the posted body. The plan wall bounds the round builder and the verifier; two readers stay on the environment alone — the generated review workflow's launch allowance, and `qwen review run`'s own `--timeout-minutes` kill, which is not exported as a deadline. The plan stores the wall as a duration from the attempt's start, so a `--resume` from a new session renews it (a same-session resume continues the attempt and its wall; the flag itself is ignored on a resumed run — only its grammar and the default rule are checked — and the run says what wall the plan holds and how much of it is left, or that it has run out, and which builds the gates will now refuse; a wall can only run out on a same-session resume, or when the ledger failed to record the attempt, so the cheapest way past it is to resume from a new session, which renews the wall and keeps the worktree; a fresh review without `--resume` records a new wall too, and `--deadline none` on that fresh capture records none). `--deadline none` records no wall and leaves the loop bounded by the round cap alone — unless the environment exports an epoch, which clocks the run regardless. The `/review` slash command does not take the flag: it warns and drops it together with a value that could be one (whole minutes, or `none` — so a PR number typed right after it is dropped too), while any other value after it is disposed of like an invalid `--effort` value (a PR URL becomes the target; a typo is reported, and survives only as a sole file-shaped token), and a skill-driven run always uses the default. The huge tier's round reduction (3 rounds instead of 5) keys on an explicit deadline only — the environment's or the flag's — never on the default. A malformed environment deadline falls through to the plan's wall; a malformed plan field leaves the review ungated — the outer timeout still bounds the run.
 
-Nested inside that reserve is a smaller **compose floor**, `QWEN_REVIEW_DEADLINE_COMPOSE_FLOOR_SECONDS` (default 1200; `0` disables this gate entirely, at every point including past the deadline). The reserve is one number covering "verify the last round **plus** compose **plus** submit", which fits a normal per-finding re-trace but not a security review whose verification re-runs real filesystem/git workloads without bound. So the verifier — not the round builder — is gated on this floor: once the floor or less remains, `agent-prompt --role verify` refuses to build (a `VERIFY BUDGET:` line, exit **4**), the findings in hand keep their unverified tag (which caps the verdict), and `compose-review` and submission run. The floor is strictly below the reserve, so a healthy run hits the reverse-audit gate first and never reaches it; it is the cover for the one span the reserve cannot bound.
+Nested inside that reserve is a smaller **compose floor**, `QWEN_REVIEW_DEADLINE_COMPOSE_FLOOR_SECONDS` (default 1200; `0` disables this gate entirely, at every point including past the deadline). The reserve is one number covering "verify the last round **plus** compose **plus** submit", which fits a normal per-finding re-trace but not a security review whose verification re-runs real filesystem/git workloads without bound. So the verifier — not the round builder — is gated on this floor: once the floor or less remains, `agent-prompt --role verify` refuses to build (a `VERIFY BUDGET:` line, exit **4**), the findings in hand keep their unverified tag (which caps the verdict), and `compose-review` and submission run. Under the plan's own rule the floor never exceeds the reserve (a plan-recorded wall's reserve can sit exactly on it), and the round gate prices the round on top of the reserve, so a healthy run hits the reverse-audit gate first and never reaches it (an explicit `QWEN_REVIEW_DEADLINE_RESERVE_SECONDS` below the floor — `0` is the documented escape hatch — is the operator's choice, and then the verifier's gate can fire first); it is the cover for the one span the reserve cannot bound.
 
 ## Cross-file Impact Analysis
 
@@ -447,6 +447,20 @@ Two things it deliberately does not do. It **never scales a dimension away**: wh
 
 Why the floors are where they are: on a nine-line typo fix, six inline walks are five walks over nothing, and the sweep — a fresh reader hunting what the first pass did not get to — has nothing to hunt when the first pass got to all of it. When a low-effort pass stays below `candidateFloor`, it takes one deterministic second look at every coverable hunk in the largest changed source file (falling back to the largest coverable file of any kind) and every coverable removed block. Files touching an uncoverable chunk are excluded from the target selection, and the pass always emits a receipt naming its target, new-candidate count, and any uncoverable chunks; when no file is coverable, it still checks the coverable removed blocks and discloses the missing target. The floor is a stopping signal, not a quota: a clean diff can still report no findings after that re-pass. Agent 8's floor is the substantive one: "one domain dominates the diff" is a judgement, and a judgement made about forty lines finds a dominant domain every time, because forty lines are usually all one thing.
 
+## Review Deadline
+
+Every review records a wall clock in its plan unless it was captured with `--deadline none` — `--deadline <minutes>` on `qwen review fetch-pr`, `capture-local` or `plan-diff`, otherwise **8 hours** on a small diff, **12** on a large one and **16** on a huge one — and a `QWEN_REVIEW_DEADLINE_EPOCH` exported by CI replaces it. At `high` effort the wall ends the reverse-audit loop at the first round it can no longer admit, and at `high` and `medium` effort it stops the verifier once no more than the compose floor remains; it never interrupts an agent that is already running. A review stopped this way composes its verdict with the stop disclosed and the verdict capped, verifies the last round's findings only while more than the compose floor remains, and reports what it proved like any other review. Running `/review` again does not continue the stopped audit: at `high` effort a PR review follows the Incremental Review rules above and may report nothing new on an unchanged head, and a local review with its cache may stop the same way on an unchanged working tree; at `medium` effort the review simply runs again.
+
+The wall is elapsed time, pauses included, and a pause is charged twice: it spends the wall, and while it is the longest gap between two round admissions it is also the price of the next round. The pause that matters in practice falls after the first audit pair — rounds 1 and 2, which launch together — and before round 3. Under the default reserve, a review whose pair launched the moment its capture finished can pause for at most:
+
+| Diff            | Default wall | Reserve | Longest pause after the first audit pair |
+| --------------- | ------------ | ------- | ---------------------------------------- |
+| Small (Step 3A) | 8 h          | 80 min  | 3 h 20 min                               |
+| Large (Step 3B) | 12 h         | 80 min  | 5 h 20 min                               |
+| Huge            | 16 h         | 80 min  | 7 h 20 min                               |
+
+Those are ceilings, and the same rule covers any wall of 4 hours or more under the default reserve: at most (wall − 80 min) / 2 after a pair launched at capture. The pause is counted from the pair's launch, so it includes the pair's own audits and the verifiers that ride with it, and every minute the review spent before the pair launched takes half a minute off. Each later gap is held to at most half of what was left above the reserve at the previous admission, and can be held to less, for instance once an earlier gap was longer than that half. The precedence rules, the environment variables that set the wall and the reserve, and the up-front refusal of a too-short `--deadline` are described under Headless runs above. The `/review` slash command takes no `--deadline`, so a review started from a session gets a different wall only through those environment variables, and they apply to every review the session runs: `QWEN_REVIEW_DEADLINE_EPOCH` is one absolute moment shared by all of them, and like an explicit `--deadline` it cuts a huge diff's round cap from 5 to 3. A `--resume` from a new session restarts the wall and the pricing for an interrupted PR review.
+
 ## Token Efficiency
 
 The high-effort pipeline bounds each stage (shard size, audit rounds), but total calls scale with findings — `ceil(F/8)` verification shards — and, under 3B, with chunk count (reverse audit runs per chunk per round). Typical 3A profile:
@@ -455,7 +469,7 @@ The high-effort pipeline bounds each stage (shard size, audit rounds), but total
 | -------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Review agents (Step 3)           | 17 (+0-2)                       | Run in parallel; Agent 1e only when the diff signals a wrapping type (16 without it); cross-repo skips Agents 1c and 7 (15 while the plan carries the PR identity, 13 without it — Agent 0 and 6d drop together); local/file skips Agent 0 and the counter-frame audit 6d (15); one more (`prose-exec`) on a diff that touches an instruction file, when the review has a tree |
 | Sharded verification (Step 4)    | ceil(F/8)                       | F = findings; at most 8 per verification agent, launched together                                                                                                                                                                                                                                                                                                              |
-| Iterative reverse audit (Step 5) | 2-10 (3A); rounds × chunks (3B) | Two consecutive dry rounds to stop; the cap follows the topology — 10 on a small diff, 5 on a chunked one, 3 on a huge one when the run has a deadline. 3B fans out one auditor per chunk per round                                                                                                                                                                            |
+| Iterative reverse audit (Step 5) | 2-10 (3A); rounds × chunks (3B) | Two consecutive dry rounds to stop; the cap follows the topology — 10 on a small diff, 5 on a chunked one, 3 on a huge one under an explicit deadline. 3B fans out one auditor per chunk per round                                                                                                                                                                             |
 | **Total**                        | **~20-31 (~16-29)**             | 3A same-repo: ~20-31 (typical ~20-22); cross-repo or local/file: ~16-29 (the floor is the identity-less cross-repo roster of 13); one fewer when Agent 1e is not rostered, one more when `prose-exec` is owed; 3B scales with chunks (see DESIGN.md)                                                                                                                           |
 
 Most PRs converge to the lower end of the range; the caps prevent runaway cost on pathological cases. At `--effort low` the review runs entirely inline — **0 subagent calls** — walking the diff once per angle instead of once in total.

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

@@ -141,6 +141,10 @@ Commands for managing AI tools and models.
 >
 > `/workflows`, `/lsp`, and `/trust` are registered only when their feature is enabled — via the user/system-scoped `tools.workflowsEnabled` setting or `QWEN_CODE_ENABLE_WORKFLOWS=1` env var, the `--experimental-lsp` CLI flag, and the `security.folderTrust.enabled` setting respectively. Workspace values for `tools.workflowsEnabled` are ignored. When disabled these commands won't appear and will report an unknown command. Similarly, `/dream` and `/forget` are registered only when managed auto-memory is available; without it they won't appear.
 
+> [!note]
+>
+> A skill from an installed extension is a slash command too, and its name carries its owner: `/rust:pdf`, not `/pdf`. The bare form is not an alias — if another skill is named `pdf`, `/pdf` runs that skill instead. `slashCommands.disabled` gates such a command under either spelling, so an entry written before the name carried the owner still bites. See [How extension Skills are named](./skills.md#how-extension-skills-are-named).
+
 ### 1.5 Built-in Skills
 
 These commands invoke bundled skills that provide specialized workflows.
@@ -1066,3 +1070,8 @@ writing one: the record schema and how liveness is judged, the socket
 paths and framing, the auth line, every frame field, the receipt states
 and their transitions, and what a receiver does with a message before its
 model sees it.
+
+A Node program does not have to write any of that by hand:
+`@qwen-code/sdk/peer` implements the contract. `PeerEndpoint.start({ name })`
+publishes the record and binds the inbox, `list()` and `send()` address
+sessions by name, and `onMessage` receives what they send.

package/bundled/qc-helper/docs/features/computer-use.md

@@ -25,8 +25,8 @@ Node.js 22 or later and npm are required.
 When first used, the skill runs these commands itself:
 
 ```bash
-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
+qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.4
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.7
 ```
 
 Restart Qwen Code after the MCP server is first added. The skill then resumes
@@ -42,19 +42,37 @@ execution path; there is no legacy fallback.
 ## Use
 
 Ask Qwen Code to use `$computer-use` for the desktop task. After bootstrap, it
-follows the standard Computer Use workflow:
+uses the app workflow on macOS:
 
-1. discovers the exact application and window;
-2. observes full accessibility state, then accumulates automatic incremental
-   updates into the current state;
-3. performs one or more actions through current semantic element tokens,
-   including unchanged tokens retained across compatible diffs;
+1. binds the application with `computer.getApp(nameOrIdentifierOrPath)`;
+2. reads `app.getState()` for compact accessibility text, followed by automatic
+   incremental updates;
+3. performs one or more actions using the short element IDs in that text;
 4. fetches the latest state before deciding what to do next; and
 5. closes the SDK client and resets the REPL only when no other persistent
    state is needed.
 
 The driver is the only component that computes observation diffs. Model code
 uses the typed SDK methods and does not dispatch arbitrary driver tool names.
+The app handle tracks the current window and dialogs, keeps native element
+identity internally, and delegates input to the native driver. Model code does
+not choose foreground/background modes. Unconfirmed actions are not replayed.
+`getState()` can open a discovered stopped app; actions never restart it.
+Existing exact-window APIs remain available on Windows and Linux.
+
+```js
+const app = await computer.getApp('Microsoft Excel');
+nodeRepl.write((await app.getState()).text);
+// Use an element ID from the returned state.
+await app.click(37);
+await app.typeText('hello');
+nodeRepl.write((await app.getState()).text);
+```
+
+Refresh state after opening or closing a dialog before reusing element IDs.
+Each App state refresh captures the current screenshot internally. The default
+return keeps it hidden; request it explicitly with
+`app.getState({ includeScreenshot: true })` when the model needs the image.
 
 ## Permissions
 

package/bundled/qc-helper/docs/features/cross-session-protocol.md

@@ -8,6 +8,13 @@ connection, and what it sends back. Everything here is what the code
 does today at schema version 1 and frame version 1; the last section
 says what may change and how you will know.
 
+For a Node program, `@qwen-code/sdk/peer` implements the joining side of
+this page — the record, the inbox, the auth line, frames and receipts — with
+nothing but Node, and its tests run it against Qwen Code's own implementation
+in both directions. It applies none of §6 to its own inbox: a program that
+needs rate limits, holds or a duplicate window applies them itself. Use it, or
+read on to write your own.
+
 Every value that crosses a process boundary is untrusted on arrival and
 validated by the reader. Where this page says a field "must" have some
 shape, a value that does not is dropped, never rejected with an error.
@@ -73,11 +80,22 @@ able to receive receipts — writes the same record for itself: its own
 `pid`, `procStart` and `pidNs` computed the same way, a `sessionId` it
 mints (any UUID), `kind: "external"`, a `name` (yours, or derived the
 same way; it is flattened to one line and bounded when displayed), and
-`ipcPath` + `ipcToken` for an inbox it binds itself (§2). Write to a
-temp file in the same directory and `rename` over the target; create the
-file 0600; refuse to write through a symlink. Remove the record on exit.
-A record whose process is gone is swept by the next session that lists,
-but only when `procStart` proves the PID is not merely reused.
+`ipcPath` + `ipcToken` for an inbox it binds itself (§2). On Linux,
+`pidNs` is required: every reader compares it with its own, so a record
+without one is never listed — and never swept. `procStart` is required too,
+for a different reason: without it a reader falls back to plain PID liveness
+and cannot tell a recycled PID from the process that wrote the record. Write
+to a temp file in the same directory and `rename` over the target; create
+the file 0600; refuse to write through a symlink. If `<pid>.json` already
+holds something you cannot prove was left by an earlier process with your
+PID — same `pidNs`, same boot id, different start ticks — write
+`<pid>-<8 hex>.json` instead of replacing it: readers accept both names,
+and the record there may belong to a live process in another namespace or
+on another machine. Remove the record on exit. A record whose process is
+gone is swept by the next session that lists, but only when `procStart`
+proves the PID is not merely reused. `PeerEndpoint.start()` in
+`@qwen-code/sdk/peer` does all of this, and removes the record again on
+`close()`.
 
 **Reading.** Anything that can read the directory can read every record,
 including tokens: being able to discover a session and being able to

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

@@ -27,16 +27,28 @@ The suggestion is generated by sending the conversation history to the model, wh
 
 ## When Suggestions Appear
 
-Suggestions are generated when all of the following conditions are met:
+The interactive CLI and the daemon decide this separately, and they do not apply the same conditions: the CLI gates generation itself, while the daemon gates it server-side for every client attached to the session.
+
+Both sides require all of the following:
 
-- The model has completed its response (not during streaming)
 - At least 2 model turns have occurred in the conversation
-- 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 (on by default — set `ui.enableFollowupSuggestions` to `false` to turn it off)
 
-Suggestions will not appear in the CLI's non-interactive mode (e.g., headless/SDK mode). In the daemon, generation is server-side and runs after every turn that meets the conditions above, so a headless or SDK client that cannot render the suggestion should set `ui.enableFollowupSuggestions` to `false` to avoid the per-turn LLM cost.
+The interactive CLI additionally requires:
+
+- The session is interactive — the CLI never generates suggestions in its own non-interactive or SDK mode
+- The model has completed its response (not during streaming)
+- There are no errors in the most recent response
+- No confirmation dialogs are pending (e.g., shell confirmation, permissions). One renderer reads that state directly; the other gates on its own pending tool calls and cannot see a shell dialog opened mid-turn, so a suggestion can still be generated behind one. Nothing is displayed in that case — the composer is unmounted while the dialog is up — so what it costs is that turn's generation call, not a suggestion you can act on by mistake.
+
+The daemon additionally requires:
+
+- The turn ended cleanly, meaning its stop reason is `end_turn` — a cancelled, refused, or truncated turn gets no suggestion
+- Automatic turns are not being held by the todo stop guard, and no queued prompt is waiting to run
+- The most recent entry in the conversation history is a model response
+
+Because daemon-side generation happens for every client attached to the session, it also happens for clients that cannot render the result. Such a client — a headless or SDK consumer of a daemon session, which is not the CLI's own non-interactive mode above — should set `ui.enableFollowupSuggestions` to `false` to avoid paying the per-turn LLM cost for output it discards.
 
 Suggestions are automatically dismissed when:
 

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

@@ -18,9 +18,13 @@ Creating, editing, or resuming a Goal requires a trusted workspace (`/trust`). H
 
 Once a Goal has billed a turn, the footer pill and every status card show what it has spent against the window it is allowed, as `1.2k/30.0m`. The figure counts the model calls the Goal makes in its own turns; subagents and the verifier's own checks are not included. The window is set by [`model.goalTokenBudget`](../configuration/settings.md); resuming a Goal that has spent its window grants another one on top of what it has already spent, so the figure reads `30.0m/60.0m` rather than starting over. A Goal with no budget shows only what it has spent. A Goal that has not billed a turn yet shows no figures at all.
 
+Two more windows are available and off by default: [`model.goalMaxTurns`](../configuration/settings.md) caps how many turns a Goal may finish, including user-driven Goal turns, and [`model.goalMaxActiveMinutes`](../configuration/settings.md) caps wall time while it remains active in a running process, including waits and idle time between turns. Time while the Goal is paused, blocked or stopped does not count against the second one, nor does downtime across a restart; a process that is merely suspended is still charged. Whichever window runs out first, the Goal gets the same single wind-down turn to hand off and then stops until you resume it, and resuming authorizes another window on top of what has already been used. Only the window that ran out moves; the others stay where they were, and the `-1` opt-out likewise only takes a ceiling off a Goal that has already spent it. The time window is read between turns rather than enforced by a timer, so a Goal can run well past it before it stops: a turn already running is never interrupted, and a window that runs out while no turn is running is not noticed until the next turn ends. Active time is counted between recorded transitions, so time in a turn a restart interrupted is not charged. Changes to either setting take effect after restart. Both windows arm only on a Goal created after the change, so bounding a Goal already on the record means replacing it with `/goal set` -- a new Goal at revision 1, with its turn, token and active-time meters reset and its evidence window starting at the replacement, so evidence the old Goal recorded is no longer citable -- or clearing it and starting again. A resume or an edit never adds a ceiling that was not armed at creation.
+
 Each turn the session takes on its own reports what the Goal has spent so far, how many turns are behind it, and — unless the Goal runs unbounded — the window it is allowed. Every such turn except the final wind-down hand-off also carries standing instructions to re-check the workspace rather than trust earlier turns' reports, to work toward the end state the objective asks for, to do something different when the previous turn changed nothing (from the second turn on, once there is a previous turn to judge), and to check every requirement against citable evidence before proposing that the Goal is done.
 
-A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model check, so later turns and the verifier still have it to cite. The check is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default. If its claims overrun the aggregate byte budget, or include a claim over the per-claim character limit, it makes one corrective model call and both calls share that ceiling. A check that does not finish in time is abandoned as inconclusive; it counts toward the checkpoint stall limit only when the evidence window has overflowed, while a non-overflowing check preserves the streak and retries on a later turn. The calls are streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the check. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
+A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model check, so later turns and the verifier still have it to cite. Each model call the check makes is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default. A reply wrapped in a markdown fence is read without the fence. If its claims overrun the aggregate byte budget, include a claim over the per-claim character limit, number more than one checkpoint may hold, cite an id that was not in the request, or change the proof kind of a source they cite, it makes one corrective model call that names what was wrong, and both calls share that ceiling. A reply that is not a JSON object holding a non-empty `claims` array gets no corrective call, and neither does one with any malformed claim, even beside usable ones: an extra key at either level, an unrecognised `proofKind`, an empty claim, or a `sourceRefs` list that is empty, holds a non-string or empty id, repeats an id, or holds more than 32 ids. A check that does not finish in time is abandoned as inconclusive; it counts toward the checkpoint stall limit only when the evidence window has overflowed, while a non-overflowing check preserves the streak and retries on a later turn. A check after a stall on an overflowing window does not resend the same request: it sends the evidence in batches of 24 records, or 12 after a second stall, one model call per batch, each bounded by that ceiling on its own. A window that still has room, and the check a resumed session replays at startup, are still sent in one call, since neither can spend a stall. Each batch's claims are carried into the next, and only the last batch's claims are kept. A batch that fails ends the check the way a failed single call does, and the recorded failure names the batch, as in `batch 2/5: …`. A check after a stall can therefore take up to five times the ceiling, or nine times after a second stall, and a message you send meanwhile waits for it; the whole span counts as active time, so it is charged against `model.goalMaxActiveMinutes` like any other wait. Batching helps when the model could not answer for the whole window in time or with usable claims; a checkpoint that comes back with the full 32 claims and still leaves evidence behind still needs a narrower objective. The calls are streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the check. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
+
+A failing checkpoint shows up before it stops the Goal. While an active Goal's stall streak runs, the footer pill switches to `checkpoint N/3 stalled` on its own; once the Goal pauses or stops, the pill shows that status instead. The web shell's Goal status strip shows the count whatever the status. Whenever a terminal Goal status card is rendered, for example by `/goal` or by a pause, resume or verifier card, it shows how many consecutive checks have stalled out of the three the Goal allows, together with the last failure while one is recorded; the web shell's Goals dialog and headless `/goal` text output show the same line, while the web shell's transcript cards for Goal events show only the stop reason, and the model sees both fields when it reads the Goal. A check that fails while the window still has room is shown too, without spending a stall, but only while the Goal is active, or when that failure is itself what stopped the Goal, as with a checkpoint request too large to send. A checkpoint stop for any other reason clears the failure and keeps the streak, and a completed Goal shows no checkpoint line. The failure is kept as a single line with control characters removed. A Goal stopped by three stalled checkpoints names what the last one ran into. A check that could not fit the window within the checkpoint claim bounds, whether a full claim list that still left evidence behind or claims over the claim count or size budget, means the objective produces more evidence than one window holds, so narrow it. An answer that could not be folded into claims means the checkpoint model is not returning the structured output it is asked for, and narrowing the objective does not fix that. A check that never answered can mean an unreachable or rate-limited provider, a check that did not finish within `model.goalCheckpointTimeoutSeconds`, or an error in the check itself; the recorded failure says which. Resuming after any of the three starts a fresh evidence window.
 
 ## Interrupting a Goal
 
@@ -45,25 +49,25 @@ So the objective has to make the agent produce evidence: run the named check and
 
 Put these into the objective, in this order:
 
-| Part         | What to write                                                                                                                         |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `Outcome:`   | One sentence: what is true when this is done.                                                                                         |
-| `Done when:` | Numbered, binary checks. At least one names a command and its expected exit code or output line, and asks for that line to be pasted. |
-| `Must not:`  | Files not to touch, tests or thresholds not to weaken, irreversible actions (push, delete, publish) not to take.                      |
-| `Budget:`    | When to give up: "stop as blocked after 20 turns" or a time limit.                                                                    |
-| `On block:`  | What to report when stuck, and which decision a human must make.                                                                      |
-| `Context:`   | Only facts the agent cannot find in the workspace: branch, environment, earlier decisions.                                            |
+| Part         | What to write                                                                                                                                                                             |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Outcome:`   | One sentence: what is true when this is done.                                                                                                                                             |
+| `Done when:` | Numbered, binary checks. At least one names a command and its expected exit code or output line, and asks for that line to be pasted.                                                     |
+| `Must not:`  | Files not to touch, tests or thresholds not to weaken, irreversible actions (push, delete, publish) not to take.                                                                          |
+| `Budget:`    | Advisory model instruction for when to give up, such as "stop as blocked after 20 turns". To enforce one, set `model.goalMaxTurns` or `model.goalMaxActiveMinutes` in settings, not here. |
+| `On block:`  | What to report when stuck, and which decision a human must make.                                                                                                                          |
+| `Context:`   | Only facts the agent cannot find in the workspace: branch, environment, earlier decisions.                                                                                                |
 
 Keep it to one objective. `/goal set` and `/goal edit` accept any length, but stay roughly under 1,200 characters: the objective is re-sent on every Goal turn. An objective the model proposes through `propose_goal` is capped at 1,500 characters. Both commands collapse newlines to spaces, so number the items rather than relying on line breaks.
 
-`Budget` is an instruction to the model about when to stop and report a blocker. Writing a turn count or time limit in the objective does not configure a runtime timer or change the Goal's token budget.
+`Budget` is an instruction to the model about when to stop and report a blocker; the model may or may not honour it. To make the runtime itself stop at a turn count or a duration, set [`model.goalMaxTurns`](../configuration/settings.md) or [`model.goalMaxActiveMinutes`](../configuration/settings.md). Writing either into the objective does not configure those, and does not change the Goal's token budget.
 
-| Weak                       | Why it fails                                                | Stronger                                                                                                                                                                                                                                |
-| -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| make checkout faster       | No threshold, no check.                                     | `Outcome: checkout p95 is below 250 ms. Done when: 1) npm run bench:checkout exits 0 and prints p95 < 250 (paste the line); 2) npm test exits 0. Must not: change the benchmark or skip tests. Budget: stop as blocked after 20 turns.` |
-| clean up the auth module   | "Clean" has no evidence.                                    | Ask what would be observable: zero lint warnings in `src/auth`, a coverage threshold, a file count.                                                                                                                                     |
-| ship the release           | Irreversible, and needs a human decision.                   | Narrow to a checkable pre-release state (tag exists, `npm run release:dry-run` exits 0) and put "do not publish" in `Must not`.                                                                                                         |
-| after I confirm the design | The verifier cannot see a confirmation that never happened. | Move it to `On block:` as the decision a human must make.                                                                                                                                                                               |
+| Weak                       | Why it fails                                                | Stronger                                                                                                                                                                                                                                                                                                         |
+| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| make checkout faster       | No threshold, no check.                                     | `Outcome: checkout p95 is below 250 ms. Done when: 1) npm run bench:checkout exits 0 and prints p95 < 250 (paste the line); 2) npm test exits 0. Must not: change the benchmark or skip tests. Budget: as model guidance, stop as blocked after 20 turns. On block: report the measured p95 and what blocks it.` |
+| clean up the auth module   | "Clean" has no evidence.                                    | Ask what would be observable: zero lint warnings in `src/auth`, a coverage threshold, a file count.                                                                                                                                                                                                              |
+| ship the release           | Irreversible, and needs a human decision.                   | Narrow to a checkable pre-release state (tag exists, `npm run release:dry-run` exits 0) and put "do not publish" in `Must not`.                                                                                                                                                                                  |
+| after I confirm the design | The verifier cannot see a confirmation that never happened. | Move it to `On block:` as the decision a human must make.                                                                                                                                                                                                                                                        |
 
 ## Let `/goal-draft` write it
 
@@ -73,13 +77,13 @@ For an audit, completion means covering the agreed scenarios and reporting evide
 
 If a success criterion, command, input path, or essential decision cannot be established, the skill returns a draft marked "Needs clarification" with `<TODO: …>` items. It does not offer that draft for approval or print a runnable `/goal set` or `/goal edit` command. Nonessential defaults are marked `[ASSUMPTION]`; they do not stand in for missing success criteria.
 
-Once the objective is ready, an interactive terminal session can show the `propose_goal` approval dialog described below. Web Shell and other ACP clients, headless runs, sessions with the tool disabled, and sessions with an active Goal receive a command to run manually instead. The hand-off says that the draft has not been applied. The skill never starts the work itself, and nothing is set without your approval.
+Once the objective is ready, an interactive terminal or Web Shell session can show the `propose_goal` approval dialog described below. Clients without Goal proposal support, headless runs, sessions with the tool disabled, and sessions with an active Goal receive a command to run manually instead. The hand-off says that the draft has not been applied. The skill never starts the work itself, and nothing is set without your approval.
 
 Pass an existing objective to tighten it: `/goal-draft all tests pass and the lint is clean`. For an active Goal, an explicit request to tighten it produces `/goal edit`; a replacement uses `/goal set`. If the intended operation is unclear, the skill includes that choice in its single round of questions.
 
 ### Approve a Goal the model proposes
 
-In an interactive terminal session the model has a `propose_goal` tool. When `/goal-draft` finishes, or when you ask for an outcome that spans several turns, it can propose the objective instead of printing a `/goal set …` line for you to copy. The proposal appears as an approval dialog showing the full objective. Approving it sets the Goal exactly as `/goal set` would, the moment the current turn ends (the model acknowledges and stops; the first Goal turn then starts on its own), and declining sets nothing — the model sees only that the tool call was not allowed, and its instructions tell it not to ask why and not to propose the same objective again. The approval is bound to the turn that asked for it: if that turn is cancelled or otherwise never reaches its end, the approval is dropped rather than applied under a later message or an automated turn. No permission rule or approval mode (including YOLO) skips this dialog, and the tool refuses while another Goal is active, in plan mode, and in untrusted folders; subagents are never offered it. It is not available in headless runs, nor yet in Web Shell or other ACP-driven sessions (they do not pass through the turn boundary that applies the approval); there the printed `/goal set` line remains the hand-off.
+In an interactive terminal or a Web Shell turn with an attached client, the model has a `propose_goal` tool. When `/goal-draft` finishes, or when you ask for an outcome that spans several turns, it can propose the objective instead of printing a `/goal set …` line for you to copy. The proposal appears as an approval dialog showing the full objective. Approving it sets the Goal exactly as `/goal set` would, the moment the current turn ends (the model acknowledges and stops; the first Goal turn then starts on its own), and declining sets nothing — the model sees only that the tool call was not allowed, and its instructions tell it not to ask why and not to propose the same objective again. The approval is bound to the turn that asked for it: if that turn is cancelled or otherwise never reaches its end, the approval is dropped rather than applied under a later message or an automated turn. No permission rule or approval mode (including YOLO) skips this dialog, and the tool refuses while another Goal is active, in plan mode, and in untrusted folders; subagents are never offered it. Web Shell uses its existing Allow/Reject permission panel. A stopped Goal can be replaced only if it still matches the version shown for approval; changing it invalidates the proposal. Headless runs, Web Shell channel deliveries and automatic turns, and ACP clients without the required approval and turn-lifecycle support retain the printed `/goal set` hand-off.
 
 Turn it off with `goals.modelProposed: "disabled"` in your user settings. Because the setting decides whether the model may ask you to start an autonomous loop, it is honored only from user and system scope; a workspace `.qwen/settings.json` value is ignored with a warning.