@qwen-code/qwen-code 0.23.2 → 0.23.3-nightly.20260911.aaa6a32aae

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/commands.md

@@ -36,7 +36,7 @@ These commands help you save, restore, and summarize work progress.
 
 > [!note]
 >
-> Opening an HTML export loads the renderer for that exact Qwen Code version from `unpkg.com`. If the version has not been published or the renderer cannot be reached, the file shows a load error. Markdown, JSON, and JSONL exports remain self-contained.
+> Opening an HTML export loads the renderer and stylesheet for that exact Qwen Code version from `unpkg.com`. If the version has not been published or either asset cannot be reached, the file shows a load error. Markdown, JSON, and JSONL exports remain self-contained.
 
 > [!note]
 >
@@ -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,19 @@ 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. Several `serve` or `headless` rows can share one PID: a
+`qwen --acp` child hosts all its sessions in one process — `serve` when
+the daemon spawned it, `headless` when a client is driving it directly —
+and each of them registers separately. 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 +792,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
@@ -1018,3 +1029,45 @@ 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.
+
+### Sessions a program drives over ACP
+
+Any `qwen --acp` child registers each session it hosts — as `serve` when
+the daemon spawned the process, as `headless` when an editor or another
+client is driving `qwen --acp` directly — and the session appears in
+`qwen sessions ps` and in another session's `list_agents` like any
+other. It can send: its model can call `send_message` to reach a terminal
+you have open. Several of them share one process and one inbox, so a
+sender has to name the session it means — every Qwen Code session does
+that automatically.
+
+Messages sent _to_ one are refused rather than held. Holding is a
+question put to a person, and nobody is watching a held-message list on a
+driven session's behalf; a sender is told at once instead of
+waiting out an expiry. Where a held message should surface for those
+sessions is not settled yet.
+
+A session registers only while its own settings have
+`agents.crossSessionMessaging` on. With it off it stays invisible,
+because the only reason to list a session nobody can message would be to
+advertise an address that never answers.
+
+### 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.
+
+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

@@ -26,7 +26,7 @@ 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.4
+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

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

@@ -0,0 +1,338 @@
+# 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.
+
+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.
+
+## 1. The session registry
+
+A running session publishes one record:
+
+```
+$QWEN_HOME/sessions/<pid>.json            (directory 0700, file 0600)
+$QWEN_HOME/sessions/<pid>-<8 hex>.json    (a process hosting several sessions)
+```
+
+`$QWEN_HOME` defaults to `~/.qwen`. The file name is keyed by the
+writer's PID — either the bare PID, or the PID, a dash, and eight
+lowercase hex characters minted at registration (see "Several records
+from one process" below). A record whose `pid` field disagrees with the
+PID prefix of its file name — compared in canonical decimal form, so a
+zero-padded name agrees with nothing — 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 PID the file name is keyed by: the whole name for the bare form, the digits before the `-<8 hex>` suffix for the minted one.                                                                                                                                  |
+| `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). 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
+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 is
+`<pid>.json` or `<pid>-<8 hex>.json` and its PID prefix equals `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.
+
+**Several records from one process.** Any `qwen --acp` child — spawned
+by the daemon, or driven directly by an editor or another client —
+writes one record per session, named `<pid>-<8 hex>.json`, from its
+first session on. The suffix is minted at
+registration and never changes; a session id swapped underneath is a
+patch to the record, not a rename of it. Every one of them carries the
+same `ipcPath`, because the process binds one inbox for all its sessions
+and tells them apart by the `toSessionId` on each frame — so **always
+send `toSessionId`**: a frame without one that reaches such a process is
+answered `misaddressed`, since there is no single session it could have
+meant. Liveness, sweeping and the namespace and boot guards read the
+record exactly as they do for the bare name; only the PID/filename
+agreement check differs, and only in comparing `pid` against the digits
+before the suffix rather than the whole name.
+
+## 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.
+- **Inbound messages to ACP-driven sessions.** A session a program
+  drives over ACP — daemon-spawned or not — registers and can send, but
+  answers `refused` to anything sent to it: a hold is a question put to
+  a person, and nobody is watching a hold list on its behalf. Where a
+  held message should surface for those sessions — its client, or the
+  daemon's own API — is still open.
+- **Sessions behind one inbox are one sender to every peer.** A process
+  hosting several sessions sends with one `from` address, so a
+  receiver's per-sender budget and duplicate window (§6) are shared by
+  all of that process's sessions at once: a busy sibling can spend
+  another's allowance, and a body just sent to one cannot be repeated
+  to its sibling inside the window. Per-session accounting would have
+  to trust a frame-asserted field, which §3's trust model rules out.

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 call, so later turns and the verifier still have it to cite. That call is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default; a checkpoint that does not finish in time is abandoned as an inconclusive check — the checkpoint stall streak is preserved rather than incremented — and a later turn retries it. The call is 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 call. 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. The check 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. 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.