feat(cli): start a background Agent View session with --bg - #10943
feat(cli): start a background Agent View session with --bg#10943yiliang114 wants to merge 25 commits into
Conversation
The Agent View supervisor, its PTY workers and its session lifecycle are all merged, and `dispatchAgentViewSession` records everything a supervisor needs to spawn a session. None of it could run: the entry was missing two wires. The first is why nothing worked end to end. The supervisor spawns itself as `qwen --internal-agent-view-supervisor` (`supervisor-runner.ts:107`) and nothing parsed that flag — the CLI's parser runs `.strict()`, so the process spawned to be a supervisor exited on an unknown argument instead of serving. Every path that dispatches a session waited on a supervisor that could never start. The entry now recognizes the flag and serves. The second is the user-facing half: `qwen --bg "<prompt>"` ensures a supervisor, records a session for it, prints the id and returns. The session shows up in `qwen sessions ps`, which learned to list managed sessions in the parent commit. Both are handled before the argv parser and behind a raw-argv scan, so an ordinary launch pays one `Array.includes` and loads none of it. `--bg` needs a prompt and a directory; routing it through the interactive startup path — auth, theme, extensions — would buy nothing and cost all of it. The flag is still declared in the option tables so `--help` lists it and the strict parser knows it. Two details worth the reviewer's attention: - The prompt is read as the default command's positional query, and the flags that consume the token after them are derived from the CLI's own option tables rather than listed by hand. A hand-written list would go stale the first time someone adds an option, and the cost of missing one is a flag's value silently becoming part of the prompt. - The scan stops at `--`. `qwen -p x -- --bg` passes `--bg` as the user's own data, and hijacking that launch into a dispatch would be a bug with no way for the user to work around it. The internal flag moves to its own module so the entry can recognize it without importing the supervisor runtime on every launch.
|
Re-run on the current head. Gate passes — and one correction up front, because it changes what this PR is waiting on. The blocker from my previous pass was wrong. I reported that Template looks good ✓ — all nine headings present. Problem: real, and I verified it in the code rather than taking the description's word. Direction: aligned, and better supported than I expected. Size: core touch is Approach: minimal, and the two judgement calls in it are the right ones. Routing through the supervisor's Risk: no Stage 1e high-risk path matches. The real risk here is not in the diff — it is that no compiler has ever looked at this branch, which is a Stage 2 problem and the reason this run does not approve. Moving on to code review. 🔍 中文说明在当前 head 上重跑。Gate 通过 —— 但先做一个更正，因为它改变了这个 PR 到底在等什么。 我上一轮的 blocker 是错的。 我当时报告 模板完整 ✓ —— 九个标题齐全。 问题：真实存在，而且我是在代码里验证的，不是照抄 PR 描述。你 base 分支上的 方向：对齐，而且支持证据比我预期的更强。参考 agent 的 CHANGELOG 里 规模：核心改动是 方案：最小化，其中两个判断都是对的。走 supervisor 的 风险：Stage 1e 无高风险路径命中。这里真正的风险不在 diff 里 —— 而是从来没有编译器看过这个分支，这是 Stage 2 的问题，也是本轮不予 approve 的原因。 进入代码审查 🔍 — Qwen Code · qwen3.8-max-2026-09-02 Reviewed at |
The PR describes an invariant it never checked: a background worker is an ordinary interactive session, so it registers itself in the live-process registry under whatever `--session-id` it was spawned with, and `qwen sessions ps` deduplicates the registry against the roster by session id. If the two ever stopped agreeing, every background session would be listed twice — once as `interactive`, once with its real state — and nothing would have failed. Verified while tracing that path: `--session-id` does become the session's own id (`config.ts:2031-2066`), so the invariant holds today. This pins the seam that would silently break it.
Code reviewMy independent proposal, written before reading the diff: intercept the supervisor's internal flag in First, I retract my own previous blocker. Last round I filed Since no compiler has run here, I spent this pass on exactly the class of error a compiler would catch, and on the cross-module contracts the intercepts depend on. All of them hold:
Non-blocking, and I am not asking for these in this round — this PR is past the point where the repo's own rule says land Criticals only:
sequenceDiagram
participant P1 as User shell
participant P2 as runCliEntry in cli.ts
participant P3 as background-entry
participant P4 as Supervisor process
participant P5 as PTY host
participant P6 as Worker session
P1->>P2: qwen --bg "audit the release"
P2->>P2: route is default, scan argv before the strict parser
P2->>P3: readBackgroundPrompt(argv)
P3-->>P2: prompt
P2->>P3: runBackgroundDispatch(prompt, cwd)
P3->>P4: ensureAgentViewSupervisor()
Note over P4: spawned as qwen --internal-agent-view-supervisor,<br/>intercepted by P2 before the strict parser (this PR)
P3->>P4: dispatch RPC (prompt, cwd)
P4->>P5: spawn qwen --internal-agent-view-pty-host launch socket
Note over P5: also intercepted by P2 before the strict parser (this PR)
P5->>P6: spawn qwen --session-id ID --prompt-interactive=PROMPT
P4-->>P3: sessionId
P3-->>P1: Started background session ID, exit 0
Test evidenceThis is the part that decides the verdict, so let me be blunt about what exists. The head commit
The three green rows are TUI-rendering gates. They do not import What we have instead is your own report: 125/125 across That is also, incidentally, how my false blocker survived a round — there was no compiler output for either of us to check it against. Sandboxed verification would settle this: The cheaper structural fix, and the one I would do first: land #10942 and retarget this to Not verified, with reasons: typecheck and build (no CI on this base; I do not execute PR-derived code on an unattended run); all five end-to-end steps in the Test Plan (needs a real build); the 中文说明代码审查我在读 diff 之前的独立方案是：在 首先，我撤回我上一轮的 blocker。 上一轮我提交了 由于这里没有编译器跑过，本轮我把精力集中在「编译器会抓到的那类错误」以及各个拦截所依赖的跨模块契约上。它们全部成立：
以下为非阻断项，本轮我不要求修改 —— 这个 PR 已经过了仓库规则所说「只落 Critical」的轮次：
（时序图见上方英文部分，此处不重复。） 测试证据这是决定结论的部分，所以我直说现有的东西。 head commit （CI 表格见上方英文部分。三个绿色行是 TUI 渲染门禁，它们不引入 我们手上有的是你自己的报告：在此 head 上 顺便说，这也正是我那个错误 blocker 能存活一轮的原因 —— 我们俩都没有编译器输出可以对照。 沙箱验证可以定这件事： 更便宜、也是我建议先做的结构性修复：先合 #10942，然后把本 PR 重定向到 未验证项及原因：类型检查与构建（此 base 上无 CI；无人值守运行中我不执行 PR 派生代码）；Test Plan 中全部五个端到端步骤（需要真实构建）；上文提到的 — Qwen Code · qwen3.8-max-2026-09-02 Reviewed at |
|
Confidence: 3/5 — I found no defect in this diff and I disprove my own previous blocker, but 486 lines of new production TypeScript have never been type-checked by any machine, and I am not willing to be the first thing that certifies them. Stepping back. The design is right, and I mean that specifically rather than as a courtesy: routing through the I went looking for the failure mode I most expected — a So why not approve? Because of what this branch has never been through. There is an awkward consequence I want to name rather than quietly resolve. The Two asks, in the order I would do them:
For the record on round count: this is round seven-ish, well past the point where this repo says land Criticals only. I have none. The three Suggestions in Stage 2 — the ⏸️ Deferring rather than approving. One note on the escalation itself: the deterministic maintainer resolver came back empty, and I am not going to invent a name. No area in 中文说明Confidence: 3/5 —— 我在这个 diff 里没有找到缺陷，也推翻了我自己上一轮的 blocker，但 486 行新的生产 TypeScript 从未被任何机器做过类型检查，我不愿意成为第一个为它背书的东西。 退一步看整体。方案是对的，我说的是具体意义上的对，不是客套：走 我去找了我最预期的失效模式 —— 一次 那为什么不 approve？因为这个分支从未经受过某些东西。 有一个尴尬的后果我想点明，而不是悄悄处理掉。这个 commit 上的 两个请求，按我会做的顺序：
关于轮次，留个记录：这已是第七轮左右，远超本仓库所说「只落 Critical」的节点。我没有 Critical。Stage 2 里的三条 Suggestion —— ⏸️ 选择延后而非批准。关于升级本身要说明一点：确定性的维护者解析器返回为空，而我不打算编造一个名字。 — Qwen Code · qwen3.8-max-2026-09-02 Reviewed at |
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Needs some rethinking — see my notes above. 🙏
@yiliang114 Three blocking items, all in the entry: the two argv intercepts sit above resolveBootstrapRoute and above the guard-token scrub, so qwen --bg --help and qwen --version --bg now exit 1 instead of printing help/version, qwen sessions ps --bg dispatches a background agent with the prompt "sessions ps" instead of running the subcommand, and both routes spawn children before QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN is deleted; valueTakingFlags() re-derives cli.ts's existing VALUE_FLAGS with a weaker predicate that misses inline-registered and array-valued options, leaking their values into the prompt; and background-entry.test.ts:63-68 has an expect(...) with no matcher inside a comma expression, so the case it names is never asserted.
Separately: ci.yml only triggers pull_request on base main / release/**, so this PR has no unit, lint, typecheck or build signal at all. Retargeting to main after #10942 lands turns the gate back on.
中文说明
需要再想一下——见上面的意见。🙏
@yiliang114 三个阻塞项，全在入口：两处 argv 拦截位于 resolveBootstrapRoute 和 guard-token 清理之上，因此 qwen --bg --help 和 qwen --version --bg 现在会以 1 退出而不是打印帮助/版本，qwen sessions ps --bg 会以 "sessions ps" 为 prompt 调度出一个后台 agent 而不是执行子命令，并且两条路由都在 QWEN_CODE_EXTERNAL_TOOL_GUARD_TOKEN 被删除之前就 spawn 了子进程；valueTakingFlags() 用更弱的判据重新推导了 cli.ts 里既有的 VALUE_FLAGS，漏掉内联注册的和 array 类选项，导致它们的值泄漏进 prompt；background-entry.test.ts:63-68 里有一个没有 matcher 的 expect(...) 被包在逗号表达式中，所以它所点名的场景从未被断言。
另外：ci.yml 的 pull_request 只在 base 为 main / release/** 时触发，所以本 PR 完全没有单测、lint、类型检查、构建信号。等 #10942 合并后重定向到 main，门禁才会恢复。
— Qwen Code · qwen3.8-max-2026-09-02
Reviewed at eaa0a23904bd49c687bda1351642d6ca5340c945 · re-run with @qwen-code /triage
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28167 passed.
中文说明
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28167 passed。
— qwen3.8-max via Qwen Code /review (v0.23.0)
Both intercepts ran before resolveBootstrapRoute and before the external Guard token scrub. Move them below both: only the default route reaches them (version keeps its base-parity win, subcommand launches fall through to the parser instead of becoming prompts), and the serve-only credential is deleted before either intercept can spawn the supervisor that would inherit it. The supervisor scan also stops at `--` now, matching the `--bg` scan and the file's other flag scans, so a supervisor flag passed as a prompt word can no longer hijack the launch into serving the shared socket. Adds entry-level runCliEntry tests for both intercepts; each goes red when its intercept block (or the scrub ordering, or the `--` cut) is removed. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtlz4ubdgq
readBackgroundPrompt skipped any other flag and tried to model which flags take values, but the derivation was weaker than the parser it mirrored: array-typed options consume N tokens while the scan consumed one, inline-registered options like --sandbox-session-id sit in no option table, and nothing stopped a value flag from swallowing a flag-shaped next token. Each shape silently dispatched a wrong prompt to an unattended session. Since --bg forwards no flags to the worker anyway, decline the launch and name the flag instead. The error paths now write through the house writeStderrLine, the test captures it (the old no-op mock would have silently broken the stderr assertions on any switch), the word-join test asserts both joins instead of comma-operator-no-op'ing the first, and the reason-not-a-stack test pins the exact one-line output so a switch to error.stack goes red. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtlz4ubdgq
Its closest siblings — the other prompt-carrying launch flags --prompt and --prompt-interactive — both have rows there, and the table is the reference for every way to hand the CLI a prompt at launch. Note the experimental status and the `qwen sessions ps` companion. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtlz4ubdgq
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28179 passed.
Deferred under the convergence posture (round 2, not a blocker) — recorded, not requested in this round:
packages/cli/src/agent-view/background-entry.ts:121 — [probe] D2-1 broken pipe after successful dispatch surfaces as failure (age-rule deferred: code read and unflagged in round 1)packages/cli/src/config/top-level-options.ts:203 — [probe] D2-2 slow-path help omits the --bg row (age-rule deferred: code read and unflagged in round 1)packages/cli/src/agent-view/background-entry.ts:99 — [probe] D2-3 the process.cwd() default of runBackgroundDispatch is untested (age-rule deferred: code read and unflagged in round 1)packages/cli/src/agent-view/background-entry.test.ts:108 — [probe] D2-4 the -- word-collection bound is unpinned (age-rule deferred: code read and unflagged in round 1)
中文说明
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28179 passed。
收敛姿态下延后（第 2 轮，非阻断）——已记录，本轮不要求修改：共 4 条（原文未翻译，列表见上方英文部分）。
— qwen3.8-max via Qwen Code /review (v0.23.0)
…gv scans
Four review findings (R1-14, R1-1 fix-induced, R1-12, R2-16):
R1-14: runBackgroundDispatch discarded the handle
ensureAgentViewSupervisor returns and wrote the store directly via
dispatchAgentViewSession — a pure record with no spawn site, so
`qwen --bg` reported success while the maintenance tick failed the
never-started session moments later. Dispatch through the supervisor
handle's dispatch RPC instead: the one path that records the session
AND launches its worker; its returned sessionId keeps the output
contract. The ready-wait it implies is reflected in the --bg help
text ("returning once the worker has started") instead of the
previous "return immediately".
R1-1 (fix-induced): the --bg gate runs below
normalizeServeFastPathArgv, but the prompt reader still consumed the
unnormalized argv, so a launch carrying the bundled entrypoint as its
first token dispatched that path as the first prompt word. Read from
the normalized argv the gate trusts.
R1-12: readBackgroundPrompt stopped before `--` and rejected dash-led
tokens in prompt slots, so `qwen --bg -- "<prompt>"` always errored
"needs a prompt" and dash-led prompt words were silently dropped.
Collect the tokens after `--` as prompt data (yargs'
positional-after-`--` semantics) while keeping the decline rule when
`--bg` appears only after `--`.
R2-16: the supervisor intercept sliced at `--` but left value slots
open, so `qwen -p --internal-agent-view-supervisor` hijacked the
launch into supervisor mode. Route the decision through hasFlag's
BASE_VALUE_FLAGS/skipOptionValues skips; the sole-token argv the
supervisor spawner produces still routes to the supervisor.
Tests pin each behavior and red when the corresponding fix is
reverted.
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmtmourmvi4
The background dispatch catch hand-rolled error extraction with an
instanceof ternary, so a plain-object rejection with a message printed
"[object Object]" instead of the reason. Use getErrorMessage from
utils/errors.js, which reads the message of error-like objects, and pin
the behavior with a rejecting { message: 'boom' } case.
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Patrol-Run: qwen-pr-closeout/jmtmxfessij
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory.
Deferred under the convergence posture (round 3, not a blocker) — recorded, not requested in this round:
packages/cli/src/cli.test.ts:1108 — [probe] D3-1 entry-level exit-code propagation for a failed --bg dispatch is untested (age-rule deferred: code read and unflagged in round 2)packages/cli/src/agent-view/background-entry.ts:110 — [probe] D3-2 the process.cwd() default of runBackgroundDispatch is untested (round-2 lineage D2-3, age-rule deferred again)packages/cli/src/agent-view/background-entry.test.ts:139 — [probe] D3-3 whitespace-only prompts are unpinned — .trim() does no work in any test (age-rule deferred: code read and unflagged in round 2)packages/cli/src/cli.test.ts:1079 — [probe] D3-4 the --bg half of the guard-token scrub test passes vacuously (age-rule deferred: code read and unflagged in round 2)packages/cli/src/agent-view/background-entry.ts:133 — [probe] D3-5 post-dispatch stdout failure reports a failed launch (round-2 lineage D2-1; fix must guard the stream, e.g. ignoreBrokenPipe())packages/cli/src/agent-view/background-entry.ts:40 — [probe] D3-6 runAsAgentViewSupervisor has zero real-code coverage (age-rule deferred: code read and unflagged in round 2)
Convergence: round 3 posted 10 inline comment(s), 2 of them reported for the first time; the previous round posted 11 (10 new). Findings keep coming back to the same files: packages/cli/src/cli.ts (findings in rounds 1, 2; 1 more now). A cluster that keeps producing siblings usually means the fixes are treating instances of a shared root cause — triaging that cause before the next round, or splitting an independent cluster into its own pull request, tends to end the loop faster than fixing them one at a time. (Observation only — nothing was withheld from this review because of this observation.)
中文说明
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory。
收敛姿态下延后（第 3 轮，非阻断）——已记录，本轮不要求修改：共 6 条（原文未翻译，列表见上方英文部分）。
收敛情况：第 3 轮发布了 10 条行内评论，其中 2 条是首次提出；上一轮发布了 11 条（其中 10 条首次提出）。发现反复回到同一批文件：packages/cli/src/cli.ts（第 1、2 轮已出过发现，本轮又有 1 条）。一个不断再生兄弟发现的簇，通常意味着逐条修复只在处理同一根因的实例——先定位并处理该根因，或把独立的簇拆成单独的 PR，通常比逐条修复更快结束循环。（仅为观察——本轮评审未因此扣留任何内容。）
— qwen3.8-max via Qwen Code /review (v0.23.0)
The --bg bounce set was narrower than the command surface the parser honors: the hooks command's `hook` alias and yargs' builtin `help` both slipped through to a silent dispatch, and the gate read only canonical first words while yargs matches `help` on the LAST positional. Derive the gate set from the registered command names plus their aliases and the help builtin, pin it to the command modules in cli.test.ts, and bounce on a last positional `help` too. The gate also ignored the flag's position, so flag-led prompts whose first word names a command (`qwen --bg sessions cleanup`) bounced to the strict parser and died on 'Unknown argument: bg'. The intercept now fires only on flag-led launches: a positional BEFORE the flag that the parser honors as a command entrance bounces, everything flag-led dispatches. Finally, admit the attached `--bg=<prompt>` spelling: the gate and readBackgroundPrompt both recognize it, matching the CLI's other prompt flags instead of dying in the strict parser. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtmxfessij
The --bg gate scanned with a bare includes-style match, so a `--bg` token sitting in a preceding value-taking flag's value slot — `qwen -p --bg`, a launch whose prompt is the literal string `--bg` — fired the intercept, which then declined the launch for `-p` with advice that cannot work (dropping `-p` leaves a bare `--bg`). The supervisor-flag scan directly above skips exactly these slots (BASE_VALUE_FLAGS unconditionally, derived value flags conditionally), so the two adjacent scans gave opposite answers for the same argv shape. Give backgroundFlagIndex the same skips, keeping its `--` stop and the attached `--bg=<prompt>` recognition, and pin both directions with cli.test.ts cases mirroring the supervisor twin. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtn1pqbuir
No test ever ran runCliEntry([BACKGROUND_FLAG]) — every existing case carrying the flag had other tokens — so the gate's handling of the bare shape, the one the usage message is written for, was load-bearing but unwitnessed. Pin the entry route: the empty prompt reaches runBackgroundDispatch (never the strict parser, which knows no `bg`), main is not called, and the dispatch's exit code propagates. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtn1pqbuir
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Partially reviewed — gaps disclosed.
3 Suggestion-level finding(s) this review confirmed are already reported on this PR and are not repeated:
- runBackgroundDispatch's process.cwd() default is untested — already reported (round-2 deferral D2-3, re-deferred as D3-2 in round 3)
- whitespace-only prompts unpinned (.trim() does no work in any test) — already reported (round-3 deferral D3-3)
- --bg silently discards piped stdin — already reported (R1-15 thread, comment 3927927680; verified real at head, deferred by the author)
Not reviewed: issue-fidelity — closing-issue discovery unavailable (gh 2.45.0 < required 2.72.0); ruled from the PR's Linked-Issues text (no closes references) and the motivating-incident replay.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory.
Convergence: round 4 posted 11 inline comment(s), 9 of them reported for the first time; the previous round posted 10 (2 new). Findings keep coming back to the same files: packages/cli/src/cli.ts (findings in rounds 2, 3; 6 more now); packages/cli/src/agent-view/background-entry.ts (findings in round 2; 3 more now). The rate of new findings is not falling. A cluster that keeps producing siblings usually means the fixes are treating instances of a shared root cause — triaging that cause before the next round, or splitting an independent cluster into its own pull request, tends to end the loop faster than fixing them one at a time. Batching the remaining fixes and verifying them before the next push, or dropping this PR's reviews to --severity-floor critical, keeps the loop from re-deriving the same set. (Observation only — nothing was withheld from this review because of this observation.)
中文说明
仅完成部分审查，审查缺口已披露。
本轮确认的 3 条建议级发现已在 PR 上报告过，不再重复发布（列表见上方英文部分）。
未审查（原文为英文）：issue-fidelity — closing-issue discovery unavailable (gh 2.45.0 < required 2.72.0); ruled from the PR's Linked-Issues text (no closes references) and the motivating-incident replay.
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory。
收敛情况：第 4 轮发布了 11 条行内评论，其中 9 条是首次提出；上一轮发布了 10 条（其中 2 条首次提出）。发现反复回到同一批文件：packages/cli/src/cli.ts（第 2、3 轮已出过发现，本轮又有 6 条）；packages/cli/src/agent-view/background-entry.ts（第 2 轮已出过发现，本轮又有 3 条）。新发现的产出速度没有下降。一个不断再生兄弟发现的簇，通常意味着逐条修复只在处理同一根因的实例——先定位并处理该根因，或把独立的簇拆成单独的 PR，通常比逐条修复更快结束循环。把剩余修复攒成一批、验证后再推送，或将本 PR 的评审降到 --severity-floor critical，可以避免循环反复推导同一组发现。（仅为观察——本轮评审未因此扣留任何内容。）
— qwen3.8-max via Qwen Code /review (v0.23.0)
The supervisor's dispatch RPC spawns each session's PTY host as `node <entry> --internal-agent-view-pty-host <launchPath> <socketPath>`, but nothing parsed that flag: the child re-entered runCliEntry, fell through to the strict parser, and exited on 'Unknown arguments' — waitForSpawnedPtyHost rejected and every `qwen --bg "<prompt>"` failed to start a session. Add the third entry intercept beside the supervisor one: a value-slot- aware scan (hasFactored into a flagIndex the hasFlag check reuses) reads the launchPath/socketPath tokens that follow the flag and runs runAgentViewPtyHostProcess before the parser. The flag's constant moves to entry-flags.ts so the entry never imports the heavy pty-host runtime on an ordinary launch; a spawn lacking the two tokens falls through to the parser, which rejects the flag. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnaadh9j8
The standalone `lastPositionalArg(argv) === HELP_COMMAND` term bounced flag-led launches too: `qwen --bg help` fell through to the strict parser and exited 1 on 'Unknown argument: bg', and `qwen --bg write help` printed top-level help with exit 0 and no session — while the gate's pinned contract says every positional after the flag is prompt data (the attached `qwen --bg=help` spelling dispatched all along). Fold the help-word term into the positional-led condition so it serves only launches the parser owns: a positional before the flag that yargs reads as a command entrance — including `help`, which yargs matches on the LAST positional — still bounces (pinned by the existing help-builtin test), and flag-led prompts ending in `help` now dispatch. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnaadh9j8
The success-path stdout writes sat inside the try whose catch reports a launch failure, with no broken-pipe protection anywhere on the path. A reader that left before the writes arrived — `qwen --bg "..." | true`, a CI step closing the pipe during the multi-second dispatch RPC — hit the closed pipe after the session was already recorded and spawned: the async EPIPE crashed the process despite exitCode 0, and the sync throw landed in the catch and printed the factually wrong 'Could not start a background session: write EPIPE'. A wrapping script keying on the exit code then retried and started a second agent on the same prompt. Call ignoreBrokenPipe() once at the top of runBackgroundDispatch (the cost-ledger/nonInteractiveCli convention) and move the two success writes out of the launch try, switched to writeStdoutLineSafe so a dead reader cannot throw. Failure reporting stays loud. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnaadh9j8
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
4 Suggestion-level finding(s) this review confirmed are already reported on this PR and are not repeated:
- runAsAgentViewSupervisor has zero real-code coverage — already reported (round-3 deferral D3-6)
- the --bg half of the guard-token scrub test passes vacuously — already reported (round-3 deferral D3-4)
- whitespace-only prompts unpinned (.trim() does no work in any test) — already reported (round-3 deferral D3-3)
- runBackgroundDispatch's default cwd (process.cwd()) unexercised — already reported (round-2 deferral D2-3, re-deferred D3-2 in round 3)
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28199 passed.
Deferred under the convergence posture (round 5, not a blocker) — recorded, not requested in this round:
packages/cli/src/agent-view/background-entry.test.ts:117 — [probe] the decline-any-other-flag contract is only pinned for flags after --bg; position-invariant decline unwitnessed (age-rule deferred: code read and unflagged in round 4)packages/cli/src/agent-view/background-entry.test.ts:104 — [probe] the attached --bg=<prompt> form is pinned for non-empty values only; empty attached value unwitnessed (age-rule deferred: code read and unflagged in round 4)packages/cli/src/agent-view/background-entry.test.ts:85 — [probe] position-invariant detection (prompt words before --bg) is pinned by no test (age-rule deferred: code read and unflagged in round 4)packages/cli/src/cli.test.ts:1342 — [probe] the command-surface pin test reads mcpCommand through the vi.mock stub, not the real module (age-rule deferred: code read and unflagged in round 4)
Convergence: round 5 posted 12 inline comment(s), 4 of them reported for the first time; the previous round posted 11 (9 new). Findings keep coming back to the same files: packages/cli/src/cli.ts (findings in rounds 2, 4; 2 more now); packages/cli/src/agent-view/background-entry.ts (findings in rounds 2, 4; 1 more now). A cluster that keeps producing siblings usually means the fixes are treating instances of a shared root cause — triaging that cause before the next round, or splitting an independent cluster into its own pull request, tends to end the loop faster than fixing them one at a time. (Observation only — nothing was withheld from this review because of this observation.)
中文说明
本轮确认的 4 条建议级发现已在 PR 上报告过，不再重复发布（列表见上方英文部分）。
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory; 455 tests passing — this review observed 28199 passed。
收敛姿态下延后（第 5 轮，非阻断）——已记录，本轮不要求修改：共 4 条（原文未翻译，列表见上方英文部分）。
收敛情况：第 5 轮发布了 12 条行内评论，其中 4 条是首次提出；上一轮发布了 11 条（其中 9 条首次提出）。发现反复回到同一批文件：packages/cli/src/cli.ts（第 2、4 轮已出过发现，本轮又有 2 条）；packages/cli/src/agent-view/background-entry.ts（第 2、4 轮已出过发现，本轮又有 1 条）。一个不断再生兄弟发现的簇，通常意味着逐条修复只在处理同一根因的实例——先定位并处理该根因，或把独立的簇拆成单独的 PR，通常比逐条修复更快结束循环。（仅为观察——本轮评审未因此扣留任何内容。）
— qwen3.8-max via Qwen Code /review (v0.23.0)
`qwen --help --bg=audit` (and `-h`, either order) demoted to the default route because the attached spelling is outside the fast path's known-safe grammar, and the --bg gate then declined the launch with exit 1 — advice that turns the help request into a dispatched session once followed. Base rendered help for every ordering. Treat a `--help`/`-h` before `--` as parser-owned and let the launch fall through to the full parser, which renders help even with the unregistered `--bg=<prompt>`; the value-slot-aware scan keeps a help token sitting in a value slot as data. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtngpuscjl
The only help-shaped gate test (['help', '--bg']) is bounced entirely by the first-positional clause, leaving the lastPositionalArg clause unwitnessed: mutating its comparison still passed the suite. Pin the clause with a positional-led launch whose last positional is `help` and whose first is not a command entrance. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtngpuscjl
The decline treats every dash-led token as a flag to drop and never mentions `--` — the only spelling that keeps a dash-led word as prompt data. `qwen --bg -repro steps` advised bare `--bg`, which lands on the empty-prompt usage error. Point the advice at the working spelling, already test-pinned in background-entry.test.ts. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtngpuscjl
The dispatch RPC blocks until the worker starts (30 s operation timeout plus a 15 s ready wait, plus a possible cold supervisor start), so both new doc pages promised a return they do not deliver; a script following them read 15-60 s of silence as a hang. Align both lines with the wording the bg help text already uses. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtngpuscjl
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtngpuscjl
An internal supervisor/pty-host flag typed as a --bg prompt word matched the intercept scans before the --bg gate ran, hijacking the launch into a daemon instead of being declined by name: `qwen --bg audit --internal-agent-view-supervisor` bound the well-known socket and served silently until killed. Compute the bg flag's presence first and run both intercepts only in its absence; spawner-produced argv never carries --bg, so legitimate spawns keep routing. New red-proof tests flip from hijack to the named decline, and the pty-host missing-token fall-through gets its own witnesses. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnn5c4cjw
The catch around the dispatch RPC conflated a client-side timeout — the supervisor keeps recording and launching the session after the client cap (LONG_AGENT_VIEW_OPERATION_TIMEOUT_MS), a store I/O stall can push the handler past it — with a genuine launch failure, certifying "Could not start a background session" and exit 1 while a session may be starting. A wrapper keyed on the exit code would retry and start a second agent on the same prompt. Branch on the client error's timeout code: report the launch as still starting, point at `qwen sessions ps`, and return exit code 2 a wrapper can treat as "do not retry". Red-proof test rejects the dispatch with a code:'timeout' error and pins the new sentence and exit code. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnn5c4cjw
The "installs broken-pipe protection before dispatching" test asserted only a call count, so its name's ordering was unwitnessed: moving ignoreBrokenPipe() below the dispatch call kept the suite green while the protection no longer covered the multi-second dispatch window. Assert the count inside the dispatch mock so the mutation reds (verified: expected +0 to be 1). Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmtnn5c4cjw
|
@qwen-code /triage |
|
Sandboxed verification: ❌ not passed — blocked (agent verdict) - workflow run Ran the PR in an isolated, token-free container: A/B against the base build, mock-free harness assertions, targeted gates. Advisory evidence for human reviewers — not a review, an approval, or a CI check. Scripted assertions: 70 passed · 2 failed · 72 total Flakiness gate: ✅ 3 changed test file(s) x 5 identical rounds, no divergence 中文 — 判定：❌ 不通过 · 阻塞（agent 判定）沙箱验证在隔离、无凭证的容器中执行了该 PR 的代码（与 base 构建 A/B 对照、无 mock harness 断言、定向门禁）。仅作为评审证据，不构成评审、批准或 CI 检查。 脚本断言：70 通过 · 2 失败 · 72 总计 抖动门：✅ 3 changed test file(s) x 5 identical rounds, no divergence Verification reportPR #10943 Deep Verification —
|
| # | argv | base-src (control) | head — authoritative | head-src |
|---|---|---|---|---|
| 1 | --bg "list the files in this directory" |
exit 1, 5.7 s — Unknown argument: bg |
dist: exit 1, 10.2 s — Could not start a background session: Agent View PTY host did not become ready. Job dd0e77c4: sessionState=failed, errorCode=pty_launch_failed, capabilities=[] |
exit 1, 6.9 s — Could not start … supervisor exited before becoming ready with code 1 |
| 2 | --internal-agent-view-supervisor |
exit 1, 6.6 s — Unknown arguments: internal-agent-view-supervisor, internalAgentViewSupervisor |
(dist not run) | exit 0, 30.16 s — served the entire 30 s window, then died to the harness kill |
| 3 | --bg (bare) |
exit 1, 7.6 s — Unknown argument: bg |
— | exit 1, 5.3 s — qwen --bg needs a prompt: qwen --bg "review the failing release" |
| 4 | -p hello -- --bg |
exit 1, 12.9 s — No auth type is selected… |
— | exit 1, 10.5 s — byte-identical No auth type is selected… |
| 5 | --bg --model qwen3-coder-plus "…" |
exit 1, 9.1 s — Unknown argument: bg |
— | exit 1, 7.6 s — qwen --bg runs only the prompt and does not honor --model. Re-run without it, or pass prompt words after --. |
| 6 | --bg audit --internal-agent-view-supervisor |
exit 1, 8.2 s — Unknown arguments: bg, internal-agent-view-supervisor, … |
— | exit 1, 6.5 s — does not honor --internal-agent-view-supervisor (declined as prompt data, did not hijack into a daemon) |
| 7 | -p --bg (value slot) |
exit 1, 10.6 s — Unknown argument: bg |
— | exit 1, 5.3 s — Unknown argument: bg (identical to base) |
| 8 | --bg write help |
exit 0, 9.6 s — printed top-level help | — | exit 1, 7.1 s — dispatch attempted (flag-led prompt not bounced to help) |
Secondary claim 1 is proven. Cell 2 is unambiguous: base dies on the strict parser in 6.6 s; head survives the whole 30 s window and exits 0 only when the harness kills it (the supervisor installs a graceful SIGTERM handler, so the observable is duration-against-window, not exit status). My first oracle for this cell was wrong — it expected spawnSync's signal field to mark the kill — and I corrected it before reporting. This half of the PR is load-bearing and correct.
Secondary claim 2 is proven. Cells 3–8 plus the sibling sweep below show the gate declining by name, honoring --, staying value-slot-aware, and — cell 6 — refusing to let an internal flag typed as a prompt word spawn a daemon. Cell 4 is an A/A parity result: both arms produce the identical ordinary-path error, so the -- escape introduces no behavior change.
The central claim fails. Check 1f asserts the PR's own documented outcome (Reviewer Test Plan step 1, the "After" evidence block, and the new docs/users/features/commands.md sample): prints Started background session <id>, exit 0. It never does. Check 1h is the runtime census of the event the dispatch blocks on: across all 17 cells exactly 1 session was recorded and 0 workers reported ready (capabilities was [] in every case).
Why the two head arms disagree, and which one to believe
head-src reports supervisor exited before becoming ready with code 1 while head-dist gets further (PTY host did not become ready). The cause is my harness, not the PR: the supervisor is spawned as node <entrypoint> --internal-agent-view-supervisor using getCurrentQwenCliEntrypoint(), and in the tsx arm that entrypoint is a .ts file which plain node cannot load — so the spawned child dies at once. head-dist is the authoritative production cell and is the one the central-claim assertion reads. Running three arms is what exposed this; a two-arm A/B would have silently reported the wrong stage.
This does yield one small real observation, recorded as Finding 4 below.
Findings
1. Critical / blocker — qwen --bg can never print its documented success line
runBackgroundDispatch awaits supervisor.dispatch(prompt, cwd). On the production path that RPC calls waitForWorkerReadyIfNeeded, which rejects after DEFAULT_WORKER_READY_TIMEOUT_MS = 15_000 (supervisor-process.ts:132) with Agent View worker <id> did not report ready before timeout. Nothing in the tree ever emits that event.
Witness: 03-ready-census-and-mutation.png. Text of record: raw/census-and-mutation.txt.
Static census, proven two ways:
- The only gateway to the
workerEventRPC issendAgentViewWorkerEvent(worker-sideband.ts:113). It has exactly two call sites in the whole tree:type: 'state'(line 204) andtype: 'heartbeat'(line 244).resolvePendingWorkerReadyis reached only insideif (event.type === 'ready')(supervisor-process.ts:881-883), so nostateorheartbeatcan ever satisfy the wait. - In the shipped
dist, the sideband's entire public API (sendAgentViewWorkerEvent,reportAgentViewWorkerState,startAgentViewWorkerHeartbeat) has zero callers outsideworker-sideband.jsitself. No UI, startup, or pty-host module imports it. The stringtype: 'ready'appears indist/src/agent-view/only inworker-sideband.d.tsandprotocol.d.ts(the declared event type) and in.test.jsfixtures — never in production code.
Runtime corroboration, two independent sessions:
- A/B
head-distcell, sessiondd0e77c4:sessionState=failed,processState=exited,errorCode=pty_launch_failed,capabilities=[]. - An earlier standalone run, session
ed6eafc0(artifacts since deleted, values quoted from the observation):lastError.code = "pty_launch_failed",lastError.message = "Agent View worker ed6eafc0-… did not report ready before timeout.",activity.jsoncapabilities: [].
The two runs stalled at successive gates — the earlier one got past PTY-host readiness and died waiting for the worker; the A/B cell died at the host. I want to be precise about what that means: the worker-ready gap is structural (no producer exists, so no environment can satisfy it), while host readiness is timing-sensitive (it succeeded in one run and not the other, under a loaded container). Only the first is the blocker.
The prompt never reaches the worker either. supervisor-process.ts:467 sets promptInArgv: !shouldWaitForWorkerReady(this.options), and shouldWaitForWorkerReady is options.waitForWorkerReady ?? !options.launchPtyHost (line 3507) — true in production, where no launchPtyHost is injected. So production both waits for ready and keeps the prompt out of argv, carrying it as initialPrompt in the launch record to be typed into the pty after a ready that never arrives. The two settings are complementary by design; the missing piece is purely the worker-side emitter.
Reproduce (any clean Linux checkout of this head, built):
QWEN_HOME=$(mktemp -d)/.qwen node packages/cli/dist/index.js --bg "list the files in this directory"
# exit 1, after ~15-23 s:
# Could not start a background session: Agent View PTY host did not become ready.
# (or: ... Agent View worker <id> did not report ready before timeout.)Attribution — named separately, so the author is not blamed for the policy. The missing emitter is in worker-sideband.ts and the interactive startup, none of which this PR touches (the diff is confined to cli.ts, entry-flags.ts, background-entry.ts, 7 lines of pty-host-process.ts, 4 of supervisor-runner.ts, top-level-options.ts, docs and tests). The gap is pre-existing in the subsystem from #7799/#7800/#7801/#9986. This PR's contribution is to make that dead wait reachable from a user-facing flag for the first time, and to document a happy path that cannot occur. The PR's own entry code is correct as far as it goes — cells 1b/1c/1d/1g prove the wire is connected, the supervisor is spawned and serves, and the session is recorded.
Why nothing caught it: every happy-path test mocks exactly this boundary. background-entry.test.ts:212 does supervisorDispatch.mockResolvedValue({ sessionId: 'sess-rpc', state: 'created' }) and asserts the id is printed. That is a correct test of the entry's contract and says nothing about whether a real dispatch can ever return. Combined with the author's disclosed inability to build, the mock is the whole reason an unreachable outcome shipped as documented behavior.
Candidate directions — <b>not implemented and not measured</b>
I did not apply or drive either of these, so treat them as pointers, not as a verified patch:
- Land the worker-side
readyemission (wiresendAgentViewWorkerEvent({ type: 'ready', … })into interactive startup once the worker is up and connected to the sideband). This is the fix that makes the subsystem whole, and it belongs to the subsystem's owners rather than to this PR. - Or, for this path only, stop waiting: constructing the supervisor with
waitForWorkerReady: falsemakespromptInArgvtrue, so the prompt rides in argv as--prompt-interactive=<prompt>anddispatchreturns a session id immediately — the branch the PR description already assumed was taken, and the behavior the docs promise. This changes what "started" means (the worker is spawned but not confirmed up), so it is a product decision, not a one-line repair.
Either way the fixture that would pin it is the one that does not exist: an integration test that drives a real supervisor and worker and asserts Started background session on stdout. The suite is green today with the feature structurally broken, which is the unpinned axis.
2. Suggestion — the new user docs promise an outcome that cannot occur
docs/users/features/commands.md adds a qwen --bg "<prompt>" section stating it "returns once the worker has started, printing the session id", with a sample transcript showing # Started background session 0f8e...c31. docs/users/configuration/settings.md adds a matching --bg row. Both describe the unreachable path from Finding 1. Shipping user-facing docs for a command that always exits 1 costs the next reader more than omitting them: the documented transcript is exactly what a user will compare their failure against.
3. Suggestion (bounded) — the real failure lands on the "retry me" exit code
The PR reasons carefully about not certifying failure when a session may still be coming up: a client-side dispatch timeout returns exit 2 with The background session may still be starting, explicitly so "a wrapper keyed on the exit code must not retry it." But the failure mode actually observed in production — session recorded, PTY host launched, ready never arriving — surfaces as pty_launch_failed through the generic catch and returns exit 1 with Could not start a background session, i.e. the code a wrapper reads as safe to retry, even though a session row was written.
What I disproved, so this is not overclaimed: I checked for the sharpest consequence and it did not hold. After the failure the supervisor had torn the session down (processState=exited, sessions/ empty) and ps showed no lingering worker — only the supervisor itself. So a retry would not have started a second agent on the same prompt in the runs I observed. The residual issue is the mismatch between the message ("Could not start") and the store's record (a session was created and a worker was spawned), not a demonstrated duplicate-agent hazard.
4. Note — a tsx/dev launch of --bg cannot spawn its supervisor
The supervisor and PTY host are spawned as plain node <getCurrentQwenCliEntrypoint()> …. When the CLI is run from TypeScript source (npm run dev, tsx), that entrypoint is a .ts file and the spawned child exits 1 — observed directly as the head-src arm's supervisor exited before becoming ready with code 1. Consequence: --bg is unusable in dev mode, so a contributor cannot reproduce or debug this feature without a full build. Low severity, and invisible to the unit tests because they mock the supervisor.
Corrections to the PR description
Labelled as corrections to the text, not requests to change code.
- The worker is not launched with
--prompt-interactive=<prompt>on this path. The description states a background worker is launched asqwen --session-id <id> --prompt-interactive=<prompt>, citingsupervisor-dispatch.ts:196.buildNativeWorkerArgvdoes build that argv, but it is called asbuildNativeWorkerArgv(sessionId, options.promptInArgv === false ? undefined : prompt)(line 77-80), and production setspromptInArgv: !shouldWaitForWorkerReady(...)= false. The launch record I captured confirms it:argv: ["node", "…/dist/index.js", "--session-id", "ed6eafc0-…"]with the prompt carried separately as"initialPrompt": "list the files in this directory". The downstream conclusion still holds — it remains a full interactive session, so the cross-session-messaging consequence is unaffected — but the cited mechanism is the branch not taken, and that branch is the one Finding 1 turns on. - "the merged code runs end to end for the first time" is not what happens. The entry wires are genuinely connected and the supervisor genuinely serves (cell 2). But the dispatch runs half way end to end and then times out; no session ever reaches a usable state. The accurate claim is that this PR makes the subsystem reachable and exposes that its worker half was never wired.
- The stated test counts are stale. The description reports "19 files, 455 tests passing, 13 of them new in
background-entry.test.ts". Measured at the verified head: 19 files, 513 tests, and 18it()blocks inbackground-entry.test.ts. The shape of the claim is right; the numbers predate the head under review.
What this round confirmed working
Recorded so the blocker is not read as a wholesale rejection — the PR's own code held up everywhere it was probed:
- Sibling sweep, 46/46 pass (
02-prompt-reader-sibling-sweep.png,raw/sibling-sweep.txt). Run against the compileddist, no mocks. Beyond the shapes the PR pins: short value flags detached (-m x) and attached (-m=x), negations (--no-color), short clusters (-dm), lookalikes (---bg,--bga,--bgxcorrectly not the flag), repeated--bg, empty attached--bg=, dash-led attached value--bg=-repro, whitespace-only, astral/CJK,=inside a word,--first, data on both sides of--, and a double separator. Plus a scaling ladder at 500/2 000/5 000/20 000 prompt words: 0.07 / 0.25 / 0.71 / 23.07 ms — linear, no blowup. (argv is the caller's own input, not an outsider-writes surface, so this was a cheap confirmation rather than a security probe.) - Route reachability, 12/12 of the sweep's routing probes. The intercepts run only on
route === 'default', so a routing sibling could bypass the gate silently. Verified:--bg x,--bg=x,--bg write help, both internal flags, andsessions --bgall reachdefault;--bg --helpcorrectly routes tohelpand-v --bgtoversion, both bypassing the intercept by design.TOP_LEVEL_COMMAND_NAMEScontainssessions,help, and thehookalias. - Typecheck passes — the gate the author explicitly could not run.
npx tsc --noEmit -p packages/cli/tsconfig.json, exit 0 in ~4 m 12 s. Proven live rather than assumed green:--listFilesOnlyshows 4 388 files in the project, 2 197 underpackages/cli/src, and all six changed.tsfiles (cli.ts,agent-view/background-entry.ts,agent-view/entry-flags.ts,agent-view/pty-host-process.ts,agent-view/supervisor-runner.ts,config/top-level-options.ts) are in the checked set. The sametscreported 66 errors against my base control tree earlier in this round, so it demonstrably fails in this repo. - The new tests are not vacuous. Mutating one hunk —
return -1;as the first statement of the PR's own newbackgroundFlagIndex— turns 11 of 108 tests incli.test.tsred, and the failures are the intended behavioral mismatch, not import or compile errors:expected "spy" to be called with arguments: [ 'audit' ] / Number of calls: 0, and for the bounce casesexpected "spy" to not be called at all, but actually been called 1 times. Positive control in the same file: unmutated, the suite is 513/513 green.cli.tswas restored byte-exact afterwards (git diff --stat HEAD -- packages/cli/src/cli.ts→ 0 lines).
Not covered
- No successful
--bgrun was observed anywhere, so I could not verify the session id format,qwen sessions pslisting a--bgsession (Reviewer Test Plan step 2), or theworking/waitingstate column. Reviewer Test Plan step 3 (ps aux | grep internal-agent-view-supervisor) was confirmed — cell 2 and a directly inspected/proc/<pid>showed the supervisor serving. Steps 4 and 5 were confirmed (cells 3 and 4). - This container has no configured CLI auth type (
No auth type is selected…, cell 4). I state it because it limits what an end-to-end success could have shown here — but Finding 1 does not depend on it: the census shows no producer exists for the event the dispatch blocks on, so no environment and no credential state can satisfy that wait. - The cross-session-messaging consequence the description names (
list_agentsvisibility,send_messageaddressability underagents.crossSessionMessaging) was not exercised — it requires a session that reaches a live state. - Per-commit attribution is out of reach. The checkout is depth 2:
git rev-list HEAD^1..HEAD^2yields 1 commit while the snapshot'scommitsarray holds 23 (including two merge commits fromfeat/agent-view-first-consumer), andgit rev-parse --is-shallow-repositoryistrue. I verified the aggregateHEAD^1..HEADdiff only. The 23 commit headlines suggest several gates were fixed iteratively ("close the --bg gate's missed entrances", "make the --bg gate value-slot-aware like its twin scan"); I could not attribute any behavior to an individual commit, and I present no per-commit table. - The suggested directions in Finding 1 were not implemented or measured — no hostile/benign fixture comparison and no suite counts for a patched build. They are labelled as candidates for that reason.
- The broken-pipe path was not exercised end-to-end.
ignoreBrokenPipe()and the exit-0-on-EPIPE behavior (qwen --bg "…" | true) are pinned by unit tests I did not independently drive, and the dispatch never succeeds anyway, so the success writes are unreachable in practice. - The exit-2 client-timeout branch was not exercised — I could not induce a client-side dispatch timeout distinct from the supervisor's own
pty_launch_failed. - Gates I did not run: ESLint, Prettier, the repo-wide test suite,
npm run buildat head (CI completed it before my clock; I verified the artifact contains the PR's code rather than rebuilding), and all integration tests. No trial merge into currentmain— the base is far behind and this checkout has no network to fetch it, so I could not check whethermainhas touched these files since the merge base. - Windows and macOS untested (the PR marks both N/A).
- Two harness defects of my own are disclosed rather than hidden, because both initially produced numbers that would have been wrong: the base worktree lacked the git-ignored generated file
packages/cli/src/generated/git-commit.ts, so every base cell first crashed withERR_MODULE_NOT_FOUNDbefore reaching the parser (fixed by copying the head tree's generated dir — a cosmetic git stamp that cannot affect argv routing); and the lane exportsFORCE_COLOR, which made the CLI ignoreNO_COLORand wrap the oracle lines in ANSI escapes (fixed by unsetting it). The first A/B run reported 14 pass / 7 fail; the corrected run reported here is 20 pass / 2 fail. An earlier full-suite run also showed 512/513 with one 15 s timeout — that was contention from my own basetscbuild, and the idle re-run is 513/513. See below. - A base
tsc --buildcontrol was attempted and abandoned. Building the base worktree failed with 66 type errors (ajvresolving to the hoisted 6.15.0 instead ofpackages/core's nested 8.20.0,ignorenot callable) because a fresh worktree lacks the per-package nestednode_modules. I linked them from the head tree, which fixed resolution, but chose the tsx source arm instead as cheaper and symmetric. These errors are artifacts of my control tree, not PR defects —packages/corehas 0 files in this PR's diff.
A note on the one test that timed out, and why it is not a finding
The new test pins the --bg gate's command surface to the registered command modules imports nine command modules inside a single test, so it is sensitive to the per-test ceiling. Measured twice:
| condition | test duration | vitest testTimeout |
outcome |
|---|---|---|---|
| idle machine | 6 915 ms | 15 000 ms | pass |
my own base tsc --build running concurrently |
15 300 ms | 15 000 ms | timed out |
The contended run crossed the threshold, which is why the first full-suite run reported 512/513. This is my contamination, not a defect: the idle margin is 2.2×. It is also already handled by the repo's own policy — packages/cli/vitest.config.ts:162 sets testTimeout to 60 s on ecs-qwen-* runners and 15 s elsewhere, with a comment about I/O-bound tests blowing the ceiling "purely under CI contention". RUNNER_NAME is unset in this verify container, so the 15 s branch applied here. Worth knowing for the lane: a heavily loaded verify run could time this test out at 15 s even though project CI gives it 60 s.
Methodology
Environment: the CI verify container (node:22-bookworm, Node v22.23.2, npm 10.9.8, 64 cores), working tree at refs/pull/10943/merge depth 2, with npm ci and npm run build already completed at HEAD. I confirmed the built artifact actually contains this PR's code before trusting it (Started background session in dist/src/agent-view/background-entry.js, TOP_LEVEL_COMMAND_NAMES in dist/src/cli.js).
Control: git worktree add tmp/base-tree HEAD^1. The PR touches no package.json or package-lock.json (0 files), so reusing the root node_modules is a clean control on dependencies. I asserted the internal workspace links rather than assuming them — readlink -f from inside the base tree resolves @qwen-code/qwen-code-core, sdk, web-templates and acp-bridge into the head tree's packages/*, which is sound only because git diff HEAD^1..HEAD -- packages/core packages/acp-bridge packages/audio-capture packages/sdk-typescript packages/channels is 0 files, making those packages byte-identical between arms. I did not use require.resolve for this: these packages are ESM-only with import-only exports, and it throws ERR_PACKAGE_PATH_NOT_EXPORTED, which reads like a missing module. The base arm runs through tsx (no typecheck, so the control tree's type-resolution noise is irrelevant), and head-src vs head-dist agreement in cell 1 is the check that the loader is not a confound.
Harnesses drove real compiled code, never a stub of the unit under test: ab-entry.mjs spawns real node child processes (17 cells, isolated HOME and QWEN_HOME per cell, model credentials scrubbed so no spawned worker could spend the lane's API key) and reads back the persisted state.json/activity.json as a second oracle independent of stdout; sibling-sweep.mjs imports the compiled dist modules directly; evidence-census.sh re-derives the census and mutation evidence live from the repo and from raw/ab-results.json rather than transcribing it. Every number in assertions.json maps to a scripted comparison that executed: 22 from the A/B, 46 from the sibling sweep, 2 from the mutation matrix, 2 from the gates (typecheck exit 0; suite 513/513). The vitest suite's own 513 test assertions are reported as a gate, not double-counted into the harness total. fail: 2 counts only unexpected outcomes — the four base control cells are assertions that base fails, and they passed.
One environment trap is worth recording for the next round: Storage.getGlobalQwenDir() honors QWEN_HOME before os.homedir(), and this lane exports QWEN_HOME=/__w/_temp/verify-agent-home/.qwen. My first probe set only HOME, so the --bg run wrote its daemon socket and job store into the lane's live home and left a detached supervisor behind. I killed that supervisor, removed the daemon/ and jobs/ directories it created, and pinned QWEN_HOME per cell thereafter. All scratch state lives under tmp/pr10943-verify-20260905-045049/; the base worktree was removed and the working tree verified byte-exact against HEAD.
Raw logs: raw/ab-entry.log, raw/ab-results.json, raw/ab-cells.txt, raw/sibling-sweep.txt, raw/census-and-mutation.txt, raw/gate-author-suite-idle.log, raw/gate-author-suite.log, raw/gate-pin-test-idle.log, raw/gate-pin-test-raised-timeout.log, raw/typecheck-cli.log, raw/mutation-bg-gate-disabled.log, raw/pr.diff, raw/base-build.log.
Flakiness gate log
rounds=5 files=3 skipped=0
file packages/cli/src/agent-view/background-entry.test.ts: (cd packages/cli) npx --no-install vitest run ./src/agent-view/background-entry.test.ts
file packages/cli/src/agent-view/supervisor-dispatch.test.ts: (cd packages/cli) npx --no-install vitest run ./src/agent-view/supervisor-dispatch.test.ts
file packages/cli/src/cli.test.ts: (cd packages/cli) npx --no-install vitest run ./src/cli.test.ts
per-file results (P=pass F=fail I=infra-exit, one letter per run):
packages/cli/src/agent-view/background-entry.test.ts: PPPPP
packages/cli/src/agent-view/supervisor-dispatch.test.ts: PPPPP
packages/cli/src/cli.test.ts: PPPPP
verdict: pass
summary: 3 changed test file(s) x 5 identical rounds, no divergence
--- per-invocation detail (full copy in the artifact) ---
round 1 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 1 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 1 · packages/cli/src/cli.test.ts: P (exit 0)
round 2 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 2 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 2 · packages/cli/src/cli.test.ts: P (exit 0)
round 3 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 3 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 3 · packages/cli/src/cli.test.ts: P (exit 0)
round 4 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 4 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 4 · packages/cli/src/cli.test.ts: P (exit 0)
round 5 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 5 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 5 · packages/cli/src/cli.test.ts: P (exit 0)
Evidence images
Harness scripts and raw logs are in the workflow run artifacts (7-day retention).
— Qwen Code · sandboxed verification
|
Qwen Code review did not complete successfully. The review pipeline failed before a review could be posted. A transient error is retried automatically; if you are seeing this, retry with |
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Needs one fix before this can merge — see my notes above. 🙏
@yiliang114 A single blocker at aefdf88f, and it is total rather than partial:
packages/cli/src/agent-view/background-entry.ts:36 imports from '../utils/stdio-helpers.js'. That file does not exist at this commit, at your base branch, or at main — the module is packages/cli/src/utils/stdioHelpers.ts (camelCase, allowlisted as legacy at eslint.legacy-filenames.mjs:353), and all three symbols are in it. So: TS2307 on build and typecheck; ERR_MODULE_NOT_FOUND at runtime on both wires, since runAsAgentViewSupervisor shares the module with the dispatch path; and all 17 tests in background-entry.test.ts plus the 31 intercept tests in cli.test.ts (whose mock factory calls importOriginal()) cannot load. Nothing on this branch currently runs.
Fix: '../utils/stdioHelpers.js'.
This is not a design objection — the rework since my last pass resolved both blocking findings properly, by subtraction, and the test surface is now the strongest part of the PR. It survived only because ci.yml fires pull_request on main and release/**, so no compiler has looked at any of the seven pushes on this stacked base. Please get one npx tsc --noEmit run, or land #10942 and retarget this to main so the real gate turns on.
Per this repo's rule on review rounds, I am blocking on this one Critical only; the two remaining Suggestions (the roster-pair assertion, and the "two wires" wording that should say three intercepts) are deferred in the Stage 2 comment and should not hold the PR up.
— Qwen Code · qwen3.8-max-2026-09-02
|
The triage blocker does not reproduce at this head (
Nothing on this branch is broken by this import; the cited file name simply does not appear anywhere in the diff. |
|
@qwen-code /triage |
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
1 Suggestion-level finding(s) this review confirmed are already reported on this PR and are not repeated:
- R6-1 the --bg gate's command-surface pin test reads mcpCommand through the vi.mock stub, not the real module — already reported (round-5 deferral list, packages/cli/src/cli.test.ts:1342)
Not reviewed: reverse audit — did not converge within the reverse-audit round cap of 5.
Not reviewed: issue-fidelity — closing-issue discovery unavailable (gh 2.45.0 < required 2.72.0); ruled from the PR's Linked-Issues text (no closes references) and the motivating-incident replay.
Not reviewed: coverage — could not read the agents' transcripts (no subagent transcripts at /home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543 (ENOENT: no such file or directory, scandir '/home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543'). The harness writes one per agent; if there are none, either no agents ran or the harness could not write them.), so this run cannot show that any of the diff was read.
Not reviewed: verification — could not check that Step 4 and Step 5 ran (no subagent transcripts at /home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543 (ENOENT: no such file or directory, scandir '/home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543'). The harness writes one per agent; if there are none, either no agents ran or the harness could not write them.).
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory.
Deferred under the convergence posture (round 6, not a blocker) — recorded, not requested in this round:
packages/cli/src/cli.ts:359 — [probe] lastPositionalArg's -- stop clause is unwitnessed — no test reaches the help-word bounce with a -- separator presentdocs/users/configuration/settings.md:806 — [review] --bg docs omit the -- prompt-words escape hatch the decline message points users topackages/cli/src/cli.test.ts:1409 — [probe] help-fall-through tests pin only the help-first orderings; the reversed orderings the comment claims to cover are unwitnesseddocs/users/features/commands.md:755 — [review] --bg docs omit the exit-code contract — exit 2 means 'may still be starting, do not retry'packages/cli/src/cli.ts:737 — [probe] helpRequested hand-rolls the parser's help grammar — --help=true and short-cluster help (-dh, -mh) declined where base rendered helpdocs/users/features/commands.md:753 — [review] Session Management summary table missing the qwen --bg row
中文说明
本轮确认的 1 条建议级发现已在 PR 上报告过，不再重复发布（列表见上方英文部分）。
未审查（原文为英文）：reverse audit — did not converge within the reverse-audit round cap of 5.
未审查（原文为英文）：issue-fidelity — closing-issue discovery unavailable (gh 2.45.0 < required 2.72.0); ruled from the PR's Linked-Issues text (no closes references) and the motivating-incident replay.
未审查：覆盖情况——无法读取 agent 的运行记录（no subagent transcripts at /home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543 (ENOENT: no such file or directory, scandir '/home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543'). The harness writes one per agent; if there are none, either no agents ran or the harness could not write them.），本次运行无法证明 diff 的任何部分被读过。
未审查：验证——无法检查步骤 4 与步骤 5 是否运行（no subagent transcripts at /home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543 (ENOENT: no such file or directory, scandir '/home/github-runner/actions-runner-hk1-7/_work/_temp/qwen-home/projects/-home-github-runner-actions-runner-hk1-7--work-qwen-code-qwen-code/subagents/e898d4ae-13cd-4383-aaa0-ff7e7b952543'). The harness writes one per agent; if there are none, either no agents ran or the harness could not write them.）。
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory。
收敛姿态下延后（第 6 轮，非阻断）——已记录，本轮不要求修改：共 6 条（原文未翻译，列表见上方英文部分）。
— qwen3.8-max via Qwen Code /review (v0.23.0)
|
@qwen-code /triage |
|
Sandboxed verification: ❌ not passed — blocked (agent verdict) - workflow run Ran the PR in an isolated, token-free container: A/B against the base build, mock-free harness assertions, targeted gates. Advisory evidence for human reviewers — not a review, an approval, or a CI check. Scripted assertions: 89 passed · 4 failed · 93 total Flakiness gate: ✅ 3 changed test file(s) x 5 identical rounds, no divergence 中文 — 判定：❌ 不通过 · 阻塞（agent 判定）沙箱验证在隔离、无凭证的容器中执行了该 PR 的代码（与 base 构建 A/B 对照、无 mock harness 断言、定向门禁）。仅作为评审证据，不构成评审、批准或 CI 检查。 脚本断言：89 通过 · 4 失败 · 93 总计 抖动门：✅ 3 changed test file(s) x 5 identical rounds, no divergence Verification reportPR #10943 Deep Verification (round 2) —
|
| # | Previous finding | Sev | Status at this head | Evidence |
|---|---|---|---|---|
| 1 | --bg can never print its documented success line — nothing emits the ready worker event |
Critical | stands — and is deeper than reported: a second, earlier gate also blocks it | census 20/20 + positive control; A/B 1f/1g/1h/1i red; variant C reaches the worker gate only after the host gate is lifted |
| 2 | New user docs promise an unreachable outcome | Suggestion | stands (diff unchanged; docs still show Started background session 0f8e…c31) |
git diff HEAD^1..HEAD -- docs/ |
| 3 | Real failure lands on exit 1 ("retry me"), not the exit 2 the PR reserves | Suggestion (bounded) | stands, now sharpened: the exit-2 branch itself is correct and reachable — measured 9/9 on a variant that gets there | raw/exit2-only.txt |
| 4 | A tsx/dev launch of --bg cannot spawn its supervisor |
Note | stands (re-measured this round) | Could not start a background session: Agent View supervisor exited before becoming ready with code 1. |
| C1 | Correction: the worker is not launched with --prompt-interactive=<prompt> on this path |
— | stands, re-confirmed from the persisted launch record | head argv ["node","…/dist/index.js","--session-id","<id>"], prompt carried as initialPrompt; variant D's argv does carry --prompt-interactive=… |
| C2 | Correction: "runs end to end for the first time" overstates it | — | stands | four-arm matrix: only a two-hunk patch reaches the documented outcome |
| C3 | Correction: stated test counts are stale (455 tests / 13 new) | — | stands, numbers updated: 19 files / 513 tests; background-entry.test.ts reports 17 tests (previous round said 18 it() blocks; vitest's own count is 17) |
raw/gate-suite-run2.log |
| — | Previous round's own candidate fix: waitForWorkerReady: false alone would make dispatch return an id |
— | measured and refuted — see Finding 2 | variant B: exit 1, same host-gate error |
Scope selection
Central claim — qwen --bg "<prompt>" starts a background Agent View session, prints the session id, and returns.
Secondary claim 1 — qwen --internal-agent-view-supervisor is recognized at the entry, so the supervisor serves instead of dying on the strict parser.
Secondary claim 2 — the pre-parser intercepts decline rather than guess (option-table-derived value slots, stop at --, ordinary launches unaffected).
Budget went to: re-measuring the Critical with a validated instrument; the four-arm variant decomposition; and the three previously-uncovered paths. Deliberately not re-run: the sibling sweep (46/46), route-reachability probes (12/12) and the backgroundFlagIndex mutation (11/108 red) — the previous round measured all three against this exact head and their entire input closure (packages/cli/src/**, unchanged OIDs) is identical; listed under Not covered rather than silently credited.
Central claim + A/B
Witnesses: 01-census-no-ready-producer-with-control.png, 02-host-probe-budget-vs-real-bind-time.png, 03-variant-matrix-four-arms-17-of-17.png.
Raw: raw/ab-base.txt, raw/ab-head-final.txt, raw/census.txt, raw/census-positive-control.txt, raw/probe-budget.txt, raw/variant-matrix.txt, raw/epipe-exit2.txt, raw/exit2-only.txt.
Entry A/B, real child processes, isolated HOME and QWEN_HOME per cell, lane credentials scrubbed:
| # | argv | base-src (control) | head-dist (authoritative) |
|---|---|---|---|
| 1 | --bg "list the files in this directory" |
exit 1, 7.8 s — Unknown argument: bg; 0 sessions recorded |
exit 1, 10.5 s — Could not start a background session: Agent View PTY host did not become ready. Session a2b3360b: sessionState=failed, errorCode=pty_launch_failed, capabilities=[] |
| 2 | --internal-agent-view-supervisor |
exit 1, 7.9 s — Unknown arguments: internal-agent-view-supervisor, internalAgentViewSupervisor |
alive at the end of the 20 s window — served throughout, no parser error |
| 3 | --bg (bare) |
exit 1 — Unknown argument: bg |
exit 1, 3.9 s — qwen --bg needs a prompt: …; 0 sessions |
| 4 | -p hello -- --bg |
exit 1, 13.3 s — No auth type is selected… |
exit 1, 6.8 s — byte-identical No auth type is selected… (A/A parity) |
| 5 | --bg --model qwen3-coder-plus "…" |
— | exit 1, 3.1 s — does not honor --model |
| 6 | --bg audit --internal-agent-view-supervisor |
— | exit 1, 4.1 s — declined as prompt data, did not hijack into a daemon |
| 7 | --internal-agent-view-pty-host <launch> <sock> |
exit 1 — Unknown arguments: internal-agent-view-pty-host, … |
(served — see Finding 1) |
Secondary claims 1 and 2 are proven (base control 7/7, head 12/16). The central claim fails: 1f (documented success line), 1g (exit 0), 1h (session reaches a usable state), 1i (non-empty capabilities) are all red, on the shipped artifact, with the persisted store read back as a second oracle independent of stdout.
Four-arm variant matrix — decomposing the blocker (17/17)
An A/B against base proves the wires are connected; it cannot say which gate stops a launch, or whether the previous round's candidate fix would have worked. Each variant differs from the shipped head by exactly one named hunk, patched into a hardlink copy of dist (pristine dist sha256-verified untouched before and after):
| build | hunk(s) vs head | exit | elapsed | success line | gate reached |
|---|---|---|---|---|---|
| A head as shipped | — | 1 | 11 230 ms | no | host readiness |
| B | waitForWorkerReady: false |
1 | 10 462 ms | no | host readiness (same error) |
| C | HOST_READY_RETRIES 50→400 |
1 | 21 191 ms | no | worker ready (15 s) |
| D | both | 0 | 10 811 ms | Started background session bff2aba1-… |
none — succeeded |
Two blockers in series, and only the pair clears them. On D the whole documented happy path reproduces, including the parts the previous round could not reach:
$ qwen --bg "list the files in this directory" # variant D
Started background session bff2aba1-0a6f-4c88-a8b8-e95f13e41ae9
See it with: qwen sessions ps
$ qwen sessions ps
NAME PID AGE STATE DIRECTORY
list the files in t… 28797 10s working /__w/qwen-code/qwen-code
Reviewer Test Plan steps 1 and 2 are therefore both real and both broken as shipped. D's worker argv also carries --prompt-interactive=list the files in this directory — the shape the PR description asserts but head does not produce (correction C1, now shown from both sides).
Findings
1. Critical / blocker — qwen --bg can never succeed: two gates in series, neither passable as shipped
Gate 1 (new this round) — the PTY-host readiness budget is ~6× shorter than its own comment claims, and shorter than the host needs. waitForPtyHost() (pty-host-process.ts:990) is bounded twice: attempt < HOST_READY_RETRIES (50) and a wall deadline of retries * (HOST_READY_DELAY_MS + requestTimeoutMs) = 15 000 ms. The source comment at line 41 says "Wall budget ≈ 15 s once per-probe request timeouts are counted" — that holds only if each failed probe consumes its 250 ms request timeout. A connect to a socket that does not exist yet fails with ENOENT in 0.38–0.47 ms mean (max 10.2 ms), so each attempt costs only the 50 ms delay and the retry count binds at ~2.55 s.
Measured (02-host-probe-budget-vs-real-bind-time.png, raw/probe-budget.txt, raw/probe-budget-capture.txt):
| quantity | measured |
|---|---|
| failed-connect cost | mean 0.38 / 0.47 ms, max 10.2 ms (vs a 250 ms request timeout) |
| probe loop wall budget | 2551 ms, 2559 ms (50 attempts, both runs) |
| host socket bind time | 2653, 2942, 3535 ms then 4511, 2667, 4062 ms |
| binds exceeding the budget | 6 / 6 (min shortfall 101 ms, max ~1.95 s) |
The host itself is healthy: spawned directly with the real argv shape and identity env, it binds and serves, writes 0 bytes to stderr, and exits 0 (raw/host-probe.txt). @lydell/node-pty imports and spawns fine in this container (pty-works, exit 0) and /dev/ptmx exists — so this is not a missing-PTY environment. The gate is a budget race the host always loses here.
Per the timing-threshold rule this is not ordinary flake: the budget is a fixed 2.55 s while the bind distribution is 2.67–4.51 s, so a retry budget does not absorb it — and the previous round's observation that host readiness "succeeded in one run and not the other" is what a crossing distribution looks like from one sample.
Nothing pins this budget. Cutting HOST_READY_RETRIES 50 → 5 (a 10× smaller budget) leaves 50/50 tests green. The exact user-visible string Agent View PTY host did not become ready. appears once in source and zero times in tests. Positive control in the same file: mutating 'Agent View PTY host exited before ready' (which a test does pin) turns exactly one test red with the intended assertion — expected [Function] to throw error including 'Agent View PTY host exited before rea…' but got 'AGENT VIEW PTY HOST EXITED EARLY (cod…'. So the survivor is a real coverage gap, not a harness that collected nothing. Source restored byte-exact (sha256 OK, git status 0 lines).
Gate 2 (the previous round's Critical, re-proven with a validated instrument) — nothing can ever satisfy the worker-ready wait. Census 20/20 over 2 260 .ts/.tsx files (1 251 production) and 1 263 shipped .js files:
- the only gateway to the
workerEventRPC issendAgentViewWorkerEvent, with exactly two production call sites (worker-sideband.ts:204,:244) emittingstateandheartbeat—readyis not in the set the gateway can put on the wire; - 0 production callers of that gateway outside its own module; 0 value-level
type: 'ready'emitters in production agent-view code; 0 shipped modules importing the emitter (B1b); waitForWorkerReadyandlaunchPtyHostare assigned in 0 production sites — onlysupervisor-process.test.tssets them — soshouldWaitForWorkerReady()=undefined ?? !undefined= true always;- the single
resolvePendingWorkerReady()call site sits inside anevent.type === 'ready'guard.
The census is validated by a positive control: planting sendAgentViewWorkerEvent({ type: 'ready', … }) into a scratch copy of agent-view/pty-host.ts turns checks A1 and A3 red (18/2). A census that only ever reports 0 is indistinguishable from one that cannot see anything; this one can.
Runtime corroboration: variant C lifts gate 1 and then dies at gate 2 with Agent View worker a4e45a5e-… did not report ready before timeout., sessionState=failed, capabilities=[].
Reproduce (any clean Linux checkout of this head, built):
QWEN_HOME=$(mktemp -d)/.qwen node packages/cli/dist/index.js --bg "list the files in this directory"
# exit 1 after ~10 s: Could not start a background session: Agent View PTY host did not become ready.
# lift gate 1 (HOST_READY_RETRIES 50->400) and it becomes:
# exit 1 after ~21 s: ... Agent View worker <id> did not report ready before timeout.Attribution, named separately. Both gaps live in code this PR does not touch: the readiness loop is in pty-host-process.ts (this PR's only change there is moving a string constant into entry-flags.ts and re-exporting it — the value is unchanged and the shipped re-export is correct), and the missing emitter is in worker-sideband.ts / interactive startup. Neither is the author's defect. This PR's contribution is that it is the first code that ever let either path execute: base rejects both internal flags (Unknown arguments: internal-agent-view-supervisor, … and Unknown arguments: internal-agent-view-pty-host, …), so before this PR the host and the supervisor could never run at all. Wiring them up is correct and is what exposes that the subsystem's readiness budgets and worker half were never finished — and what ships user-facing docs for an outcome that cannot occur.
Measured candidate fix — applied and driven, not eyeballed
Both hunks were applied to the shipped dist and driven through the same harnesses (variant D). Results:
- Hostile fixture goes clean:
--bg "<prompt>"printsStarted background session bff2aba1-…, exit 0, in 10.8 s (vs exit 1 at head). - Zero collateral on the decline paths: cells 3–6 behave identically at head and on the patched builds — a bare
--bgstill reports an empty prompt,--modeland an internal flag typed as prompt data are still declined by name, and--is still honored. - Suite counts: the patched trees are
dist-only edits; the vitest suite runs from source and is unaffected, which is itself the signal — no fixture goes red or green either way, because nothing asserts the readiness budget (M1) or the end-to-end dispatch.
The fixture that would pin it does not exist: an integration test that drives a real supervisor, host and worker and asserts Started background session on stdout. Any real fix should ship with it. Note also that neither hunk belongs to this PR's diff — gate 1 is a budget/comment defect in the subsystem, gate 2 is a missing emitter — so the product decision ("what does started mean") is the maintainers', not a one-line repair.
2. Correction to the previous report — its candidate fix does not work alone
The previous round offered, as candidate direction 2: "constructing the supervisor with waitForWorkerReady: false makes promptInArgv true, so … dispatch returns a session id immediately", explicitly labelled unimplemented and unmeasured. Measured this round as variant B: it does not. Exit 1, 10.5 s, the same PTY host did not become ready error as head — because the dispatch launches and waits for the PTY host before the worker-ready wait is ever consulted. A reviewer who had acted on that suggestion would have shipped a no-op. This is why the round built the intermediate variants instead of trusting either round's reasoning.
3. Suggestion (carried) — the new user docs promise an outcome that cannot occur
docs/users/features/commands.md states --bg "returns once the worker has started, printing the session id", with a sample transcript # Started background session 0f8e...c31; docs/users/configuration/settings.md adds a matching row. Both describe the unreachable path. The transcript is exactly what a user will compare their failure against. Unchanged since the previous round.
4. Suggestion (carried, sharpened) — the real failure lands on the "retry me" exit code
The PR carefully reserves exit 2 for a client-side dispatch timeout so "a wrapper keyed on the exit code must not retry it". The failure actually observed in production — session recorded, host spawned, ready never arriving — surfaces as pty_launch_failed through the generic catch and returns exit 1 with Could not start a background session, i.e. the code a wrapper reads as safe to retry, even though a session row was written.
The exit-2 branch itself is correct — the previous round could not reach it, so this round built variant E (host budget raised, server worker timeout 45 s, client cap left at 30 s) and drove it: exit 2, The background session may still be starting: Timed out waiting for Agent View supervisor response.. Check: qwen sessions ps, 9/9. The ordering is proven without a wall-clock model: the client-cap text is present and the server-timeout text is absent, so 30 s beat 45 s. A session really was recorded while the client gave up (sessionState=starting), so "may still be starting" is a true statement rather than comforting fiction.
What I disproved, so this is not overclaimed: the sharpest consequence does not hold. The abandoned client left exactly one worker in flight, not two — so a retry would not have doubled the agent in the runs I observed. The residual issue is the mismatch between the message ("Could not start") and the store's record (a session was created and a worker spawned), not a demonstrated duplicate-agent hazard.
5. Confirmed working (so the blocker is not read as a wholesale rejection)
Three paths the previous round listed under Not covered are now measured, and all three are correct:
- Broken pipe, end to end — 6/6. With stdout closed before the success write (variant D, where that write is reachable): exit 0, no
EPIPE/ERR_STREAM_DESTROYEDon stderr, no signal death, session recorded and not marked failed, exactly one live worker. The design in the PR's newest commit —ignoreBrokenPipe()plus success writes outside the launchtry— does precisely what its comment says, and prevents the inversion that would have a wrapper start a second agent. sessions pslisting — 2/2 (Reviewer Test Plan step 2): lists the--bgsession with a PID andSTATE=working, exit 0. On variant C the same command correctly showsfailed.- Exit-2 branch — 9/9 (Finding 4).
Plus the entry gate itself, re-measured: cells 3–6 above (decline by name, honor --, value-slot awareness, internal flag as prompt data does not spawn a daemon), and cell 4's byte-identical A/A parity showing the -- escape changes nothing on the ordinary path.
6. Note (carried, re-measured) — a tsx/dev launch of --bg cannot spawn its supervisor
node <getCurrentQwenCliEntrypoint()> … spawns plain node at a .ts path under tsx, so the child dies at once: Could not start a background session: Agent View supervisor exited before becoming ready with code 1. --bg is therefore unusable via npm run dev, so a contributor cannot reproduce or debug this feature without a full build. This is also why every authoritative cell here runs against dist.
7. Note (lane, not PR) — the verify container's 15 s testTimeout produces a moving false failure
The author's cited command ran twice, both 512/513, and the victim moved: run 1 src/agent-view/pty-host-process.test.ts > rejects oversized PTY host responses, run 2 src/cli.test.ts > pins the --bg gate's command surface to the registered command modules. Both losses are 15 s timeouts, not assertion failures. Classification, not speculation:
- run alone and idle, the run-1 victim passes in 1398 ms — a 10.7× margin under the ceiling (50/50, file duration 4.6 s);
- that test file is byte-identical at base and head (
git diff→ 0 files), so the PR did not change it; - the PR's own new/changed files passed on both runs —
background-entry.test.ts17/17 (173 ms, 19 ms) andsupervisor-dispatch.test.ts5/5; packages/cli/vitest.config.ts:162setstestTimeoutto 60 s onecs-qwen-*runners and 15 s elsewhere, with a comment about I/O-bound tests blowing the ceiling "purely under CI contention".RUNNER_NAMEis unset in this verify container, so the 15 s branch applies.
A moving target across identical runs is contention, not a defect. Worth knowing for the lane: the verify job applies a stricter per-test ceiling than project CI, so it will keep reporting a spurious 1/513 on whichever I/O-bound test loses the race.
Not covered
- Per-commit attribution is out of reach. Depth 2:
git rev-list HEAD^1..HEAD^2yields 1 commit while the snapshot'scommitsarray holds 23;git rev-parse --is-shallow-repositoryistrue. Only the aggregateHEAD^1..HEADdiff was verified. No per-commit table is presented. npx tsc --noEmitwas not re-run this round. Carried forward on an explicitly compared input closure: the base and head OIDs are identical to the round that measured exit 0, and the closure that measurement consumed is unchanged —git diff HEAD^1..HEADtouches 0 files outsidepackages/cli/src/**anddocs/**, 0package.json/package-lock.jsonfiles, and 0 files inpackages/core,packages/acp-bridge,packages/sdk-typescript,packages/web-templatesorpackages/channels;node_modulescame from the samenpm ciat the same HEAD. If you want the number re-measured rather than carried, it needs ~4 min of a fresh round.- Carried forward on the same identical-closure basis, not re-run: the 46-check sibling sweep of the prompt reader, the 12 route-reachability probes, and the
backgroundFlagIndexmutation (11/108 red). Their inputs are the unchangedpackages/cli/src/**at the same OIDs. Everything else in this report was re-executed. - No successful
--bgrun on the shipped artifact — by definition, since that is the blocker. The success path was observed only on patched variants, and the session id format,workingstate column andsessions psrow quoted above all come from variant D, not from head. - Cross-session messaging (the description's
list_agentsvisibility /send_messageaddressability underagents.crossSessionMessaging) was not exercised: this container has no configured auth type (No auth type is selected…, cell 4), so a spawned worker never reaches a live model-backed state. Finding 1 does not depend on this — the census shows no producer exists, so no credential state can satisfy the wait. - No trial merge into current
main— no network in this container, so I could not check whethermainhas touched these files since the merge base. The base is far behind. - Gates not run: ESLint, Prettier, the repo-wide suite,
npm run buildat head (CI completed it before my clock; I verified instead that the artifact contains the PR's code), and all integration tests. - Windows and macOS untested (the PR marks both N/A).
- The patched variants are measurement scaffolding, not a proposed patch. They edit compiled
distonly, live undertmp/, and were removed at the end of the round; no fix is being offered for merge. - Two harness defects of my own are disclosed because both initially produced numbers that would have been wrong: (a) my first session read-back looked under
agent-view/sessions/, which does not exist — the real layout is<QWEN_HOME>/jobs/<id>/{state,launch,activity,worker}.json— so checks1h/1iread an always-empty array and reported false reds until corrected and re-run; (b) my first exit-2 check asserted total wall time ≈ 30 s, which was my arithmetic rather than the code's contract (total also includes node startup and supervisor-ensure before the RPC cap starts) — measured 43.4 s, then 37.7 s. Both were fixed and re-run; the supersededX1is counted nowhere as a PR failure. My first census also produced three false reds of its own (TypeScriptExtract<…, { type: 'ready' }>annotations, the unrelatedchannel/voice'ready'protocols, and counting module importers as emitter importers) — all three are now scoped, and the scoping is itself asserted (A2d,A4,B1a). - The lane exports
FORCE_COLOR, which put ANSI escapes inside vitest's piped output and silently broke eight of my log-parsing checks before I stripped them. Recorded because it will recur.
Methodology
Environment: the CI verify container (node:22-bookworm, Node v22.23.2, npm 10.9.8, 64 cores), working tree at refs/pull/10943/merge depth 2, npm ci and npm run build already completed at HEAD. I confirmed the built artifact carries this PR's code before trusting it (Started background session in dist/src/agent-view/background-entry.js, TOP_LEVEL_COMMAND_NAMES in dist/src/cli.js).
Control: git worktree add tmp/base-tree HEAD^1, run through tsx. The PR touches no package.json/package-lock.json (0 files), so reusing the root node_modules is a clean dependency control. I asserted the internal workspace links rather than assuming them — readlink -f node_modules/@qwen-code/{qwen-code-core,sdk,web-templates,acp-bridge} resolves into the head tree's packages/*, which is sound only because git diff HEAD^1..HEAD over those packages is 0 files, making them byte-identical between arms. The base worktree also needed the git-ignored generated file packages/cli/src/generated/git-commit.ts copied in, or every base cell crashes with ERR_MODULE_NOT_FOUND before reaching the parser. I did not use require.resolve for the link check: these packages are ESM-only with import-only exports and it throws ERR_PACKAGE_PATH_NOT_EXPORTED.
Harnesses drove real compiled code, never a stub of the unit under test. ab-entry.mjs spawns real node/tsx children (isolated HOME and QWEN_HOME per cell, credentials scrubbed so no spawned worker could spend the lane's API key or act with its GitHub token) and reads the persisted state.json/launch.json/activity.json back as a second oracle independent of stdout. host-probe.mjs spawns the real PTY host with the production argv shape and identity env, with no supervisor involved, to isolate the failing unit. probe-budget.mjs measures the failed-connect cost, replicates the readiness loop exactly, and times the real host's socket bind over 3 runs. variant-matrix.mjs and epipe-exit2.mjs/exit2-only.mjs drive the patched dist trees. census.mjs scans source and shipped dist, with a positive control on a scratch copy. gates-tally.mjs reads the real vitest logs and sums each harness's own emitted counts.
Every number in assertions.json maps to a scripted check that executed: 20 census + 2 census positive control + 7 base A/B + 16 head A/B + 5 probe budget + 17 variant matrix + 7 broken-pipe/blast-radius + 9 exit-2 + 8 gate + 3 mutation + 1 tally control = 93, of which 4 are unexpected outcomes (the central claim). Base-control cells assert that base fails and are counted as passes when it does; the superseded X1 from my own arithmetic error is counted nowhere. All scratch state lives under tmp/pr10943-verify-20260905-064302/; leftover detached supervisors and workers were terminated after each harness, the base worktree and variant trees were removed, mutated source files were restored byte-exact (sha256-verified), and the working tree was verified clean against HEAD.
Flakiness gate log
rounds=5 files=3 skipped=0
file packages/cli/src/agent-view/background-entry.test.ts: (cd packages/cli) npx --no-install vitest run ./src/agent-view/background-entry.test.ts
file packages/cli/src/agent-view/supervisor-dispatch.test.ts: (cd packages/cli) npx --no-install vitest run ./src/agent-view/supervisor-dispatch.test.ts
file packages/cli/src/cli.test.ts: (cd packages/cli) npx --no-install vitest run ./src/cli.test.ts
per-file results (P=pass F=fail I=infra-exit, one letter per run):
packages/cli/src/agent-view/background-entry.test.ts: PPPPP
packages/cli/src/agent-view/supervisor-dispatch.test.ts: PPPPP
packages/cli/src/cli.test.ts: PPPPP
verdict: pass
summary: 3 changed test file(s) x 5 identical rounds, no divergence
--- per-invocation detail (full copy in the artifact) ---
round 1 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 1 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 1 · packages/cli/src/cli.test.ts: P (exit 0)
round 2 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 2 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 2 · packages/cli/src/cli.test.ts: P (exit 0)
round 3 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 3 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 3 · packages/cli/src/cli.test.ts: P (exit 0)
round 4 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 4 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 4 · packages/cli/src/cli.test.ts: P (exit 0)
round 5 · packages/cli/src/agent-view/background-entry.test.ts: P (exit 0)
round 5 · packages/cli/src/agent-view/supervisor-dispatch.test.ts: P (exit 0)
round 5 · packages/cli/src/cli.test.ts: P (exit 0)
Evidence images
Harness scripts and raw logs are in the workflow run artifacts (7-day retention).
— Qwen Code · sandboxed verification
wenshao
left a comment
wenshao
left a comment
There was a problem hiding this comment.
Partially reviewed — gaps disclosed.
4 Suggestion-level finding(s) this review confirmed are already reported on this PR and are not repeated:
- the --bg half of the guard-token scrub test is vacuous (cli.test.ts:1135) — already reported (round-3 deferral D3-4, review 5113708902; re-listed in the round-4 and round-5 bodies)
- the command-surface pin's authority is the test's own vi.mock stub and import list rather than config.ts's registrations (cli.test.ts:1440, :1457) — already reported (round-5 deferral, review 5118274822); the inline-object .command({...}) s…
- bg declared in DEFAULT_COMMAND_OPTIONS but never registered in the real parser (config/top-level-options.ts:203) — already reported (R3-2, comment 3934593183) and dispositioned by the author in that thread
- runBackgroundDispatch's process.cwd() default is untested (background-entry.test.ts:201) — already reported (round-2 deferral D2-3, review 5109570361; re-deferred D3-2 in round 3)
Not reviewed: build-and-test — Qwen Code CI never triggered on this stacked base (ci.yml fires pull_request only on main and release/**), and the local packages/cli suite was killed at its 540 s ceiling in both runs; all 16 workspaces built clean and the three diff-touched test files passed 130/130, but the workspace suite as a whole is unproven.
Not reviewed: reverse audit — did not converge within the reverse-audit round cap of 5.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory.
Deferred under the convergence posture (round 6, not a blocker) — recorded, not requested in this round; 1 Critical(s) among them are deferred by their axes — fails-closed on new surface, where no wrong result is certified and the merge base had neither the surface nor the defect — and remain follow-up work recorded in the findings artifact:
packages/cli/src/agent-view/background-entry.ts:164 — [probe] Critical [fails-closed] [new-surface] the dispatch RPC can never complete: no production code sends the workerEvent{type:'ready'} the handler blocks on, so every --bg launch fail…packages/cli/src/agent-view/background-entry.test.ts:234 — [probe] R5-3 (fix-induced) the ordering witness asserts inside the dispatch mock, so the catch under test swallows its AssertionError and the mutation survives at 17/17packages/cli/src/cli.test.ts:1416 — [probe] the flag-led help ordering the cli.ts:728-736 comment claims to support is untested; the order-sensitive mutant left 108/108 greendocs/users/configuration/settings.md:806 — [probe] 'Other launch flags are not honored' reads as ignored-but-still-starts; the launch actually refuses with exit 1 and starts nothing, and the row omits the -- escape hatchdocs/users/features/commands.md:755 — [probe] the --bg docs state no exit-code contract, including the deliberate code 2 meaning 'may still be starting — do not retry'docs/users/features/commands.md:757 — [probe] the promised working / needs input readout has no producer — nothing emits worker state events, so 'needs input' can never print for a --bg sessiondocs/users/features/commands.md:757 — [probe] the list_agents claim holds only because the worker DOES write a registry record, which the same page's sessions ps paragraph denies 20 lines belowpackages/cli/src/agent-view/background-entry.test.ts:221 — [probe] the success output is pinned by substring only and the mocked writeStdoutLine omits the real helper's newline rule, so rewording the banner keeps 17/17 greenpackages/cli/src/agent-view/background-entry.ts:164 — [review] the invoking shell's environment never reaches the worker when a supervisor is already alive; the daemon freezes the env of whoever spawned it firstdocs/users/features/commands.md:765 — [probe] 'no way to … stop it' is contradicted by the sibling sessions ps PID column — kill <pid> is a real, undocumented off switch for a running sessionpackages/cli/src/agent-view/pty-host-process.ts:42 — [probe] the PTY-host ready budget binds at the attempt count (~2.5 s measured) rather than the ~15 s its own comment models, and the failure message carries no causepackages/cli/src/agent-view/supervisor-process.ts:3616 — [probe] 'pty_launch_failed' is markFailedSession's default and both call sites pass no code, so a worker-ready timeout is persisted under a PTY-launch codepackages/cli/src/agent-view/background-entry.ts:102 — [probe] every bare --bg token is consumed as the launch flag, so a --bg word inside an unquoted prompt is silently deleted instead of declining by namepackages/cli/src/cli.ts:751 — [probe] R4-6 (fix-induced) both halves of the decline's re-run advice are unworkable for value-taking flags — dropping the flag orphans its value into the prompt, and the after-- hatch declines identicallypackages/cli/src/agent-view/background-entry.test.ts:313 — [probe] the exit-code contract's negative arm is unwitnessed: 'timeout' is the only code any fixture carries, so broadening the guard to ?.code leaves 17/17 greenpackages/cli/src/cli.test.ts:1309 — [probe] no test witnesses that a positional-led non-command launch still dispatches, so widening parserOwnsLaunch leaves the suite green while prompt-first launches die in the strict parserdocs/users/features/commands.md:757 — [review] the new paragraph links section 6 as its authority, but section 6's scope sentence ('Two interactive sessions') excludes the managed session it is linked forpackages/cli/src/cli.ts:330 — [review] R4-3 Still stands — the value-slot-skipping argv scan exists in four hand-maintained copies; the author tracks the consolidation as #11065packages/cli/src/agent-view/background-entry.ts:95 — [review] R4-4 Still stands — the --bg token-shape predicate is implemented in two files, kept consistent only by call ordering; tracked as #11065packages/cli/src/cli.ts:636 — [review] R2-5 Still stands — the 'argv before -- is routable' boundary is computed twice; identical today, so the trigger is a future one-sided edit- …and 1 more (see the run report)
Convergence: round 6 posted 5 inline comment(s), 5 of them reported for the first time. Findings keep coming back to the same files: packages/cli/src/cli.ts (findings in rounds 2, 4, 5; 4 more now); packages/cli/src/agent-view/background-entry.ts (findings in rounds 2, 4, 5; 1 more now). (Evidence: the previous round was recovered from a marker this account did not post, so those rounds may not be this account's own.) A cluster that keeps producing siblings usually means the fixes are treating instances of a shared root cause — triaging that cause before the next round, or splitting an independent cluster into its own pull request, tends to end the loop faster than fixing them one at a time. (Observation only — nothing was withheld from this review because of this observation.)
中文说明
仅完成部分审查，审查缺口已披露。
本轮确认的 4 条建议级发现已在 PR 上报告过，不再重复发布（列表见上方英文部分）。
未审查（原文为英文）：build-and-test — Qwen Code CI never triggered on this stacked base (ci.yml fires pull_request only on main and release/**), and the local packages/cli suite was killed at its 540 s ceiling in both runs; all 16 workspaces built clean and the three diff-touched test files passed 130/130, but the workspace suite as a whole is unproven.
未审查：反向审计——在 5 轮的反审轮数上限内未收敛。
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory。
收敛姿态下延后（第 6 轮，非阻断）——已记录，本轮不要求修改；其中 1 条 Critical 按其失败方向与对照基线延后——fails-closed 且 new-surface：未认证任何错误结果，且 merge base 既无该功能面也无该缺陷——作为后续工作记录在 findings 工件中：共 21 条（原文未翻译，列表见上方英文部分）。
收敛情况：第 6 轮发布了 5 条行内评论，其中 5 条是首次提出。发现反复回到同一批文件：packages/cli/src/cli.ts（第 2、4、5 轮已出过发现，本轮又有 4 条）；packages/cli/src/agent-view/background-entry.ts（第 2、4、5 轮已出过发现，本轮又有 1 条）。（证据说明：上一轮的数据来自并非本账号发布的标记，上述轮次可能不属于本账号。）一个不断再生兄弟发现的簇，通常意味着逐条修复只在处理同一根因的实例——先定位并处理该根因，或把独立的簇拆成单独的 PR，通常比逐条修复更快结束循环。（仅为观察——本轮评审未因此扣留任何内容。）
— qwen3.8-max-2026-09-02 via Qwen Code /review (v0.23.0)
…dispatch as failed Five related holes in the --bg entry, all in the argv scanning and the dispatch certification: - `--bg=false` / `--bg=0` are the boolean off spellings the flag's own `type: 'boolean'` declaration advertises; both scanners read the attached value as prompt text and dispatched a real agent on the prompt `false ...`, certified with exit 0. One shared predicate in entry-flags.ts now decides what a background-flag token is (an off spelling is not a launch, an on spelling means the bare flag) and what prompt word it carries; every other attached value stays prompt data. - A `-v`/`--version` token among a --bg launch's prompt words hit the version intercept first, printed the version and exited 0 with no session and no diagnostic. The intercept is order-aware now: a version token after the flag stays on the default route, where the gate declines it by name like every other flag it does not honor. - bg-absence was the only condition on the two internal-flag intercepts, so an ordinary positional-led launch whose prompt words name one of those flags was hijacked into serving as the supervisor daemon, binding the process-global socket until killed. Both intercepts now require a spawn-shaped argv: the flag with no positional before it, which is what both spawners produce. - The whole-argv `--help`/`-h` scan covered a bare --bg launch's prompt words, so `qwen --bg add a --help section to the README` rendered top-level help and dropped the prompt with exit 0. The scan is bounded to the tokens before the flag unless the flag token carries its prompt inside itself. - A supervisor killed between recording a session and the ready wait settles the client with `code: 'closed'` and was certified as a launch failure (exit 1) beside a persisted `starting` session and a live detached host, so a wrapper honoring the exit-code contract retried into a second agent on the same prompt. A dispatch rejection now asks the store the positive question and reports an in-flight launch with the do-not-retry exit code when a managed session for this cwd was recorded after the dispatch began; pre-record rejections and a supervisor that never came up stay exit 1. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmto4amd1ku
The store row the in-flight certification test hands the entry was stamped when the mock was built, which can land a millisecond before the entry dates its own dispatch window; the row then read as a session from a previous launch and the exit-2 arm went red on a loaded machine. Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> Patrol-Run: qwen-pr-closeout/jmto4amd1ku
|
@wenshao re-requesting your review — your
Required CI on this head: |
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Partially reviewed — gaps disclosed.
6 Suggestion-level finding(s) this review confirmed are already reported on this PR and are not repeated:
- the --bg half of the guard-token scrub test is vacuous (cli.test.ts:1135) — already reported (round-3 deferral D3-4, re-listed in rounds 4, 5 and 6)
- the command-surface pin's authority is the test's own vi.mock of ./commands/mcp.js (cli.test.ts:1584) — already reported (round-5 deferral, re-listed in round 6)
- bg declared in DEFAULT_COMMAND_OPTIONS but never registered in the real parser (config/top-level-options.ts:203) — already reported (R3-2, comment 3934593183) and dispositioned by the author in that thread; round 3 re-filed the same root ca…
- --bg in a derived value slot and the unworkable decline advice (cli.ts:751) — already reported (round-6 deferral R4-6)
- the attached-spelling help ordering is unwitnessed (cli.test.ts:1416) — already reported (round-6 deferral)
- runBackgroundDispatch's process.cwd() default is untested (background-entry.test.ts:201) — already reported (round-2 deferral D2-3, re-deferred D3-2)
Not reviewed: build-and-test — the packages/cli workspace suite was killed at its 540 s deadline in both runs; all 16 workspaces built clean and the three diff-touched test files passed 144/144, but the workspace suite as a whole is unproven.
Not reviewed: test-efficacy — the probe harness could not be validated (harnessValidated: null): the positive control never ran because no probe file was green in the unmutated baseline (the probe runner tripped the repo's git-commit.ts generation guard), so this PR's test efficacy is unmeasured.
Not reviewed: reverse audit — stopped before round 4 by the review time budget.
Test Plan (not a blocker): src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory.
8 Suggestion(s) were drafted inline past the resolved critical posting floor; the CLI moved them into the deferral list below (floor enforcement).
Deferred under the convergence posture (round 7, not a blocker) — recorded, not requested in this round; 1 Critical(s) among them are deferred by their axes — fails-closed on new surface, where no wrong result is certified and the merge base had neither the surface nor the defect — and remain follow-up work recorded in the findings artifact:
packages/cli/src/agent-view/background-entry.test.ts:96 — [review] Critical [fails-closed] [new-surface] D7-1 the store-row fixture hardcodes POSIX projectCwd '/w/app' while the code compares against path.resolve(cwd), so the in-flight cert…packages/cli/src/cli.ts:404 — [review] R7-4: backgroundFlagIndex crosses the -- separator when -- lands in a BASE value flag's slot, because the unconditional i++ swallows the sentinel — so a --bg word that is the user's own post-…packages/cli/src/cli.ts:808 — [review] R7-5: The dispatch exit code's propagation is witnessed only for 0 and 1 — the distinct code 2, the "in flight, do not retry" value background-entry.ts exists to produce, is never asserted to reach …packages/cli/src/cli.ts:685 — [review] R7-6: isSpawnShaped reads "no positional before the flag" as spawn-shaped, which is also true of an argv that is *all flags* — so an internal flag typed after a boolean flag, or sitting in a derived …packages/cli/src/agent-view/background-entry.test.ts:17 — [review] R7-7: runAsAgentViewSupervisor — this PR's other headline wire, and the one that fixes the narrated incident — is executed by no test, and this stub omits runAgentViewSup…packages/cli/src/agent-view/background-entry.test.ts:414 — [review] R7-8: The in-flight store guard's only positive witness stamps the row 1 s in the **future**, so the >= boundary that sessionRecordedSince 's own doc states ("recorded *…packages/cli/src/cli.ts:794 — [review] R7-9: The prompt-less ON spellings --bg=true / --bg=1 are the only --bg spellings for which a --help / -h token is **declined** with exit 1 instead of **rendered** — and the decline's own advic…packages/cli/src/cli.test.ts:1174 — [review] R7-10: The two tests that pin the backgroundFlag === -1 ? flagIndex(…) : -1 guard on the internal intercepts ( cli.ts:695-701 , :723-729 ) are insensitive to it — the positional prompt word '…packages/cli/src/cli.test.ts:1064 — [review] R7-11: Nothing pins the route === 'default' precondition for the two **internal** intercepts, so the block's stated guarantee that "the version/help/subcommand routes keep their established beh…packages/cli/src/agent-view/background-entry.test.ts:314 — [review] D7-2 R5-3 the broken-pipe ordering witness asserts inside the dispatch mock, so the catch under test swallows its AssertionErrorpackages/cli/src/agent-view/background-entry.ts:161 — [review] D7-3 sessionRecordedSince's fail-closed catch { return false } is unexercised — 0 rejecting store mocks across 4 mock sites and 21 tests
Convergence: round 7 posted 5 inline comment(s), 5 of them reported for the first time; the previous round posted 0 (0 new). Findings keep coming back to the same files: packages/cli/src/agent-view/background-entry.ts (findings in round 6; 2 more now); packages/cli/src/cli.ts (findings in rounds 2, 6; 2 more now). (Evidence: the previous round was recovered from a marker this account did not post, so those rounds and its counts may not be this account's own.) A cluster that keeps producing siblings usually means the fixes are treating instances of a shared root cause — triaging that cause before the next round, or splitting an independent cluster into its own pull request, tends to end the loop faster than fixing them one at a time. (Observation only — nothing was withheld from this review because of this observation.)
中文说明
仅完成部分审查，审查缺口已披露。
本轮确认的 6 条建议级发现已在 PR 上报告过，不再重复发布（列表见上方英文部分）。
未审查（原文为英文）：build-and-test — the packages/cli workspace suite was killed at its 540 s deadline in both runs; all 16 workspaces built clean and the three diff-touched test files passed 144/144, but the workspace suite as a whole is unproven.
未审查（原文为英文）：test-efficacy — the probe harness could not be validated (harnessValidated: null): the positive control never ran because no probe file was green in the unmutated baseline (the probe runner tripped the repo's git-commit.ts generation guard), so this PR's test efficacy is unmeasured.
未审查：反向审计——评审时间预算不足，未能开始第 4 轮。
Test Plan（非阻断）：src/cli.test.ts — no such file or directory; src/config/top-level-options.test.ts — no such file or directory。
8 条 Suggestion 在已解析的 critical 发布下限之外被起草为行内评论；CLI 已将其移入下方延后清单（下限强制执行）。
收敛姿态下延后（第 7 轮，非阻断）——已记录，本轮不要求修改；其中 1 条 Critical 按其失败方向与对照基线延后——fails-closed 且 new-surface：未认证任何错误结果，且 merge base 既无该功能面也无该缺陷——作为后续工作记录在 findings 工件中：共 11 条（原文未翻译，列表见上方英文部分）。
收敛情况：第 7 轮发布了 5 条行内评论，其中 5 条是首次提出；上一轮发布了 0 条（其中 0 条首次提出）。发现反复回到同一批文件：packages/cli/src/agent-view/background-entry.ts（第 6 轮已出过发现，本轮又有 2 条）；packages/cli/src/cli.ts（第 2、6 轮已出过发现，本轮又有 2 条）。（证据说明：上一轮的数据来自并非本账号发布的标记，上述轮次与其计数可能不属于本账号。）一个不断再生兄弟发现的簇，通常意味着逐条修复只在处理同一根因的实例——先定位并处理该根因，或把独立的簇拆成单独的 PR，通常比逐条修复更快结束循环。（仅为观察——本轮评审未因此扣留任何内容。）
— qwen3.8-max via Qwen Code /review (v0.23.0)
| state.ownership === 'managed' && | ||
| state.projectCwd === resolvedCwd && | ||
| Date.parse(state.createdAt) >= since, |
There was a problem hiding this comment.
[Critical] R6-1: (fix-induced) [certifies-falsely] [new-surface] The guard added to close R6-1 filters only on ownership, projectCwd and createdAt, so it also matches a session row the supervisor has already patched to failed/exited. A launch that definitively failed is then certified as "may still be starting" and returns exit 2 — the code this module documents as do not retry.
markFailedSession (supervisor-process.ts:3612-3644) patches only sessionState, processState, updatedAt and lastError over ...existing, leaving ownership: 'managed', projectCwd and the original createdAt intact, so every post-record failure with a live supervisor still satisfies all three conditions. The server maps the handler throw to internal_error, not timeout (supervisor-server.ts:445-455), so this predicate alone decides. qwen --bg "audit the release" then blocks ~15 s, prints the in-flight sentence and exits 2, while qwen sessions ps lists the session as failed with its host retired: the CLI states the opposite of the product's own store, and a wrapper that should retry a transient host-launch failure is told not to. At the previous reviewed head aefdf88 the identical run returned exit 1 with the truthful Could not start a background session: ….
Witness:
$ node packages/cli/dist/index.js --bg "list the files in this directory" (built head 074599a, isolated HOME)
EXIT=2
stdout: (empty)
stderr: The background session may still be starting: Agent View worker a729376c-… did not
report ready before timeout.. Check: qwen sessions ps
store row: {"sessionState":"failed","processState":"exited","ownership":"managed",
"lastError":{"code":"pty_launch_failed"}}
15.2 s record→failure; pgrep afterwards showed only the supervisor — no host, no worker
Exclude the terminal states the supervisor itself writes, so only a record left behind by a supervisor that died mid-dispatch qualifies:
const TERMINAL_SESSION_STATES = new Set(['failed', 'stopped', 'completed']);
// …
state.ownership === 'managed' &&
!TERMINAL_SESSION_STATES.has(state.sessionState) &&
state.projectCwd === resolvedCwd &&
Date.parse(state.createdAt) >= since,Please do not narrow this to sessionState === 'starting' instead: when a failure lands after readyCompleted = true (supervisor-process.ts:487) the rollback at :513 is skipped, the worker is alive and the row reads idle/working, and that case genuinely needs the exit-2 answer.
markFailedSession returns { sessionState: 'failed', processState: 'exited', updatedAt, lastError } with no ownership change (supervisor-process.ts:3634-3640) and the terminal spellings are 'completed' | 'stopped' | 'failed' (protocol.ts:15-22), so the state fields are the only discriminator; the pre-record rollback cleanupFailedDispatchCreation (supervisor-dispatch.ts:145-172) does set ownership: 'unmanaged', so that path must keep reading as not recorded. Please add a case to background-entry.test.ts with listAgentViewSessionStates resolving [recordedSession({ sessionState: 'failed' })] and supervisorDispatch rejecting with an internal_error-coded error, asserting code === 1 — and confirm it goes red when the terminal-state clause is removed, while reports a supervisor that died after recording the session as in flight, not failed stays green at exit 2.
中文说明
为修复 R6-1 而新增的这个判定只过滤了 ownership、projectCwd 和 createdAt，因此它同样会匹配到 supervisor 已经改写为 failed/exited 的 session 行。一次已经确定失败的启动会被认证为「可能仍在启动中」并返回退出码 2 —— 而本模块的文档把 2 定义为不要重试。
markFailedSession（supervisor-process.ts:3612-3644）只在 ...existing 之上改写 sessionState、processState、updatedAt 和 lastError，保留了 ownership: 'managed'、projectCwd 和原始的 createdAt，所以只要 supervisor 还活着，任何「记录之后」的失败仍然满足全部三个条件。服务端会把 handler 抛出的错误映射为 internal_error 而不是 timeout（supervisor-server.ts:445-455），因此完全由这个判定来决定结果。于是 qwen --bg "audit the release" 会阻塞约 15 秒、打印「可能仍在启动中」并以 2 退出，而 qwen sessions ps 里该 session 显示为 failed、host 已回收：CLI 陈述了与产品自身存储相反的事实，并且告诉一个本应重试瞬时 host 启动失败的包装脚本「不要重试」。在上一次审查的 head aefdf88 上，同样的运行返回退出码 1，并给出真实的信息 Could not start a background session: …。
修法：排除 supervisor 自己写入的终止状态，使只有「supervisor 在 dispatch 中途死掉所留下的记录」才算数（见上方代码）。请不要改成只允许 sessionState === 'starting'：当失败发生在 readyCompleted = true（supervisor-process.ts:487）之后时，:513 的回滚会被跳过，worker 仍然存活、该行读作 idle/working，这种情况确实需要退出码 2 的答案。
约束：markFailedSession 返回的对象不改动 ownership（supervisor-process.ts:3634-3640），终止状态拼写为 'completed' | 'stopped' | 'failed'（protocol.ts:15-22），因此状态字段是唯一的区分手段；记录前的回滚 cleanupFailedDispatchCreation（supervisor-dispatch.ts:145-172）确实会把 ownership 置为 'unmanaged'，所以那条路径必须继续读作「未记录」。请在 background-entry.test.ts 中补一个用例：让 listAgentViewSessionStates 返回 [recordedSession({ sessionState: 'failed' })]、supervisorDispatch 以带 internal_error code 的错误 reject，断言 code === 1；并确认移除终止状态条件后该用例变红，而 reports a supervisor that died after recording the session as in flight, not failed 仍然以退出码 2 保持绿色。
— qwen3.8-max via Qwen Code /review (v0.23.0)
| const backgroundFlag = backgroundFlagIndex(argv); | ||
| if (backgroundFlag === -1 || versionToken < backgroundFlag) { | ||
| return 'version'; |
There was a problem hiding this comment.
[Critical] R6-3: (fix-induced) [certifies-falsely] [regression] The order-aware exception that closed R6-3 is scoped by token position only, not by whether the argv is a --bg launch at all — so a subcommand-led argv that merely contains a --bg token loses the version intercept and executes the subcommand, which is the demote-then-execute direction the intercept's own comment calls fail-open.
versionTokenIndex returns the index of -v and backgroundFlagIndex the index of --bg; the intercept is skipped whenever versionToken > backgroundFlag, and firstArg === 'mcp' then routes to runMcpFastPath (cli.ts:523). That parser is built .version(false) with a .fail() that only writes stderr, shows help and sets process.exitCode = 1 without exiting, so the strict Unknown arguments: bg, v failure does not stop the command — yargs runs kRunValidation/kPostProcess around runCommand (yargs-factory.js:1386-1387, 1472-1490) and helpOnly is false because .version(false) makes versionOptSet false. The exception's stated justification does not cover this case: the --bg gate lives inside if (route === 'default') (cli.ts:653) and never sees an mcp route. (The serve spelling was checked and is benign — qwen serve --bg --version still prints the version — so the confirmed harm is the mcp fast path.)
Witness:
built head 074599a, fresh HOME per row:
PR: qwen mcp add victim node --bg -v
EXIT=0 stdout: MCP server "victim" added to user settings. (stdio)
$HOME/.qwen/settings.json written:
{"mcpServers":{"victim":{"command":"node","args":["--bg","-v"]}}}
PR, pinned neighbour: qwen mcp add victim2 node -v
EXIT=0 stdout: 0.23.0 no settings.json written
PR: qwen mcp remove victim --bg -v
EXIT=1 stdout: mcp-remove usage stderr: Unknown arguments: bg, v
parser-shape probe (.version(false) .strict() .exitProcess(false), log-only .fail()):
FAIL: Unknown arguments: bg, v
HANDLER RAN name=victim
| const backgroundFlag = backgroundFlagIndex(argv); | |
| if (backgroundFlag === -1 || versionToken < backgroundFlag) { | |
| return 'version'; | |
| const backgroundFlag = backgroundFlagIndex(argv); | |
| const firstPositional = firstPositionalArgIndex(argv); | |
| const flagLedBackgroundLaunch = | |
| backgroundFlag !== -1 && | |
| (firstPositional === -1 || firstPositional > backgroundFlag); | |
| if (!flagLedBackgroundLaunch || versionToken < backgroundFlag) { | |
| return 'version'; |
This must not flip the orderings already pinned: runCliEntry(['--version', BACKGROUND_FLAG]) prints the version (cli.test.ts:1382-1387), runCliEntry([BACKGROUND_FLAG,'-v','audit']) asserts stdout does not contain 9.9.9 and stderr contains does not honor -v (cli.test.ts:1456-1470), and resolveBootstrapRoute(['mcp','remove','victim','-v','help']) === 'version' (cli.test.ts:613), whose comment records the probe this intercept exists for. Please add expect(resolveBootstrapRoute(['mcp','remove','victim','--bg','-v'])).toBe('version') beside that block and confirm it goes red against the code as it stands and red again if the firstPositional > backgroundFlag clause is removed.
中文说明
修复 R6-3 时加入的「按顺序判定」的例外，只按 token 的位置来限定作用域，而没有判断这个 argv 到底是不是一次 --bg 启动 —— 于是一个以子命令开头、仅仅包含 --bg token 的 argv 会丢掉 version 拦截，并真的执行该子命令，这正是拦截逻辑自身注释里称为 fail-open 的「降级后执行」方向。
versionTokenIndex 返回 -v 的下标，backgroundFlagIndex 返回 --bg 的下标；只要 versionToken > backgroundFlag，拦截就被跳过，随后 firstArg === 'mcp' 会走到 runMcpFastPath（cli.ts:523）。该 parser 以 .version(false) 构建，其 .fail() 只写 stderr、显示帮助并设置 process.exitCode = 1 而不退出，所以 strict 校验的 Unknown arguments: bg, v 并不能阻止命令执行 —— yargs 在 runCommand 外围绕运行 kRunValidation/kPostProcess（yargs-factory.js:1386-1387, 1472-1490），并且因为 .version(false) 使 versionOptSet 为 false，helpOnly 也为 false。该例外所声称的理由并不覆盖这种情况：--bg 判定门位于 if (route === 'default') 内部（cli.ts:653），根本看不到 mcp 路由。（serve 的拼写已经验证过是无害的 —— qwen serve --bg --version 仍会打印版本号 —— 所以已确认的危害在 mcp 快速路径上。）
修法见上方 suggestion：把例外限定在「以 flag 开头的 background 启动」上，复用拦截逻辑已经在用的 positional 判定。
约束：不能翻转已经固定的顺序行为 —— runCliEntry(['--version', BACKGROUND_FLAG]) 要打印版本号（cli.test.ts:1382-1387）；runCliEntry([BACKGROUND_FLAG,'-v','audit']) 断言 stdout 不含 9.9.9 且 stderr 含 does not honor -v（cli.test.ts:1456-1470）；resolveBootstrapRoute(['mcp','remove','victim','-v','help']) === 'version'（cli.test.ts:613），其注释记录了这个拦截存在的理由。请补上 expect(resolveBootstrapRoute(['mcp','remove','victim','--bg','-v'])).toBe('version')，并确认它在当前代码下变红、在移除 firstPositional > backgroundFlag 条件后再次变红。
— qwen3.8-max via Qwen Code /review (v0.23.0)
| const supervisor = await ensureAgentViewSupervisor(); | ||
| reachedDispatch = true; | ||
| ({ sessionId } = (await supervisor.dispatch(prompt, cwd)) as { |
There was a problem hiding this comment.
[Critical] R7-1: [certifies-falsely] [new-surface] The dispatch RPC this diff is the only production caller of can never complete — nothing in production sends the workerEvent {type:'ready'} the handler blocks on — so qwen --bg "<prompt>" still never starts a session, while the doc lines this diff adds promise a started session and a working / needs input readout that has no producer.
The incident the description narrates is fixed: the supervisor now serves instead of dying in .strict(). A second gate fires behind it. Production runAgentViewSupervisor builds the handler with only globalDir/hibernationPolicy/onShutdown (supervisor-runner.ts:145-172), and launchPtyHost is an injected test seam, so shouldWaitForWorkerReady = (waitForWorkerReady ?? !launchPtyHost) is true (supervisor-process.ts:3470-3474). promptInArgv is therefore false (:429) and the prompt is stripped from the worker argv, delivered only by queuePromptForSession after ready (:490-492). await ready (:481/487) rejects after DEFAULT_WORKER_READY_TIMEOUT_MS = 15_000 unless a workerEvent {type:'ready'} arrives, and resolvePendingWorkerReady is called only inside if (event.type === 'ready') (:845-849). Nothing can emit one: the sole gateway sendAgentViewWorkerEvent (worker-sideband.ts:107-122) is called in production exactly twice from inside its own module, with type: 'state' (:204) and 'heartbeat' (:244). So every --bg launch blocks ~15 s, records a session, marks it failed, and prints no session id — against settings.md:806 ("returns once the worker has started, printing the session id") and commands.md:755-757, both added by this diff.
Witness:
repo-wide sweep (oracle: grep over packages/**/*.ts*, 91 hits):
reportAgentViewWorkerState / startAgentViewWorkerHeartbeat /
readAgentViewWorkerControlEvents / isAgentViewWorkerEnv
-> ZERO production callers outside worker-sideband.ts
(every hit is a definition or internal call there, or a line of worker-sideband.test.ts)
live run of the built head, isolated HOME:
$ node packages/cli/dist/index.js --bg "list the files in this directory"
EXIT=2 stdout: (empty) no worker or host process alive
store lastError.message: "Agent View worker a729376c-… did not report ready before timeout."
.qwen/jobs/<id>/launch.json argv:
["/usr/bin/node","…/dist/index.js","--session-id","a729376c-…"]
-> no --prompt-interactive=<prompt>, confirming promptInArgv is false in production
This needs an author design decision, one of: (a) give the worker a ready producer — wire the sideband reporter into the interactive startup path for a process launched as an Agent View worker, so the session emits ready (and thereafter state) to QWEN_AGENT_VIEW_SIDEBAND; or (b) run the --bg dispatch with waitForWorkerReady: false, which also makes promptInArgv true and yields exactly the argv the description documents (--session-id <id> --prompt-interactive=<prompt>), returning once the PTY host is up. Until one lands, the two doc rows this diff adds should not promise a started session or a working readout.
Note the constraint on option (b): promptInArgv is !shouldWaitForWorkerReady(this.options) (supervisor-process.ts:429), so it also puts the prompt in the worker argv, where MAX_ARGV_PROMPT_BYTES = 16 * 1024 (supervisor-dispatch.ts:36, enforced at :47-55) starts applying to --bg prompts the ready-wait path never size-checked. No existing test can pin either fix, which is the shape of the defect — background-entry.test.ts mocks ./supervisor-runner.js wholesale and supervisor-process.test.ts either stubs launchPtyHost (turning the ready wait off) or hand-sends handler.workerEvent({type:'ready'}). The witness this owes is an integration test that starts the real supervisor (runAgentViewSupervisor({ globalDir }), no launchPtyHost stub), calls ensureAgentViewSupervisor() then dispatch(prompt, cwd), and asserts the RPC resolves with a sessionId inside the ready budget and that the persisted state.json is not sessionState: 'failed'; with the gap in place that test times out.
中文说明
本次改动是这条 dispatch RPC 在生产代码中唯一的调用方，而这条 RPC 永远无法完成 —— 生产中没有任何代码会发送 handler 所阻塞等待的 workerEvent {type:'ready'} —— 所以 qwen --bg "<prompt>" 依然不会真正启动一个 session；但本次改动新增的文档却承诺「worker 启动后返回并打印 session id」，以及一个并无生产者的 working / needs input 状态读数。
PR 描述中所叙述的那个故障确实被修复了：supervisor 现在能正常服务，而不再死在 .strict() 上。但它背后还有第二道门。生产环境的 runAgentViewSupervisor 构建 handler 时只传了 globalDir/hibernationPolicy/onShutdown（supervisor-runner.ts:145-172），而 launchPtyHost 是注入式的测试接口，因此 shouldWaitForWorkerReady = (waitForWorkerReady ?? !launchPtyHost) 为 true（supervisor-process.ts:3470-3474）。于是 promptInArgv 为 false（:429），prompt 被从 worker argv 中剥离，只能在 ready 之后由 queuePromptForSession 投递（:490-492）。await ready（:481/487）在 DEFAULT_WORKER_READY_TIMEOUT_MS = 15_000 之后 reject，除非收到 workerEvent {type:'ready'}；而 resolvePendingWorkerReady 只在 if (event.type === 'ready') 分支内被调用（:845-849）。没有任何代码能发出该事件：唯一的出口 sendAgentViewWorkerEvent（worker-sideband.ts:107-122）在生产中只被其自身模块内部调用两次，分别是 type: 'state'（:204）和 'heartbeat'（:244）。因此每次 --bg 启动都会阻塞约 15 秒、记录一个 session、把它标记为 failed，并且不打印任何 session id —— 这与本次改动新增的 settings.md:806 和 commands.md:755-757 相矛盾。
修法需要作者做设计决策，二选一：(a) 给 worker 一个 ready 生产者 —— 把 sideband 上报接入以 Agent View worker 身份启动的进程的交互式启动路径，使该 session 向 QWEN_AGENT_VIEW_SIDEBAND 发出 ready（此后发出 state）；或 (b) 让 --bg 的 dispatch 以 waitForWorkerReady: false 运行，这同时会使 promptInArgv 为 true，从而得到描述中所记载的 argv（--session-id <id> --prompt-interactive=<prompt>），并在 PTY host 起来后返回。在两者之一落地之前，本次改动新增的那两行文档不应承诺「已启动的 session」或 working 读数。
方案 (b) 的约束：promptInArgv 就是 !shouldWaitForWorkerReady(this.options)（supervisor-process.ts:429），所以它同时会把 prompt 放进 worker argv，于是 MAX_ARGV_PROMPT_BYTES = 16 * 1024（supervisor-dispatch.ts:36，在 :47-55 强制执行）开始适用于 --bg 的 prompt，而 ready 等待路径从未对其做长度检查。现有测试都无法固定这两种修法，这正是该缺陷的形态 —— background-entry.test.ts 把 ./supervisor-runner.js 整体 mock 掉，而 supervisor-process.test.ts 要么打桩 launchPtyHost（从而关闭 ready 等待），要么手工发送 handler.workerEvent({type:'ready'})。这里应补的是一个集成测试：启动真实的 supervisor（runAgentViewSupervisor({ globalDir })，不打桩 launchPtyHost），调用 ensureAgentViewSupervisor() 再调用 dispatch(prompt, cwd)，断言 RPC 在 ready 预算内返回 sessionId，且持久化的 state.json 不是 sessionState: 'failed'；在该缺口存在时这个测试会超时。
— qwen3.8-max via Qwen Code /review (v0.23.0)
| const promptInsideFlagToken = | ||
| backgroundFlagPromptWord(argv[backgroundFlag] ?? '') !== undefined; | ||
| const helpRequested = | ||
| flagIndex( | ||
| promptInsideFlagToken ? argv : argv.slice(0, backgroundFlag), |
There was a problem hiding this comment.
[Critical] R7-2: [certifies-falsely] [new-surface] The help-scan scope switch keys on the flag's token form rather than on whether positional prompt words follow it, so every attached --bg= spelling followed by prompt words gets the whole-argv --help scan and silently drops the launch: exit 0, top-level help rendered, no session, no diagnostic. The bare spelling of the identical prompt declines by name with exit 1.
The premise in the comment above this line is that an attached token "consumes no positional words … the tokens after it are still flags", but readBackgroundPrompt joins every trailing positional behind an attached prompt — a contract this PR's own test pins at background-entry.test.ts:158-161 (readBackgroundPrompt(['--bg=audit','the','release']) → { prompt: 'audit the release' }, "Trailing positionals still join behind the attached prompt"). So promptInsideFlagToken is true for both attached forms and flagIndex scans the whole argv, matching a --help/-h that is a prompt word. This includes the empty attached spelling --bg= — the wrapper shape entry-flags.ts:33 documents (qwen --bg=$ENABLED "$TASK" with ENABLED unset), because backgroundFlagPromptWord('--bg=') returns '', which is !== undefined.
Witness:
real built CLI at HEAD, isolated HOME:
$ qwen --bg=audit add a --help section to the README
EXIT=0 stdout: 80 lines beginning 'Usage: qwen [options] [command]' stderr: (empty)
$ qwen --bg= add a --help section to the README
EXIT=0 same 80-line help stderr: (empty)
$ qwen --bg add a --help section to the README # control, bare spelling
EXIT=1 stderr: qwen --bg runs only the prompt and does not honor --help.
Re-run without it, or pass prompt words after --.
mocked-harness probe at HEAD:
{"mainCalls":1,"dispatchCalls":[],"exitCode":null,"stderr":""}
A wrapper's qwen --bg="$TASK" … && notify therefore reports success with nothing running, while the same prompt one keystroke away (--bg "$TASK" instead of --bg="$TASK") fails loudly. Bound the attached spelling's scan at the first prompt word after the flag rather than keying on where the prompt sits:
const carriedWord = backgroundFlagPromptWord(argv[backgroundFlag] ?? '');
let helpScanEnd = backgroundFlag;
if (carriedWord !== undefined) {
helpScanEnd = argv.length;
for (let i = backgroundFlag + 1; i < argv.length; i++) {
if (!argv[i]!.startsWith('-')) {
helpScanEnd = i;
break;
}
}
}
const helpRequested =
flagIndex(argv.slice(0, helpScanEnd), '--help', '-h') !== -1;The narrower variant — treating an empty carried word as no word — was measured insufficient: it flips the --bg= symptom but the --bg=audit add --help section one survives. The bound must stop at the first prompt word after the flag, not at the flag itself, because cli.test.ts:1416-1427 pins that ['--help','--bg=audit'] and ['-h','--bg=audit'] must not dispatch and must reach the full parser (expect(mocks.main).toHaveBeenCalledTimes(1)), and the --bg=x --help ordering must keep falling through to the parser. cli.test.ts:1438 (['--bg','add','--help','section'] → exit 1, does not honor --help) must stay green too, and entry-flags.ts:34-36 keeps every non-literal attached value as prompt data so --bg=-repro still works. Please add a twin of the bare-form pin at :1428 — runCliEntry(['--bg=audit','add','--help','section']) asserting mocks.runBackgroundDispatch not called, mocks.main not called, process.exitCode === 1 and stderr containing does not honor --help — and confirm it is red against the code as it stands and red again if the bound is removed.
中文说明
help 扫描范围的选择依据的是 flag 的token 形态，而不是它后面是否跟着 positional 的 prompt 词，因此所有「带附加值的 --bg=」拼写只要后面跟着 prompt 词，就会对整个 argv 做 --help 扫描，从而静默丢弃这次启动：退出码 0、渲染顶层帮助、没有 session、没有任何诊断信息。而同一个 prompt 用裸 flag 拼写时，会被指名拒绝并返回退出码 1。
这段代码上方注释的前提是「带附加值的 token 不消耗 positional 词……它后面的 token 仍然是 flag」，但 readBackgroundPrompt 会把所有尾随的 positional 词拼接到附加 prompt 之后 —— 这一约定正是本 PR 自己的测试在 background-entry.test.ts:158-161 固定的（readBackgroundPrompt(['--bg=audit','the','release']) → { prompt: 'audit the release' }，注释为「Trailing positionals still join behind the attached prompt」）。所以两种附加形态下 promptInsideFlagToken 都为 true，flagIndex 会扫描整个 argv，从而匹配到作为 prompt 词出现的 --help/-h。这也包括空的附加拼写 --bg= —— 即 entry-flags.ts:33 所记载的包装脚本形态（qwen --bg=$ENABLED "$TASK" 且 ENABLED 未设置），因为 backgroundFlagPromptWord('--bg=') 返回 ''，而它 !== undefined。
于是包装脚本的 qwen --bg="$TASK" … && notify 会在什么都没运行的情况下报告成功，而只差一次按键的同一个 prompt（--bg "$TASK" 而非 --bg="$TASK"）会大声失败。
修法：把附加拼写的扫描边界设在 flag 之后的第一个 prompt 词处，而不是依据 prompt 位于何处（见上方代码）。更窄的变体 —— 把空的附加值视作「没有词」—— 经实测不足够：它能翻转 --bg= 的症状，但 --bg=audit add --help section 的症状仍然存在。边界必须停在 flag 之后的第一个 prompt 词，而不是 flag 本身，因为 cli.test.ts:1416-1427 固定了 ['--help','--bg=audit'] 与 ['-h','--bg=audit'] 不得 dispatch 且必须走到完整 parser（expect(mocks.main).toHaveBeenCalledTimes(1)），并且 --bg=x --help 的顺序必须继续落到 parser 上。cli.test.ts:1438（['--bg','add','--help','section'] → 退出码 1、does not honor --help）也必须保持绿色；entry-flags.ts:34-36 保证所有非字面量的附加值都是 prompt 数据，所以 --bg=-repro 仍然可用。请补一个与 :1428 裸拼写固定用例对称的测试：runCliEntry(['--bg=audit','add','--help','section'])，断言未调用 mocks.runBackgroundDispatch、未调用 mocks.main、process.exitCode === 1 且 stderr 含 does not honor --help；并确认它在当前代码下变红、在移除该边界后再次变红。
— qwen3.8-max via Qwen Code /review (v0.23.0)
| const BACKGROUND_FLAG_OFF_VALUES = new Set(['false', '0']); | ||
| const BACKGROUND_FLAG_ON_VALUES = new Set(['true', '1']); |
There was a problem hiding this comment.
[Critical] R7-3: [certifies-falsely] [new-surface] The attached-value boolean literal sets hold four exact lowercase literals matched case-sensitively, while the type: 'boolean' declaration they cite as authority coerces every attached value except exact 'true' to false — so the off and on spellings a wrapper actually emits are read as prompt data and dispatch a corrupted launch certified with exit 0.
A Python orchestrator building argv with f"--bg={enabled}" produces --bg=False / --bg=True; PowerShell "$false", .NET bool.ToString() and Make/CI ENABLED=FALSE produce the same shapes. isBackgroundFlagToken('--bg=False') is true ('False' is not in the OFF set), so backgroundFlagIndex fires the gate, backgroundFlagPromptWord returns 'False' as a prompt word, and runBackgroundDispatch starts a supervisor, records a session, spawns a worker on the prompt False audit the release, burns quota on a task the caller asked to have off, then prints Started background session … and exits 0. The mirror case --bg=True launches as intended but glues the literal onto the prompt, so the agent runs on True audit the release. --bg=off, --bg=no and the empty --bg= behave the same way. That is word-for-word the incident this PR added the OFF guard and its test to close (background-entry.test.ts:164-174: "dispatched a real agent … quota burned — and certified it with exit 0"), and no existing arm catches it: :170-190 pins only lowercase false/0/true/1, while the --bg=falsey arm at :187 makes the literal-only rule look deliberate and complete.
Witness:
classification probe against the real functions at HEAD:
{"token":"--bg=False","isLaunch":true,"word":"False",
"read":{"prompt":"False audit the release"}}
identically for --bg=FALSE, --bg=True, --bg=TRUE, --bg=off, --bg=no
--bg=false and --bg=0 -> isLaunch:false
entry level, dispatch mocked:
PROBE C2 {"token":"--bg=False","dispatchCalls":[["False audit the release"]],
"mainCalls":0,"exitCode":0}
the cited authority — real installed yargs-parser with {boolean:['bg']}:
--bg=False -> bg:false | FALSE -> false | True -> false | off -> false
no -> false | --bg= -> false | 0 -> false | 1 -> false
only --bg=true -> bg:true
Normalize for the set lookup only, and widen the literals:
const BACKGROUND_FLAG_OFF_VALUES = new Set(['false', '0', 'off', 'no', 'n']);
const BACKGROUND_FLAG_ON_VALUES = new Set(['true', '1', 'on', 'yes', 'y']);
export function isBackgroundFlagToken(token: string): boolean {
const attached = backgroundFlagAttachedValue(token);
if (attached === undefined) return token === BACKGROUND_FLAG;
return !BACKGROUND_FLAG_OFF_VALUES.has(attached.toLowerCase());
}
export function backgroundFlagPromptWord(token: string): string | undefined {
const attached = backgroundFlagAttachedValue(token);
if (
attached === undefined ||
BACKGROUND_FLAG_ON_VALUES.has(attached.toLowerCase())
) {
return undefined;
}
return attached;
}Two things this must not do. Do not add '' to the OFF set: measured, that makes --bg= stop being a launch and land on the strict parser's Unknown argument: bg, trading the usage line for a worse error. And do not mirror yargs wholesale — it coerces --bg=1 to false, so turning 1 off would break the affirmative wrapper the ON set exists for. The lowercase must also be applied to the set lookup only, never to the returned prompt word, or --bg=-Repro would dispatch -repro. background-entry.test.ts:187 pins readBackgroundPrompt(['--bg=falsey']) → { prompt: 'falsey' } and :184 pins --bg=-repro → { prompt: '-repro' }, so the match must stay exact-literal on the normalized value — a prefix rule, includes, startsWith or Boolean()-style coercion reds those arms. Please add expect(readBackgroundPrompt(['--bg=False','audit the release'])).toBeUndefined(), the same for --bg=off, and expect(readBackgroundPrompt(['--bg=True','audit the release'])).toEqual({ prompt: 'audit the release' }) to that block, and confirm removing the .toLowerCase() turns all three red while every existing arm stays green (measured with the fix: cli.test.ts 118/118 and background-entry.test.ts 21/21).
中文说明
附加值的布尔字面量集合只有四个精确的小写字面量，且区分大小写匹配；而它们援引为权威的 type: 'boolean' 声明，会把除精确 'true' 之外的所有附加值都强制转为 false —— 因此包装脚本实际会产出的「关」和「开」拼写被当成 prompt 数据，从而派发一次内容被污染的启动，并以退出码 0 认证成功。
用 f"--bg={enabled}" 构造 argv 的 Python 编排脚本会产出 --bg=False / --bg=True；PowerShell 的 "$false"、.NET 的 bool.ToString() 以及 Make/CI 的 ENABLED=FALSE 会产生同样的形态。isBackgroundFlagToken('--bg=False') 为 true（'False' 不在 OFF 集合中），于是 backgroundFlagIndex 触发判定门，backgroundFlagPromptWord 把 'False' 作为 prompt 词返回，runBackgroundDispatch 启动 supervisor、记录 session、以 prompt False audit the release 派生 worker，在一个调用方明确要求关闭的任务上消耗配额，然后打印 Started background session … 并以 0 退出。镜像情况 --bg=True 会按预期启动，但把字面量粘到 prompt 上，于是 agent 运行在 True audit the release 上。--bg=off、--bg=no 和空的 --bg= 行为相同。这正是本 PR 新增 OFF 守卫及其测试所要关闭的事故（background-entry.test.ts:164-174：「dispatched a real agent … quota burned — and certified it with exit 0」），而现有任何用例都抓不到它：:170-190 只固定了小写的 false/0/true/1，而 :187 的 --bg=falsey 用例让「仅字面量」规则看起来是刻意且完整的。
修法：只对集合查找做小写归一化，并扩充字面量（见上方代码）。有两件事不能做：不要把 '' 加进 OFF 集合 —— 实测这会让 --bg= 不再算作启动，并落到 strict parser 的 Unknown argument: bg 上，把用法提示换成更糟的错误；也不要完全照搬 yargs —— 它会把 --bg=1 强制转为 false，所以把 1 当作关闭会破坏 ON 集合本来要服务的「肯定式」包装脚本。小写化也只能用于集合查找，绝不能用于返回的 prompt 词，否则 --bg=-Repro 会派发 -repro。background-entry.test.ts:187 固定了 readBackgroundPrompt(['--bg=falsey']) → { prompt: 'falsey' }，:184 固定了 --bg=-repro → { prompt: '-repro' }，所以匹配必须保持对归一化值的精确字面量比较 —— 前缀规则、includes、startsWith 或 Boolean() 式转换都会让这些用例变红。请在该块中补上 expect(readBackgroundPrompt(['--bg=False','audit the release'])).toBeUndefined()、对 --bg=off 的同样断言，以及 expect(readBackgroundPrompt(['--bg=True','audit the release'])).toEqual({ prompt: 'audit the release' })；并确认移除 .toLowerCase() 后这三条都变红，而所有现有用例仍然绿色（带上该修法实测：cli.test.ts 118/118、background-entry.test.ts 21/21）。
— qwen3.8-max via Qwen Code /review (v0.23.0)
3 participants
What this PR does
Stack position 2/2. Parent: #10942 — review that first; this PR's diff is only the commit on top.
Adds
qwen --bg "<prompt>": it starts a background Agent View session, prints the session id and returns. The session outlives the shell it was started from, andqwen sessions ps(the parent PR) lists it and says whether it is working or has stopped to ask something.It also fixes the reason none of this could run. The supervisor spawns itself as
qwen --internal-agent-view-supervisor(supervisor-runner.ts:107) and nothing parsed that flag. The CLI's parser runs.strict(), so the process spawned to be a supervisor exited on an unknown argument instead of serving, and every path that dispatches a session waited on a supervisor that could never start. The entry now recognizes the flag and serves.Why it's needed
The infrastructure has been merged and unreachable for weeks: the supervisor runtime (#7799), the PTY workers (#7800) and the session lifecycle (#7801, re-landed as #9986) all shipped, and
dispatchAgentViewSessionalready records everything a supervisor needs to spawn a session. What was missing was two wires at the entry — one internal, one user-facing. This adds both, so the merged code runs end to end for the first time.The parent PR gave the subsystem a reader; this gives it a writer. Together they are the smallest thing that is actually useful: start work in the background, see what it is doing.
There is also a second, unplanned consequence worth naming, because it decides how this feature relates to cross-session messaging. A background worker is launched as
qwen --session-id <id> --prompt-interactive=<prompt>(supervisor-dispatch.ts:196), which is a full interactive session — so it registers in the live-process registry (startInteractiveUI.tsx:421, unconditional) and, whenagents.crossSessionMessagingis on, binds a peer inbox. A--bgsession therefore appears in another session'slist_agentsand can be addressed withsend_message, with no further work. That is not a feature this PR adds; it is what these two existing tracks do once the entry is wired.Two details worth the reviewer's attention:
--.qwen -p x -- --bgpasses--bgas the user's own data; hijacking that launch into a dispatch would be a bug with no way for the user to work around it.Both entry points sit before the argv parser and behind a raw-argv scan, so an ordinary launch pays one
Array.includesand loads none of this.--bgneeds a prompt and a directory; routing it through the interactive startup path — auth, theme, extensions — would buy nothing and cost all of it. The flag is still declared in the option tables so--helplists it and the strict parser knows it. The internal flag moves to its own module so the entry can recognize it without importing the supervisor runtime on every launch.Reviewer Test Plan
How to verify
Unit level, from
packages/cli:npx vitest run src/cli.test.ts src/agent-view/ src/commands/sessions/ --coverage.enabled=false→ 19 files, 455 tests passing, 13 of them new inbackground-entry.test.ts: the prompt is read from the positional query and joined; a flag's value is not swallowed in either the detached (--model x) or attached (--model=x) form; a boolean flag consumes nothing; nothing past--is scanned; a bare--bgreports an empty prompt rather than guessing; the supervisor is ensured before the session is recorded; a supervisor that will not start is reported as a reason, not a stack, and dispatches nothing.npx vitest run src/config/top-level-options.test.tspasses with the new flag declared.End to end, on a build of this branch:
qwen --bg "list the files in this directory"printsStarted background session <id>.qwen sessions pslists it, initially asworking.ps aux | grep internal-agent-view-supervisorshows the supervisor serving — before this PR, that process exited immediately with an unknown-argument error.qwen --bgwith no prompt prints the usage and exits 1 without starting a supervisor.qwen -p "hello" -- --bgruns the ordinary non-interactive path, not a dispatch.Evidence (Before & After)
Before:
qwen --bg "..."→Unknown argument: bg. The supervisor, when something did try to spawn it, exited the same way on its own internal flag.After:
Not a live capture: the machine this was written on cannot build the CLI (see below), so both blocks are the documented and unit-tested shapes. Steps 1–5 above need a real build and are the substance of what a reviewer should confirm.
Tested on
Unit tests only, on Linux.
npx tsc --noEmitandnpm run buildwere not run — this machine cannot complete either — so the end-to-end steps above are unverified and need CI or a reviewer with a build. Foursrc/config/*.test.tsfiles cannot be collected in this environment at all (an unbuilt workspace dependency), with and without this change alike.Environment (optional)
Linux, vitest only.
Risk & Scope
--bgafter--falls through to the ordinary path, and an empty prompt is refused. The prompt reader models argv itself, which is the part most likely to be wrong; it is derived from the option tables rather than hand-listed for exactly that reason, and it is the bulk of the new tests.--bgtakes no--model, worktree or approval-mode options yet; it uses the defaults for the directory it is run in.--bgis new and experimental; the internal supervisor flag was already being spawned and simply never worked.Linked Issues
Builds on #10942. Makes the subsystem from #7799, #7800 and #7801/#9986 reachable. Related to #7802, which would add the rest of the command surface.
中文说明
这个 PR 做了什么
栈位置 2/2。父 PR：#10942 —— 请先看那个；本 PR 的 diff 只有叠在其上的这一个 commit。
新增
qwen --bg "<prompt>"：启动一个后台 Agent View session，打印 session id 后立即返回。该 session 的生命周期长于启动它的那个 shell，而qwen sessions ps（父 PR）会列出它，并说明它是在工作还是停下来在问你问题。本 PR 同时修复了「这一切此前根本跑不起来」的原因。supervisor 以
qwen --internal-agent-view-supervisor的形式自我 spawn（supervisor-runner.ts:107），而没有任何代码解析这个 flag。CLI 的解析器开着.strict()，因此那个本该成为 supervisor 的进程会因未知参数直接退出，而不是开始服务；于是每一条调度 session 的路径，都在等一个永远起不来的 supervisor。现在入口会识别该 flag 并进入服务。为什么需要
基础设施已经合并且不可达好几周了：supervisor runtime（#7799）、PTY workers（#7800）、session lifecycle（#7801，由 #9986 重新落地）全部已 ship，而
dispatchAgentViewSession早已记录了 supervisor spawn 一个 session 所需的全部信息。缺的只是入口处的两根线 —— 一根内部的，一根面向用户的。本 PR 把两根都接上，使已合并的代码第一次能端到端运行。父 PR 给了这个子系统一个读取方；本 PR 给它一个写入方。两者合起来是「真正有用」的最小集合：把活儿丢到后台，并能看见它在干什么。
还有一个计划外的结果值得点名，因为它决定了本功能与跨 session 通信的关系。后台 worker 是以
qwen --session-id <id> --prompt-interactive=<prompt>启动的（supervisor-dispatch.ts:196），那是一个完整的交互式 session —— 因此它会注册进 live-process registry（startInteractiveUI.tsx:421，无条件调用），并在agents.crossSessionMessaging打开时绑定 peer inbox。于是一个--bgsession 会出现在别的 session 的list_agents里，并可被send_message寻址，无需任何额外工作。这不是本 PR 新增的功能，而是入口接上之后，两条既有轨道本身的行为。有两处细节值得评审者留意：
--处停止。qwen -p x -- --bg是把--bg当作用户自己的数据传入的；把这样一次启动劫持成调度会是一个用户无从绕开的 bug。两个入口都位于 argv 解析器之前，且由一次原始 argv 扫描把守，因此普通启动只多付一次
Array.includes，不加载其中任何模块。--bg只需要一个 prompt 和一个目录；让它走交互式启动路径（认证、主题、扩展）不会带来任何收益，却要付出全部代价。该 flag 仍在 option 表中声明，因此--help会列出它，strict 解析器也认得它。内部 flag 被移到独立模块，使入口无需在每次启动时导入 supervisor 运行时即可识别它。评审者测试计划
如何验证
单测，在
packages/cli下：npx vitest run src/cli.test.ts src/agent-view/ src/commands/sessions/ --coverage.enabled=false→ 19 个文件、455 个测试通过，其中 13 个是background-entry.test.ts中的新用例：prompt 从位置参数读取并拼接；flag 的值不会被吞掉（分离式--model x与附着式--model=x都覆盖）；布尔 flag 不消耗值；--之后不再扫描；裸--bg报告空 prompt 而不是猜一个；supervisor 一定先于 session 记录被拉起；起不来的 supervisor 以原因而非堆栈报告，且不进行任何调度。npx vitest run src/config/top-level-options.test.ts在新 flag 声明后通过。端到端，在本分支的构建产物上：
qwen --bg "list the files in this directory"打印Started background session <id>。qwen sessions ps列出它，初始为working。ps aux | grep internal-agent-view-supervisor能看到 supervisor 正在服务 —— 在本 PR 之前，该进程会因未知参数立即退出。qwen --bg不带 prompt 时打印用法并以 1 退出，且不会启动 supervisor。qwen -p "hello" -- --bg走普通的非交互路径，而不是调度。证据（前后对比）
之前：
qwen --bg "..."→Unknown argument: bg。而 supervisor 在确有东西尝试 spawn 它时，也会因为自己的内部 flag 以同样方式退出。之后：
非实时截取：撰写本 PR 的机器无法构建 CLI（见下），因此以上两段都是文档与单测所钉住的形状。上面的第 1–5 步需要真实构建，也正是评审者应当确认的实质内容。
测试环境
仅 Linux 上的单元测试。
npx tsc --noEmit与npm run build未运行 —— 本机无法完成其中任何一个 —— 因此上述端到端步骤未经验证，需要 CI 或有构建环境的评审者。另有 4 个src/config/*.test.ts在本环境中完全无法收集（一个未构建的 workspace 依赖），且与本改动无关（改动前后表现一致）。运行环境（可选）
Linux，仅 vitest。
风险与范围
--之后的--bg会落回普通路径，空 prompt 会被拒绝。prompt 读取器自行建模了 argv，这是最可能出错的部分；正因如此它是从 option 表推导而非手工列举的，并且新增测试的主体都在覆盖它。--bg目前还不接受--model、worktree 或审批模式选项；它使用运行所在目录的默认配置。--bg是新增且实验性的；内部 supervisor flag 本来就已经在被 spawn，只是从未生效过。关联 Issue
基于 #10942。使 #7799、#7800、#7801/#9986 的子系统变得可达。与 #7802 相关 —— 那个 PR 会补齐其余的命令表面。