@tshu-w/pi-agents 0.2.2 → 0.3.0

package/README.md

@@ -21,7 +21,7 @@ https://github.com/user-attachments/assets/52dd1de6-bf26-45ea-8775-2b1a1a187f4f
 - **Async agents**: Agents run in parallel in the background and notify their parent when done.
 - **Dynamic workflows**: Extends Pi's [codemode](https://pi.dev/docs/latest/codemode) to recursively split long-horizon tasks into calls the model handles well, as in [RLM](https://alexzhang13.github.io/blog/2026/harness/).
 - **Inter-agent messaging**: Agents message each other, even in other Pi instances.
-- **Persistent agents**: Agents keep running after the terminal closes, with a workbench to manage them.
+- **Persistent agents**: Agents keep running after the terminal closes, with a workbench to manage them and a main Agent to talk to.
 
 ## Install
 
@@ -55,6 +55,7 @@ Ask Pi in plain words; it starts Agents and Programs when the work calls for the
 | `/tasks panel` | Hides or shows the task panel |
 | `Ctrl+Z`, `/detach` | Leaves a Session running and returns to the shell |
 | `pd agents` | Opens the workbench |
+| `pd main` | Opens the main Agent, which hands your work to other Agents |
 | `pd attach <session>` | Attaches to a Session, starting it if needed |
 
 ## Configuration

package/bin/pd.mjs

@@ -2,15 +2,15 @@
 // The `pd` command: runs Pi in a host, attaching this terminal to interactive Pi and connecting
 // non-interactive Pi to the hosted Session; `--no-session` and package commands run Pi directly.
 import { spawn } from 'node:child_process';
-import { accessSync, constants } from 'node:fs';
+import { accessSync, constants, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { styleText } from 'node:util';
 import { attach, hostSessionFile, settledHosts, startHost } from '../src/host/client.mjs';
 import { detachKey, detachMatcher } from '../src/host/keys.mjs';
 import { discoverRoots, findRoot } from '../src/roots/discovery.mjs';
-import { defaultSessionDir, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
+import { defaultSessionDir, prepareDirectory, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
 import { piPackage } from '../src/pi.mjs';
 import { markedFiles } from '../src/daemon/sessions.mjs';
 import { argGroups } from '../src/host/rpc-client.mjs';
@@ -22,13 +22,13 @@ if (!real) {
   process.stderr.write(`${error('pd needs Pi: install it so that pi is on PATH.')}\n`);
   process.exit(1);
 }
-const args = process.argv.slice(2);
+let args = process.argv.slice(2);
 const paths = statePaths();
 const dist = file => import(pathToFileURL(join(piPackage(real), 'dist', file)).href);
 // Pi's own parsing, so that `pd` reads every argument as `pi` does.
 const { parseArgs } = await dist('cli/args.js');
 const { ENV_SESSION_DIR, getAgentDir } = await dist('config.js');
-const parsed = parseArgs(args);
+let parsed = parseArgs(args);
 
 const COMMANDS = new Set(['install', 'remove', 'uninstall', 'update', 'list', 'config', 'auth', 'mcp']);
 
@@ -154,6 +154,40 @@ function headlessMode() {
   if (!interactive || parsed.print) return 'text';
 }
 
+/** Prepares the main Agent's directory, whose `AGENTS.md` links to the main Agent's instructions, and continues its Session there. */
+async function openMain() {
+  await prepareDirectory(paths.main);
+  const link = join(paths.main, 'AGENTS.md');
+  const instructions = fileURLToPath(new URL('../src/main-agent.md', import.meta.url));
+  let target;
+  try { target = readlinkSync(link); }
+  catch (failure) {
+    // A file put in place of the link stays.
+    if (failure.code !== 'ENOENT' && failure.code !== 'EINVAL') throw failure;
+    target = failure.code === 'EINVAL' ? instructions : undefined;
+  }
+  // The link follows this copy of pi-agents; another `pd main` may be making it at the same time.
+  if (target !== instructions) {
+    try { if (target !== undefined) unlinkSync(link); }
+    catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
+    try { symlinkSync(instructions, link); }
+    catch (failure) { if (failure.code !== 'EEXIST') throw failure; }
+  }
+  process.chdir(paths.main);
+  const options = args.slice(1);
+  // A running main Agent may have no file yet for `-c` to find.
+  const here = host => host.session?.cwd === process.cwd();
+  const running = (await settledHosts(paths, here)).filter(here);
+  args = running.length === 1 ? ['--session', hostSessionFile(running[0]), ...options] : ['-c', ...options];
+  parsed = parseArgs(args);
+  // A new main Agent is named, so other Agents can address it; options go first, as messages may follow `--`.
+  if (!running.length && parsed.name === undefined && !(await recentSession())) {
+    args.unshift('--name', 'main');
+    parsed = parseArgs(args);
+  }
+}
+
+if (args[0] === 'main') await openMain();
 const interactive = process.stdin.isTTY && process.stdout.isTTY;
 if (args[0] === 'attach' && interactive) await attachCommand(args[1]);
 else if (args[0] === 'agents' && interactive) {

package/docs/HOSTS.md

@@ -16,6 +16,7 @@ Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
 
 - `workbench.json`: seen marks and which Sessions are listed.
 - `host.log`, `daemon.log`: logs.
+- `main/`: the main Agent's working directory. Its `AGENTS.md` links to the main Agent's instructions in pi-agents.
 
 Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no `XDG_RUNTIME_DIR`, so there they go in `runtime/` under the state directory.
 
@@ -35,6 +36,7 @@ pi install "$(npm root -g)/@tshu-w/pi-agents"
 - `pd [pi options]` starts Pi interactively in a new host and attaches the terminal. If the Session is already running in a host, `pd` attaches to it instead, sending it the messages as follow-ups and ignoring other options.
 - `pd agents` opens the workbench.
 - `pd attach <session>` attaches to a Session, starting it first if it is not running.
+- `pd main [pi options]` opens the main Agent, which hands work to other Agents: it runs `pd -c [pi options]` in `main/`, named `main`.
 - Non-interactive starts (`-p`, `--mode json`, `--mode rpc`, piped stdin) work as in Pi, on the Session in a host, so several of them and an attached terminal can use one Session at once. Their commands act on that Session, as `abort` stops whichever turn is running. Unlike Pi:
   - Dialogs are not sent to them. A dialog waits while a terminal is attached and is cancelled otherwise.
   - Extensions see interactive mode, so what an extension writes to stdout does not reach them; `/program` prints as with `pi -p`.

package/docs/SPEC.md

@@ -302,7 +302,7 @@ Tasks (<N> live, /tasks to view)
   +<N> more
 ```
 
-The live work is the owned Agents that are not `idle`, and the running background Programs with their Agents that are not `idle`. The rows list them as a tree in the order they started, each under its owner and each Program under its caller, with the owners needed to keep the tree. Rows that do not fit are counted in the last row. The time is how long the Agent's current turn or the Program has run, and the cost what the replies in that turn have cost, or for a Program, those of all the Agents under it. When a reply has no price, the cost is the input and output tokens instead, like `7.3M tok`.
+The live work is the Agents under the current Agent that are not `idle`, including Programs' Agents, and the running background Programs. The rows list them as a tree in the order they started, each under its owner and each Program under its caller, with the owners needed to keep the tree. Rows that do not fit are counted in the last row. The time is how long the Agent's current turn or the Program has run, and the cost what the replies in that turn have cost, or for a Program, those of all the Agents under it, once there is any. When a reply has no price, the cost is the input and output tokens instead, like `7.3M tok`.
 
 The panel updates as states change, and its times each second. It is shown while it has a row. `/tasks panel` hides or shows it.
 
@@ -339,7 +339,7 @@ Expanding (`app.tools.expand`) shows them as Pi shows them by default.
 
 ### Task viewer
 
-`/tasks` lists the Agents in the current Agent's tree, including its Programs' Agents, and its background Programs, live ones first and newest first, with their state and latest activity, and opens the selected one in a viewer. An Agent not owned by the current Agent is named with its owners, as `<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer follows an Agent's conversation as Pi's chat shows it, or a Program as it shows in the foreground, while the current Session keeps running.
+`/tasks` lists the Agents under the current Agent, including Programs' Agents, its background Programs, and the running ones of those Agents, live ones first and newest first, with their state and latest activity, and opens the selected one in a viewer. A foreground Program is watched in its caller's conversation. An Agent or Program not owned by the current Agent is named with its owners, as `<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer follows an Agent's conversation as Pi's chat shows it, or a Program as it shows in the foreground, while the current Session keeps running.
 
 Text entered in an Agent's viewer is the user's input to it, sent as in Pi's editor; a Program takes no input.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Multi-agent runtime for Pi: persistent async agents, dynamic workflows, and inter-agent messaging",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/agents/registry.ts

@@ -1,6 +1,7 @@
 /** The Agents loaded in this process, shared across trees: who sees whom, how targets resolve, and how messages are addressed. */
 import type { Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Programs } from "../programs/programs.ts";
 import type { Agents } from "./agents.ts";
 import { TreeScheduler } from "./scheduler.ts";
 
@@ -30,6 +31,8 @@ export interface AgentNode {
 	busy(): boolean;
 	sessionFile(): string | undefined;
 	agents: Agents;
+	/** An Agent's background Programs, which the task viewer lists. */
+	programs?: Programs;
 	/** Delivers a message to this node; used only for root Agents. */
 	receive(text: string, delivery: Delivery, messageId?: string, sender?: Sender): void;
 	/** A root Agent's turn was stopped: messages from other Agents become writes until the user's next input. */
@@ -118,19 +121,35 @@ export function programsOf(node: AgentNode): AgentNode[] {
 		.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
 }
 
-/** The node's running owned Agents and background Programs, with those under them. */
-export function liveWork(node: AgentNode): number {
-	let count = 0;
-	for (const entry of node.agents.owned()) {
-		if (entry.state !== "idle") count += 1;
+/** An owned Agent or a Program in the user's view of a tree, with the work under it. */
+export type Task = { entry: Entry; owner: AgentNode; tasks: Task[] } | { program: AgentNode; tasks: Task[] };
+
+/**
+ * The work under a node as the task panel and the task viewer show it, oldest first: its owned Agents, and
+ * its Programs that run in the background or have Agents. A foreground Program without Agents shows only in
+ * its caller's conversation.
+ */
+export function tasksOf(node: AgentNode): Task[] {
+	const tasks: Array<{ at: string; task: Task }> = node.agents.owned().map((entry) => {
 		const loaded = shared.nodes.get(entry.id);
-		if (loaded) count += liveWork(loaded);
-	}
+		return { at: entry.createdAt ?? "", task: { entry: { ...entry, ownerId: node.id }, owner: node, tasks: loaded ? tasksOf(loaded) : [] } };
+	});
 	for (const program of programsOf(node)) {
-		if (program.background) count += 1;
-		count += liveWork(program);
+		const under = tasksOf(program);
+		if (program.background || under.length > 0) tasks.push({ at: program.createdAt ?? "", task: { program, tasks: under } });
 	}
-	return count;
+	return tasks.sort((a, b) => a.at.localeCompare(b.at)).map(({ task }) => task);
+}
+
+/** Whether a task is live work: an Agent that is not idle, or a background Program. */
+export function taskLive(task: Task): boolean {
+	return "program" in task ? task.program.background === true : task.entry.state !== "idle";
+}
+
+/** The node's live work, with that under it. */
+export function liveWork(node: AgentNode): number {
+	const count = (tasks: Task[]): number => tasks.reduce((sum, task) => sum + Number(taskLive(task)) + count(task.tasks), 0);
+	return count(tasksOf(node));
 }
 
 /** `Program <short ID>`, unique among its caller's running Programs. */

package/src/host/client.mjs

@@ -15,6 +15,35 @@ const RESET = '\x1b[<u\x1b[>4;0m\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b
 const ALT_SCREEN = /\x1b\[\?1049([hl])/g;
 // Splits terminal input into key sequences: CSI and SS3 sequences, Alt+key, or a single character.
 const KEYS = /\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b?[\s\S]/g;
+// The terminal's reply to the device status query (`\x1b[5n`), which pi-tui does not send, unlike `\x1b[c`.
+const STATUS_QUERY = '\x1b[5n';
+const STATUS_OK = /\x1b\[0n/;
+const DRAIN_TIMEOUT_MS = 1000;
+
+/**
+ * Reads and drops the input the terminal sent before it took the output written so far, such as the release of the
+ * detach key in Pi's keyboard mode, so the shell does not get it. Over a slow link, such as SSH, it arrives late; the
+ * terminal answers a query after it, or the wait ends after `DRAIN_TIMEOUT_MS`.
+ */
+export function drain(stdin, stdout) {
+  return new Promise(resolve => {
+    let input = '';
+    const done = () => {
+      clearTimeout(timer);
+      stdin.off('data', onData);
+      resolve();
+    };
+    const onData = data => {
+      input += data.toString('latin1');
+      if (STATUS_OK.test(input)) done();
+      // A reply split across chunks starts in the kept tail.
+      else input = input.slice(-64);
+    };
+    const timer = setTimeout(done, DRAIN_TIMEOUT_MS);
+    stdin.on('data', onData);
+    stdout.write(STATUS_QUERY);
+  });
+}
 
 export function hostStatus(path) {
   return new Promise((resolve, reject) => {
@@ -107,9 +136,10 @@ export async function startHost(paths, { pi, args, cwd, cols = 120, rows = 40, e
  * Attaches this process's terminal to a host until the host detaches it or Pi exits.
  * The detach key detaches here, before Pi sees it, so it works whatever Pi shows.
  * `onAttach` runs once the host has attached the terminal and told Pi.
+ * With `drainInput`, late input is dropped before returning (see `drain`); a caller that reads the terminal next turns it off.
  * Resolves to { reason: 'detach' | 'takeover' | 'exited' | 'closed', session }.
  */
-export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin, stdout = process.stdout }) {
+export function attach(socketPath, { isDetach, onAttach, drainInput = true, stdin = process.stdin, stdout = process.stdout }) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(socketPath);
     const size = () => ({ cols: stdout.columns, rows: stdout.rows });
@@ -124,16 +154,19 @@ export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin,
       socket.write(frame(FRAME.detached));
     };
     let result, connected = false, altScreen = false, attached = false;
-    function finish() {
+    async function finish() {
       stdout.off('resize', onResize);
       stdin.off('data', onInput);
       if (connected) {
-        stdin.setRawMode(false);
-        stdin.pause();
         // An exiting Pi restores the terminal itself.
         // Leaving the alternate screen returns the cursor to the line below the command; otherwise it ends a line.
         // Terminals keep a keyboard mode stack per screen, so the reset comes before leaving it.
-        if (result?.reason !== 'exited') stdout.write(altScreen ? `${RESET}\x1b[?1049l` : `${RESET}\r\n`);
+        // The drain comes before leaving, so the screen changes once, when it ends.
+        if (result?.reason !== 'exited') stdout.write(RESET);
+        if (drainInput) await drain(stdin, stdout);
+        if (result?.reason !== 'exited') stdout.write(altScreen ? '\x1b[?1049l' : '\r\n');
+        stdin.setRawMode(false);
+        stdin.pause();
       }
       resolve(result ?? { reason: 'closed' });
     }

package/src/index.ts

@@ -170,6 +170,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			notify: (text) => agents.notify(text),
 			changed: () => panel.update(),
 		});
+		created.programs = programs;
 		programs.restore(current);
 		panel.start(current);
 	});
@@ -227,7 +228,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			if (!node) return;
 			browsing = true;
 			try {
-				await openTaskViewer(current, requireNode(current), programs, pi.getSettings().editorPaddingX ?? 0);
+				await openTaskViewer(current, requireNode(current), pi.getSettings().editorPaddingX ?? 0);
 			} finally {
 				browsing = false;
 			}

package/src/main-agent.md

@@ -0,0 +1,8 @@
+# Main Agent
+
+You are the user's main Agent. The user talks only to you; you hand work to other Agents and report back.
+
+- Handle a request yourself only if it takes at most three read-only tool calls; otherwise hand it to an Agent.
+- Before spawning, `list` Agents: send work in an area an Agent already handles to that Agent.
+- Spawn Agents in the directory the work belongs to, or `~` if none; never in your working directory.
+- Relay an Agent's questions to the user, and its results as a short conclusion.

package/src/programs/execute.ts

@@ -105,9 +105,9 @@ const sandboxExtras = new AsyncLocalStorage<SandboxExtras>();
 let sandboxPatch: Promise<void> | undefined;
 
 /**
- * Since Pi 1.3.0, its executor admits at most two codemode workers per process, which background
- * Programs waiting on Agents use up. A Program's worker is admitted on its own terms instead: any
- * number may run, and none starts while this many are still exiting after their scripts ended.
+ * Since Pi 1.3.0, its executor admits a limited number of codemode workers per process (two by default),
+ * which background Programs waiting on Agents use up. A Program's worker is admitted on its own terms
+ * instead: any number may run, and none starts while this many are still exiting after their scripts ended.
  */
 const MAX_EXITING_WORKERS = 2;
 const exitingWorkers = new Set<{ exited: boolean }>();
@@ -143,6 +143,26 @@ function programWorker(codemode: Awaited<ReturnType<typeof loadCodemode>>, wasmP
 	};
 }
 
+const WORKER_LIMIT_ENV = "PI_CODEMODE_MAX_WORKERS";
+
+/**
+ * Since Pi 1.4.0, its executor also reserves one of its worker slots before a script starts and holds
+ * it until the script ends, so Programs waiting on Agents make later Programs wait. Its limit is raised
+ * while `start` calls the executor, which reserves before its first `await`, and restored as soon as the
+ * call returns. The Program still holds its slot, which only Programs share unless the host runs scripts
+ * through the same executor, as Pi from source or an SDK host does.
+ */
+function admitAtOnce<T>(start: () => T): T {
+	const limit = process.env[WORKER_LIMIT_ENV];
+	process.env[WORKER_LIMIT_ENV] = String(Number.MAX_SAFE_INTEGER);
+	try {
+		return start();
+	} finally {
+		if (limit === undefined) delete process.env[WORKER_LIMIT_ENV];
+		else process.env[WORKER_LIMIT_ENV] = limit;
+	}
+}
+
 async function patchSandbox(): Promise<void> {
 	const [codemode, source] = await Promise.all([loadCodemode(), loadPiWorkerSource()]);
 	const wasmPath = source.getQuickJSWasmPath();
@@ -269,11 +289,11 @@ export async function executeProgram(
 	};
 	let result: Awaited<ReturnType<typeof executeCodemode>>;
 	try {
-		result = await withSandboxExtras(extras, () => executeCodemode(toolCallId, { code: source }, signal, onUpdate, programCtx, {
+		result = await withSandboxExtras(extras, () => admitAtOnce(() => executeCodemode(toolCallId, { code: source }, signal, onUpdate, programCtx, {
 			models: true,
 			appendEntry: options.appendEntry,
 			getToolNamespace: options.getToolNamespace,
-		}));
+		})));
 	} finally {
 		if (!scriptEnded) extras.ended();
 	}

package/src/roots/paths.mjs

@@ -26,6 +26,7 @@ export function statePaths(env = process.env) {
     workbench: join(state, 'workbench.json'),
     hostLog: join(state, 'host.log'),
     daemonLog: join(state, 'daemon.log'),
+    main: join(state, 'main'),
     host(pid) { return join(runtime, `h-${pid}.sock`); },
     locks: join(runtime, 'locks'),
     daemon: join(runtime, 'daemon.sock'),

package/src/ui/panel.ts

@@ -1,6 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, TruncatedText } from "@earendil-works/pi-tui";
-import { label, nodes, onTreeChange, programLabel, programsOf, type AgentNode, type Spend } from "../agents/registry.ts";
+import { label, liveWork, onTreeChange, programLabel, taskLive, tasksOf, type AgentNode, type Spend, type Task } from "../agents/registry.ts";
 
 const WIDGET_KEY = "pi-agents";
 
@@ -23,53 +23,38 @@ function cost({ cost, tokens, unpriced }: Spend): string {
 	return tokens < 10_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M tok` : `${Math.round(tokens / 1_000_000)}M tok`;
 }
 
+/** The cost of `spent`, once there is any. */
+function spend(spent: Spend | undefined): string[] {
+	return spent && (spent.cost > 0 || spent.tokens > 0) ? [cost(spent)] : [];
+}
+
 /**
- * The task panel: the Agent's live owned Agents and running background Programs as a tree, in the
- * order they started, with their Programs' live Agents under them, and how long each has run and what
- * it has cost. Empty when none.
+ * The task panel: the Agent's live work as a tree, in the order it started, with how long each has run
+ * and what it has cost. Empty when none.
  */
 export function panelLines(self: AgentNode, now = Date.now()): string[] {
-	const rows: Array<{ line: string; parent?: number; shown: boolean }> = [];
 	const ids = self.agents.ids();
-	let live = 0;
-	// A live row is listed with its owners, so the tree stays readable.
-	const show = (index: number | undefined) => {
-		for (let row = index === undefined ? undefined : rows[index]; row && !row.shown; row = row.parent === undefined ? undefined : rows[row.parent]) row.shown = true;
-	};
-	const visit = (node: AgentNode, level: number, parent?: number) => {
-		const children = [
-			...node.agents.owned().map((entry) => ({ at: entry.createdAt ?? "", entry })),
-			...programsOf(node).filter((program) => program.background).map((program) => ({ at: program.createdAt ?? "", program })),
-		].sort((a, b) => a.at.localeCompare(b.at));
-		for (const child of children) {
-			const index = rows.length;
-			if ("program" in child) {
-				const since = Date.parse(child.program.createdAt ?? "");
-				const time = since ? [elapsed(since, now), ...(child.program.spent ? [cost(child.program.spent)] : [])] : [];
-				rows.push({ line: `${"  ".repeat(level)}${[programLabel(child.program), "running", ...time].join("  ")}`, parent, shown: false });
-				live += 1;
-				show(index);
-				visit(child.program, level + 1, index);
-				continue;
-			}
-			const { entry } = child;
-			const own = node.agents.counts(entry.id);
-			const pending = own?.pending ? [`${own.pending} pending`] : [];
-			const time = own?.since ? [elapsed(own.since, now), ...(own.spent ? [cost(own.spent)] : [])] : [];
-			rows.push({ line: `${"  ".repeat(level)}Agent ${[label(entry, ids), entry.state, ...time, ...pending].join("  ")}`, parent, shown: false });
-			if (entry.state !== "idle") {
-				live += 1;
-				show(index);
-			}
-			const loaded = nodes.get(entry.id);
-			if (loaded) visit(loaded, level + 1, index);
+	const line = (task: Task): string => {
+		if ("program" in task) {
+			const since = Date.parse(task.program.createdAt ?? "");
+			const time = since ? [elapsed(since, now), ...spend(task.program.spent)] : [];
+			return [programLabel(task.program), "running", ...time].join("  ");
 		}
+		const { entry, owner } = task;
+		const own = owner.agents.counts(entry.id);
+		const pending = own?.pending ? [`${own.pending} pending`] : [];
+		const time = own?.since ? [elapsed(own.since, now), ...spend(own.spent)] : [];
+		return `Agent ${[label(entry, ids), entry.state, ...time, ...pending].join("  ")}`;
 	};
-	visit(self, 0);
-	const lines = rows.filter((row) => row.shown).map((row) => row.line);
+	// A row is listed while it is live or has live work under it, so the tree stays readable.
+	const rows = (tasks: Task[], level: number): string[] => tasks.flatMap((task) => {
+		const under = rows(task.tasks, level + 1);
+		return taskLive(task) || under.length > 0 ? [`${"  ".repeat(level)}${line(task)}`, ...under] : [];
+	});
+	const lines = rows(tasksOf(self), 0);
 	if (lines.length === 0) return [];
 	if (lines.length > MAX_LINES - 1) lines.splice(MAX_LINES - 2, Infinity, `+${lines.length - (MAX_LINES - 2)} more`);
-	return [`Tasks (${live} live, /tasks to view)`, ...lines.map((line) => `  ${line}`)];
+	return [`Tasks (${liveWork(self)} live, /tasks to view)`, ...lines.map((line) => `  ${line}`)];
 }
 
 /**

package/src/ui/viewer.ts

@@ -10,6 +10,7 @@ import {
 	getMarkdownTheme,
 	getSelectListTheme,
 	keyHint,
+	keyText,
 	parseSkillBlock,
 	SkillInvocationMessageComponent,
 	ToolExecutionComponent,
@@ -24,7 +25,9 @@ import {
 	Container,
 	fuzzyFilter,
 	Input,
+	isViewportTUI,
 	Loader,
+	ScrollView,
 	SelectList,
 	Spacer,
 	Text,
@@ -35,8 +38,12 @@ import {
 	type KeybindingsManager,
 	type SelectItem,
 	type TUI,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+	type ViewportTUI,
+	VStack,
 } from "@earendil-works/pi-tui";
-import { MESSAGE_TYPE, nodes, onTreeChange, programLabel, programsOf, type AgentNode, type Entry } from "../agents/registry.ts";
+import { MESSAGE_TYPE, nodes, onTreeChange, programLabel, tasksOf, type AgentNode, type Entry, type Task } from "../agents/registry.ts";
 import { latestActivity } from "../agents/search.ts";
 import { PROGRAM_TOOL_NAME } from "../programs/execute.ts";
 import type { Programs } from "../programs/programs.ts";
@@ -46,6 +53,9 @@ import { execFileSync } from "node:child_process";
 type Message = AgentSession["messages"][number];
 type ToolResult = Parameters<ToolExecutionComponent["updateResult"]>[0];
 type StatusIndicator = Parameters<CustomEditor["setWorkingStatusIndicator"]>[0];
+type Conversation = NonNullable<ReturnType<AgentNode["agents"]["conversation"]>>;
+type ToolCall = Extract<Extract<Message, { role: "assistant" }>["content"][number], { type: "toolCall" }>;
+type Display = ReturnType<AgentViewer["display"]>;
 
 /** Stops the elapsed-time timer of a tool component the viewer drops; only a final result stops it otherwise. */
 function stopTimer(tool: ToolExecutionComponent): void {
@@ -87,6 +97,39 @@ function footerData(cwd: string, ctx: ExtensionContext): ReadonlyFooterDataProvi
 	};
 }
 
+/** The lines a scroll key of Pi's fullscreen mode moves the view up, negative for down, or undefined for another key. */
+function scrollKey(keys: KeybindingsManager, data: string, page: number): number | undefined {
+	const moves = [
+		["tui.altScreen.pageUp", page], ["tui.altScreen.pageDown", -page],
+		["tui.altScreen.halfPageUp", Math.ceil(page / 2)], ["tui.altScreen.halfPageDown", -Math.ceil(page / 2)],
+		["tui.altScreen.lineUp", 1], ["tui.altScreen.lineDown", -1],
+		["tui.altScreen.top", Infinity], ["tui.altScreen.bottom", -Infinity],
+	] as const;
+	return moves.find(([action]) => keys.matches(data, action))?.[1];
+}
+
+/**
+ * Shows a viewer in place of Pi's chat in fullscreen mode, and returns a function that restores it. The viewer takes
+ * Pi's layout, so its transcript above `dock` is browsed as Pi's transcript.
+ */
+function mountViewer(tui: ViewportTUI, theme: Theme, ctx: ExtensionContext, transcript: Component, dock: Component[]): () => void {
+	const previous = (tui as unknown as { layoutRoot?: Component }).layoutRoot;
+	const view = new ScrollView(transcript, {
+		follow: "end",
+		primary: true,
+		overscroll: "chain",
+		scrollbar: agentSession(ctx.sessionManager)?.settingsManager.getFullscreenScrollbar() ?? "auto",
+		scrollbarTrackStyle: (text) => theme.fg("scrollbarTrack", text),
+		scrollbarThumbStyle: (text) => theme.fg("scrollbarThumb", text),
+	});
+	// As Pi's fullscreen layout: the transcript takes the room the dock leaves.
+	tui.setLayoutRoot(new VStack([
+		{ component: view, basis: 0, grow: 1, shrink: 1, minSize: 1 },
+		{ component: new VStack(dock.map((component) => ({ component, shrink: 1, minSize: 0 }))), basis: "auto", grow: 0, shrink: 1, minSize: 1 },
+	]));
+	return () => tui.setLayoutRoot(previous);
+}
+
 /** The user's view of one owned Agent: its conversation, and an editor whose text goes to it. */
 class AgentViewer implements Component, Focusable {
 	private readonly editor: CustomEditor;
@@ -94,15 +137,20 @@ class AgentViewer implements Component, Focusable {
 	private readonly footer: FooterComponent;
 	private session?: AgentSession;
 	private streaming?: Message;
-	/** The streaming message's component and tool calls from the last rebuild, which its updates change in place. */
-	private live?: { component: AssistantMessageComponent; calls: string };
-	/** Tool components without a result from the last rebuild. */
+	/** The component of the streaming assistant message and its tool calls, which its updates change in place. */
+	private live?: { component: AssistantMessageComponent; calls: Set<string> };
+	/** Tool components without a result. */
 	private tools = new Map<string, ToolExecutionComponent>();
 	private running = new Map<string, { partial?: ToolResult }>();
+	/** The conversation's messages the transcript shows, by their count and the last one. */
+	private shown = 0;
+	private last?: Message;
+	/** Streaming messages that ended in the transcript before reaching the conversation's messages. */
+	private ended = 0;
 	private expanded = false;
-	/** Lines scrolled up from the end. */
+	/** Lines scrolled up from the end, in regular mode. */
 	private scroll = 0;
-	private dirty = true;
+	private fullscreen: boolean;
 	private status = "";
 	private indicator?: WorkingStatus;
 	/** Inputs sent from the viewer that the Agent has not received yet, as Pi shows queued messages. */
@@ -136,11 +184,21 @@ class AgentViewer implements Component, Focusable {
 		this.editor.onAction("app.message.followUp", () => this.send(this.editor.getText(), "followUp"));
 		this.editor.onAction("app.tools.expand", () => {
 			this.expanded = !this.expanded;
-			this.dirty = true;
+			// As Pi does, in place.
+			for (const child of this.transcript.children) (child as { setExpanded?: (expanded: boolean) => void }).setExpanded?.(this.expanded);
 			this.tui.requestRender();
 		});
 		this.disposers.push(onTreeChange(() => this.refresh()));
 		this.attach();
+		this.fullscreen = isViewportTUI(tui);
+		if (isViewportTUI(tui)) {
+			const part = (render: (width: number) => string[]): Component => ({ render, invalidate: () => this.invalidate() });
+			this.disposers.push(mountViewer(tui, theme, ctx, part((width) => this.renderTranscript(width)), [
+				part((width) => [" ".repeat(width), ...this.renderQueue(width)]),
+				this.editor,
+				part((width) => this.renderFooter(width)),
+			]));
+		}
 	}
 
 	get focused(): boolean {
@@ -153,28 +211,20 @@ class AgentViewer implements Component, Focusable {
 	}
 
 	handleInput(data: string): void {
-		const page = Math.max(1, this.tui.terminal.rows - 8);
-		// The page keys of Pi's fullscreen mode.
-		if (this.keys.matches(data, "tui.altScreen.pageUp")) this.scroll += page;
-		else if (this.keys.matches(data, "tui.altScreen.pageDown")) this.scroll = Math.max(0, this.scroll - page);
+		const lines = this.fullscreen ? undefined : scrollKey(this.keys, data, Math.max(1, this.tui.terminal.rows - 8));
+		if (lines !== undefined) this.scroll = Math.max(0, this.scroll + lines);
 		else this.editor.handleInput(data);
 		this.tui.requestRender();
 	}
 
+	/** In fullscreen mode, the viewer draws itself in place of Pi's chat (`mountViewer`); in regular mode, over the screen. */
 	render(width: number): string[] {
-		const conversation = this.owner.agents.conversation(this.entry.id);
-		if (this.dirty) this.rebuild(conversation);
-		this.syncStatus(conversation);
-		const queue = this.outbox.map(({ text, delivery }) =>
-			truncateToWidth(this.theme.fg("dim", ` ${delivery === "steer" ? "Steering" : "Follow-up"}: ${text.replace(/\s+/g, " ")}`), width));
+		if (this.fullscreen) return [];
+		const queue = this.renderQueue(width);
 		const editor = this.editor.render(width);
-		const [cwd = "", ...footer] = this.footer.render(width);
-		// The way back sits at the right of the footer's first line, when it fits.
-		const back = keyHint("app.clear", "back");
-		const gap = width - visibleWidth(cwd) - visibleWidth(back);
-		footer.unshift(gap >= 2 ? cwd + " ".repeat(gap) + back : cwd);
+		const footer = this.renderFooter(width);
 		const budget = Math.max(1, this.tui.terminal.rows - queue.length - editor.length - footer.length - 1);
-		const lines = this.transcript.render(width);
+		const lines = this.renderTranscript(width);
 		this.scroll = Math.min(this.scroll, Math.max(0, lines.length - budget));
 		const end = lines.length - this.scroll;
 		const shown = lines.slice(Math.max(0, end - budget), end);
@@ -184,8 +234,34 @@ class AgentViewer implements Component, Focusable {
 		return [...padding, ...shown, blank, ...queue, ...editor, ...footer];
 	}
 
+	private renderTranscript(width: number): string[] {
+		this.prepare();
+		return this.transcript.render(width);
+	}
+
+	/** Brings the transcript, the outbox and the working status up to the conversation, before any of them renders. */
+	private prepare(): void {
+		const conversation = this.owner.agents.conversation(this.entry.id);
+		this.sync(conversation);
+		this.syncStatus(conversation);
+	}
+
+	private renderQueue(width: number): string[] {
+		this.prepare();
+		return this.outbox.map(({ text, delivery }) =>
+			truncateToWidth(this.theme.fg("dim", ` ${delivery === "steer" ? "Steering" : "Follow-up"}: ${text.replace(/\s+/g, " ")}`), width));
+	}
+
+	/** Pi's footer for the Agent, with the way back at the right of its first line when it fits, marked so it stands out. */
+	private renderFooter(width: number): string[] {
+		const [cwd = "", ...footer] = this.footer.render(width);
+		const back = this.theme.fg("accent", `${keyText("app.clear")} back`);
+		const gap = width - visibleWidth(cwd) - visibleWidth(back);
+		return [gap >= 2 ? cwd + " ".repeat(gap) + back : cwd, ...footer];
+	}
+
 	invalidate(): void {
-		this.dirty = true;
+		this.transcript.invalidate();
 		this.editor.invalidate();
 	}
 
@@ -206,7 +282,7 @@ class AgentViewer implements Component, Focusable {
 			this.editor.addToHistory(trimmed);
 			this.editor.setText("");
 			this.scroll = 0;
-			this.dirty = true;
+			this.tui.requestRender();
 		} catch (error) {
 			this.ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
 		}
@@ -225,35 +301,32 @@ class AgentViewer implements Component, Focusable {
 				const tool = this.running.get(event.toolCallId);
 				if (tool) tool.partial = event.partialResult as ToolResult;
 			} else if (event.type === "tool_execution_end") this.running.delete(event.toolCallId);
-			if (!this.update(event)) this.dirty = true;
+			this.update(event);
 			this.tui.requestRender();
 		}));
 	}
 
-	/** Applies a streaming update to the shown components, as Pi does; false when the transcript needs a rebuild. */
-	private update(event: AgentSessionEvent): boolean {
-		if (this.dirty) return false;
-		if (event.type === "message_update") {
-			if (!this.live || event.message.role !== "assistant") return false;
-			const calls = event.message.content.flatMap((part) => part.type === "toolCall" ? [part] : []);
-			if (calls.map((call) => call.id).join("\n") !== this.live.calls) return false;
+	/** Applies a streaming update to the shown components in place, as Pi does; the next render adds new messages. */
+	private update(event: AgentSessionEvent): void {
+		if (event.type === "message_update" && this.live && event.message.role === "assistant") {
 			this.live.component.updateContent(event.message, true);
-			for (const call of calls) this.tools.get(call.id)?.updateArgs(call.arguments);
-			return true;
-		}
-		if (event.type === "tool_execution_start" || event.type === "tool_execution_update") {
-			const tool = this.tools.get(event.toolCallId);
-			if (!tool) return false;
-			if (event.type === "tool_execution_start") tool.markExecutionStarted();
-			else tool.updateResult(event.partialResult as ToolResult, true);
-			return true;
-		}
-		return false;
+			const conversation = this.owner.agents.conversation(this.entry.id);
+			for (const part of event.message.content) {
+				if (part.type !== "toolCall") continue;
+				if (this.live.calls.has(part.id)) this.tools.get(part.id)?.updateArgs(part.arguments);
+				else if (conversation) this.addTool(part, conversation, this.display(conversation), this.live.calls);
+			}
+		} else if (event.type === "message_end" && this.live && event.message.role === "assistant") {
+			// As Pi does, the streaming message's component ends with it, before the next message streams.
+			const conversation = this.owner.agents.conversation(this.entry.id);
+			if (conversation) this.end(event.message, conversation, this.display(conversation));
+			this.ended++;
+		} else if (event.type === "tool_execution_start") this.tools.get(event.toolCallId)?.markExecutionStarted();
+		else if (event.type === "tool_execution_update") this.tools.get(event.toolCallId)?.updateResult(event.partialResult as ToolResult, true);
 	}
 
 	private refresh(): void {
 		this.attach();
-		this.dirty = true;
 		this.tui.requestRender();
 	}
 
@@ -261,7 +334,7 @@ class AgentViewer implements Component, Focusable {
 	 * The working status in the editor's border, and its color from the Agent's thinking level, as in Pi: `Working`,
 	 * spinner and text in the border's color.
 	 */
-	private syncStatus(conversation: ReturnType<AgentNode["agents"]["conversation"]>): void {
+	private syncStatus(conversation: Conversation | undefined): void {
 		this.editor.borderColor = this.theme.getThinkingBorderColor((conversation?.thinkingLevel ?? "off") as never);
 		const state = this.owner.agents.counts(this.entry.id)?.state;
 		const text = state === "running" || state === "waiting" ? "Working" : "";
@@ -273,103 +346,145 @@ class AgentViewer implements Component, Focusable {
 		this.editor.setWorkingStatusIndicator(this.indicator as unknown as StatusIndicator);
 	}
 
-	private rebuild(conversation: ReturnType<AgentNode["agents"]["conversation"]>): void {
-		this.dirty = false;
-		this.transcript.clear();
-		this.live = undefined;
-		for (const tool of this.tools.values()) stopTimer(tool);
-		this.tools.clear();
-		if (!conversation) return;
-		const messages = [...conversation.messages];
+	/** The transcript's display settings: as Pi's chat shows messages, with the settings of the Session the viewer is in. */
+	private display(conversation: Conversation) {
+		const current = agentSession(this.ctx.sessionManager);
+		const settings = current?.settingsManager;
+		const pad = settings?.getOutputPad() ?? 1;
+		return {
+			settings,
+			markdown: settings ? { ...getMarkdownTheme(), codeBlockIndent: settings.getCodeBlockIndent() } : getMarkdownTheme(),
+			transformers: current?.extensionRunner.getMarkdownTransformers(),
+			pad,
+			runner: (conversation.session ?? current)?.extensionRunner,
+			images: { showImages: settings?.getShowImages() ?? false, imageWidthCells: settings?.getImageWidthCells(), outputPad: pad },
+		};
+	}
+
+	/** Adds the conversation's new messages to the transcript, and starts over when its earlier messages changed. */
+	private sync(conversation: Conversation | undefined): void {
+		const messages = conversation?.messages ?? [];
+		if (messages.length < this.shown || (this.shown > 0 && messages[this.shown - 1] !== this.last)) {
+			this.transcript.clear();
+			this.live = undefined;
+			for (const tool of this.tools.values()) stopTimer(tool);
+			this.tools.clear();
+			this.shown = 0;
+			this.ended = 0;
+		}
 		// An input leaves the outbox once it is in the conversation, or when the Agent ends its work without it.
 		const state = this.owner.agents.counts(this.entry.id)?.state;
 		const working = state !== undefined && state !== "idle";
 		this.outbox = this.outbox.filter(({ text, after }) => working && !messages.slice(after).some((message) =>
 			message.role === "custom" && message.content === text && (message.details as { user?: boolean } | undefined)?.user));
-		if (this.streaming && !messages.includes(this.streaming)) messages.push(this.streaming);
-		// As Pi's chat shows them, with the display settings of the Session the viewer is in.
-		const current = agentSession(this.ctx.sessionManager);
-		const settings = current?.settingsManager;
-		const markdown = settings ? { ...getMarkdownTheme(), codeBlockIndent: settings.getCodeBlockIndent() } : getMarkdownTheme();
-		const transformers = current?.extensionRunner.getMarkdownTransformers();
-		const pad = settings?.getOutputPad() ?? 1;
-		const runner = (conversation.session ?? current)?.extensionRunner;
-		const images = { showImages: settings?.getShowImages() ?? false, imageWidthCells: settings?.getImageWidthCells(), outputPad: pad };
-		for (const message of messages) {
-			if (message.role === "assistant") {
-				const component = new AssistantMessageComponent(message, settings?.getHideThinkingBlock() ?? false, markdown, undefined, pad, transformers);
-				if (message === this.streaming) {
-					// As Pi does, so Markdown transformers know the message is still streaming.
-					component.updateContent(message, true);
-					const calls = message.content.flatMap((part) => part.type === "toolCall" ? [part.id] : []);
-					this.live = { component, calls: calls.join("\n") };
-				}
+		if (!conversation) return;
+		const streaming = this.streaming?.role === "assistant" && !this.live && !messages.includes(this.streaming) ? this.streaming : undefined;
+		if (messages.length === this.shown && !streaming) return;
+		const display = this.display(conversation);
+		for (const message of messages.slice(this.shown)) {
+			if (message.role !== "assistant") this.add(message, conversation, display);
+			// An ended streaming message is shown already.
+			else if (this.ended > 0) this.ended--;
+			else if (this.live) this.end(message, conversation, display);
+			else this.add(message, conversation, display);
+		}
+		this.shown = messages.length;
+		this.last = messages.at(-1);
+		if (streaming?.role === "assistant") {
+			const component = new AssistantMessageComponent(streaming, display.settings?.getHideThinkingBlock() ?? false, display.markdown, undefined, display.pad, display.transformers);
+			// As Pi does, so Markdown transformers know the message is still streaming.
+			component.updateContent(streaming, true);
+			this.transcript.addChild(component);
+			this.live = { component, calls: new Set() };
+			for (const part of streaming.content) if (part.type === "toolCall") this.addTool(part, conversation, display, this.live.calls);
+		}
+	}
+
+	/** Shows the streaming message whole as it ended. */
+	private end(message: Message, conversation: Conversation, display: Display): void {
+		if (!this.live || message.role !== "assistant") return;
+		this.live.component.updateContent(message);
+		for (const part of message.content) if (part.type === "toolCall" && !this.live.calls.has(part.id)) this.addTool(part, conversation, display);
+		this.live = undefined;
+		this.settle(message);
+	}
+
+	private addTool(call: ToolCall, conversation: Conversation, display: Display, calls?: Set<string>): void {
+		const tool = new ToolExecutionComponent(call.name, call.id, call.arguments, display.images,
+			conversation.session?.getToolDefinition(call.name), this.tui, conversation.cwd);
+		tool.setExpanded(this.expanded);
+		this.transcript.addChild(tool);
+		this.tools.set(call.id, tool);
+		calls?.add(call.id);
+		const running = this.running.get(call.id);
+		if (running) {
+			tool.markExecutionStarted();
+			if (running.partial) tool.updateResult(running.partial, true);
+		}
+	}
+
+	/** Ends the tool calls of an assistant message that stopped without running them. */
+	private settle(message: Message): void {
+		if (message.role !== "assistant" || (message.stopReason !== "aborted" && message.stopReason !== "error")) return;
+		const text = message.stopReason === "aborted" ? "Operation aborted" : message.errorMessage || "Error";
+		for (const part of message.content) {
+			if (part.type !== "toolCall") continue;
+			this.tools.get(part.id)?.updateResult({ content: [{ type: "text", text }], isError: true });
+			this.tools.delete(part.id);
+		}
+	}
+
+	private add(message: Message, conversation: Conversation, display: Display): void {
+		const { markdown, transformers, pad, runner } = display;
+		if (message.role === "assistant") {
+			this.transcript.addChild(new AssistantMessageComponent(message, display.settings?.getHideThinkingBlock() ?? false, markdown, undefined, pad, transformers));
+			for (const part of message.content) if (part.type === "toolCall") this.addTool(part, conversation, display);
+			this.settle(message);
+		} else if (message.role === "toolResult") {
+			this.tools.get(message.toolCallId)?.updateResult(message);
+			this.tools.delete(message.toolCallId);
+		} else if (message.role === "user") {
+			const text = typeof message.content === "string"
+				? message.content
+				: message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
+			if (!text) return;
+			this.transcript.addChild(new Spacer(1));
+			const skill = parseSkillBlock(text);
+			if (skill) {
+				const component = new SkillInvocationMessageComponent(skill, markdown, pad);
+				component.setExpanded(this.expanded);
 				this.transcript.addChild(component);
-				for (const part of message.content) {
-					if (part.type !== "toolCall") continue;
-					const tool = new ToolExecutionComponent(part.name, part.id, part.arguments, images,
-						conversation.session?.getToolDefinition(part.name), this.tui, conversation.cwd);
-					tool.setExpanded(this.expanded);
-					this.transcript.addChild(tool);
-					if (message.stopReason === "aborted" || message.stopReason === "error") {
-						const text = message.stopReason === "aborted" ? "Operation aborted" : message.errorMessage || "Error";
-						tool.updateResult({ content: [{ type: "text", text }], isError: true });
-					} else {
-						this.tools.set(part.id, tool);
-					}
-				}
-			} else if (message.role === "toolResult") {
-				this.tools.get(message.toolCallId)?.updateResult(message);
-				this.tools.delete(message.toolCallId);
-			} else if (message.role === "user") {
-				const text = typeof message.content === "string"
-					? message.content
-					: message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
-				if (!text) continue;
-				this.transcript.addChild(new Spacer(1));
-				const skill = parseSkillBlock(text);
-				if (skill) {
-					const component = new SkillInvocationMessageComponent(skill, markdown, pad);
-					component.setExpanded(this.expanded);
-					this.transcript.addChild(component);
-					if (skill.userMessage) {
-						this.transcript.addChild(new Spacer(1));
-						this.transcript.addChild(new UserMessageComponent(skill.userMessage, markdown, pad, transformers));
-					}
-				} else {
-					this.transcript.addChild(new UserMessageComponent(text, markdown, pad, transformers));
-				}
-			} else if (message.role === "custom" && message.display) {
-				const user = message.customType === MESSAGE_TYPE && (message.details as { user?: boolean } | undefined)?.user;
-				if (user && typeof message.content === "string") {
+				if (skill.userMessage) {
 					this.transcript.addChild(new Spacer(1));
-					this.transcript.addChild(new UserMessageComponent(message.content, markdown, pad, transformers));
-				} else {
-					// The component starts with its own blank line.
-					const component = new CustomMessageComponent(message, runner?.getMessageRenderer(message.customType), markdown, pad);
-					component.setExpanded(this.expanded);
-					this.transcript.addChild(component);
+					this.transcript.addChild(new UserMessageComponent(skill.userMessage, markdown, pad, transformers));
 				}
-			} else if (message.role === "bashExecution") {
-				const component = new BashExecutionComponent(message.command, this.tui, message.excludeFromContext, pad);
-				if (message.output) component.appendOutput(message.output);
-				component.setComplete(message.exitCode, message.cancelled, message.truncated ? { truncated: true } as never : undefined, message.fullOutputPath);
-				component.setExpanded(this.expanded);
-				this.transcript.addChild(component);
-			} else if (message.role === "compactionSummary" || message.role === "branchSummary") {
+			} else {
+				this.transcript.addChild(new UserMessageComponent(text, markdown, pad, transformers));
+			}
+		} else if (message.role === "custom" && message.display) {
+			const user = message.customType === MESSAGE_TYPE && (message.details as { user?: boolean } | undefined)?.user;
+			if (user && typeof message.content === "string") {
 				this.transcript.addChild(new Spacer(1));
-				const component = message.role === "compactionSummary"
-					? new CompactionSummaryMessageComponent(message, markdown, pad)
-					: new BranchSummaryMessageComponent(message, markdown, pad);
+				this.transcript.addChild(new UserMessageComponent(message.content, markdown, pad, transformers));
+			} else {
+				// The component starts with its own blank line.
+				const component = new CustomMessageComponent(message, runner?.getMessageRenderer(message.customType), markdown, pad);
 				component.setExpanded(this.expanded);
 				this.transcript.addChild(component);
 			}
-		}
-		for (const [id, tool] of this.tools) {
-			const running = this.running.get(id);
-			if (!running) continue;
-			tool.markExecutionStarted();
-			if (running.partial) tool.updateResult(running.partial, true);
+		} else if (message.role === "bashExecution") {
+			const component = new BashExecutionComponent(message.command, this.tui, message.excludeFromContext, pad);
+			if (message.output) component.appendOutput(message.output);
+			component.setComplete(message.exitCode, message.cancelled, message.truncated ? { truncated: true } as never : undefined, message.fullOutputPath);
+			component.setExpanded(this.expanded);
+			this.transcript.addChild(component);
+		} else if (message.role === "compactionSummary" || message.role === "branchSummary") {
+			this.transcript.addChild(new Spacer(1));
+			const component = message.role === "compactionSummary"
+				? new CompactionSummaryMessageComponent(message, markdown, pad)
+				: new BranchSummaryMessageComponent(message, markdown, pad);
+			component.setExpanded(this.expanded);
+			this.transcript.addChild(component);
 		}
 	}
 }
@@ -406,20 +521,25 @@ class ProgramViewer implements Component, Focusable {
 	}
 
 	handleInput(data: string): void {
-		const page = Math.max(1, this.tui.terminal.rows - 4);
+		const lines = scrollKey(this.keys, data, Math.max(1, this.tui.terminal.rows - 4));
 		if (this.keys.matches(data, "app.clear" as never)) return this.done();
 		if (this.keys.matches(data, "app.interrupt" as never)) this.stop();
 		else if (this.keys.matches(data, "app.tools.expand" as never)) {
 			this.expanded = !this.expanded;
 			this.tool.setExpanded(this.expanded);
-		} else if (this.keys.matches(data, "tui.altScreen.pageUp")) this.scroll += page;
-		else if (this.keys.matches(data, "tui.altScreen.pageDown")) this.scroll = Math.max(0, this.scroll - page);
+		} else if (lines !== undefined) this.scroll = Math.max(0, this.scroll + lines);
 		this.tui.requestRender();
 	}
 
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (event.type !== "wheel" || !event.wheelDelta) return undefined;
+		this.scroll = Math.max(0, this.scroll - event.wheelDelta);
+		return { handled: true };
+	}
+
 	render(width: number): string[] {
 		const running = this.programs.view(this.id)?.record.state === "running";
-		const hints = [...running ? [keyHint("app.interrupt", "stop")] : [], keyHint("app.clear", "back")].join("  ");
+		const hints = [...running ? [keyHint("app.interrupt", "stop")] : [], this.theme.fg("accent", `${keyText("app.clear")} back`)].join("  ");
 		const footer = truncateToWidth(" ".repeat(Math.max(0, width - visibleWidth(hints))) + hints, width);
 		const border = new DynamicBorder().render(width);
 		const budget = Math.max(1, this.tui.terminal.rows - border.length - 2);
@@ -514,27 +634,28 @@ class ListSelector extends Container implements Focusable {
 /** The Agents in the current Agent's tree, including Programs' Agents, those not idle first and newest first within each group. */
 export function ownedEntries(self: AgentNode): Entry[] {
 	const entries: Entry[] = [];
-	const visit = (node: AgentNode) => {
-		for (const agent of node.agents.owned()) {
-			entries.push({ ...agent, ownerId: node.id });
-			const loaded = nodes.get(agent.id);
-			if (loaded) visit(loaded);
+	const visit = (tasks: Task[]) => {
+		for (const task of tasks) {
+			if ("entry" in task) entries.push(task.entry);
+			visit(task.tasks);
 		}
-		for (const program of programsOf(node)) visit(program);
 	};
-	visit(self);
+	visit(tasksOf(self));
 	return entries.sort((a, b) => Number(b.state !== "idle") - Number(a.state !== "idle") || (b.createdAt ?? "").localeCompare(a.createdAt ?? ""));
 }
 
 const PROGRAM_ITEM = "program:";
 
 /**
- * `/tasks`: picks an Agent in the tree or a background Program, live ones first and newest first, and opens it in
- * the viewer. `paddingX` is Pi's editor padding, so the viewer's editor lines up as Pi's does.
+ * `/tasks`: picks an Agent in the tree, a background Program of the current Agent, or a running one of another Agent, live ones first and newest first, and opens
+ * it in the viewer. `paddingX` is Pi's editor padding, so the viewer's editor lines up as Pi's does.
  */
-export async function openTaskViewer(ctx: ExtensionContext, self: AgentNode, programs: Programs | undefined, paddingX: number): Promise<void> {
+export async function openTaskViewer(ctx: ExtensionContext, self: AgentNode, paddingX: number): Promise<void> {
 	const entries = ownedEntries(self);
-	const records = programs?.list() ?? [];
+	const records = [self, ...entries.flatMap((entry) => nodes.get(entry.id) ?? [])]
+		.flatMap((caller) => caller.programs?.list().map((record) => ({ caller, programs: caller.programs!, record })) ?? [])
+		// Another Agent's ended Programs show in its conversation; its Session may not be loaded to list them.
+		.filter(({ caller, record }) => caller === self || record.state === "running");
 	if (entries.length === 0 && records.length === 0) {
 		ctx.ui.notify("No tasks.", "info");
 		return;
@@ -554,20 +675,25 @@ export async function openTaskViewer(ctx: ExtensionContext, self: AgentNode, pro
 			label: path(entry),
 			description: [entry.state, latestActivity(entry.sessionFile) ?? ""].filter(Boolean).join("  "),
 		} })),
-		...records.map((record) => ({ live: record.state === "running", at: new Date(record.startedAt).toISOString(), item: {
+		...records.map(({ caller, programs, record }) => ({ live: record.state === "running", at: new Date(record.startedAt).toISOString(), item: {
 			value: PROGRAM_ITEM + record.id,
-			label: `Program ${programs!.label(record)}`,
+			label: `Program ${programs.label(record)}${caller === self ? "" : ` ‹ ${path(byId.get(caller.id)!)}`}`,
 			description: record.state,
 		} })),
 	];
 	const items: SelectItem[] = tasks
 		.sort((a, b) => Number(b.live) - Number(a.live) || b.at.localeCompare(a.at))
 		.map((task) => task.item);
-	const id = await ctx.ui.custom<string | undefined>((_tui, theme, keys, done) =>
-		new ListSelector("Open task:", items, theme, keys, (value) => done(value), () => done(undefined)));
-	if (id?.startsWith(PROGRAM_ITEM) && programs) {
+	// In regular mode, a viewer shows over the screen; in fullscreen mode, it takes Pi's layout (`mountViewer`).
+	let overlay = true;
+	const id = await ctx.ui.custom<string | undefined>((tui, theme, keys, done) => {
+		overlay = !isViewportTUI(tui);
+		return new ListSelector("Open task:", items, theme, keys, (value) => done(value), () => done(undefined));
+	});
+	const program = id?.startsWith(PROGRAM_ITEM) ? records.find(({ record }) => record.id === id.slice(PROGRAM_ITEM.length)) : undefined;
+	if (program) {
 		await ctx.ui.custom<void>(
-			(tui, theme, keys, done) => new ProgramViewer(tui, theme, keys, ctx, programs, id.slice(PROGRAM_ITEM.length), () => done()),
+			(tui, theme, keys, done) => new ProgramViewer(tui, theme, keys, ctx, program.programs, program.record.id, () => done()),
 			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" } },
 		);
 		return;
@@ -584,6 +710,6 @@ export async function openTaskViewer(ctx: ExtensionContext, self: AgentNode, pro
 	}
 	await ctx.ui.custom<void>(
 		(tui, theme, keys, done) => new AgentViewer(tui, theme, keys, ctx, owner, entry, session, paddingX, () => done()),
-		{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" } },
+		overlay ? { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" } } : undefined,
 	);
 }

package/src/workbench.mjs

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { styleText } from 'node:util';
 import { setTimeout as delay } from 'node:timers/promises';
-import { alive, attach, listHosts, settledHosts, startHost } from './host/client.mjs';
+import { alive, attach, drain, listHosts, settledHosts, startHost } from './host/client.mjs';
 import { detachKey, detachMatcher } from './host/keys.mjs';
 import { piPackage } from './pi.mjs';
 import { ensureDaemon, sendViaDaemon } from './daemon/client.mjs';
@@ -351,7 +351,8 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function attachTo(socket) {
     ui.stop();
     let result;
-    try { result = await attach(socket, { isDetach }); }
+    // The list reads the terminal again at once, and skips late key releases itself.
+    try { result = await attach(socket, { isDetach, drainInput: false }); }
     finally {
       process.stdout.write(ALT_SCREEN);
       ui.start();
@@ -551,9 +552,8 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
         fold();
         summarize('branch summary');
       } else if (message.role === 'custom') {
-        const from = message.customType === 'pi-agents' ? message.details?.sender?.name ?? message.details?.sender?.id : undefined;
         fold();
-        summarize(from ? `message from ${from}` : `${message.customType} message`);
+        summarize(`${message.customType} message`);
       }
     }
     fold();
@@ -623,10 +623,14 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     if (quitting) return;
     quitting = true;
     stream?.close();
-    // Late key releases would otherwise leak into the shell, as Pi avoids on exit.
     themeSync.disableAutoSync();
-    await terminal.drainInput(1000);
     ui.stop();
+    // Late key releases would otherwise leak into the shell, as when detaching from a Session.
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    await drain(process.stdin, process.stdout);
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
     process.stdout.write(`${MAIN_SCREEN}${styleText('dim', 'Sessions keep running. To reopen:')} pd agents\n`);
     finish();
   }