feat(cli): see, answer and stop a background session

docs/users/features/commands.md

@@ -707,10 +707,13 @@ These commands are run from the shell as `qwen <subcommand>` before starting an
 
 ### Session Management
 
-| Command              | Description                         | Usage Examples                                               |
-| -------------------- | ----------------------------------- | ------------------------------------------------------------ |
-| `qwen sessions list` | List recent conversation sessions   | `qwen sessions list`, `qwen sessions list --json --limit 50` |
-| `qwen sessions ps`   | List the sessions running right now | `qwen sessions ps`, `qwen sessions ps --json`                |
+| Command                | Description                                   | Usage Examples                                               |
+| ---------------------- | --------------------------------------------- | ------------------------------------------------------------ |
+| `qwen sessions list`   | List recent conversation sessions             | `qwen sessions list`, `qwen sessions list --json --limit 50` |
+| `qwen sessions ps`     | List the sessions running right now           | `qwen sessions ps`, `qwen sessions ps --json`                |
+| `qwen sessions peek`   | Show what a background session is doing       | `qwen sessions peek 0f8e1c42`                                |
+| `qwen sessions answer` | Answer a background session waiting for input | `qwen sessions answer 0f8e1c42 "yes, go ahead"`              |
+| `qwen sessions stop`   | Stop a background session                     | `qwen sessions stop 0f8e1c42`                                |
 
 #### `qwen sessions list`
 
@@ -762,7 +765,7 @@ qwen --bg "find out why the release job is flaky"
 # See it with: qwen sessions ps
 ```
 
-What it does not do yet: there is no way to attach to a background session, read its transcript, answer its question from the CLI, or stop it. Those land with the Agent View roster.
+See what it is doing with `qwen sessions peek`, reply to it with `qwen sessions answer`, and end it with `qwen sessions stop`. What is still missing: attaching to a background session's terminal and reading its full transcript. Those land with the Agent View roster.
 
 #### `qwen sessions ps`
 
@@ -848,6 +851,31 @@ qwen sessions ps --json | jq -r .cwd
 qwen sessions ps --json | jq -r 'select(.taskState == "waiting") | .name'
 ```
 
+#### `qwen sessions peek|answer|stop <session>`
+
+A background session started with `--bg` runs with nobody watching it. These three commands are how you catch up with one. Each takes a session id or any unique prefix of one — the full id `--bg` prints at launch is enough, and `qwen sessions ps --json` lists it as `sessionId`.
+
+`peek` shows what the session is doing, and what it has stopped to ask:
+
+```bash
+$ qwen sessions peek 0f8e1c42
+find out why the release job is flaky  [0f8e1c42]
+State:     waiting
+Directory: /w/app
+Waiting:   permission to write scripts/flake-report.md
+
+Answer it with: qwen sessions answer 0f8e1c42 "<your answer>"
+```
+
+`answer` replies to a session that is waiting, and `stop` ends one, leaving its transcript in place:
+
+```bash
+qwen sessions answer 0f8e1c42 "yes, write the report"
+qwen sessions stop 0f8e1c42
+```
+
+All three talk to a supervisor that is already running and never start one: if none is, they say so rather than spawning a process to report that nothing exists.
+
 ## 6. Messaging Another Running Session
 
 Two interactive sessions on the same machine can send each other

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

@@ -51,10 +51,12 @@ import {
   patchAgentViewSessionStateIf,
   readAgentViewLaunch,
   readAgentViewActivity,
+  readAgentViewRoster,
   readAgentViewRosterStrict,
   readAgentViewSessionState,
   readAgentViewWorker,
   redactAgentViewActivity,
+  redactAgentViewLaunch,
   redactAgentViewWorker,
   removeAgentViewRosterEntry,
   sanitizeSessionId,
@@ -1109,10 +1111,24 @@ class AgentViewSupervisorProcessHandler
     if (activity !== storedActivity) {
       this.notifyChanged();
     }
+    // The same join `listAgentViewSessionSnapshots` does for `sessions
+    // ps`: the title derives from the roster entry, the summary and the
+    // launch prompt in that order, so peek and ps cannot name the same
+    // session two different ways. The roster read is the soft-fail one —
+    // peek reports a session rather than making safety decisions on the
+    // entry, so an unreadable roster degrades to the untitled placeholder
+    // instead of failing the whole read.
+    const roster = await readAgentViewRoster(store);
     return {
       sessionId,
       state,
       activity: redactAgentViewActivity(activity),
+      rosterEntry: roster.sessions.find(
+        (entry) => sanitizeSessionId(entry.sessionId) === sessionId,
+      ),
+      launch: redactAgentViewLaunch(
+        await readAgentViewLaunch(sessionId, store),
+      ),
       worker: redactAgentViewWorker(
         await readAgentViewWorker(sessionId, store),
       ),

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

@@ -817,7 +817,7 @@ function normalizeLaunch(
   }) as AgentViewLaunchFile;
 }
 
-function redactAgentViewLaunch(
+export function redactAgentViewLaunch(
   launch: AgentViewLaunchFile | undefined,
 ): AgentViewLaunchFile | undefined {
   if (!launch) return undefined;

packages/cli/src/commands/sessions.test.ts

@@ -18,10 +18,16 @@ vi.mock('./sessions/list.js', () => ({
 vi.mock('./sessions/ps.js', () => ({
   psCommand: {
     command: 'ps',
-    describe: 'List interactive Qwen Code sessions running right now',
+    describe: 'List the Qwen Code sessions running right now',
   },
 }));
 
+vi.mock('./sessions/control-commands.js', () => ({
+  peekCommand: { command: 'peek <session>', describe: 'Peek' },
+  answerCommand: { command: 'answer <session> <text>', describe: 'Answer' },
+  stopCommand: { command: 'stop <session>', describe: 'Stop' },
+}));
+
 import { sessionsCommand } from './sessions.js';
 import { type Argv } from 'yargs';
 import yargs from 'yargs';
@@ -51,7 +57,7 @@ describe('sessions command', () => {
     expect(options.key).toHaveProperty('help');
   });
 
-  it('should register list and ps subcommands', () => {
+  it('should register every session subcommand', () => {
     const mockYargs = {
       command: vi.fn().mockReturnThis(),
       demandCommand: vi.fn().mockReturnThis(),
@@ -64,13 +70,21 @@ describe('sessions command', () => {
     }
     builder(mockYargs as unknown as Argv);
 
-    expect(mockYargs.command).toHaveBeenCalledTimes(2);
+    expect(mockYargs.command).toHaveBeenCalledTimes(5);
 
     const commandCalls = mockYargs.command.mock.calls;
     const commandNames = commandCalls.map((call) => call[0].command);
 
-    expect(commandNames).toContain('list');
-    expect(commandNames).toContain('ps');
+    // Reading a background session's question, answering it and stopping
+    // it are what make the `needs input` state `ps` reports actionable;
+    // losing one of them silently would strand the user there.
+    expect(commandNames).toEqual([
+      'list',
+      'ps',
+      'peek <session>',
+      'answer <session> <text>',
+      'stop <session>',
+    ]);
 
     expect(mockYargs.demandCommand).toHaveBeenCalledWith(
       1,

packages/cli/src/commands/sessions.ts

@@ -7,6 +7,11 @@
 import type { CommandModule, Argv } from 'yargs';
 import { listCommand } from './sessions/list.js';
 import { psCommand } from './sessions/ps.js';
+import {
+  answerCommand,
+  peekCommand,
+  stopCommand,
+} from './sessions/control-commands.js';
 
 export const sessionsCommand: CommandModule = {
   command: 'sessions',
@@ -15,6 +20,9 @@ export const sessionsCommand: CommandModule = {
     yargs
       .command(listCommand)
       .command(psCommand)
+      .command(peekCommand)
+      .command(answerCommand)
+      .command(stopCommand)
       .demandCommand(1, 'You need at least one command before continuing.')
       .version(false),
   // demandCommand(1) ensures a subcommand is always required;

packages/cli/src/commands/sessions/control-commands.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+const connectExistingAgentViewSupervisor = vi.fn();
+
+vi.mock('../../agent-view/supervisor-runner.js', () => ({
+  connectExistingAgentViewSupervisor: (...args: unknown[]) =>
+    connectExistingAgentViewSupervisor(...args),
+}));
+
+const stdout: string[] = [];
+const stderr: string[] = [];
+
+vi.mock('../../utils/stdioHelpers.js', () => ({
+  writeStdoutLine: (line: string) => stdout.push(line),
+  writeStderrLine: (line: string) => stderr.push(line),
+}));
+
+const { answerCommand, peekCommand } = await import('./control-commands.js');
+
+const SESSION = '0f8e1c42-9d3a-4d21-8f77-2b6a7c9e0c31';
+
+let savedExitCode: typeof process.exitCode;
+
+beforeEach(() => {
+  stdout.length = 0;
+  stderr.length = 0;
+  savedExitCode = process.exitCode;
+  process.exitCode = undefined;
+  connectExistingAgentViewSupervisor.mockReset();
+});
+
+afterEach(() => {
+  process.exitCode = savedExitCode;
+});
+
+async function run(
+  command: { handler?: unknown },
+  argv: Record<string, unknown>,
+): Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  await (command.handler as any)(argv);
+}
+
+describe('session control command reporting', () => {
+  it('writes a failure to stderr and keeps stdout clean', async () => {
+    // No supervisor running: peek fails, and the message must not land
+    // in the success channel of a `qwen sessions peek <id> > last.log`.
+    connectExistingAgentViewSupervisor.mockResolvedValue(undefined);
+    await run(peekCommand, { session: SESSION });
+    expect(stderr.join('\n')).toContain('No background sessions');
+    expect(stdout).toEqual([]);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('writes a refused answer to stderr, not into the result', async () => {
+    // The shape that bit before the fix: `answer "$id" "$reply" > last.log`
+    // against a stale id wrote the error into the redirected file, mixed
+    // with what success prints, distinguishable only by exit code.
+    connectExistingAgentViewSupervisor.mockResolvedValue({
+      answer: vi
+        .fn()
+        .mockRejectedValue(new Error('No Agent View session found for zz.')),
+    });
+    await run(answerCommand, { session: 'zz', text: 'yes' });
+    expect(stderr).toEqual(['No Agent View session found for zz.']);
+    expect(stdout).toEqual([]);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('writes a delivered answer to stdout', async () => {
+    connectExistingAgentViewSupervisor.mockResolvedValue({
+      answer: vi.fn().mockResolvedValue({ sessionId: SESSION, answered: true }),
+    });
+    await run(answerCommand, { session: SESSION, text: 'yes' });
+    expect(stdout).toEqual(['Answer delivered.']);
+    expect(stderr).toEqual([]);
+    expect(process.exitCode).toBeUndefined();
+  });
+});

packages/cli/src/commands/sessions/control-commands.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2026 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `qwen sessions peek|answer|stop` — the three things a background
+ * session needs before `qwen sessions ps` reporting "needs input" means
+ * anything.
+ *
+ * The argv shape is most of what is here; the decisions live in
+ * `managed-control.ts`. The one thing this file decides on its own is
+ * which stream a result goes to.
+ */
+
+import type { Argv, CommandModule } from 'yargs';
+import { writeStdoutLine, writeStderrLine } from '../../utils/stdioHelpers.js';
+import {
+  answerManagedSession,
+  peekManagedSession,
+  stopManagedSession,
+  type ConnectSupervisor,
+  type ManagedControlResult,
+} from './managed-control.js';
+
+interface SessionIdArgs {
+  session: string;
+}
+
+interface AnswerArgs extends SessionIdArgs {
+  text: string;
+}
+
+/**
+ * Connect to a running supervisor, or report that there is none.
+ *
+ * Deliberately `connectExisting` rather than `ensure`: these commands ask
+ * about sessions, and starting a supervisor to answer would spawn a
+ * process only to be told nothing is running.
+ */
+const connectSupervisor: ConnectSupervisor = async () => {
+  const { connectExistingAgentViewSupervisor } = await import(
+    '../../agent-view/supervisor-runner.js'
+  );
+  return connectExistingAgentViewSupervisor();
+};
+
+/**
+ * Print a result, and set the exit code if it failed.
+ *
+ * Failure lines go to stderr, the way `list`, `ps` and `--bg` report
+ * errors; success lines stay on stdout, so redirecting the command's
+ * output never captures an error message alongside the result.
+ */
+function report(result: ManagedControlResult): void {
+  const write = result.exitCode !== 0 ? writeStderrLine : writeStdoutLine;
+  for (const line of result.lines) write(line);
+  if (result.exitCode !== 0) process.exitCode = result.exitCode;
+}
+
+function sessionPositional(yargs: Argv): Argv {
+  return yargs.positional('session', {
+    type: 'string',
+    describe: 'Session id, or a unique prefix of one',
+    demandOption: true,
+  });
+}
+
+export const peekCommand: CommandModule<unknown, SessionIdArgs> = {
+  command: 'peek <session>',
+  describe: 'Show what a background session is doing or waiting for',
+  builder: (yargs: Argv) => sessionPositional(yargs) as Argv<SessionIdArgs>,
+  handler: async (argv) => {
+    report(await peekManagedSession(argv.session, connectSupervisor));
+  },
+};
+
+export const answerCommand: CommandModule<unknown, AnswerArgs> = {
+  command: 'answer <session> <text>',
+  describe: 'Answer a background session that is waiting for input',
+  builder: (yargs: Argv) =>
+    sessionPositional(yargs).positional('text', {
+      type: 'string',
+      describe: 'What to tell it',
+      demandOption: true,
+    }) as Argv<AnswerArgs>,
+  handler: async (argv) => {
+    report(
+      await answerManagedSession(argv.session, argv.text, connectSupervisor),
+    );
+  },
+};
+
+export const stopCommand: CommandModule<unknown, SessionIdArgs> = {
+  command: 'stop <session>',
+  describe: 'Stop a background session',
+  builder: (yargs: Argv) => sessionPositional(yargs) as Argv<SessionIdArgs>,
+  handler: async (argv) => {
+    report(await stopManagedSession(argv.session, connectSupervisor));
+  },
+};