feat(cli): list managed Agent View sessions in qwen sessions ps

.qwen/skills/find-simplifications/SKILL.md

@@ -120,6 +120,7 @@ the issue comment.
 | Several strong candidates in one run                             | File them all; land at most one                            |
 | Report-only territory                                            | File with evidence, marked report-only. Never a PR         |
 | Path or symbol younger than ~90 days                             | Drop **silently** — unwired new feature, not rot           |
+| A young **subsystem** unwired, its wiring PR open and stale      | Not a deletion. Report the stall to that PR stack          |
 | A never-called migrator, validator, guard, or dropped wire-up    | Not cleanup. It may be a defect → `/bugfix` or `/review`   |
 | Any consumer cannot be named                                     | Drop                                                       |
 | Correct but tiny (one dead import, a typo)                       | Reject on the ledger: below both skills' intake bar        |

.qwen/skills/find-simplifications/references/survey.md

@@ -139,6 +139,33 @@ feature someone is still wiring up. (90 days is a heuristic, not a measured
 threshold; widen it for a large subsystem.) Proposing deletion of something
 that landed last week is the fastest way to lose a reviewer for good.
 
+But "young" is not the fact the gate is reaching for — "still being wired
+up" is, and the two come apart. A directory can keep growing for months
+while its consumer never lands, and then every re-run of this survey dates
+it young again and drops it again, which is how a subsystem gets to five
+figures with nothing calling it. So when the gate fires on a **subsystem**
+(not a single symbol), date the wiring rather than the code:
+
+```bash
+# has anything outside it ever referenced it? The two spellings differ on
+# purpose: `<dir>` is the full repo-relative path in the glob, while the
+# pattern is only its last segment, because an import specifier spells
+# '../agent-view/x.js' and never 'packages/cli/src/agent-view/'. Classify
+# the hits — a bare segment also reaches same-named directories elsewhere,
+# and cross-package consumers spell the package export subpath, so § 4's
+# corpus grep stays the authoritative consumer check.
+"$RG" -l '/<basename>/' --glob '!<dir>/**' packages
+# and are the PRs that would wire it still open?
+gh pr list --repo QwenLM/qwen-code --search '<feature> in:title' --state all
+```
+
+Recent commits inside the directory plus no external reference plus an open,
+stalled wiring PR is **not** a deletion candidate and **not** a drop. It is a
+different finding with a different owner: the wiring stalled. Report it to
+that stack — the merged infrastructure has no entry point — and never as a
+deletion PR. The code is wanted; the review that would connect it is what is
+missing.
+
 **3 — Published-surface escape.** Is the surface reachable from outside the
 repo? SKILL.md § Territory is the authoritative list; keep the two in step.
 Everything under `packages/core/src` is, via that package's `"./src/*"`
@@ -262,13 +289,27 @@ registry entry), not in `packages/core`, and `git log` puts it well past the
 recency gate. Deletion is the component, its test, and its snapshot entry, in
 one commit. This is what a filed candidate should look like.
 
-**2. Everything says dead; `git` says five days old.** `packages/cli/src/agent-view`
-is ~6,000 lines whose entry flag is passed to a spawned process but parsed
-nowhere; every static signal calls it rot. Then:
+**2. Everything says dead; `git` says five days old — and says it again a
+month later.** `packages/cli/src/agent-view` was ~6,000 lines whose entry flag
+is passed to a spawned process but parsed nowhere; every static signal called
+it rot. Then:
 `git log --follow --diff-filter=A --format=%ad --date=short -- packages/cli/src/agent-view
-| tail -1` → `2026-08-01`, five days before HEAD. It is a feature mid-wiring.
-**Drop silently.** Do not file it, do not mention it — a "should we delete
-your new subsystem?" question costs more trust than the finding is worth.
+| tail -1` → `2026-08-01`, five days before HEAD. A feature mid-wiring, so:
+**do not file a deletion.** A "should we delete your new subsystem?" question
+costs more trust than the finding is worth.
+
+What this example originally got wrong was the second half — "do not mention
+it". Measured again on 2026-09-04: **11,004 production lines, still zero
+external references**, up ~8,000 in four weeks. The five merged PRs of its
+stack shipped the supervisor, the PTY workers and the lifecycle; the two that
+would give it an entry point (#7802 commands, #7803 roster TUI) have been
+open since 2026-07-27, the second at +31,699 lines across 104 files and
+conflicting. The recency gate kept firing and the survey kept dropping it, so
+nothing ever said out loud that a five-figure subsystem had no caller.
+
+The deletion verdict was right and stays right. The silence was not: this is
+the stalled-wiring finding above, owed to that PR stack, not to a cleanup
+list.
 
 **3. The naive count is wrong in both directions.**
 `eslint.legacy-filenames.mjs` lists 559 bare basenames. Checking "does a

docs/users/features/commands.md

@@ -715,11 +715,11 @@ These commands are run from the shell as `qwen <subcommand>` before starting an
 
 ### Session Management
 
-| Command                     | Description                                 | Usage Examples                                                                   |
-| --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
-| `qwen sessions list`        | List recent conversation sessions           | `qwen sessions list`, `qwen sessions list --json --limit 50`                     |
-| `qwen sessions ps`          | List interactive sessions running right now | `qwen sessions ps`, `qwen sessions ps --json`                                    |
-| `qwen sessions controllers` | Manage trusted controller tokens            | `qwen sessions controllers add --label <name>`, `qwen sessions controllers list` |
+| Command                     | Description                         | Usage Examples                                                                   |
+| --------------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
+| `qwen sessions list`        | List recent conversation sessions   | `qwen sessions list`, `qwen sessions list --json --limit 50`                     |
+| `qwen sessions ps`          | List the sessions running right now | `qwen sessions ps`, `qwen sessions ps --json`                                    |
+| `qwen sessions controllers` | Manage trusted controller tokens    | `qwen sessions controllers add --label <name>`, `qwen sessions controllers list` |
 
 #### `qwen sessions list`
 
@@ -761,11 +761,20 @@ qwen sessions list --json | jq .
 
 #### `qwen sessions ps`
 
-Lists the Qwen Code sessions registered on this machine right now.
+Lists the Qwen Code sessions running on this machine right now.
 `sessions list` walks saved transcripts ("what have I worked on"); this
-walks the live-process registry ("what is running at this moment").
-Records left behind by a killed session are swept as they are found. A
-one-shot `qwen -p` run never registers, so it is never shown.
+answers "what is running at this moment".
+
+Two kinds of session are listed. An **interactive** session is one you
+started in a terminal; it registers in the live-process registry, and
+records left behind by a killed session are swept as they are found. A
+**managed** session is an Agent View session owned by a supervisor: it
+stores richer lifecycle state in the supervisor store, which the registry
+alone cannot provide. A session present in both sources is listed once, as
+managed. Managed sessions are listed first, because one of them may be
+waiting for an answer.
+
+Headless sessions (`qwen -p`) register nowhere and are not shown.
 
 **Flags:**
 
@@ -775,7 +784,7 @@ one-shot `qwen -p` run never registers, so it is never shown.
 
 **Human-readable output (default):**
 
-A table with columns: NAME, KIND, PID, AGE, DIRECTORY.
+A table with columns: NAME, KIND, PID, AGE, STATE, DIRECTORY.
 
 KIND says what registered the session — `tui` for someone at a terminal,
 `external` for a program that is not a Qwen Code session at all (a voice
@@ -785,22 +794,48 @@ program drives. Several `serve` or `headless` rows can share one PID: a
 the daemon spawned it, `headless` when a client is driving it directly —
 and each of them registers separately. It is a self-report, like NAME and DIRECTORY: every field
 here was written by the process it describes, and nothing about what a
-session is allowed to do depends on it. See
+session is allowed to do depends on it. A managed session has no registry
+record behind it, so nothing registered it and its KIND reads `managed`
+rather than borrowing a word some registrant wrote. See
 [Cross-Session Protocol](./cross-session-protocol.md) for the record
 format and for how to register a program of your own.
 
+STATE is `interactive` for a session you started yourself. For a managed
+session it is what that session is actually doing — `needs input`,
+`working`, `ready`, `stopped` or `failed`. Those are display labels; the
+`--json` output carries stable tokens instead (see below). PID and AGE print `-` for a
+managed session only when their own source value is unavailable: PID when
+there is no live worker process, and AGE when the creation stamp is unusable.
+
 **JSON output (`--json`):**
 
-Outputs JSON Lines on stdout, newest session first. Each line is a JSON
-object with fields:
+Outputs JSON Lines on stdout, managed sessions first. Every line carries
+a `managed` field saying which kind it is.
+
+An interactive session is emitted as its whole registry record, plus
+`managed: false`:
 
 ```
 schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
-qwenVersion, kind, ipcPath (when peer messaging is available)
+qwenVersion, kind, ipcPath (when peer messaging is available), managed
 ```
 
+A managed session is emitted in the managed row shape, even when the same
+session also has a registry record:
+
+```
+name, pid, startedAt, cwd, taskState, sessionId, managed
+```
+
+`taskState` is the machine-readable form of the STATE column, and is the
+field to script against: `running`, `waiting`, `ready`, `stopped` or
+`failed`. The column's wording can change; these tokens will not.
+
 Nothing else is written to stdout — an empty listing prints nothing at
-all — so `qwen sessions ps --json | jq .` is safe to script against.
+all — so `qwen sessions ps --json | jq .` is safe to script against. If
+the supervisor's own bookkeeping cannot be read, the interactive half is
+still listed and the reason is reported on stderr, which leaves stdout
+parseable.
 
 JSON output is raw data: field values are emitted exactly as recorded,
 with no terminal sanitization. Treat them as data, and sanitize before
@@ -816,6 +851,12 @@ qwen sessions ps
 # Note: `jq -r` renders the raw recorded value in your terminal (see the
 # raw-data note above); pipe through a sanitizer if the path is untrusted.
 qwen sessions ps --json | jq -r .cwd
+
+# Which background sessions are waiting on me?
+# Note: `jq -r` renders the raw recorded value in your terminal (see the
+# raw-data note above); a session name is session-generated text, so pipe
+# through a sanitizer if it is untrusted.
+qwen sessions ps --json | jq -r 'select(.taskState == "waiting") | .name'
 ```
 
 ## 6. Messaging Another Running Session

packages/cli/src/agent-view/presentation.ts

@@ -13,6 +13,15 @@ import type {
   AgentViewSessionStateFile,
 } from './protocol.js';
 
+/**
+ * Title shown for a session that has produced nothing to name it by.
+ *
+ * Exported because a caller that cannot afford an unidentifiable row —
+ * a one-line listing, where there is nothing to arrow onto — has to be
+ * able to recognize the placeholder and substitute the session id.
+ */
+export const AGENT_VIEW_UNTITLED_TITLE = 'Untitled session';
+
 export type AgentViewTaskState =
   | 'running'
   | 'waiting'
@@ -326,7 +335,7 @@ function deriveTitle(
     cleanText(rosterEntry?.displayName) ??
     cleanRuntimeSummary(activity?.summary) ??
     cleanText(launch?.initialPrompt) ??
-    'Untitled session'
+    AGENT_VIEW_UNTITLED_TITLE
   );
 }
 

packages/cli/src/agent-view/protocol.ts

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import * as path from 'node:path';
+
 export const AGENT_VIEW_PROTOCOL_VERSION = 1;
 
 export type AgentViewOwnership =
@@ -115,6 +117,28 @@ export interface AgentViewWorkerFile {
   schemaVersion: 1;
   hostPid?: number;
   workerPid?: number;
+  /**
+   * Process start tokens for the pids above, and the PID namespace they
+   * were recorded in.
+   *
+   * A pid number does not identify a process. Nothing reaps this store
+   * while no supervisor runs, so a crash or a reboot leaves recorded pids
+   * behind that the OS later recycles to unrelated processes; and a
+   * shared `~/.qwen` — an NFS home, a devcontainer with the home mounted
+   * — puts another machine's pids in front of a reader who would resolve
+   * them in its own namespace. A reader pairs these with `isSameProcess`
+   * to answer the question the live-session registry already answers for
+   * its own records.
+   *
+   * All three are optional on purpose: this is a durable
+   * `schemaVersion: 1` record, and a file written before these fields
+   * existed must stay readable. A reader that finds them absent degrades
+   * to a bare liveness check — the same rule `isSameProcess` applies on a
+   * platform that has no start token.
+   */
+  hostProcStart?: string | null;
+  workerProcStart?: string | null;
+  pidNs?: number | null;
   endpoint?: string;
   hostEndpoint?: string;
   hostAuthToken?: string;
@@ -232,3 +256,25 @@ export type AgentViewWorkerAnswerOutcome =
   | 'modify_with_editor'
   | 'restore_previous'
   | 'cancel';
+
+/**
+ * The directory name a session id is filed under.
+ *
+ * This lives with the on-disk shapes rather than with the store because
+ * it *is* one: it defines the identity two readers must agree on. The
+ * store files a session under this name and reports it back as the
+ * session's id, while the live-session registry keeps the raw spelling
+ * the worker registered with — adoption deliberately keeps both, because
+ * the native session store is case-sensitive. Anything that joins the two
+ * sources has to canonicalize through this one function, or a mixed-case
+ * session is two sessions to whichever half is comparing raw strings.
+ */
+export function sanitizeSessionId(sessionId: string): string {
+  const safe = path
+    .basename(sessionId.replace(/\\/g, '/'))
+    .toLowerCase()
+    .replace(/^\.+/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[<>:"|?*\x00-\x1F]/g, '_');
+  return safe || '_';
+}

packages/cli/src/agent-view/supervisor-process.ts

@@ -14,6 +14,10 @@ import {
   DEFAULT_AGENT_VIEW_ATTACH_LEASE_TTL_MS,
 } from './attach-lease.js';
 import type { AgentViewAttachLease } from './attach-lease.js';
+import {
+  readPidNamespaceId,
+  readProcStartToken,
+} from '@qwen-code/qwen-code-core/utils/process-liveness.js';
 import { AGENT_VIEW_PROTOCOL_VERSION } from './protocol.js';
 import type {
   AgentViewActivityFile,
@@ -80,6 +84,40 @@ import {
   getAgentViewActivityInputState,
 } from './presentation.js';
 
+/**
+ * The pid fields of a worker file, with the identity that makes them
+ * trustworthy to a later reader.
+ *
+ * Recording the numbers alone is not enough. Nothing reaps this store
+ * while no supervisor runs — `clearAgentViewWorkerPids` does not get to
+ * run after a SIGKILL or a reboot — so the durable file keeps naming pids
+ * the OS is free to hand to unrelated processes, and a `~/.qwen` shared
+ * between machines or namespaces offers pids that mean nothing here. A
+ * reader pairing these tokens with `isSameProcess` gets the same evidence
+ * standard the live-session registry already holds its own records to,
+ * instead of a bare `kill(pid, 0)`.
+ *
+ * Reading the token can fail (the process exits between spawn and this
+ * call, `/proc` is unreadable, the platform has none); `null` then records
+ * "no identity available", which readers degrade to a liveness check
+ * rather than treating as a mismatch.
+ */
+function workerPidIdentity(host: { pid: number; workerPid: number }): {
+  hostPid: number;
+  workerPid: number;
+  hostProcStart: string | null;
+  workerProcStart: string | null;
+  pidNs: number | null;
+} {
+  return {
+    hostPid: host.pid,
+    workerPid: host.workerPid,
+    hostProcStart: readProcStartToken(host.pid),
+    workerProcStart: readProcStartToken(host.workerPid),
+    pidNs: readPidNamespaceId(),
+  };
+}
+
 function resolveSessionCwd(cwd: string): string {
   try {
     return fs.realpathSync(cwd);
@@ -470,8 +508,7 @@ class AgentViewSupervisorProcessHandler
           result.sessionId,
           {
             schemaVersion: 1,
-            hostPid: host.pid,
-            workerPid: host.workerPid,
+            ...workerPidIdentity(host),
             ...(host.hostId ? { hostId: host.hostId } : {}),
             ...(host.endpoint ? { hostEndpoint: host.endpoint } : {}),
             ...(host.authToken ? { hostAuthToken: host.authToken } : {}),
@@ -703,8 +740,7 @@ class AgentViewSupervisorProcessHandler
           adoption.sessionId,
           {
             schemaVersion: 1,
-            hostPid: host.pid,
-            workerPid: host.workerPid,
+            ...workerPidIdentity(host),
             ...(host.hostId ? { hostId: host.hostId } : {}),
             ...(host.endpoint ? { hostEndpoint: host.endpoint } : {}),
             ...(host.authToken ? { hostAuthToken: host.authToken } : {}),
@@ -2322,8 +2358,7 @@ class WorkerRegistry {
           sessionId,
           {
             schemaVersion: 1,
-            hostPid: host.pid,
-            workerPid: host.workerPid,
+            ...workerPidIdentity(host),
             ...(host.hostId ? { hostId: host.hostId } : {}),
             hostEndpoint: worker.hostEndpoint,
             ...(worker.hostAuthToken
@@ -2521,8 +2556,7 @@ class WorkerRegistry {
         sessionId,
         {
           schemaVersion: 1,
-          hostPid: host.pid,
-          workerPid: host.workerPid,
+          ...workerPidIdentity(host),
           ...(host.hostId ? { hostId: host.hostId } : {}),
           ...(host.endpoint ? { hostEndpoint: host.endpoint } : {}),
           ...(host.authToken ? { hostAuthToken: host.authToken } : {}),