@tshu-w/pi-agents 0.1.1 → 0.2.0

package/src/roots/transport.mjs

@@ -1,9 +1,10 @@
 import net from 'node:net';
-import { StringDecoder } from 'node:string_decoder';
 import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 
 const MAX_BYTES = 1024 * 1024;
+// Pi's events on an rpc stream carry whole messages, images included.
+const RPC_MAX_BYTES = 256 * 1024 * 1024;
 const MAX_SOCKET_PATH_BYTES = 103;
 const MAX_PENDING = 64;
 // Each running Pi keeps a stream open to the daemon.
@@ -39,9 +40,9 @@ function safeDirectory(path, create = false) {
 function privateSocket(path) {
   safeDirectory(dirname(path));
   const info = lstatSync(path);
-  if (!info.isSocket() || info.uid !== process.getuid() || (info.mode & 0o777) !== 0o600) {
-    throw fault('UNSAFE_PATH', 'Socket must be owned by the current user with mode 0600');
-  }
+  if (!info.isSocket() || info.uid !== process.getuid()) throw fault('UNSAFE_PATH', 'Socket must be owned by the current user');
+  // A listener sets the mode just after it binds; a client waiting for a new listener may retry this.
+  if ((info.mode & 0o777) !== 0o600) throw fault('SOCKET_MODE', 'Socket must have mode 0600');
 }
 
 const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -51,7 +52,7 @@ function validate(value) {
   if (!record(value)) throw fault('INVALID_REQUEST', 'Expected a request object');
   if (value.action === 'status') return { action: 'status' };
   if (value.action === 'stream') {
-    if (value.role !== 'session' && value.role !== 'workbench') throw fault('INVALID_REQUEST', 'stream role must be session or workbench');
+    if (!['session', 'workbench', 'rpc', 'print'].includes(value.role)) throw fault('INVALID_REQUEST', 'stream role must be session, workbench, rpc or print');
     return { action: 'stream', role: value.role };
   }
   const m = value.message, l = value.launch;
@@ -75,12 +76,14 @@ function validate(value) {
   }, ...(l === undefined ? {} : { launch: { command: l.command, args: [...l.args], env: { ...l.env } } }) };
 }
 
-function encode(value) {
+function encode(value, limit = MAX_BYTES) {
   const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
-  if (bytes.length > MAX_BYTES) throw fault('FRAME_TOO_LARGE', 'JSONL frame exceeds 1 MiB');
+  if (bytes.length > limit) throw fault('FRAME_TOO_LARGE', `JSONL frame exceeds ${limit / 1024 / 1024} MiB`);
   return bytes;
 }
 
+const streamLimit = role => role === 'rpc' || role === 'print' ? RPC_MAX_BYTES : MAX_BYTES;
+
 // Consume exactly one bounded JSONL frame; never dispatch additional requests.
 function readFrame(socket, done) {
   let chunks = [], size = 0, finished = false;
@@ -108,28 +111,33 @@ function readFrame(socket, done) {
 }
 
 // JSONL messages after a stream's opening frame.
-function readLines(socket, onLine, onInvalid) {
-  const decoder = new StringDecoder('utf8');
-  let buffer = '';
+function readLines(socket, onLine, onInvalid, limit) {
+  // An unfinished line is kept as chunks, so each byte is scanned once.
+  let pending = [], size = 0;
   socket.on('data', chunk => {
-    buffer += decoder.write(chunk);
-    for (let newline; (newline = buffer.indexOf('\n')) >= 0;) {
-      const line = buffer.slice(0, newline);
-      buffer = buffer.slice(newline + 1);
+    let start = 0;
+    for (let newline; (newline = chunk.indexOf(10, start)) >= 0; start = newline + 1) {
+      const line = Buffer.concat([...pending, chunk.subarray(start, newline)]).toString('utf8');
+      pending = [];
+      size = 0;
       let value;
       try { value = JSON.parse(line); } catch { return onInvalid(); }
       onLine(value);
     }
-    if (Buffer.byteLength(buffer) > MAX_BYTES) onInvalid();
+    if (start < chunk.length) {
+      pending.push(chunk.subarray(start));
+      size += chunk.length - start;
+    }
+    if (size > limit) onInvalid();
   });
 }
 
-function channel(socket, signal) {
+function channel(socket, signal, limit) {
   const listeners = [];
-  readLines(socket, value => { for (const listener of listeners) listener(value); }, () => socket.destroy());
+  readLines(socket, value => { for (const listener of listeners) listener(value); }, () => socket.destroy(), limit);
   return {
     signal,
-    send(value) { if (!socket.destroyed && !socket.writableEnded) socket.write(encode(value)); },
+    send(value) { if (!socket.destroyed && !socket.writableEnded) socket.write(encode(value, limit)); },
     onMessage(listener) { listeners.push(listener); },
     close() { socket.destroy(); },
   };
@@ -145,7 +153,8 @@ function errorFrame(error) {
 
 /**
  * FIFO by default. Handlers receive a connection-lifetime signal, not an acceptance rollback.
- * `stream` takes over the connections that open a stream; they keep the server from being idle.
+ * `stream` takes over the connections that open a stream; they keep the server from being idle. It may
+ * refuse a stream by throwing; its result joins the acceptance, which reaches the client before anything it sends.
  * @param {string} socketPath
  * @param {{ status: Function, accept: Function, stream?: Function, serialize?: boolean }} handlers
  */
@@ -189,8 +198,17 @@ export async function listen(socketPath, { status, accept, stream, serialize = t
       if (input.action === 'stream') {
         if (!stream) return respond(fault('INVALID_REQUEST', 'Streams are not supported here'));
         clearTimeout(timer);
-        socket.write(encode({ ok: true, result: { pid: process.pid } }));
-        return stream(input, channel(socket, signal));
+        const opened = channel(socket, signal, streamLimit(input.role));
+        const send = opened.send;
+        const early = [];
+        opened.send = value => early.push(value);
+        let result;
+        try { result = stream(input, opened); }
+        catch (failure) { return respond(failure); }
+        socket.write(encode({ ok: true, result: { pid: process.pid, ...result } }));
+        opened.send = send;
+        for (const value of early) send(value);
+        return;
       }
       if (pending >= MAX_PENDING) return respond(fault('SERVER_BUSY', 'Request queue is full'));
       pending++;
@@ -332,10 +350,10 @@ export function openStream(socketPath, input, { onMessage, onClose }) {
       opened = true;
       resolvePromise({
         result: response.result,
-        send(message) { if (!socket.destroyed && !socket.writableEnded) socket.write(encode(message)); },
+        send(message) { if (!socket.destroyed && !socket.writableEnded) socket.write(encode(message, streamLimit(value.role))); },
         close() { socket.destroy(); },
         unref() { socket.unref(); },
       });
-    }, () => socket.destroy());
+    }, () => socket.destroy(), streamLimit(value.role));
   });
 }

package/src/ui/panel.ts

@@ -1,16 +1,34 @@
 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 } from "../agents/registry.ts";
+import { label, nodes, onTreeChange, programLabel, programsOf, type AgentNode, type Spend } from "../agents/registry.ts";
 
 const WIDGET_KEY = "pi-agents";
 
 const MAX_LINES = 10;
 
+/** Time since `since` as Pi's bash tool shows durations, in whole seconds: `45s`, `1m 32s`, `1h 5m 3s`. */
+function elapsed(since: number, now: number): string {
+	const seconds = Math.max(0, Math.floor((now - since) / 1000));
+	const minutes = Math.floor(seconds / 60);
+	if (minutes === 0) return `${seconds}s`;
+	return minutes < 60 ? `${minutes}m ${seconds % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m ${seconds % 60}s`;
+}
+
+/** `$2.10`, or the input and output tokens as Pi's footer shows them, `7.3M tok`, when a reply had no price. */
+function cost({ cost, tokens, unpriced }: Spend): string {
+	if (!unpriced) return `$${cost.toFixed(2)}`;
+	if (tokens < 1000) return `${tokens} tok`;
+	if (tokens < 10_000) return `${(tokens / 1000).toFixed(1)}k tok`;
+	if (tokens < 1_000_000) return `${Math.round(tokens / 1000)}k tok`;
+	return tokens < 10_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M tok` : `${Math.round(tokens / 1_000_000)}M tok`;
+}
+
 /**
  * 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. Empty when none.
+ * order they started, with their Programs' live Agents under them, and how long each has run and what
+ * it has cost. Empty when none.
  */
-export function panelLines(self: AgentNode): string[] {
+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;
@@ -26,7 +44,9 @@ export function panelLines(self: AgentNode): string[] {
 		for (const child of children) {
 			const index = rows.length;
 			if ("program" in child) {
-				rows.push({ line: `${"  ".repeat(level)}${programLabel(child.program)}  running`, parent, shown: false });
+				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);
@@ -35,7 +55,8 @@ export function panelLines(self: AgentNode): string[] {
 			const { entry } = child;
 			const own = node.agents.counts(entry.id);
 			const pending = own?.pending ? [`${own.pending} pending`] : [];
-			rows.push({ line: `${"  ".repeat(level)}Agent ${[label(entry, ids), entry.state, ...pending].join("  ")}`, parent, shown: false });
+			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);
@@ -48,21 +69,30 @@ export function panelLines(self: AgentNode): string[] {
 	const lines = rows.filter((row) => row.shown).map((row) => row.line);
 	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 hide)`, ...lines.map((line) => `  ${line}`)];
+	return [`Tasks (${live} live, /tasks to view)`, ...lines.map((line) => `  ${line}`)];
 }
 
-/** Keeps the task panel above the editor current while the Session is loaded; `toggle` hides or shows it. */
+/**
+ * Keeps the task panel above the editor current while the Session is loaded, and its times each second
+ * while it shows; `toggle` hides or shows it.
+ */
 export function createPanel(getNode: () => AgentNode | undefined) {
 	let ctx: ExtensionContext | undefined;
 	let hidden = false;
 	let scheduled = false;
 	let unsubscribe: (() => void) | undefined;
+	let ticker: ReturnType<typeof setInterval> | undefined;
 
 	const render = () => {
 		scheduled = false;
 		const node = getNode();
 		if (!ctx?.hasUI || !node) return;
 		const lines = hidden ? [] : panelLines(node);
+		if (lines.length > 0) ticker ??= setInterval(render, 1000);
+		else {
+			clearInterval(ticker);
+			ticker = undefined;
+		}
 		ctx.ui.setWidget(WIDGET_KEY, lines.length === 0 ? undefined : (_tui, theme) => {
 			const panel = new Container();
 			lines.forEach((line, index) => panel.addChild(new TruncatedText(theme.fg(index === 0 ? "accent" : "muted", line), 0, 0)));
@@ -87,6 +117,8 @@ export function createPanel(getNode: () => AgentNode | undefined) {
 			render();
 		},
 		stop() {
+			clearInterval(ticker);
+			ticker = undefined;
 			unsubscribe?.();
 			unsubscribe = undefined;
 			if (ctx?.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);

package/src/ui/queue.ts

@@ -0,0 +1,46 @@
+import type { AgentSession, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { TruncatedText, type TUI } from "@earendil-works/pi-tui";
+import { MESSAGE_TAG, MESSAGE_TYPE } from "../agents/registry.ts";
+
+const WIDGET_KEY = "pi-agents-queue";
+
+type Queued = { role: string; customType?: string; content?: unknown; details?: { delivery?: string } };
+
+/** One line for an Agent message: its sender and body. */
+function summary(content: unknown): string {
+	const text = typeof content === "string" ? content : "";
+	const match = new RegExp(`^<${MESSAGE_TAG} from="([^"]*)"[^>]*>\\n([\\s\\S]*)\\n</${MESSAGE_TAG}>$`).exec(text);
+	return (match ? `[${match[1]}] ${match[2]}` : text).replace(/\s+/g, " ").trim();
+}
+
+/** Agent messages waiting in the Session's queues, which Pi does not list as it lists the user's. */
+export function queuedLines(agent: AgentSession["agent"]): string[] {
+	const queues = agent as unknown as Record<"steeringQueue" | "followUpQueue", { messages: Queued[] }>;
+	const lines = (label: string, messages: Queued[]) => messages
+		.filter((message) => message.role === "custom" && message.customType === MESSAGE_TYPE)
+		// A write waits in the steering queue but asks for nothing, so it is labeled apart from a steer.
+		.map((message) => `${message.details?.delivery === "write" ? "Write" : label}: ${summary(message.content)}`);
+	return [...lines("Steering", queues.steeringQueue.messages), ...lines("Follow-up", queues.followUpQueue.messages)];
+}
+
+/**
+ * Lists the Agent messages queued in `session` under Pi's own queued messages. The list is read from
+ * the queues on each render, so it follows them as they are consumed or cleared; `update` renders it
+ * after a message is queued.
+ */
+export function showQueue(ctx: ExtensionContext, session: () => AgentSession | undefined) {
+	let tui: TUI | undefined;
+	if (ctx.hasUI) {
+		ctx.ui.setWidget(WIDGET_KEY, (current, theme) => {
+			tui = current;
+			return {
+				render: (width: number) => {
+					const agent = session()?.agent;
+					return agent ? queuedLines(agent).flatMap((line) => new TruncatedText(theme.fg("dim", line), 1, 0).render(width)) : [];
+				},
+				invalidate() {},
+			};
+		});
+	}
+	return { update: () => tui?.requestRender() };
+}

package/src/ui/viewer.ts

@@ -36,12 +36,22 @@ import {
 } from "@earendil-works/pi-tui";
 import { MESSAGE_TYPE, nodes, onTreeChange, programLabel, programsOf, type AgentNode, type Entry } 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";
+import { agentSession } from "../roots/rpc.ts";
 import { execFileSync } from "node:child_process";
 
 type Message = AgentSession["messages"][number];
 type ToolResult = Parameters<ToolExecutionComponent["updateResult"]>[0];
 type StatusIndicator = Parameters<CustomEditor["setWorkingStatusIndicator"]>[0];
 
+/** Stops the elapsed-time timer of a tool component the viewer drops; only a final result stops it otherwise. */
+function stopTimer(tool: ToolExecutionComponent): void {
+	const state = (tool as unknown as { rendererState: { interval?: ReturnType<typeof setInterval> } }).rendererState;
+	clearInterval(state.interval);
+	state.interval = undefined;
+}
+
 /** A spinner and message for the editor's top border, like Pi's working status. */
 class WorkingStatus extends Loader {
 	renderInBorder(width: number): string {
@@ -179,6 +189,7 @@ class AgentViewer implements Component, Focusable {
 	dispose(): void {
 		this.indicator?.dispose();
 		this.footer.dispose();
+		for (const tool of this.tools.values()) stopTimer(tool);
 		for (const dispose of this.disposers.splice(0)) dispose();
 	}
 
@@ -264,6 +275,7 @@ class AgentViewer implements Component, Focusable {
 		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];
@@ -328,6 +340,80 @@ class AgentViewer implements Component, Focusable {
 	}
 }
 
+/** The user's view of one background Program, as its tool call shows in the foreground. */
+class ProgramViewer implements Component, Focusable {
+	private readonly tool: ToolExecutionComponent;
+	private expanded = false;
+	/** Lines scrolled up from the end. */
+	private scroll = 0;
+	private disposers: Array<() => void> = [];
+	focused = false;
+
+	constructor(
+		private tui: TUI,
+		private theme: Theme,
+		private keys: KeybindingsManager,
+		private ctx: ExtensionContext,
+		private programs: Programs,
+		private id: string,
+		private done: () => void,
+	) {
+		const code = programs.view(id)?.code;
+		this.tool = new ToolExecutionComponent(PROGRAM_TOOL_NAME, `program-${id}`, { action: "run", background: true, ...(code !== undefined && { code }) }, { showImages: false },
+			agentSession(ctx.sessionManager)?.getToolDefinition(PROGRAM_TOOL_NAME), tui, ctx.cwd);
+		this.tool.markExecutionStarted();
+		this.sync();
+		this.disposers.push(programs.onView(() => {
+			this.sync();
+			this.tui.requestRender();
+		}));
+	}
+
+	handleInput(data: string): void {
+		const page = 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 (matchesKey(data, "pageUp")) this.scroll += page;
+		else if (matchesKey(data, "pageDown")) this.scroll = Math.max(0, this.scroll - page);
+		this.tui.requestRender();
+	}
+
+	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 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);
+		const lines = this.tool.render(width);
+		this.scroll = Math.min(this.scroll, Math.max(0, lines.length - budget));
+		const end = lines.length - this.scroll;
+		// As tall as its content, so the Session shows above it.
+		return [...border, ...lines.slice(Math.max(0, end - budget), end), " ".repeat(width), footer];
+	}
+
+	invalidate(): void {
+		this.tool.invalidate();
+	}
+
+	dispose(): void {
+		stopTimer(this.tool);
+		for (const dispose of this.disposers.splice(0)) dispose();
+	}
+
+	private sync(): void {
+		const view = this.programs.view(this.id);
+		if (view?.result) this.tool.updateResult(view.result as ToolResult, view.record.state === "running");
+	}
+
+	private stop(): void {
+		this.programs.stop(this.programs.target(this.id)).catch((error: unknown) =>
+			this.ctx.ui.notify(error instanceof Error ? error.message : String(error), "error"));
+	}
+}
+
 /** A filterable list in place of the editor, like Pi Durable's conversation switcher. */
 class ListSelector extends Container implements Focusable {
 	private readonly input = new Input();
@@ -404,12 +490,17 @@ export function ownedEntries(self: AgentNode): Entry[] {
 	return entries.sort((a, b) => Number(b.state !== "idle") - Number(a.state !== "idle") || (b.createdAt ?? "").localeCompare(a.createdAt ?? ""));
 }
 
-/** `/agents`: picks an owned Agent 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 openAgentViewer(ctx: ExtensionContext, self: AgentNode, paddingX: number): Promise<void> {
+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.
+ */
+export async function openTaskViewer(ctx: ExtensionContext, self: AgentNode, programs: Programs | undefined, paddingX: number): Promise<void> {
 	const entries = ownedEntries(self);
-	if (entries.length === 0) {
-		ctx.ui.notify("No owned Agents.", "info");
+	const records = programs?.list() ?? [];
+	if (entries.length === 0 && records.length === 0) {
+		ctx.ui.notify("No tasks.", "info");
 		return;
 	}
 	const byId = new Map(entries.map((entry) => [entry.id, entry]));
@@ -421,13 +512,30 @@ export async function openAgentViewer(ctx: ExtensionContext, self: AgentNode, pa
 		return program?.program ? ` ‹ ${programLabel(program)}${owners(program.ownerId)}` : "";
 	};
 	const path = (entry: Entry): string => `${entry.name ?? entry.id}${owners(entry.ownerId)}`;
-	const items: SelectItem[] = entries.map((entry) => ({
-		value: entry.id,
-		label: path(entry),
-		description: [entry.state, latestActivity(entry.sessionFile) ?? ""].filter(Boolean).join("  "),
-	}));
+	const tasks = [
+		...entries.map((entry) => ({ live: entry.state !== "idle", at: entry.createdAt ?? "", item: {
+			value: entry.id,
+			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: {
+			value: PROGRAM_ITEM + record.id,
+			label: `Program ${programs!.label(record)}`,
+			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 Agent:", items, theme, keys, (value) => done(value), () => done(undefined)));
+		new ListSelector("Open task:", items, theme, keys, (value) => done(value), () => done(undefined)));
+	if (id?.startsWith(PROGRAM_ITEM) && programs) {
+		await ctx.ui.custom<void>(
+			(tui, theme, keys, done) => new ProgramViewer(tui, theme, keys, ctx, programs, id.slice(PROGRAM_ITEM.length), () => done()),
+			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "bottom-center" } },
+		);
+		return;
+	}
 	const entry = id === undefined ? undefined : byId.get(id);
 	const owner = entry?.ownerId === undefined ? undefined : nodes.get(entry.ownerId);
 	if (!entry || !owner) return;

package/src/workbench.mjs

@@ -6,8 +6,9 @@ import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 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, startHost } from './host/client.mjs';
+import { alive, attach, 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';
@@ -75,9 +76,9 @@ const COMMANDS = [
 // Pi's working spinner.
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const GROUPS = [
-  ['attention', 'Needs input', 'Sessions waiting on you or with a finished turn you have not seen land here'],
-  ['working', 'Working', 'Sessions Pi is working on; they keep running after you leave'],
-  ['completed', 'Completed', 'Sessions you have seen wait here'],
+  ['attention', 'Needs attention', 'Sessions with a question for you or a reply you have not read'],
+  ['working', 'Working', 'Sessions still working; they keep running when you close the terminal'],
+  ['completed', 'Completed', 'Sessions with nothing new for you'],
 ];
 
 function stateOf(session) {
@@ -112,6 +113,8 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   let sessions = [], stream, connected = false, quitting = false;
   // `picked` is the Session last chosen with `@` and its mention; a message starting with the mention goes to it.
   let selectedKey, top = 0, notice, modal, pane, picked, lastCtrlC = 0, finish;
+  // Messages in flight by Session ID; each settles once the daemon has delivered it, waking the Session if needed.
+  const sending = new Map();
 
   /** How `@` refers to a Session: its name when that is one word, otherwise the shortest unique ID prefix. */
   function mention(session) {
@@ -201,8 +204,9 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     // While the preview is open, the keys are its own: Enter may send a message, so `app.tools.expand` attaches.
     const keys = pane ? [
       hints.keyHint('app.tools.expand', 'attach'),
-      hints.rawKeyHint(`${hints.keyText('tui.altScreen.pageUp')}/${hints.keyText('tui.altScreen.pageDown')}`, 'scroll'),
-      hints.rawKeyHint('esc', 'close'),
+      hints.rawKeyHint(['lineUp', 'halfPageUp', 'pageUp', 'lineDown', 'halfPageDown', 'pageDown']
+        .map(name => hints.keyText(`tui.altScreen.${name}`)).filter(Boolean).join('/'), 'scroll'),
+      hints.rawKeyHint(`${detach}/esc`, 'close'),
     ].join(theme.fg('muted', ' · ')) : [
       hints.rawKeyHint('enter', 'attach'),
       hints.rawKeyHint(detach, 'quit'),
@@ -275,8 +279,8 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     handleInput(data) {
       // Holding only the preview's mention, the input counts as empty.
       const empty = ['', pane?.mention].includes(editor.getText());
-      // As in a Session, the detach key leaves and everything keeps running.
-      if (isDetach(data)) return void quit();
+      // As in a Session, the detach key leaves and everything keeps running; in the preview, it returns to the list.
+      if (isDetach(data)) return void (pane ? pane.close() : quit());
       if (pane?.handleInput(data, empty)) return;
       if (T.matchesKey(data, 'ctrl+c')) {
         if (!empty) return editor.setText(pane?.mention ?? '');
@@ -365,7 +369,10 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function openSession(session) {
     stream?.send({ type: 'show', id: session.id });
     try {
-      const hosted = (await listHosts(paths)).find(host => host.session?.id === session.id);
+      // A message just sent may be waking the Session in a host.
+      await sending.get(session.id);
+      const running = host => host.session?.id === session.id;
+      const hosted = (await settledHosts(paths, running)).find(running);
       if (hosted) return await attachTo(hosted.socket);
       if (session.running || session.status === 'unknown') {
         return say(`${named(session)} runs outside a host; attach it after it exits.`, 'warning');
@@ -422,7 +429,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     catch (error) { return say(error.message, 'error'); }
     let body = conversation(messages);
     const border = themes.getEditorTheme().borderColor;
-    let scroll = 0, page = 1, timer;
+    let scroll = 0, page = 1, timer, scrolled, hideBar;
     // A turn the preview shows counts as seen.
     const see = () => stream?.send({ type: 'see', id: session.id });
     see();
@@ -440,6 +447,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
       watcher.close();
       see();
       clearTimeout(timer);
+      clearTimeout(hideBar);
       // A draft stays, still addressed to the Session.
       if (editor.getText() === pane?.mention) editor.setText('');
       pane = undefined;
@@ -454,14 +462,23 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
       invalidate() { body.invalidate(); },
       /** A short conversation takes only its own height; a longer one takes `max` lines and scrolls. */
       render(width, max) {
-        const current = sessions.find(other => other.id === session.id) ?? session;
-        const live = ['working', 'blocked', 'unknown'].includes(current.status) ? `  ${icon(current)} ${activity(current)}` : '';
-        const head = truncate(` ${theme.bold(label(session))}  ${theme.fg('dim', session.cwd ?? '')}${live}`, width);
-        const lines = body.render(width);
+        // The selected row and the input's mention name the Session, so the preview needs no title. A blank line
+        // sets it apart from the list.
+        const top = ['', border('─'.repeat(width))];
+        const bar = width > 1 ? settings.getFullscreenScrollbar() : 'hidden';
+        // The conversation starts right below the border.
+        const lines = body.render(bar === 'always' ? width - 1 : width);
+        while (lines.length && !T.stripTerminalSequences(lines[0]).trim()) lines.shift();
         page = Math.max(1, max - 2);
         scroll = Math.min(scroll, Math.max(0, lines.length - page));
-        const end = lines.length - scroll;
-        return [border('─'.repeat(width)), head, ...lines.slice(Math.max(0, end - page), end)];
+        const end = lines.length - scroll, start = Math.max(0, end - page);
+        const shown = lines.slice(start, end);
+        if (bar !== 'always' && !(bar === 'auto' && scrolled && lines.length > page)) return [...top, ...shown];
+        // The scrollbar of Pi's fullscreen transcript, in the last column.
+        const track = shown.length, size = Math.max(Math.min(2, track), Math.min(track, Math.round(track * track / lines.length)));
+        const offset = lines.length === track ? 0 : Math.round(start / (lines.length - track) * (track - size));
+        const cell = row => row >= offset && row < offset + size ? theme.fg('scrollbarThumb', '┃') : theme.fg('scrollbarTrack', '│');
+        return [...top, ...shown.map((line, row) => `${T.truncateToWidth(line, width - 1, '', true)}${cell(row)}`)];
       },
       /** Enter, `↑`/`↓`, and Space act on the preview only while no message is typed. */
       handleInput(data, empty) {
@@ -478,10 +495,17 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
           close();
           return true;
         }
-        const step = empty && T.matchesKey(data, 'up') ? 1 : empty && T.matchesKey(data, 'down') ? -1
-          : keybindings.matches(data, 'tui.altScreen.pageUp') ? page - 1 : keybindings.matches(data, 'tui.altScreen.pageDown') ? 1 - page : 0;
+        // The scroll keys of Pi's fullscreen mode; a step counts lines up from the end.
+        const half = Math.max(1, Math.floor(page / 2));
+        const steps = { lineUp: 1, lineDown: -1, halfPageUp: half, halfPageDown: -half, pageUp: page - 1, pageDown: 1 - page, top: Infinity, bottom: -Infinity };
+        const action = Object.keys(steps).find(name => keybindings.matches(data, `tui.altScreen.${name}`));
+        const step = empty && T.matchesKey(data, 'up') ? 1 : empty && T.matchesKey(data, 'down') ? -1 : action ? steps[action] : 0;
         if (!step) return false;
         scroll = Math.max(0, scroll + step);
+        // As in Pi's `auto` mode, the scrollbar shows while scrolling and for a second after.
+        scrolled = true;
+        clearTimeout(hideBar);
+        hideBar = setTimeout(() => { scrolled = false; ui.requestRender(); }, 1000);
         ui.requestRender();
         return true;
       },
@@ -528,8 +552,12 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function send(session, body) {
     say(`Sending to ${named(session)}…`);
     const message = { id: randomUUID(), user: true, recipient: session.id, body };
+    const pending = sendViaDaemon(paths, message, { sessionDir, launch: { command: executable, args: [], env } });
+    const settled = pending.then(() => {}, () => {});
+    sending.set(session.id, settled);
+    void settled.then(() => { if (sending.get(session.id) === settled) sending.delete(session.id); });
     try {
-      const receipt = await sendViaDaemon(paths, message, { sessionDir, launch: { command: executable, args: [], env } });
+      const receipt = await pending;
       if (receipt?.accepted !== true || receipt.messageId !== message.id) throw new Error(`Invalid acknowledgement from ${named(session)}; it may have received the message.`);
       say(`Sent to ${named(session)}.`);
     } catch (error) { say(error.message, 'error'); }
@@ -587,7 +615,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     themeSync.disableAutoSync();
     await terminal.drainInput(1000);
     ui.stop();
-    process.stdout.write(`${MAIN_SCREEN}Sessions keep running. To reopen, run pd agents\n`);
+    process.stdout.write(`${MAIN_SCREEN}${styleText('dim', 'Sessions keep running. To reopen:')} pd agents\n`);
     finish();
   }