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

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

@@ -757,12 +757,11 @@ qwen sessions list --json | jq .
 
 #### `qwen sessions ps`
 
-Lists the interactive Qwen Code sessions running on this machine right
-now. `sessions list` walks saved transcripts ("what have I worked on");
-this walks the live-process registry ("what is running at this moment").
-Records left behind by a killed session are swept as they are found.
-Headless sessions (`qwen -p`) do not register with the live-process
-registry, so they are not shown.
+Lists the Qwen Code sessions registered on this machine right now.
+`sessions list` walks saved transcripts ("what have I worked on"); this
+walks the live-process registry ("what is running at this moment").
+Records left behind by a killed session are swept as they are found. A
+one-shot `qwen -p` run never registers, so it is never shown.
 
 **Flags:**
 
@@ -772,7 +771,16 @@ registry, so they are not shown.
 
 **Human-readable output (default):**
 
-A table with columns: NAME, PID, AGE, DIRECTORY.
+A table with columns: NAME, KIND, PID, AGE, DIRECTORY.
+
+KIND says what registered the session — `tui` for someone at a terminal,
+`external` for a program that is not a Qwen Code session at all (a voice
+front-end, a relay), and `headless` or `serve` for a session another
+program drives. It is a self-report, like NAME and DIRECTORY: every field
+here was written by the process it describes, and nothing about what a
+session is allowed to do depends on it. See
+[Cross-Session Protocol](./cross-session-protocol.md) for the record
+format and for how to register a program of your own.
 
 **JSON output (`--json`):**
 
@@ -781,7 +789,7 @@ object with fields:
 
 ```
 schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
-qwenVersion, ipcPath (when peer messaging is available)
+qwenVersion, kind, ipcPath (when peer messaging is available)
 ```
 
 Nothing else is written to stdout — an empty listing prints nothing at
@@ -871,14 +879,50 @@ session registry rather than deriving it.
 
 The `send_message` call only confirms the message was handed to the other
 session. What became of it arrives later as a receipt: if it was held,
-declined, refused, expired, or misaddressed (the address changed hands —
-list the agents again) — or released after a hold — a notice appears in
-the sending session's transcript (`Message to <name>: …`). Declined and
-refused are different answers: declined means someone reviewed the
-message and said no, while refused means that session's
-`agents.crossSessionInbound` is `refuse` and nobody saw it at all. The
-model that sent it is not told; if the other session replies, the reply
-arrives as a cross-session message.
+declined, refused, dropped, expired, or misaddressed (the address changed
+hands — list the agents again) — or released after a hold — a notice
+appears in the sending session's transcript (`Message to <name>: …`).
+Declined, refused and dropped are three different answers: declined means
+someone reviewed the message and said no, refused means that session's
+`agents.crossSessionInbound` is `refuse` and nobody saw it at all, and
+dropped means its inbox turned the message away before any of that (see
+below). The first drop is answered at once and the rest are folded into a
+receipt every few seconds, each naming the messages it stands for, so a
+run of them costs a handful of lines rather than one line each. The model that
+sent it is not told; if the other session replies, the reply arrives as a
+cross-session message.
+
+### Flood protection
+
+A session accepts up to 30 messages at once from one sender and then one
+every two seconds, and up to 32 at once from all senders together and
+then one a second. The second limit exists because a sender names itself:
+rotating that name gets a fresh allowance from the first limit but not
+from the second. It is barely above the first because every accepted
+message draws a receipt, and a session can only have so many of those
+going out at once. A message from another session that repeats that
+sender's previous message word for word within 30 seconds is also turned
+away — a model looping on one sentence mints a fresh message id every
+time, so the text is what catches it. Messages from a script the session
+started and from a trusted controller are exempt from the repeat check,
+because a hook reporting the same line twice is reporting two facts and a
+person saying "continue" twice means it twice; both are still subject to
+the rate limits. Finally, a message that is accepted but cannot be queued
+because the session already has 50 waiting is turned away too.
+
+A message turned away this way is never held, never shown to the model,
+and leaves no record, so the sender can try again later and land. The
+receiving session says so in its transcript at most once a minute per
+sender, with a count of what that line stands for. The sending session
+gets one receipt naming every message the burst cost it, and its
+transcript says to fold what still matters into one later message rather
+than re-sending.
+
+The sending side does not wait to find out. Each session tracks what it
+has sent to each address and refuses a send that the receiver would
+drop, so the model is told to batch before the message is written rather
+than after — and the receiver never spends a connection on a message it
+was going to turn away.
 
 ### Inbox authentication and scripted injection
 
@@ -904,7 +948,10 @@ recognized as the session's own rather than as another session's.
 
 Give every injection a fresh `msgId`. The receiving gate remembers the
 ids it has already settled, so a hook that reuses one is delivered the
-first time and silently deduplicated on every run after that.
+first time and silently deduplicated on every run after that. Repeating
+the same _text_ is fine — the repeat check above does not apply to a
+session's own processes — but the rate limits do apply, so a hook in a
+loop is dropped like any other flood.
 
 An injected message still goes through the inbound gate and is marked as
 not coming from the user, but the gate knows it came from the session's
@@ -979,3 +1026,18 @@ on your behalf.
 Anyone who holds the token can send as that controller, so treat it like
 any other credential: give it to one program, keep it out of shared
 config, and revoke it when that program is done.
+
+### Programs that are not Qwen Code sessions
+
+Everything above works between sessions, but nothing in it is specific to
+one. A program that writes a registry record for itself and binds an
+inbox the same way is listed by `qwen sessions ps` and by `list_agents`,
+can be addressed by name from `send_message`, and receives delivery
+receipts for what it sends — a voice front-end, a relay, a build watcher.
+It should record `kind: "external"` so a listing can say what it is.
+
+[Cross-Session Protocol](./cross-session-protocol.md) is the contract for
+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.

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.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
 ```
 
 Restart Qwen Code after the MCP server is first added. The skill then resumes
@@ -45,11 +45,13 @@ Ask Qwen Code to use `$computer-use` for the desktop task. After bootstrap, it
 follows the standard Computer Use workflow:
 
 1. discovers the exact application and window;
-2. observes full accessibility state;
-3. acts through current semantic element tokens when possible;
-4. fetches fresh state after every mutation;
-5. verifies the requested result; and
-6. closes the SDK client and resets the REPL.
+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;
+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.

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

@@ -0,0 +1,291 @@
+# Cross-Session Protocol
+
+This page is the contract for a program that wants to take part in
+cross-session messaging without being a Qwen Code session: a voice
+front-end, a relay daemon, a script that watches a build. It describes
+what a session writes to the registry, what its inbox reads off a
+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.
+
+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.
+
+## 1. The session registry
+
+A running session publishes one record:
+
+```
+$QWEN_HOME/sessions/<pid>.json        (directory 0700, file 0600)
+```
+
+`$QWEN_HOME` defaults to `~/.qwen`. The file name is the writer's PID
+and nothing else; a record whose `pid` field disagrees with its file
+name is ignored.
+
+```json
+{
+  "schemaVersion": 1,
+  "pid": 41337,
+  "procStart": "a1b2c3d4-…-boot-uuid:8895124",
+  "pidNs": 4026531836,
+  "sessionId": "8e016be8-5b48-4c13-ad22-1f5326ae64ac",
+  "cwd": "/home/me/project",
+  "name": "project-3f",
+  "startedAt": 1788959000000,
+  "qwenVersion": "0.23.0",
+  "kind": "tui",
+  "ipcPath": "/run/user/1000/qwen-socks/41337.sock",
+  "ipcToken": "c0ffee…64 hex…"
+}
+```
+
+| Field           | Meaning                                                                                                                                                                                                                                                                                               |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion` | Always `1`. A reader skips a record with a higher version and never deletes it.                                                                                                                                                                                                                       |
+| `pid`           | The writer's process id. Must equal the file name.                                                                                                                                                                                                                                                    |
+| `procStart`     | `<boot id>:<process start ticks>` on Linux (`/proc/sys/kernel/random/boot_id` and field 22 of `/proc/<pid>/stat`); `null` elsewhere. Guards against PID reuse, and against records written on another machine that shares this home directory.                                                        |
+| `pidNs`         | Inode number of `/proc/self/ns/pid` on Linux; `null` elsewhere. A reader only lists and sweeps records from its own namespace.                                                                                                                                                                        |
+| `sessionId`     | The session's id. `/clear` and `/resume` swap it under the same PID, so re-read the record before each send.                                                                                                                                                                                          |
+| `cwd`           | Working directory at registration.                                                                                                                                                                                                                                                                    |
+| `name`          | Display name. Derived from the cwd basename (Unicode letters, marks, digits, `.`, `_`, `-`; up to 32 code points) plus `-` and the first two hex characters of `sha256(sessionId)`, unless the writer chose one. Not unique.                                                                          |
+| `startedAt`     | Epoch milliseconds. Newest first is the listing order and the tie-break between twins.                                                                                                                                                                                                                |
+| `qwenVersion`   | Free text or `null`.                                                                                                                                                                                                                                                                                  |
+| `kind`          | What registered: `tui` (someone at a terminal), `headless`, `serve`, `external`. Lowercase ASCII, digits and dashes, at most 16 characters; anything else is dropped on read. Absent means a writer older than the field, which reads as `tui`. A label for listings — never a credential; see below. |
+| `ipcPath`       | The inbox socket, present only while it is bound. Absent means discoverable but not messageable.                                                                                                                                                                                                      |
+| `ipcToken`      | 64 hex characters. What a connection to `ipcPath` presents on its auth line. Absent means the inbox requires none (records from older builds).                                                                                                                                                        |
+
+**A record is a self-report.** Every field in it was written by the
+process it describes, so `name`, `cwd` and `kind` are claims, not facts a
+reader can lean on. Nothing that decides what a sender may do reads
+them — that is settled by what a connection presents (§3) and by the
+receiving session's own policy (§6). Set `kind` so a listing can group
+sessions honestly; do not expect it to buy you anything.
+
+**Writing your own record.** An external process that wants to be
+found — listed by `qwen sessions ps`, addressable from `send_message`,
+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.
+
+**Reading.** Anything that can read the directory can read every record,
+including tokens: being able to discover a session and being able to
+authenticate to it are one capability by design. Do not print
+`ipcToken` anywhere a model or a log can see it.
+
+**Liveness.** A record is live when all of these hold: the file name
+matches `pid`; `pidNs` equals the reader's; the boot id inside
+`procStart` equals the reader's (or `procStart` is `null`); and the PID
+is alive with the same start ticks. A live record with an `ipcPath`
+still has to be dialed before it is advertised as reachable — a socket
+file outlives a crash.
+
+**Refs.** Displayed handles use `ref = sha256(sessionId)[0:6]`. Two
+sessions may share a `name`; the address grammar a sender types is
+`name`, `name [ref]`, `[ref]` or the bare `ref`, and an ambiguous
+`name` is an error rather than a guess.
+
+## 2. The inbox socket
+
+One UNIX domain socket per session, at the first of these that binds:
+
+1. `$XDG_RUNTIME_DIR/qwen-socks/<pid>.sock`
+2. `$TMPDIR/qwen-socks-<16 hex>/<pid>.sock`
+3. `/tmp/qwen-socks-<16 hex>/<pid>.sock`
+
+The directory is 0700 and the socket 0600. A path longer than 103 bytes
+is skipped. When the PID-keyed name is already held by a live listener
+(two PID namespaces sharing a runtime directory), the session binds
+`<pid>-<8 hex>.sock` next to it instead. Peers never derive a socket
+path; they read `ipcPath` from the record.
+
+A connection carries newline-delimited JSON, one object per line, UTF-8.
+A single line longer than 1 MiB (measured in UTF-16 code units) drops
+the connection. A connection that goes 30 seconds without completing a
+line that parses is dropped; junk lines do not extend the deadline. The
+listener accepts at most 64 connections at once.
+
+The expected exchange is one message per connection: connect, write the
+auth line and the frame in one write, half-close, wait for the peer to
+close. The receiver never writes on the same connection; anything it
+has to say comes back as a separate connection to your own `ipcPath`.
+
+## 3. The auth line
+
+When the target record has an `ipcToken`, the first line must be:
+
+```json
+{ "msgV": 1, "type": "auth", "token": "<token>" }
+```
+
+Three kinds of token are accepted, and the inbox remembers which one it
+saw:
+
+| Presented                                                                     | The inbox concludes            | Effect                                                                           |
+| ----------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------- |
+| The `ipcToken` from the target's registry record                              | an ordinary peer               | subject to policy and mode parity (§6)                                           |
+| `QWEN_CODE_MESSAGING_TOKEN` from the target's own environment                 | a process that session started | delivered under the parity default; `origin="own-process"`                       |
+| A controller token `qpc_<64 hex>` minted with `qwen sessions controllers add` | a program the user trusts      | delivered under the parity default; `origin="controller"` with the grant's label |
+
+A first line that is not an auth line, or that presents a token matching
+none of the three, drops the connection silently. When the record has no
+`ipcToken`, do not send an auth line; an older inbox reads it as an
+unknown frame type and skips it, so leading with one is always safe.
+
+Nothing here authenticates the _sender_: a token proves the connection is
+allowed, not who opened it. `from`, `fromName`, `fromMode` and every
+field of the record are claims.
+
+This is also the whole of the trust model. A program the user wants
+driving their sessions gets a controller token, minted by hand and given
+to that one program; it is what makes the difference between a message
+that is delivered and one that waits for review. Writing
+`kind: "external"` or a familiar-looking `name` buys nothing.
+
+## 4. The user frame
+
+```json
+{
+  "msgV": 1,
+  "msgId": "5f1d0c9e-3b2a-4e8f-9c7d-1a2b3c4d5e6f",
+  "type": "user",
+  "from": "/run/user/1000/qwen-socks/40011.sock",
+  "replyToken": "<my own ipcToken>",
+  "fromName": "project-3f",
+  "fromMode": "prompting",
+  "toSessionId": "8e016be8-…",
+  "priority": "next",
+  "message": { "role": "user", "content": "build finished, 0 failures" }
+}
+```
+
+| Field         | Rule                                                                                                                                                                                                                          |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `msgV`        | Number. Must be ≤ 1; higher is dropped.                                                                                                                                                                                       |
+| `msgId`       | `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`, and must not canonicalize (dashes stripped, lower-cased) to `all`. Use a fresh UUID per message: the receiver remembers ids it has settled and repeats the old verdict for a re-sent one. |
+| `type`        | `"user"`.                                                                                                                                                                                                                     |
+| `from`        | Your `ipcPath`, if you have one. Where receipts go. Absent means no receipts.                                                                                                                                                 |
+| `replyToken`  | Your `ipcToken`, so the receiver can authenticate its receipts to you.                                                                                                                                                        |
+| `fromName`    | Display name; flattened to one line, at most 200 characters.                                                                                                                                                                  |
+| `fromMode`    | `"prompting"` (a person reviews each action) or `"bypass"` (some actions apply without review). Absent means "asserts nothing", which is held for review (§6).                                                                |
+| `toSessionId` | The `sessionId` you read from the record. A receiver holding a different id answers `misaddressed`. Always send it.                                                                                                           |
+| `priority`    | `"now"` or `"next"`; anything else reads as `"next"`. Carried for a future interrupt path; today the receiver queues both for the next turn.                                                                                  |
+| `message`     | `role` must be `"user"`; `content` a non-empty string.                                                                                                                                                                        |
+
+Unknown fields are ignored.
+
+## 5. The delivery-status frame
+
+The receiver reports what became of a message with one control frame per
+outcome, sent to the message's `from` and authenticated with its
+`replyToken`:
+
+```json
+{
+  "msgV": 1,
+  "msgId": "<fresh id>",
+  "type": "control",
+  "action": "delivery_status",
+  "status": "held",
+  "origMsgId": "5f1d0c9e-…",
+  "from": "/run/user/1000/qwen-socks/41337.sock",
+  "reason": "Your message is held for the recipient user to review …"
+}
+```
+
+| `status`       | When                                                                                                                                                      | What to do                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `held`         | Parked for the user to review. Repeated on a retry, and on a release that could not be queued.                                                            | Wait; a decision or an expiry follows.                                             |
+| `delivered`    | Queued for the model.                                                                                                                                     | Nothing. Not proof it was read.                                                    |
+| `denied`       | A person reviewed it and said no.                                                                                                                         | Do not re-send.                                                                    |
+| `refused`      | The session's policy turns peer messages away; nobody saw it. Only ever the first receipt.                                                                | Stop; reach that user another way.                                                 |
+| `expired`      | A held message ran out its wait, the session exited with it unread, or it arrived while that session was shutting down. Can follow `held` or `delivered`. | Re-send later if it still matters.                                                 |
+| `misaddressed` | `toSessionId` does not match the session at that address.                                                                                                 | Re-read the registry.                                                              |
+| `dropped`      | The inbox turned it away before any policy ran (§6).                                                                                                      | Treat as unsent. Do not retry in a loop; fold what matters into one later message. |
+
+A `dropped` receipt carries two more fields. `dropReason` is
+`rate-limited`, `duplicate` or `queue-full`. `droppedMsgIds` lists up to
+256 further ids the same receipt settles: a burst is answered with one
+receipt rather than one each, so a sender moves every message it lost to
+a terminal state from a single frame. Both are meaningless on any other
+status and are ignored there.
+
+`reason` is free text for a human. Order of receipts is not guaranteed
+across connections; apply them as state transitions:
+
+```
+pending   → held | delivered | denied | refused | expired | misaddressed | dropped
+held      → delivered | denied | expired | misaddressed
+delivered → expired | misaddressed
+```
+
+Anything else is a repeat and should be ignored. A receipt for an id you
+never sent is noise; ignore it. Receipts are best-effort on the
+receiver's side: a full outbound limit or a dead `from` loses them
+silently, so a sender must tolerate never hearing back.
+
+Your own inbox receives these frames from the sessions you messaged. If
+you only ever send, bind an inbox and give `from` anyway: without one you
+are blind to every outcome above.
+
+## 6. What the receiver does with a message
+
+In order:
+
+1. **Admission.** Per sender: a burst of 30, then one message every two seconds. All senders together: a burst of 32, then one a second — a sender names itself on the frame, so rotating that name buys a fresh allowance from the first limit but not the second. The same body from another session inside 30 seconds is a `duplicate`; a process the session started and a trusted controller are exempt from that check, and rate-limited like everyone else. A dropped message is never held, never delivered, and leaves no record, so a sender that waits out its burst and retries still lands.
+2. **Settled ids.** A `msgId` the gate already decided repeats its earlier verdict.
+3. **Policy.** `agents.crossSessionInbound` set to `accept`, `hold` or `refuse` wins. Unset: a process the session started or a trusted controller is accepted; otherwise a message is accepted only when `fromMode` names the same review class the receiver is in, and held in every other case, including when `fromMode` is absent.
+4. **Hold.** Up to 50 messages wait. A message arriving at a full buffer is `dropped` with `queue-full` rather than evicting one already parked. A held message expires after `agents.crossSessionHeldExpiry` (`1m`, `5m`, `10m`, `never`; default `5m`). The user releases or denies from `/peers`; a mode change re-evaluates the backlog.
+5. **Queue.** An accepted message joins the session's input queue, which holds at most 50 from peers. A full queue is `dropped` with `queue-full` too.
+
+A sender does not have to discover the limits the hard way: a Qwen Code
+session mirrors them per address and refuses its own send before writing
+it, telling its model to batch instead.
+
+The model sees a delivered message as:
+
+```
+<cross_session_message from="/run/user/1000/qwen-socks/40011.sock" name="project-3f">
+build finished, 0 failures
+</cross_session_message>
+```
+
+followed by a notice stating the sender's authority. `origin="own-process"`
+or `origin="controller" controller="<label>"` is added by the receiver
+from what the connection presented, never from the frame; a controller's
+label comes from the grant the user minted, not from `fromName`. Tags
+that look like the envelope are defanged inside `content`.
+
+## 7. Compatibility
+
+- A reader ignores fields it does not know. Adding a field to a record or
+  a frame is not a breaking change.
+- `schemaVersion` and `msgV` are bumped only for a change to the shape of
+  existing fields. A reader drops a frame or skips a record with a
+  version above what it knows, and never deletes such a record.
+- New `status` values may appear; treat an unknown one as "no transition"
+  and keep waiting. The same goes for a `kind` you do not recognize:
+  show it, do not correct it.
+- Constants that may change without notice: the burst and rate figures,
+  the hold ceiling and expiry choices, the 1 MiB line cap, the 30-second
+  line deadline, the 64-connection cap.
+
+## 8. Not settled yet
+
+- **Name yielding.** Two sessions in one directory can register the same
+  `name`; today they are told apart only by `ref`. A registration that
+  yields to a live name, and a control frame that tells peers a session
+  renamed itself, are both still to come.
+- **Same-name reporting.** `qwen sessions ps` and `list_agents` do not
+  flag records that still collide.
+- **Daemon-managed sessions.** Only the interactive UI registers today, so
+  a session `qwen serve` drives is not in the registry, cannot be
+  addressed, and cannot send. The `serve` and `headless` kinds are
+  reserved for it.

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

@@ -2,7 +2,7 @@
 
 Qwen Code can predict what you want to type next and show it as placeholder text in the input area. This feature uses an LLM call to analyze the conversation context and generate a natural next step suggestion.
 
-This feature works end-to-end in both the CLI and Web Shell. Generation is automatic and server-side: after each completed turn the daemon emits the suggestion on the session stream (on by default; set `ui.enableFollowupSuggestions` to `false` to opt out), and Web Shell's composer already wires the `useDaemonFollowupSuggestion` hook, so suggestions render and accept with no additional host wiring.
+This feature works end-to-end in both the CLI and Web Shell. Generation is automatic and server-side: after each cleanly completed turn (the daemon's `end_turn` stop reason — a `cancelled`, `refusal`, `max_tokens`, or `max_turn_requests` turn gets none) the daemon emits the suggestion on the session stream (on by default; set `ui.enableFollowupSuggestions` to `false` to opt out), and Web Shell's composer already wires the `useDaemonFollowupSuggestion` hook, so suggestions render and accept with no additional host wiring.
 
 ## How It Works
 
@@ -36,7 +36,7 @@ Suggestions are generated when all of the following conditions are met:
 - 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 non-interactive mode (e.g., headless/SDK mode).
+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.
 
 Suggestions are automatically dismissed when:
 

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

@@ -16,13 +16,19 @@ A Goal keeps Qwen Code working across turns until a stated condition is met. Set
 
 Creating, editing, or resuming a Goal requires a trusted workspace (`/trust`). Headless usage is covered in [Headless Mode](./headless.md#run-a-persistent-goal).
 
+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.
+
+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.
+
 ## Interrupting a Goal
 
 Cancelling a Goal turn pauses the Goal. Press Esc while the model is answering or while its tools are still running, and the turn stops, the Goal moves to `paused`, and the card and `/goal` both say why it stopped. Nothing continues until you run `/goal resume`.
 
 Typing a message while a Goal is active does not pause it. Your message runs as the next Goal turn, so use it to steer the work; use `/goal pause` or `/goal clear` to stop it.
 
-Every pause states its reason: that you interrupted it, that you ran `/goal pause`, that the session token limit blocked the next model request, or that the turn failed. A Goal stopped by a limit keeps the reason for that limit instead.
+Every pause states its reason: that you interrupted it, that you ran `/goal pause`, that the session token limit blocked the next model request, that the turn failed, or that three turns in a row recorded nothing the verifier could judge and no proposal — Goal bookkeeping reads (`get_goal`, `update_goal`) do not count as progress. A Goal stopped by a limit keeps the reason for that limit instead.
 
 ## How a Goal is judged
 
@@ -50,6 +56,8 @@ Put these into the objective, in this order:
 
 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.
+
 | 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.` |
@@ -59,9 +67,15 @@ Keep it to one objective. `/goal set` and `/goal edit` accept any length, but st
 
 ## Let `/goal-draft` write it
 
-`/goal-draft <what you want done>` is a bundled skill that does the above for you. It checks whether the request is a Goal at all, reads the workspace for the real test and lint commands instead of guessing, asks at most one round of multiple-choice questions when the answer changes the check or the scope, drafts the objective in the format above, runs the self-check, and hands it over: in an interactive session it proposes the objective through the `propose_goal` approval dialog described below, otherwise it prints a `/goal set …` line you can run as-is. It never starts the work itself, and nothing is set without your approval.
+`/goal-draft <what you want done>` is a bundled skill that does the above for you. It reads only enough of the workspace to establish the scope and real verification commands, without running tests, building, installing dependencies, or starting services. It asks at most one round of questions when essential choices are unclear, then writes a compact objective, usually with 3–5 completion checks (fewer when enough). Explicit requirements are preserved; it does not add checks just to reach a count.
+
+For an audit, completion means covering the agreed scenarios and reporting evidence, including reproduction steps for confirmed defects. Finding no defects is a valid result. The draft should not invent a minimum number of scenarios, evidence files, exploration rounds, or defects.
+
+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.
 
-Pass an existing objective to tighten it: `/goal-draft all tests pass and the lint is clean`.
+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
 

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

@@ -131,6 +131,14 @@ When a session is restored, compatible background agents are added back to the s
 
 Use continuation for related follow-up work. Launch a new agent when the task is unrelated or the previous agent cannot be resumed.
 
+## Notification Queue
+
+In the interactive TUI and ACP session, completion notifications from background agents, shells, monitors and workflows share a queue that drains into a model turn once the session is idle. These queues hold at most 20 notifications so a noisy producer cannot accumulate an unbounded backlog. The headless CLI's local queue is not capped by this rule.
+
+When a 21st notification arrives, Qwen Code evicts an interim monitor pulse first — the monitor's next poll supersedes it — and otherwise the oldest queued notification. Agent results, workflow results and scheduled prompts are never evicted in the interactive TUI; a notification that would displace one is dropped instead, and so is an arriving pulse when only terminal results are queued.
+
+Discarded notifications are reported rather than dropped quietly. The summary appears before the next notification in the live transcript. ACP also prefixes it to that turn's model input; the TUI keeps it parked for the next Notification batch so cron prompts still pass unchanged through slash, shell and `@` preprocessing. A daemon notification is recorded before it is acknowledged, so after a reload its durable record can precede the later overflow summary. ACP can discard a pending summary if the session is cleared or switched, or if a client cancels or preempts the notification turn. Discarding a notification never stops or deletes its task, and completed tasks retain their results; the summary points at `/tasks` and task output files when there is a task to inspect. A discarded scheduled prompt was never delivered and is not retried. A daemon notification that was recorded but could not be delivered live remains available in the session transcript and is reported separately from lost notifications.
+
 ## Agent Working Directory
 
 For a named regular subagent, `working_dir` pins the agent to an existing git worktree of the current repository. Relative paths resolve from the current directory, and the worktree must already be registered with git as a linked worktree of this repository.