Skip to content
Closed
Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
52 commits
Select commit Hold shift + click to select a range
dbe9950
feat(cli): list managed Agent View sessions in qwen sessions ps
yiliang114 Sep 3, 2026
8879852
docs(skills): stop the recency gate from silencing a stalled wiring
yiliang114 Sep 3, 2026
06741f4
feat(cli): start a background Agent View session with --bg
yiliang114 Sep 3, 2026
6eb41f0
feat(cli): see, answer and stop a background session
yiliang114 Sep 3, 2026
eaa0a23
test(cli): pin the id a background worker registers under
yiliang114 Sep 3, 2026
cb77045
Merge branch 'feat/agent-view-bg-dispatch' into feat/agent-view-sessi…
yiliang114 Sep 3, 2026
85c5e36
feat(serve): expose the background agents the supervisor is running
yiliang114 Sep 3, 2026
a4baf7c
fix(serve): wire the background-agents trust gate in production
yiliang114 Sep 3, 2026
7d20281
fix(serve): give the background-agents 503 the daemon error envelope
yiliang114 Sep 3, 2026
3620141
test(serve): pin the background-agents field guards in a mixed state
yiliang114 Sep 3, 2026
9b14578
fix(cli): keep non-owned supervisor snapshots out of sessions ps
yiliang114 Sep 3, 2026
94610b3
fix(cli): verify managed session pids before listing them
yiliang114 Sep 3, 2026
3e3dac5
test(cli): pin LF and TAB stripping on the ps store-failure note
yiliang114 Sep 3, 2026
4d84fbc
docs(commands): warn that the jq -r example renders session text raw
yiliang114 Sep 3, 2026
29a69d0
fix(cli): route Agent View intercepts after bootstrap routing and scrub
yiliang114 Sep 3, 2026
993944c
fix(cli): decline --bg launches carrying flags they would silently drop
yiliang114 Sep 3, 2026
2031747
fix(cli): strip LF/TAB from one-line session control output
yiliang114 Sep 3, 2026
02b87ee
docs(settings): list --bg in the command-line arguments table
yiliang114 Sep 3, 2026
6c194f9
fix(cli): name peek's title the way sessions ps does
yiliang114 Sep 4, 2026
572de7a
fix(cli): stop peek printing the summary twice
yiliang114 Sep 4, 2026
2fde009
fix(cli): write session control failures to stderr
yiliang114 Sep 4, 2026
6b2c711
fix(cli): keep the sessions ps JSON contract off display wording
yiliang114 Sep 4, 2026
e5e0b6d
Merge branch 'feat/agent-view-first-consumer' into feat/agent-view-bg…
yiliang114 Sep 4, 2026
6a96db5
Merge branch 'feat/agent-view-session-control' into feat/daemon-backg…
yiliang114 Sep 4, 2026
7614b86
Merge branch 'feat/agent-view-bg-dispatch' into feat/agent-view-sessi…
yiliang114 Sep 4, 2026
136e783
fix(serve): report the stable task token, not the table's wording
yiliang114 Sep 4, 2026
cd68e10
fix(cli): import the task-state type the row test annotates
yiliang114 Sep 4, 2026
1077718
Merge branch 'feat/agent-view-first-consumer' into feat/agent-view-bg…
yiliang114 Sep 4, 2026
04735cc
Merge branch 'feat/agent-view-bg-dispatch' into feat/agent-view-sessi…
yiliang114 Sep 4, 2026
5315cc4
Merge branch 'feat/agent-view-session-control' into feat/daemon-backg…
yiliang114 Sep 4, 2026
2416476
fix(serve): give the background-agents test a pid that is really alive
yiliang114 Sep 4, 2026
edddf36
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 7, 2026
1f84edb
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 9, 2026
318237d
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 12, 2026
a5f3bb7
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 18, 2026
ad24822
fix(cli): take isPidAlive from the core module that defines it
yiliang114 Sep 18, 2026
3bc3f95
fix(cli): make the background agent surfaces tell the truth
yiliang114 Sep 19, 2026
ebf5c1d
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 19, 2026
8294768
test(cli): keep the stdout recorder mock's return type void
yiliang114 Sep 19, 2026
7f43e6b
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 23, 2026
1b58fbb
fix(serve): merge the session registry into GET /background-agents
yiliang114 Sep 24, 2026
b2e1fea
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 25, 2026
0c5f997
Merge origin/main (73aa65a4b4) into feat/daemon-background-agents
yiliang114 Sep 25, 2026
420ab83
fix(serve): scope GET /background-agents to the bound workspace
yiliang114 Sep 25, 2026
4467b79
chore(skills): drop the find-simplifications survey edits from this PR
yiliang114 Sep 26, 2026
3b97553
Merge branch 'main' into feat/daemon-background-agents
wenshao Sep 26, 2026
4f275d0
fix(cli): let a leading --bg reach cli.js instead of answering -v
yiliang114 Sep 26, 2026
d5627a0
chore(serve): merge main into feat/daemon-background-agents
qwen-code-dev-bot Sep 26, 2026
4ae0857
Merge branch 'feat/daemon-background-agents' (d5627a0c94) into local …
yiliang114 Sep 26, 2026
ec7f7ae
fix(cli): close the round-13/14 critical findings on the background-a…
qwen-code-dev-bot Sep 27, 2026
b98dfa1
Merge origin/main into feat/daemon-background-agents
yiliang114 Sep 27, 2026
728f08a
Merge origin/main into feat/daemon-background-agents
yiliang114 Oct 2, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .qwen/skills/find-simplifications/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,7 @@ the issue comment.
| Several strong candidates in one run | File them all; land at most one |
| Report-only territory | File with evidence, marked report-only. Never a PR |
| Path or symbol younger than ~90 days | Drop **silently** — unwired new feature, not rot |
| A young **subsystem** unwired, its wiring PR open and stale | Not a deletion. Report the stall to that PR stack |
| A never-called migrator, validator, guard, or dropped wire-up | Not cleanup. It may be a defect → `/bugfix` or `/review` |
| Any consumer cannot be named | Drop |
| Correct but tiny (one dead import, a typo) | Reject on the ledger: below both skills' intake bar |
Expand Down
47 changes: 41 additions & 6 deletions .qwen/skills/find-simplifications/references/survey.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,27 @@ feature someone is still wiring up. (90 days is a heuristic, not a measured
threshold; widen it for a large subsystem.) Proposing deletion of something
that landed last week is the fastest way to lose a reviewer for good.

But "young" is not the fact the gate is reaching for — "still being wired
up" is, and the two come apart. A directory can keep growing for months
while its consumer never lands, and then every re-run of this survey dates
it young again and drops it again, which is how a subsystem gets to five
figures with nothing calling it. So when the gate fires on a **subsystem**
(not a single symbol), date the wiring rather than the code:

```bash
# has anything outside it ever referenced it?
"$RG" -l '<dir>/' --glob '!<dir>/**' packages
Comment thread
yiliang114 marked this conversation as resolved.
Resolved
# and are the PRs that would wire it still open?
gh pr list --repo QwenLM/qwen-code --search '<feature> in:title' --state all
```

Recent commits inside the directory plus no external reference plus an open,
stalled wiring PR is **not** a deletion candidate and **not** a drop. It is a
different finding with a different owner: the wiring stalled. Report it to
that stack — the merged infrastructure has no entry point — and never as a
deletion PR. The code is wanted; the review that would connect it is what is
missing.

**3 — Published-surface escape.** Is the surface reachable from outside the
repo? SKILL.md § Territory is the authoritative list; keep the two in step.
Everything under `packages/core/src` is, via that package's `"./src/*"`
Expand Down Expand Up @@ -262,13 +283,27 @@ registry entry), not in `packages/core`, and `git log` puts it well past the
recency gate. Deletion is the component, its test, and its snapshot entry, in
one commit. This is what a filed candidate should look like.

**2. Everything says dead; `git` says five days old.** `packages/cli/src/agent-view`
is ~6,000 lines whose entry flag is passed to a spawned process but parsed
nowhere; every static signal calls it rot. Then:
**2. Everything says dead; `git` says five days old — and says it again a
month later.** `packages/cli/src/agent-view` was ~6,000 lines whose entry flag
is passed to a spawned process but parsed nowhere; every static signal called
it rot. Then:
`git log --follow --diff-filter=A --format=%ad --date=short -- packages/cli/src/agent-view
| tail -1` → `2026-08-01`, five days before HEAD. It is a feature mid-wiring.
**Drop silently.** Do not file it, do not mention it — a "should we delete
your new subsystem?" question costs more trust than the finding is worth.
| tail -1` → `2026-08-01`, five days before HEAD. A feature mid-wiring, so:
**do not file a deletion.** A "should we delete your new subsystem?" question
costs more trust than the finding is worth.

What this example originally got wrong was the second half — "do not mention
it". Measured again on 2026-09-04: **11,004 production lines, still zero
external references**, up ~8,000 in four weeks. The five merged PRs of its
stack shipped the supervisor, the PTY workers and the lifecycle; the two that
would give it an entry point (#7802 commands, #7803 roster TUI) have been
open since 2026-07-27, the second at +31,699 lines across 104 files and
conflicting. The recency gate kept firing and the survey kept dropping it, so
nothing ever said out loud that a five-figure subsystem had no caller.

The deletion verdict was right and stays right. The silence was not: this is
the stalled-wiring finding above, owed to that PR stack, not to a cleanup
list.

**3. The naive count is wrong in both directions.**
`eslint.legacy-filenames.mjs` lists 559 bare basenames. Checking "does a
Expand Down
1 change: 1 addition & 0 deletions docs/developers/daemon/02-serve-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serve/fs/` | `WorkspaceFileSystem` factory plus `policy.ts` (size/trust/binary checks), `paths.ts` (canonicalize, resolveWithin, symlink rejection), `audit.ts`, and typed `FsError` values. |
| `serve/routes/workspace-file-read.ts`, `workspace-file-write.ts` | HTTP handlers for `GET /file`, `GET /file/bytes`, `POST /file/write`, and `POST /file/edit`. |
| `serve/routes/background-agents.ts` | `GET /background-agents` — the sessions the Agent View supervisor is running, read from the roster rather than from the daemon's own session model. Read-only: acting on one goes through the supervisor's socket, which the CLI does. |
Comment thread
yiliang114 marked this conversation as resolved.
Resolved
| `serve/workspace-memory.ts` | `GET/POST /workspace/memory` (QWEN.md CRUD). |
| `serve/workspace-agents.ts` | `GET/POST/DELETE /workspace/agents` (subagent CRUD). |
| `serve/daemon-status-provider.ts` | Env snapshot plus daemon-host preflight cells: Node version, CLI entry, workspace stat, ripgrep, git, npm. |
Expand Down
100 changes: 85 additions & 15 deletions docs/users/features/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -707,10 +707,13 @@ These commands are run from the shell as `qwen <subcommand>` before starting an

### Session Management

| Command | Description | Usage Examples |
| -------------------- | ------------------------------------------- | ------------------------------------------------------------ |
| `qwen sessions list` | List recent conversation sessions | `qwen sessions list`, `qwen sessions list --json --limit 50` |
| `qwen sessions ps` | List interactive sessions running right now | `qwen sessions ps`, `qwen sessions ps --json` |
| Command | Description | Usage Examples |
| ---------------------- | --------------------------------------------- | ------------------------------------------------------------ |
| `qwen sessions list` | List recent conversation sessions | `qwen sessions list`, `qwen sessions list --json --limit 50` |
| `qwen sessions ps` | List the sessions running right now | `qwen sessions ps`, `qwen sessions ps --json` |
| `qwen sessions peek` | Show what a background session is doing | `qwen sessions peek 0f8e1c42` |
| `qwen sessions answer` | Answer a background session waiting for input | `qwen sessions answer 0f8e1c42 "yes, go ahead"` |
| `qwen sessions stop` | Stop a background session | `qwen sessions stop 0f8e1c42` |

#### `qwen sessions list`

Expand Down Expand Up @@ -750,14 +753,35 @@ qwen sessions list --limit 50
qwen sessions list --json | jq .
```

#### `qwen --bg "<prompt>"`

Experimental. Runs a prompt as a background session and returns immediately, printing the session id.

The session is owned by a supervisor process that outlives the shell you started it from, so closing that terminal does not stop the work. `qwen sessions ps` lists it, and says whether it is `working` or has stopped to ask you something. It is a full Qwen Code session, so — when `agents.crossSessionMessaging` is on — it also appears in another session's `list_agents` and can be addressed with `send_message` (see [Messaging Another Running Session](#6-messaging-another-running-session)).
Comment thread
yiliang114 marked this conversation as resolved.
Resolved

```bash
qwen --bg "find out why the release job is flaky"
# Started background session 0f8e...c31
Comment on lines +775 to +776

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at head 8294768c6f. Verdict: REAL — the --bg launch cannot produce the transcript this page publishes, and there is no production emitter for the event it waits on.

The wait is armed by default. shouldWaitForWorkerReady is options.waitForWorkerReady ?? !options.launchPtyHost (packages/cli/src/agent-view/supervisor-process.ts:3486-3490), and neither option is assigned anywhere in non-test packages/cli/src — launchPtyHost exists only as the injectable function type at :146 and is read at :2186/:2196. So --bg dispatch waits.

Nothing can satisfy it. The ready event is consumed at supervisor-process.ts:838-860 (resolve or reject the pending waiter), but its only producers are sendAgentViewWorkerEvent / reportAgentViewWorkerState / startAgentViewWorkerHeartbeat in packages/cli/src/agent-view/worker-sideband.ts:107,159,238, and all three are referenced only inside that module: the production importers take createAgentViewWorkerSidebandEnv (supervisor-process.ts:71-74, supervisor-dispatch.ts:21) and AGENT_VIEW_WORKER_ENV_KEYS (pty-host.ts:9) and nothing else. Same shape as the gap behind the commands.md:907 verdict — the sideband has readers, no writers.

So the documented success path is unreachable. waitForWorkerReadyIfNeeded rejects after DEFAULT_WORKER_READY_TIMEOUT_MS = 15_000 (:96, :2222-2225) with did not report ready before timeout; runBackgroundDispatch catches that, writes Could not start a background session: … to stderr and returns 1 (packages/cli/src/agent-view/background-entry.ts:152-157) — which is before Started background session ${sessionId} at :159. The transcript at commands.md:773-777, "returns immediately, printing the session id" at commands.md:767, and the same claim in the flag table at docs/users/configuration/settings.md:872 all describe the arm that does not happen.

One narrowing, so a fix does not chase the wrong mechanism: working is a printable state. TASK_STATE_LABEL maps running: 'working' for the ps STATE column (packages/cli/src/commands/sessions/ps.ts:118-124), and deriveTaskState folds sessionState: 'starting' into running (packages/cli/src/agent-view/presentation.ts:163-166), with starting written on every dispatch (supervisor-dispatch.ts:61-62). What has no production writer is sessionState: 'working' itself — every non-test occurrence in packages/cli/src is a comparison (supervisor-process.ts:1538, :3109, :3514, supervisor-store.ts:943, worker-sideband.ts:176), and the only sessionState: 'working' literals are test fixtures (managed-rows.test.ts:40,259,276, managed-control.test.ts:89). The claim at commands.md:779 is still false, but because a --bg session never gets to sit under that label — as shipped it lands failed, and with the missing event supplied it ends ready — not because the token is absent from the table. Any rewording has to stay consistent with :779 and with the peek verdict on the commands.md:907 thread.

No code lands this round: the PR is +3193/-71, 2.1x over patrol's 1500-addition scope fuse, with a maintainer scope ruling pending. This one is docs-only and small — commands.md:767 plus :773-779 and the one settings.md:872 cell, two files, no contract and no data structure. It is still human-gated for the same reason as :907: the two available wordings (hold the --bg section back, or document that it exits 1 today) are a statement about whether worker state reporting ships in this PR or in the Agent View follow-up, which is the scope question the maintainer has not ruled on. Leaving this thread unresolved.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Held at 1b58fbbd86 and deliberately left unresolved — this is the documentation face of N1, which wenshao's round 4 (2026-09-24T03:28Z, on this head) names as the sole merge blocker.

Site status at the live head. Re-read at 1b58fbbd86: commands.md:775 is still # Started background session 0f8e...c31 inside the qwen --bg "find out why the release job is flaky" transcript (:773-777), and :779 still carries the sibling claim "until that reporting lands, a background session is listed as working and answer has nothing waiting to answer". Both are byte-identical to the round-9 re-check head 7f43e6bcdd — the only commands.md hunk in the intervening commit is the controller-discovery recipe at :1097-1108, well below both cited lines.

Why it is held rather than reworded. The correct text is different depending on which branch of N1 is chosen, so writing anything now means writing it twice:

  • Under (a) — wire a production ready producer plus the prompt-consuming control plane — this transcript becomes true as written, and the only edit needed is to :779's working token, which the finding already shows is unreachable (working is not in the closed AgentViewTaskState key set at presentation.ts:25-31 without a sessionState: 'working' writer, which does not exist).
  • Under (c) — ship this stack without the --bg entry point — the whole --bg block comes out of commands.md, settings.md:872's "returns immediately, printing the session id" goes with it, and per the author's own 2026-09-23 note the same removal has to be applied to PR #10943.

Round 4 measured the shipped behaviour on this head: 2/2 real launches exit 1 after ~15 s with did not report ready before timeout and an empty stdout, and injecting a ready makes the launch succeed but the prompt is never consumed (idle 40 s). So the finding is accurate and I am not disputing it — but choosing between (a) and (c) is a product/architecture call for the maintainer and the author, and rewriting the doc ahead of that call would either certify a behaviour that does not ship or pre-empt the decision.

Leaving this thread open until the N1 ruling lands.

中文

在 1b58fbbd86 上挂起,刻意不 resolve——这是 N1 的文档面,而 wenshao 第 4 轮(2026-09-24T03:28Z,跑在这个 head 上)认定 N1 是唯一的合并阻塞项。

站点状态:在当前 head 上重读,commands.md:775 仍然是 qwen --bg "find out why the release job is flaky" 那段转录(:773-777)里的 # Started background session 0f8e...c31;:779 仍然带着那句兄弟断言「在该上报落地之前,后台会话会被列为 working,answer 也没有待回答的内容」。两处都与第 9 轮复核 head 7f43e6bcdd 逐字节相同——中间那个 commit 对 commands.md 的唯一 hunk 在 :1097-1108(controller 发现配方),远在两条引用行之下。

为什么挂起而不改文案:正确的文字取决于 N1 选哪条分支,所以现在写等于要写两遍:

  • 选 (a)(接上生产环境的 ready 生产者 + 消费 prompt 的控制面):这段转录照原样就成立,唯一要改的是 :779 的 working 这个 token——finding 已经证明它不可达(没有 sessionState: 'working' 的写入方,presentation.ts:25-31 的封闭 AgentViewTaskState 键集里到不了 working)。
  • 选 (c)(这一栈不带 --bg 入口发布):整段 --bg 要从 commands.md 移除,settings.md:872 的「立即返回并打印 session id」也要一起去掉,而且按作者自己 2026-09-23 的说明,同样的移除还必须应用到 PR #10943。

第 4 轮在这个 head 上量到了实际行为:2/2 次真实启动都在约 15 秒后以退出码 1 结束、报 did not report ready before timeout、stdout 为空;手动注入一个 ready 后启动成功,但 prompt 从未被消费(空转 40 秒)。所以 finding 是准确的,我不质疑它——但在 (a) 与 (c) 之间做选择是维护者和作者的产品/架构决定,在裁决之前改文档,要么去认证一个不会发布的行为,要么抢在那个决定前面。

在 N1 裁决落地前保持本线程不 resolve。

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Held for the N1 decision, as recorded on this thread before: whether the shipped --bg launch ever succeeds is exactly the (a)/(b)/(c) call the maintainer owns (wire a production ready producer, or ship without --bg). Rewriting the transcript now preempts that decision in one direction; if (b) lands the passage becomes true as written. Not silently dropped — it rides with N1.

中文说明

按此前在该线程记录的处置,本条随 N1 一并等待:已发布的 --bg 启动能否成功,正是由维护者裁决的 (a)/(b)/(c) 选择(接上生产端 ready 产出方,或本栈不带 --bg)。现在改写这段交互记录等于提前替该决定选了方向;若选择 (b),现有文字将如实成立。本条未被丢弃——随 N1 一并处理。

@yiliang114 yiliang114 Oct 3, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at head 728f08a67e. Verdict: REAL, and it is not out of scope — this is the documentation face of N1, the PR's own merge blocker. Left UNRESOLVED.

Disclosure first: I built and ran nothing this round. No install, no bundle, no qwen --bg. Everything below about exit codes, timings and store state rests on wenshao's round-10 deep verification of this exact head on a real build (comment, 2026-10-03T00:01:37Z). What is mine is the doc text and the caller sweep, both read at 728f08a67e.

The published promises, re-read at head (line numbers moved since the finding was filed; wording did not):

  • docs/users/features/commands.md:768 — "Experimental. Runs a prompt as a background session and returns immediately, printing the session id."
  • commands.md:774-778 — the transcript, with :776 = # Started background session 0f8e...c31. This is the thread's anchor line.
  • commands.md:780 — "…until that reporting lands, a background session is listed as working and answer has nothing waiting to answer."
  • docs/users/configuration/settings.md:892 — the --bg row: "…and returns immediately, printing the session id." (was :872 when filed, then :878, :879.)

wenshao's measurement of those four lines, on a fresh build of this head: with the same QWEN_HOME, qwen -p answers PONG in 9.5 s, so the model path is fine; qwen --bg exits 1 after 15.3 s with did not report ready before timeout; all 7 launches recorded this round exited 1 in 15.2–15.3 s; stdout is empty, so no session id is ever printed; state.json is failed/exited with lastError.code = pty_launch_failed, and sessions ps lists failed. Nothing prints working. Every one of the four passages above describes the arm that does not happen.

My own reading of the mechanism at head agrees, and it is the same root as N1. The only functions that can send a worker ready are sendAgentViewWorkerEvent, reportAgentViewWorkerState and startAgentViewWorkerHeartbeat (packages/cli/src/agent-view/worker-sideband.ts:107, :159, :238). A repo-wide grep over packages/**/*.{ts,tsx} excluding node_modules, dist and *.test.* finds no caller outside worker-sideband.ts itself (internal recursion at :131, :204, :244) and worker-sideband.test.ts. The three production importers of that module take other symbols only: pty-host.ts:9 (AGENT_VIEW_WORKER_ENV_KEYS), supervisor-process.ts:74, supervisor-dispatch.ts:21 (both createAgentViewWorkerSidebandEnv). wenshao's independent read of the same head: dispatch sets promptInArgv: !shouldWaitForWorkerReady(...), so when the supervisor waits for ready the prompt is not even on the worker's argv — his recorded launch.json shows argv [node, dist/cli.js, --session-id, <id>] with the prompt only in initialPrompt.

One narrowing, so a rewording does not chase the wrong token. working is a printable STATE word: TASK_STATE_LABEL maps running: 'working' (packages/cli/src/commands/sessions/ps.ts:122-128) and deriveTaskState folds sessionState: 'starting' into running (agent-view/presentation.ts:163-166). What has no non-test writer is sessionState: 'working' itself — the only sessionState: '<literal>' writes in non-test packages/cli/src are idle (supervisor-process.ts:593), failed (:2699, :2710, :3652, supervisor-dispatch.ts:165), stopped (:3581) and starting (supervisor-dispatch.ts:61, :148). So commands.md:780 is false because a --bg session never sits under that label — as shipped it lands failed, and with the missing event supplied wenshao's earlier rounds measured ready — not because the word is absent from the table.

Routing. Not deferred, not out of scope: this is N1's user-visible surface, and N1 is the reason wenshao says "do not merge the stack". His landable path is the route-only split plus the round-9 candidate (+76/−5, which still applies unchanged and still closes R13-4/R4-4), and that split explicitly leaves --bg and sessions peek|answer|stop out. Choosing between "wire a production ready producer" and "ship this stack without the --bg entry point" is an architecture decision for the author and maintainer, and the correct doc text is different under each — so writing either wording now means writing it twice and pre-empting that call.

What I will state plainly: the docs must not keep promising a launch the stack cannot perform. Whichever branch is picked, commands.md:768, :774-778, :780 and settings.md:892 have to move together, and if the answer is "ship without --bg" the same removal applies to PR #10943 per the author's own 2026-09-23 note.

No code lands this round and nothing is pushed: the PR is +3765/−196, 2.5x patrol's 1500-addition scope fuse, and this pass is reply-only. Thread stays open until the N1/split decision lands.

# See it with: qwen sessions ps
```

See what it is doing with `qwen sessions peek`, reply to it with `qwen sessions answer`, and end it with `qwen sessions stop`. What is still missing: attaching to a background session's terminal and reading its full transcript. Those land with the Agent View roster.

#### `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 running on this machine right now.
Comment thread
yiliang114 marked this conversation as resolved.
Resolved
`sessions list` walks saved transcripts ("what have I worked on"); this
answers "what is running at this moment".

Two kinds of session are listed. An **interactive** session is one you
started in a terminal; it registers in the live-process registry, and
records left behind by a killed session are swept as they are found. A
**managed** session is an Agent View session owned by a supervisor: it
writes no registry record, so it used to be invisible here. Managed
Comment thread
yiliang114 marked this conversation as resolved.
Resolved
sessions are listed first, because one of them may be waiting for an
answer.

Headless sessions (`qwen -p`) register nowhere and are not shown.
Comment thread
qwen-code-dev-bot marked this conversation as resolved.
Resolved
Comment thread
qwen-code-dev-bot marked this conversation as resolved.
Resolved

**Flags:**

Expand All @@ -767,20 +791,38 @@ registry, so they are not shown.

**Human-readable output (default):**

A table with columns: NAME, PID, AGE, DIRECTORY.
A table with columns: NAME, PID, AGE, STATE, DIRECTORY.

STATE is `interactive` for a session you started yourself. For a managed
session it is what that session is actually doing — `needs input`,
`working`, `ready`, `stopped` or `failed`. PID and AGE print `-` for a
managed session with no process behind it (one that has exited, or has
not started its worker yet).

**JSON output (`--json`):**

Outputs JSON Lines on stdout, newest session first. Each line is a JSON
object with fields:
Outputs JSON Lines on stdout, managed sessions first. Every line carries
a `managed` field saying which kind it is.

An interactive session is emitted as its whole registry record, plus
`managed: false`:
Comment thread
yiliang114 marked this conversation as resolved.
Resolved

```
schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
qwenVersion
qwenVersion, managed
```

A managed session has no such record and is emitted as the row itself:

```
name, pid, startedAt, cwd, state, sessionId, managed
```

Nothing else is written to stdout — an empty listing prints nothing at
all — so `qwen sessions ps --json | jq .` is safe to script against.
all — so `qwen sessions ps --json | jq .` is safe to script against. If
the supervisor's own bookkeeping cannot be read, the interactive half is
still listed and the reason is reported on stderr, which leaves stdout
parseable.

JSON output is raw data: field values are emitted exactly as recorded,
with no terminal sanitization. Treat them as data, and sanitize before
Expand All @@ -796,8 +838,36 @@ qwen sessions ps
# Note: `jq -r` renders the raw recorded value in your terminal (see the
# raw-data note above); pipe through a sanitizer if the path is untrusted.
qwen sessions ps --json | jq -r .cwd

# Which background sessions are waiting on me?
qwen sessions ps --json | jq -r 'select(.state == "needs input") | .name'
```

#### `qwen sessions peek|answer|stop <session>`

A background session started with `--bg` runs with nobody watching it. These three commands are how you catch up with one. Each takes a session id or any unique prefix of one — the short form `qwen sessions ps` and `--bg` print is enough.
Comment thread
yiliang114 marked this conversation as resolved.
Resolved

`peek` shows what the session is doing, and what it has stopped to ask:

```bash
$ qwen sessions peek 0f8e1c42
find out why the release job is flaky [0f8e1c42]
State: waiting
Directory: /w/app
Waiting: permission to write scripts/flake-report.md
Comment on lines +910 to +912

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at head 8294768c6f. Verdict: REAL, narrowed as stated — the peek transcript is the one entrance still open, and it is the only peek example on the page.

What the page publishes, verbatim at docs/users/features/commands.md:901-911: a peek transcript with State: waiting, Waiting: permission to write scripts/flake-report.md and Answer it with: qwen sessions answer 0f8e1c42 "<your answer>", immediately followed at :913-917 by that answer invocation as the documented next step.

Neither line can render in the shipped CLI:

  • Waiting: comes only from response.activity?.waitingFor (packages/cli/src/commands/sessions/managed-control.ts:170-172), and Answer it with: only when presentation.taskState === 'waiting' (:188-192).
  • taskState === 'waiting' requires sessionState === 'needs_input' (packages/cli/src/agent-view/presentation.ts:163-168 — the switch is on state.sessionState alone; the _inputState parameter at :161 is unused, so no activity-derived state can substitute).
  • Nothing produces either field. Every non-test needs_input occurrence in packages/cli/src is a comparison, not a write (supervisor-process.ts:1889, :3110, :3515, :3961-3963, :4036), and waitingFor is a sideband-only field (packages/cli/src/agent-view/worker-sideband.ts:48) whose reporters have no production callers outside that module — the sweep behind the commands.md:864 verdict established that, and re-grepping waitingFor at this head returns the same shape: readers in managed-control.ts and presentation.ts, declaration in worker-sideband.ts, no writer.

So a user whose background session really is stuck on a tool approval follows the table at :722 into this section, gets a peek that prints the title, State: running and the directory — no question, no hint — and then the documented answer exits 1 with Agent View session <id> is not waiting for input. The explanation that would resolve this ("until that reporting lands, a background session is listed as working and answer has nothing waiting to answer") is ~130 lines earlier under a different command.

Consistency with the earlier verdict: the commands.md:864 thread was closed on 3bc3f95f12 for the --bg prose, the jq example and the taskState contract. That closure is still correct as far as it goes; this thread is the part it did not cover, and the bot's narrowing to the peek half matches what I read.

No code lands this round: the PR is +3193/-71, 2.1x over patrol's 1500-addition scope fuse, with a maintainer scope ruling pending. Worth saying plainly, though — unlike the other two open Criticals this one is cheap and local: it is a docs-only reword of one transcript in commands.md, no contract and no data structure. The reason it is still human-gated is that the right wording depends on a decision this PR should not make unilaterally — whether worker state reporting ships here or in the Agent View follow-up. If it ships later, the transcript should be led with "once a worker can report that it has stopped to ask" plus one line stating today's behaviour; if it ships here, the transcript is fine and the producer is what is missing. Suggest folding it into the same follow-up commit as that decision. Leaving this thread unresolved.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Held at 1b58fbbd86 and deliberately left unresolved — same N1 dependency as the --bg transcript thread, on the peek half.

Site status at the live head. Re-read at 1b58fbbd86: the peek transcript renders at commands.md:902-911 exactly as the round-9 re-check found it — :905 State: waiting, :907 Waiting: permission to write scripts/flake-report.md, :909 Answer it with: qwen sessions answer 0f8e1c42 "<your answer>", and the following answer example at :913-914. commands.md is unchanged below :1097; the intervening commit's only hunk in this file is the controller-discovery recipe at :1097-1108.

Why it is held. The finding is that nothing in the shipped CLI can write sessionState: 'needs_input', so presentation.taskState can never be 'waiting' (presentation.ts:167), so peekManagedSession's Waiting: line and answer hint never render and the published answer example exits 1 with "is not waiting for input". That is the same missing producer N1 is about — the worker sideband reporting that a background session stopped to ask. Round 4 confirms it on this head from the other direction: injecting a ready makes the launch succeed but the prompt is never consumed (idle 40 s), i.e. there is still no control plane for a worker to report through or to be answered through.

So the correct wording here is decided by the same (a)/(c) ruling: under (a) the transcript becomes accurate once worker reporting ships and only the framing sentence needs adjusting; under (c) the peek/answer documentation for background sessions comes out along with the --bg entry point, and per the author's 2026-09-23 note the matching removal applies to PR #10943. Writing the "today's behaviour" caveat now would be the right call if this PR were merging on its own, but it would have to be unwritten immediately under (a), and it is a doc change on a PR already past this patrol's scope ceiling.

Leaving this thread open until the N1 ruling lands.

中文

在 1b58fbbd86 上挂起,刻意不 resolve——与 --bg 转录那条线程同一个 N1 依赖,这是 peek 那半边。

站点状态:在当前 head 上重读,peek 转录仍然渲染在 commands.md:902-911,与第 9 轮复核一致——:905 State: waiting、:907 Waiting: permission to write scripts/flake-report.md、:909 Answer it with: qwen sessions answer 0f8e1c42 "<your answer>",紧随其后的 answer 示例在 :913-914。commands.md 在 :1097 以下没有变化;中间那个 commit 在本文件的唯一 hunk 是 :1097-1108 的 controller 发现配方。

为什么挂起:finding 说的是——已发布的 CLI 里没有任何位置写入 sessionState: 'needs_input',所以 presentation.taskState 永远不可能是 'waiting'(presentation.ts:167),所以 peekManagedSession 的 Waiting: 行和回答提示永远不渲染,文档里那个 answer 示例会以退出码 1 报「is not waiting for input」。这与 N1 缺的是同一个生产者——后台会话停下来提问时的 worker sideband 上报。第 4 轮从另一个方向在这个 head 上确认了它:注入一个 ready 后启动成功,但 prompt 从未被消费(空转 40 秒),也就是说仍然没有供 worker 上报、也没有供其被回答的控制面。

所以这里的正确措辞由同一个 (a)/(c) 裁决决定:选 (a),等 worker 上报落地后这段转录就准确了,只需调整那句引导语;选 (c),后台会话的 peek/answer 文档随 --bg 入口一起移除,并且按作者 2026-09-23 的说明,同样的移除也适用于 PR #10943。现在写「当前实际行为」的注记,在本 PR 单独合并的前提下是对的做法,但在 (a) 下它马上又得撤掉,而且本 PR 的累计规模已超出巡检 scope 上限。

在 N1 裁决落地前保持本线程不 resolve。

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Held for the N1 decision: whether anything ever reports waiting / needs_input is decided by the same (a)/(b)/(c) launch call. If the worker sideband lands, this transcript becomes reachable as written; if the stack ships without it, the transcript goes with the feature. Correcting it now preempts the decision either way.

中文说明

随 N1 决定一并等待:是否会有代码上报 waiting / needs_input,由同一个 (a)/(b)/(c) 启动决策决定。若 worker 旁路通道落地,这段交互记录将如实可达;若本栈不带该功能,这段记录也随功能一并移除。现在改动它,无论哪个方向都是提前替决定作答。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-verified at head b98dfa1927 from the files, not from earlier rounds. Verdict: REAL and unchanged — held on the existing N1 ruling, not re-opened.

The site, verbatim (git show refs/prheads/10954:docs/users/features/commands.md):

  • :905 "peek shows what a session is doing, and what it has stopped to ask"
  • :910 State: waiting
  • :912 Waiting: permission to write scripts/flake-report.md
  • :914 Answer it with: qwen sessions answer 0f8e1c42 "<your answer>", with that answer invocation as the next documented step at :920
  • and the same page contradicting it 39 lines earlier, :870-871: "taskState is … running, waiting, ready, stopped or failed. … Nothing reports waiting yet — see the --bg note above."

Producer sweep I ran myself rather than inheriting batch 1's pre-confirmation:

  • git grep -n "reportAgentViewWorkerState\|sendAgentViewWorkerEvent\|startAgentViewWorkerHeartbeat\|readAgentViewWorkerControlEvents" refs/prheads/10954 -- packages | grep -v '\.test\.' → 7 hits, all inside worker-sideband.ts (:107, :124, :131, :159, :204, :238, :244). External production callers: 0.
  • What supervisor-process.ts:71-74 imports from that module is only createAgentViewWorkerSidebandEnv and QWEN_AGENT_VIEW_TOKEN — env plumbing, no emitter.
  • The receive half is fully built, which sharpens the finding instead of softening it: op workerEvent is declared at supervisor-client.ts:93, the parser accepts type: 'state' carrying sessionState and waitingFor at supervisor-process.ts:4260-4288, and the store write lands at :3772-3812. Only the send half is uncalled.
  • deriveTaskState (presentation.ts:159-179) switches on state.sessionState alone and its second parameter is _inputState (:161, unused), so waiting comes only from needs_input (:167-168); deriveInputState's waitingFor rules (:211-227) cannot substitute. peekManagedSession's Waiting: line (managed-control.ts:170-173) and its answer hint (:188-193) are gated on exactly those two.

So the shipped build renders State: running with no Waiting: line, and the documented answer exits 1 with "is not waiting for input".

The standing ruling is respected, not contradicted: dev-bot's hold of 2026-09-27 ("Held for the N1 decision") and my two earlier replies still describe the situation. Because the receive half is already merged, option (a) needs only a caller — which would make this transcript accurate as written — while option (c) removes the peek/answer docs together with the --bg entry point. Writing a "today's behaviour" caveat now preempts that either way. Nothing lands this round regardless: the PR is +3765/-196, past this patrol's 1500-addition scope fuse. Leaving unresolved.

中文

在 head b98dfa1927 上从文件重新核实(不沿用前几轮结论)。结论:REAL,且未变化——按既有 N1 裁决挂起,不重开。

站点原文::905 引导句、:910 State: waiting、:912 Waiting: permission to write scripts/flake-report.md、:914 Answer it with: …,紧随其后 :920 就是这个 answer 调用;而同页 :870-871 写着「Nothing reports waiting yet」,自相矛盾。

我自己跑的生产者扫描:四个 sideband 符号在非测试代码里 7 处命中全部位于 worker-sideband.ts 内部,外部生产调用者 0;supervisor-process.ts:71-74 只从该模块导入 createAgentViewWorkerSidebandEnv 与 QWEN_AGENT_VIEW_TOKEN(环境变量管道,不含发射器)。接收半边是完整的——supervisor-client.ts:93 声明了 workerEvent op、supervisor-process.ts:4260-4288 解析 type: 'state'(带 sessionState/waitingFor)、:3772-3812 落盘——只是没人调用发送半边。presentation.ts:159-179 的 deriveTaskState 只看 state.sessionState,第二个参数 _inputState 未使用,所以 waiting 只能来自 needs_input(:167-168),deriveInputState 的 waitingFor 规则替代不了;managed-control.ts:170-173 的 Waiting: 行与 :188-193 的提示正以此为门。

维持既有裁决:dev-bot 2026-09-27 的 N1 挂起与我先前两条回复仍然成立。由于接收半边已合并,选 (a) 只差一个调用方,这段转录届时即如实;选 (c) 则文档随 --bg 入口一并移除。现在补「当前行为」注记会替裁决提前作答。本轮也不落任何改动:PR 为 +3765/-196,已超巡检 1500 行新增的 scope 熔断。保持 unresolved。


Answer it with: qwen sessions answer 0f8e1c42 "<your answer>"
```

`answer` replies to a session that is waiting, and `stop` ends one, leaving its transcript in place:

```bash
qwen sessions answer 0f8e1c42 "yes, write the report"
qwen sessions stop 0f8e1c42
```

All three talk to a supervisor that is already running and never start one: if none is, they say so rather than spawning a process to report that nothing exists.

## 6. Messaging Another Running Session

Two interactive sessions on the same machine can send each other
Expand Down
Loading
Loading