@giladbarnea/pi-user-agents 0.0.5 → 0.0.7

package/INTERNALS.md

@@ -16,9 +16,9 @@ How a finished run reaches (or hides from) the main agent rests on two Pi SDK ch
 
 - **`pi.appendEntry(customType, data)` + `pi.registerEntryRenderer`** — the only channel that renders in the transcript while staying out of LLM context *forever*. Entries are persisted in the session file and re-rendered on reload. The entry's `data` is optional in the type — renderers must guard it.
 
-This extension maps the two extremes onto the `-s` flag: the default posts the result card via `appendEntry` (main agent structurally oblivious), and `-s` posts a visible custom message with `{ triggerTurn: true }` (steered mid-turn or answered immediately). Both channels share one card renderer in `transcript.ts`.
+Default completion writes no entry or message to the parent session. The widget and agent overlay show the response. `-s` sends a hidden custom message with `{ triggerTurn: true }`, steered mid-turn or answered immediately.
 
-Immediate `-s` delivery and late `s` squash delivery share one canonical message builder. Its `display` option prevents a second visible result card. Both paths use the same selected conversation and `{ triggerTurn: true }` delivery. For a run launched without `-s`, the context message stays hidden at squash time because the TUI-only result card is already visible.
+Immediate `-s` delivery and late `s` squash delivery share one canonical message builder and use `display: false`. Both paths preserve the selected conversation and `{ triggerTurn: true }` delivery. `transcript.ts` renders old completion entries and messages as zero lines, preventing Pi's fallback renderer from showing them. Command errors and detach, attach, and rebase breadcrumbs remain visible.
 
 ## Squashed message format
 
@@ -46,7 +46,7 @@ A child compaction passes through deliberately and lands as a real `compaction`
 
 Two mechanics make that exact. First, a live compaction emits no message event — only `compaction_end` — so the child subscription captures it there as a synthetic `compactionSummary` message, or the append-only conversation would never contain it. Second, the kept-tail boundary (`firstKeptEntryId`) is a child-session entry id that means nothing in the main session's file; but at `compaction_end` the child's live context is exactly `[summary, kept tail]`, so the capture records `keptTailCount`, and the rebase replay counts back that many context messages to pass the main-session id of the message that starts the tail. The tail may reach past the replayed messages into main's pre-existing context — a child that inherits a nearly full context compacts early — so the delivery prepends main's own per-message entry ids to the count.
 
-The fast-forward precondition is fingerprint equality: at dispatch the agent stores `JSON.stringify` of the inherited context messages (`[]` for `-i`), and `r` is offered only while the main session's current `buildSessionContext().messages` fingerprint still matches. The live fingerprint is cached per session manager and recomputed only when the branch leaf moves, so TUI-only entries (result cards, detach lines) move the leaf, trigger one recompute, and correctly do not block the rebase. One rule covers isolated agents too: their base is empty, so they rebase only onto a still-empty session.
+The fast-forward precondition is fingerprint equality: at dispatch the agent stores `JSON.stringify` of the inherited context messages (`[]` for `-i`), and `r` is offered only while the main session's current `buildSessionContext().messages` fingerprint still matches. The live fingerprint is cached per session manager and recomputed only when the branch leaf moves, so TUI-only entries (detach and attach lines) move the leaf, trigger one recompute, and correctly do not block the rebase. One rule covers isolated agents too: their base is empty, so they rebase only onto a still-empty session.
 
 Because the session switch tears the extension down, live widget rows cannot survive it: `r` is withheld while any agent is mid-turn, and the remaining parked and completed agents are detached first through the ordinary detach paths, so every one of them leaves its `Detached session …` breadcrumb before the switch. The switch re-opens the same file, so the session id does not change.
 
@@ -67,6 +67,16 @@ The file itself appears on the child's first assistant message (`_persist` defer
 
 `d` `d` ends the live child session and drops its widget row. The session file is untouched, and the transcript gets a `pi-user-agents-detached` custom entry naming the session id so it can be resumed later. Both detach paths funnel through `closeRunning` and `removeCompleted`, which is where the announcement is made; squashing and session shutdown deliberately do not announce.
 
+## Attaching
+
+`/agent-attach <session-id>` reverses a detach. The id (or a unique prefix) resolves in one pass over the whole universe of candidates: the widget's rows (live and completed) united with file names in pi's default session directory for the cwd — the directory every dispatch creates children in. File names, not `SessionManager.list()`, because list() reads every session file whole, gigabytes in a mature project; the union, because a prefix unique among rows could otherwise mask an ambiguity with a detached file, and a live row whose file is not flushed yet must still resolve. A resolved id that is already a row short-circuits to the "View agent?" confirmation and nothing else — the idempotent case. The authority for "is a child of this session" is the child file's header: its `parentSession` path must equal the main session's file. That is the same field `/fork` writes, so a fork of the main session attaches too.
+
+The session file does not persist the dispatch options, so every dispatch writes a `pi-user-agents-dispatch` custom entry into the child — the forwarded pi tokens, the plain task, and the isolate flag. At attach the record replays through the same projections dispatch used (`buildChildResourceLoaderOptions`, `resolveToolOptions`), so `--tools`, `--no-extensions`, `--system-prompt` and friends survive the round trip instead of silently widening back to pi defaults. The model and thinking level deliberately come from the file, not the record: reattachment is pi's own resume path — `SessionManager.open` plus `createAgentSessionFromServices` on a non-empty manager takes `createAgentSession`'s has-existing-session branch — and the file reflects any later changes. A record-less child (dispatched before the record existed, or `/fork`-made) still attaches, with pi's default tools and resources.
+
+The dispatch preamble — built at the dispatch call site, sent verbatim by `runChildTurns` — doubles as the boundary marker: `splitAtDispatchBoundary` finds the first user message carrying it and recovers the child's own conversation for the overlay and the inherited base whose fingerprint re-arms the rebase fast-forward. The fingerprint compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries from a session file re-stamps their timestamps (and a branch summary's `fromId`), so `conversationFingerprint` drops those fields or a round-tripped base would never equal main's live context. Without a recognizable boundary (a fork child, or a child whose compaction summarized it away) the whole context attaches and the base is a sentinel that never matches, so `r` stays withheld.
+
+The attached agent parks idle first (`runAttachedTurns` waits for an instruction before running the shared turn loop), and its latest persisted response seeds `pendingSquashMessage`, so steering, `s`, and `r` work immediately without a new turn. A successful attach leaves an `Attached session …` breadcrumb — the detach line's counterpart — and both success states end with a "View agent?" confirmation that opens the overlay.
+
 ## Runtime sharing
 
 Child agent sessions share the parent's `ModelRuntime` instance. This is critical because extension-registered providers (like `claude-bridge`) use a global `Symbol.for` dedup guard — they register once per process and skip subsequent loads. A child session with its own fresh runtime would never receive the provider, leaving it without auth for bridge-backed models.

package/README.md

@@ -81,7 +81,7 @@ Press `←` or `↓` from the editor to focus the widget, pick an agent, press `
 
 A background agent is not fire-and-forget — it's a session you can talk to.
 
-Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need; every completed turn posts its own result card.
+Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need. Read each response in the agent overlay.
 
 `Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, squashing, or detaching. In fact, nothing ends an agent except you: pressing `d` twice, squashing or rebasing it, or ending the Pi session.
 
@@ -95,18 +95,20 @@ Detached session 0199c4f2-8b1a-7c3d-9e05-6a2f18d7b4ce
 
 Pick it back up whenever you like — `/resume 0199c4f2`, or `pi -r` and choose it from the list. It resumes as an ordinary Pi session with its full history, its model, and its thinking level, and from there it is a normal agent you talk to directly.
 
+Or take it back as a background agent instead: `/agent-attach 0199c4f2` puts the session back in the widget — parked idle, restored as dispatched down to its `--tools` and the rest of its options — and offers to open it. A unique id prefix is enough, only this conversation's own agents qualify, and the transcript records the return: `Attached session 0199c4f2-…`.
+
 ### 5. Squash — or don't
 
 This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
 
-Each completed turn posts a result card into your transcript — metadata, a collapsed preview, expandable to the full Markdown response. The card is TUI-only: you read it, expand it, copy it, and the main agent's context is untouched. Ask an agent ten questions and your main agent's token budget doesn't move.
+Completed responses stay in the agent overlay, accessible through the widget below the editor. Completion adds no transcript card. Ask an agent ten questions and your main agent's token budget does not move.
 
 When a result does belong in the main conversation, squash it in:
 
 - Dispatch with `-s`/`--squash` and the result is delivered automatically on completion.
 - Or press `s` in the overlay of any completed agent, whenever you decide it earned its place.
 
-A squash delivers a compact record, not a transcript dump: every message you sent the agent and the final answer to each — no thinking, no tool traffic. The record is rebuilt from the agent's full history at squash time, so early turns survive even after the agent compacts its own context. If the main agent is mid-turn, the record is steered in; if idle, it triggers a turn. A squashed agent retires; its overlay stays readable.
+A squash delivers a compact record, not a transcript dump: every message you sent the agent and the final answer to each — no thinking, no tool traffic. The record is rebuilt from the agent's full history at squash time, so early turns survive even after the agent compacts its own context. If the main agent is mid-turn, the record is steered in; if idle, it triggers a turn. Squash adds no transcript card. A squashed agent retires; its overlay stays readable.
 
 ### 6. Or rebase — rewrite history
 
@@ -146,7 +148,7 @@ And what you do type by hand is checked live, as you type. Valid options and val
 
 Every dispatch writes a real session file, exactly like the one you're sitting in, so dispatched agents show up in `/resume` and `pi -r` alongside your own sessions.
 
-Result cards persist across session reloads; the widget doesn't. After a reload you keep every card, and every agent's session is still on disk — but the steerable rows are gone. Reach them with `/resume`.
+The widget does not survive a session reload. Each agent's session remains on disk, accessible through `/resume` or `/agent-attach`. Completion cards from older versions stay hidden.
 
 ### 🌡️ A context meter in one cell
 
@@ -154,7 +156,7 @@ Each row carries the agent's own footer gauge: it fills `▁▂▃▄▅▆▇
 
 ## Reference
 
-Everything goes through one command: `/agent [options] <task>`.
+Everything goes through one command: `/agent [options] <task>`. Its one companion, `/agent-attach <session-id>`, brings a detached session back into the widget.
 
 | Flag | Effect |
 |---|---|
@@ -187,6 +189,7 @@ Everything goes through one command: `/agent [options] <task>`.
 - [x] Agents stay alive until you end them — steer, interrupt, resume, across turns.
 - [x] Squash: a compact record of the exchange, delivered into the main context.
 - [x] Rebase: the raw conversation grafted onto the main session — fast-forward only, compaction-faithful.
+- [x] Attach: a detached session returns to the widget, restored as dispatched.
 - [x] Live syntax coloring and eager autocomplete for the `/agent` line.
 - [ ] Render an agent's compaction event in the overlay.
 - [ ] Wire the accepted-but-inert `pi` options.
@@ -194,7 +197,7 @@ Everything goes through one command: `/agent [options] <task>`.
 
 ## Under the hood
 
-Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase mechanism, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
+Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase and attach mechanisms, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
 
 ---
 

package/agent-viewer.ts

@@ -102,7 +102,14 @@ function describeAssistantPart(part: AssistantContentPart): ActivityDescription
 
 export function renderActivity(description: ActivityDescription, width: number, theme: Theme): string {
 	if (width <= 0) return "";
-	const normalized = description.text.replace(/\s+/g, " ").trim();
+	const limit = Math.min(4096, Math.max(128, width * 4));
+	const text = description.text;
+	const bounded = text.length <= limit
+		? text
+		: description.truncation === "tail"
+			? `${text.slice(0, limit - 1)}…`
+			: `${text.slice(0, Math.ceil((limit - 1) / 2))}…${text.slice(-Math.floor((limit - 1) / 2))}`;
+	const normalized = bounded.replace(/\s+/g, " ").trim();
 	const dim = (text: string) => theme.fg("dim", text);
 	const markdown = new Markdown(normalized, 0, 0, dimMarkdownThemeFromTheme(theme), { color: dim });
 	const rendered = markdown
@@ -158,7 +165,7 @@ export class AgentViewer implements Component {
 		this.tui.requestRender(),
 	);
 	private composer: Input | undefined;
-	/** Rich tool rendering is far too costly to repeat on every 100 ms widget tick. */
+	/** Rich tool rendering is far too costly to repeat on every widget tick. */
 	private renderedContent: { key: string; lines: string[] } | undefined;
 
 	constructor(
@@ -364,7 +371,9 @@ export class AgentViewer implements Component {
 		return lines;
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		this.renderedContent = undefined;
+	}
 
 	dispose(): void {}
 

package/attach.ts

@@ -0,0 +1,339 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createAgentSessionFromServices, SessionManager } from "@earendil-works/pi-coding-agent";
+import { conversationFingerprint } from "./rebase.js";
+import {
+	assistantText,
+	buildChildResourceLoaderOptions,
+	createChildServices,
+	DISPATCH_PREAMBLE,
+	parseForwardedArgs,
+	reportAgentFailure,
+	resolveToolOptions,
+	runChildTurns,
+	subscribeToChildSession,
+	waitForInstruction,
+} from "./runner.js";
+import type {
+	AgentMessage,
+	AgentSession,
+	AttachedEntryData,
+	DispatchRecordData,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	Model,
+	RunningAgent,
+} from "./shared.js";
+import {
+	ATTACHED_ENTRY_TYPE,
+	DISPATCH_ENTRY_TYPE,
+	errorMessage,
+	formatModel,
+	formatModelLabel,
+	logSteering,
+} from "./shared.js";
+import { buildAgentResultMessage, reportCommandError } from "./transcript.js";
+import type { UserAgentWidget } from "./widget.js";
+
+/** A dispatch base that can never fingerprint-match a live context, so rebase stays withheld. */
+export const UNKNOWN_DISPATCH_BASE = "unknown-dispatch-base";
+
+export type DispatchBoundary = {
+	/** The main-session context the child inherited at dispatch — the rebase fast-forward base. */
+	base: AgentMessage[];
+	/** The child's own conversation, starting at the preambled dispatch message. */
+	conversation: AgentMessage[];
+	/** The dispatch task, preamble stripped. */
+	task: string;
+};
+
+/**
+ * Split a child's resolved context at its dispatch boundary — the first user message carrying
+ * the dispatch preamble. Undefined when no message carries it (a /fork child, or a child whose
+ * own compaction summarized the boundary away).
+ */
+export function splitAtDispatchBoundary(
+	messages: readonly AgentMessage[],
+): DispatchBoundary | undefined {
+	for (const [index, message] of messages.entries()) {
+		if (message.role !== "user") continue;
+		const text = userMessageText(message);
+		if (!text.startsWith(DISPATCH_PREAMBLE)) continue;
+		return {
+			base: messages.slice(0, index),
+			conversation: messages.slice(index),
+			task: text.slice(DISPATCH_PREAMBLE.length),
+		};
+	}
+	return undefined;
+}
+
+function userMessageText(message: Extract<AgentMessage, { role: "user" }>): string {
+	if (typeof message.content === "string") return message.content;
+	return message.content
+		.flatMap((part) => (part.type === "text" ? [part.text] : []))
+		.join("\n");
+}
+
+export type ChildSessionFileMatch = { sessionId: string; file: string };
+
+/**
+ * The session files in a directory whose id matches the query exactly or by prefix.
+ * Pi names session files `<timestamp>_<session-id>.jsonl`, so matching reads names only.
+ */
+export function matchChildSessionFiles(
+	query: string,
+	sessionDirectory: string,
+): ChildSessionFileMatch[] {
+	const fileNames = existsSync(sessionDirectory) ? readdirSync(sessionDirectory) : [];
+	return fileNames.flatMap((name) => {
+		const sessionId = sessionIdFromFileName(name);
+		if (sessionId === undefined || !sessionId.startsWith(query)) return [];
+		return [{ sessionId, file: join(sessionDirectory, name) }];
+	});
+}
+
+function sessionIdFromFileName(fileName: string): string | undefined {
+	if (!fileName.endsWith(".jsonl")) return undefined;
+	const separator = fileName.indexOf("_");
+	if (separator === -1) return undefined;
+	return fileName.slice(separator + 1, -".jsonl".length);
+}
+
+/** The dispatch record persisted in the child's file, or undefined for pre-record and /fork children. */
+export function readDispatchRecord(
+	childSessionManager: SessionManager,
+): DispatchRecordData | undefined {
+	for (const entry of childSessionManager.getEntries()) {
+		if (entry.type === "custom" && entry.customType === DISPATCH_ENTRY_TYPE)
+			return entry.data as DispatchRecordData | undefined;
+	}
+	return undefined;
+}
+
+/**
+ * Rebuild an idle, steerable RunningAgent from a reopened child session and its resolved model.
+ * The child's own conversation, task, latest response, and rebase base all come from the file;
+ * the dispatch record refines the task and context flag, and with no recognizable dispatch
+ * boundary the whole context attaches and rebase stays withheld.
+ */
+export function buildAttachedAgent(
+	sequenceNumber: number,
+	childSessionManager: SessionManager,
+	model: Model,
+	invocation: string,
+	record?: DispatchRecordData,
+): RunningAgent {
+	const contextMessages = childSessionManager.buildSessionContext().messages;
+	const boundary = splitAtDispatchBoundary(contextMessages);
+	const conversationMessages = structuredClone(boundary?.conversation ?? contextMessages);
+	const firstUserMessage = contextMessages.find((message) => message.role === "user");
+	const lastAssistantMessage = conversationMessages.findLast(
+		(message): message is Extract<AgentMessage, { role: "assistant" }> =>
+			message.role === "assistant",
+	);
+	const responseText = lastAssistantMessage ? assistantText(lastAssistantMessage).trim() : "";
+	const now = Date.now();
+	const agent: RunningAgent = {
+		id: `user-${sequenceNumber.toString(36)}`,
+		sessionId: childSessionManager.getSessionId(),
+		command: "agent",
+		inheritedContext: record
+			? !record.isolate
+			: boundary
+				? boundary.base.length > 0
+				: true,
+		model: formatModel(model),
+		modelLabel: formatModelLabel(model),
+		task:
+			record?.task ??
+			boundary?.task ??
+			(firstUserMessage === undefined ? "(no messages)" : userMessageText(firstUserMessage)),
+		invocation,
+		notifyMainAgent: false,
+		dispatchBaseFingerprint: boundary
+			? conversationFingerprint(boundary.base)
+			: UNKNOWN_DISPATCH_BASE,
+		mainContextState: "separate",
+		status: "idle",
+		startedAt: now,
+		turnStartedAt: now,
+		completedAt: now,
+		activeTools: new Map(),
+		toolUses: 0,
+		turnCount: 0,
+		responseText,
+		conversationMessages,
+		finished: Promise.resolve(),
+	};
+	if (responseText)
+		agent.pendingSquashMessage = buildAgentResultMessage(
+			agent,
+			{ ok: true, response: responseText },
+			{ display: false },
+		);
+	return agent;
+}
+
+/**
+ * The attached agent's lifecycle: bind the child's extensions, park until the user steers or
+ * retires it, then run turns exactly like a dispatched child. Every failure — the bind's
+ * included — settles through the shared error path, and the end shuts the child's extensions
+ * down.
+ */
+export async function runAttachedTurns(
+	pi: ExtensionAPI,
+	isShuttingDown: () => boolean,
+	session: AgentSession,
+	runningAgent: RunningAgent,
+	widget: UserAgentWidget,
+): Promise<void> {
+	let unsubscribe: (() => void) | undefined;
+	try {
+		await session.bindExtensions({ mode: "print" });
+		unsubscribe = subscribeToChildSession(session, runningAgent, widget);
+		// The user can detach during the extension bind, before this lifecycle parks.
+		if (runningAgent.aborted) return;
+		const instruction = await waitForInstruction(runningAgent, widget);
+		if (instruction !== undefined)
+			await runChildTurns(pi, isShuttingDown, instruction, session, runningAgent, widget);
+	} catch (error) {
+		reportAgentFailure(pi, isShuttingDown, runningAgent, widget, error);
+	} finally {
+		unsubscribe?.();
+		logSteering(runningAgent.id, "session-shutdown", { streaming: session.isStreaming });
+		await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+	}
+}
+
+export async function handleAttachCommand(
+	pi: ExtensionAPI,
+	runningAgents: Set<RunningAgent>,
+	widget: UserAgentWidget,
+	isShuttingDown: () => boolean,
+	nextAgentNumber: () => number,
+	args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	try {
+		await attachUserAgent(pi, runningAgents, widget, isShuttingDown, nextAgentNumber, args, ctx);
+	} catch (error) {
+		reportCommandError(pi, "agent-attach", args, ctx, errorMessage(error));
+	}
+}
+
+/**
+ * Reattach a detached child session as a live, parked agent row. Idempotent for a session
+ * that already has a row; errors for anything that is not a child session of this session.
+ * Both success states end by offering to open the agent's overlay.
+ */
+async function attachUserAgent(
+	pi: ExtensionAPI,
+	runningAgents: Set<RunningAgent>,
+	widget: UserAgentWidget,
+	isShuttingDown: () => boolean,
+	nextAgentNumber: () => number,
+	args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const query = args.trim();
+	if (!query || /\s/.test(query)) throw new Error("Usage: /agent-attach <child-session-id>");
+	if (ctx.hasUI) widget.setUI(ctx.ui);
+
+	// One resolution over the whole universe — attached rows and files on disk together — so a
+	// prefix unique among rows cannot mask an ambiguity with a detached session, and a live row
+	// whose file is not written yet still resolves. Dispatch creates children in pi's default
+	// session directory for the cwd; that is where the files are.
+	const attachedIds = widget.matchAttachedSessionIds(query);
+	const childSessionDirectory = SessionManager.create(ctx.cwd).getSessionDir();
+	const fileMatches = matchChildSessionFiles(query, childSessionDirectory);
+	const matchedSessionIds = [
+		...new Set([...attachedIds, ...fileMatches.map((match) => match.sessionId)]),
+	];
+	if (matchedSessionIds.length === 0) throw new Error(`No agent session matches "${query}"`);
+	if (matchedSessionIds.length > 1)
+		throw new Error(`"${query}" matches ${matchedSessionIds.length} sessions; use more characters`);
+	const sessionId = matchedSessionIds[0]!;
+
+	if (attachedIds.includes(sessionId)) {
+		await confirmViewAgent(ctx, widget, sessionId, "Agent already attached");
+		return;
+	}
+
+	const mainSessionFile = ctx.sessionManager.getSessionFile();
+	if (!mainSessionFile)
+		throw new Error("This session has no file; only a persisted session can attach agents");
+	const childSessionFile = fileMatches.find((match) => match.sessionId === sessionId)!.file;
+	const childSessionManager = SessionManager.open(childSessionFile);
+	if (childSessionManager.getHeader()?.parentSession !== mainSessionFile)
+		throw new Error(
+			`Session ${childSessionManager.getSessionId()} is not a child session of this session`,
+		);
+
+	// The record replays through the same projections dispatch uses; a record-less child (an old
+	// dispatch, or a /fork) restores pi defaults.
+	const record = readDispatchRecord(childSessionManager);
+	const dispatchArgs = parseForwardedArgs(record?.forwardedArgs ?? []);
+	const services = await createChildServices(
+		ctx,
+		buildChildResourceLoaderOptions(dispatchArgs, ctx.cwd),
+	);
+	// A non-empty session manager takes pi's resume path: messages, model, and thinking level
+	// are restored from the child's own file; tools and resources come from the dispatch record.
+	const { session, modelFallbackMessage } = await createAgentSessionFromServices({
+		services,
+		sessionManager: childSessionManager,
+		...resolveToolOptions(dispatchArgs),
+	});
+	const model = session.agent.state.model as Model | undefined;
+	if (!model) {
+		session.dispose();
+		throw new Error(modelFallbackMessage ?? "No model is available for the attached session");
+	}
+	if (modelFallbackMessage && ctx.hasUI) ctx.ui.notify(modelFallbackMessage, "warning");
+
+	const runningAgent = buildAttachedAgent(
+		nextAgentNumber(),
+		childSessionManager,
+		model,
+		`/agent-attach ${query}`,
+		record,
+	);
+	runningAgent.session = session;
+	runningAgents.add(runningAgent);
+	logSteering(runningAgent.id, "agent-attached", { sessionId: runningAgent.sessionId });
+	if (ctx.hasUI) {
+		widget.ensureTimer();
+		widget.update();
+	}
+	// No awaits between the add above and this assignment: every later failure settles inside
+	// the lifecycle, so the row can never outlive its own removal hook.
+	runningAgent.finished = runAttachedTurns(
+		pi,
+		isShuttingDown,
+		session,
+		runningAgent,
+		widget,
+	).finally(() => {
+		logSteering(runningAgent.id, "agent-disposed", { status: runningAgent.status });
+		runningAgent.session?.dispose();
+		runningAgents.delete(runningAgent);
+		widget.update();
+	});
+	// The detach breadcrumb's counterpart: after a reload the transcript still tells the truth.
+	pi.appendEntry<AttachedEntryData>(ATTACHED_ENTRY_TYPE, { sessionId: runningAgent.sessionId });
+	if (runningAgent.aborted) return;
+	await confirmViewAgent(ctx, widget, runningAgent.sessionId, "Agent attached");
+}
+
+/** The follow-up both success states share: offer to open the agent's overlay. */
+async function confirmViewAgent(
+	ctx: ExtensionCommandContext,
+	widget: UserAgentWidget,
+	sessionId: string,
+	title: string,
+): Promise<void> {
+	if (!ctx.hasUI) return;
+	const view = await ctx.ui.confirm(title, "View agent?");
+	if (view) widget.openViewer(sessionId);
+}

package/index.ts

@@ -2,6 +2,7 @@ import type {
 	MessageEndEvent,
 	MessageEndEventResult,
 } from "@earendil-works/pi-coding-agent";
+import { handleAttachCommand } from "./attach.js";
 import { registerAgentAutocomplete } from "./autocomplete.js";
 import { createRebaseDelivery, handleAgentCommand } from "./runner.js";
 import type {
@@ -52,6 +53,22 @@ export default function userAgent(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("agent-attach", {
+		description: "Reattach a detached agent session by id, back into the widget",
+		handler: async (args, ctx) => {
+			mainSessionContext = ctx;
+			await handleAttachCommand(
+				pi,
+				runningAgents,
+				widget,
+				() => shuttingDown,
+				() => ++nextAgentNumber,
+				args,
+				ctx,
+			);
+		},
+	});
+
 	pi.on("session_shutdown", async () => {
 		shuttingDown = true;
 		widget.dispose();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",

package/rebase.ts

@@ -8,10 +8,21 @@ type MainSessionManager = ExtensionCommandContext["sessionManager"];
  * Fingerprint a context snapshot for the rebase fast-forward precondition: the main session's
  * live context must still fingerprint-equal the base the child was dispatched from.
  *
+ * Compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries
+ * from a session file re-stamps their timestamps (and a branch summary's fromId), so a base
+ * round-tripped through a child's file would never equal main's live context otherwise.
+ *
  * @example conversationFingerprint([]) === conversationFingerprint([]) // true
  */
 export function conversationFingerprint(messages: readonly AgentMessage[]): string {
-	return JSON.stringify(messages);
+	return JSON.stringify(messages.map(fingerprintedMessage));
+}
+
+function fingerprintedMessage(message: AgentMessage): Omit<AgentMessage, "timestamp"> {
+	const { timestamp: _timestamp, ...content } = message;
+	if (content.role !== "branchSummary") return content;
+	const { fromId: _fromId, ...branchContent } = content;
+	return branchContent;
 }
 
 /** Rebuilding a session-sized context string is only worth doing when the branch tip moved. */

package/runner.ts

@@ -33,7 +33,9 @@ import type {
 	RunningAgent,
 	ThinkingLevel,
 } from "./shared.js";
+import type { DispatchRecordData } from "./shared.js";
 import {
+	DISPATCH_ENTRY_TYPE,
 	errorMessage,
 	formatModel,
 	formatModelLabel,
@@ -90,17 +92,10 @@ async function startUserAgent(
 ): Promise<void> {
 	const parsed = parseAgentCommand(args, command);
 	const parsedForwardedArgs = parseForwardedArgs(parsed.forwardedArgs);
-	const agentDir = getAgentDir();
-	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
-		projectTrusted: ctx.isProjectTrusted(),
-	});
-	const services = await createAgentSessionServices({
-		cwd: ctx.cwd,
-		agentDir,
-		settingsManager,
-		modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
-		resourceLoaderOptions: buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
-	});
+	const services = await createChildServices(
+		ctx,
+		buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
+	);
 	const forwarded = resolveForwardedOptions(parsedForwardedArgs, services.modelRuntime);
 	const selectedModel = forwarded.model ?? ctx.model;
 	if (!selectedModel) throw new Error("No current model is selected; pass -m MODELNAME");
@@ -112,6 +107,12 @@ async function startUserAgent(
 	const childSessionManager = SessionManager.create(services.cwd, undefined, {
 		parentSession: ctx.sessionManager.getSessionFile(),
 	});
+	// The dispatch record: /agent-attach restores tool and resource options from it later.
+	childSessionManager.appendCustomEntry(DISPATCH_ENTRY_TYPE, {
+		forwardedArgs: parsed.forwardedArgs,
+		task: parsed.task,
+		isolate: parsed.isolate,
+	} satisfies DispatchRecordData);
 	const runningAgent = createRunningAgent(
 		nextAgentNumber(),
 		childSessionManager.getSessionId(),
@@ -191,14 +192,9 @@ function postUserAgentResult(
 	notifyMainAgent: boolean,
 	message: AgentResultMessage,
 ): boolean {
-	if (isShuttingDown()) return false;
-	if (notifyMainAgent) {
-		// Steers into a streaming turn, or triggers an immediate response when idle.
-		pi.sendMessage(message, { triggerTurn: true });
-	} else {
-		// TUI-only session entry: renders in the transcript but never enters the main agent's context.
-		pi.appendEntry(message.customType, { content: message.content, details: message.details });
-	}
+	if (isShuttingDown() || !notifyMainAgent) return false;
+	// Steers into a streaming turn, or triggers an immediate response when idle.
+	pi.sendMessage(message, { triggerTurn: true });
 	return true;
 }
 
@@ -263,7 +259,7 @@ export function createRebaseDelivery(
 }
 
 /** Session inputs derived from forwarded pi CLI options, ready to hand to the child session. */
-type ChildResourceLoaderOptions = {
+export type ChildResourceLoaderOptions = {
 	systemPrompt?: string;
 	appendSystemPrompt?: string[];
 	additionalExtensionPaths?: string[];
@@ -276,14 +272,37 @@ type ChildResourceLoaderOptions = {
 	noContextFiles?: boolean;
 };
 
-type ForwardedOptions = {
-	model?: Model;
-	thinkingLevel?: ThinkingLevel;
+export type ChildToolOptions = {
 	tools?: string[];
 	excludeTools?: string[];
 	noTools?: "all" | "builtin";
 };
 
+type ForwardedOptions = ChildToolOptions & {
+	model?: Model;
+	thinkingLevel?: ThinkingLevel;
+};
+
+/** The cwd-bound services for one child session; the parent's ModelRuntime rides along (see INTERNALS). */
+export function createChildServices(
+	ctx: ExtensionCommandContext,
+	resourceLoaderOptions?: ChildResourceLoaderOptions,
+): Promise<AgentSessionServices> {
+	const agentDir = getAgentDir();
+	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
+		projectTrusted: ctx.isProjectTrusted(),
+	});
+	return createAgentSessionServices({
+		cwd: ctx.cwd,
+		agentDir,
+		settingsManager,
+		// The extension facade wraps the parent's runtime as a plain property; sharing it keeps
+		// extension-registered providers (their process-global dedup guard) available to the child.
+		modelRuntime: (ctx.modelRegistry as unknown as { runtime: ModelRuntime }).runtime,
+		resourceLoaderOptions,
+	});
+}
+
 /** Parse forwarded pi CLI tokens once before model and session resolution. */
 export function parseForwardedArgs(forwardedArgs: string[]): Args {
 	const parsed = parseArgs(forwardedArgs);
@@ -382,12 +401,17 @@ export function resolveForwardedOptions(
 		}
 	}
 	if (parsed.thinking) forwarded.thinkingLevel = parsed.thinking;
+	return { ...forwarded, ...resolveToolOptions(parsed) };
+}
 
-	if (parsed.noTools) forwarded.noTools = "all";
-	else if (parsed.noBuiltinTools) forwarded.noTools = "builtin";
-	if (parsed.tools) forwarded.tools = parsed.tools;
-	if (parsed.excludeTools) forwarded.excludeTools = parsed.excludeTools;
-	return forwarded;
+/** Map parsed pi tool options onto child-session inputs; dispatch and attach share this. */
+export function resolveToolOptions(parsed: Args): ChildToolOptions {
+	const options: ChildToolOptions = {};
+	if (parsed.noTools) options.noTools = "all";
+	else if (parsed.noBuiltinTools) options.noTools = "builtin";
+	if (parsed.tools) options.tools = parsed.tools;
+	if (parsed.excludeTools) options.excludeTools = parsed.excludeTools;
+	return options;
 }
 
 export function buildChildResourceLoaderOptions(
@@ -449,29 +473,9 @@ async function runAgentLifecycle(
 			widget,
 		);
 		unsubscribe = subscribeToChildSession(session, runningAgent, widget);
-		await runChildTurns(pi, isShuttingDown, task, session, runningAgent, widget);
+		await runChildTurns(pi, isShuttingDown, DISPATCH_PREAMBLE + task, session, runningAgent, widget);
 	} catch (error) {
-		if (runningAgent.aborted) {
-			logSteering(runningAgent.id, "agent-aborted");
-			return;
-		}
-		const message = errorMessage(error);
-		logSteering(runningAgent.id, "agent-error", { error: message });
-		runningAgent.status = "error";
-		runningAgent.completedAt = Date.now();
-		runningAgent.error = message;
-		if (runningAgent.notifyMainAgent && isShuttingDown()) {
-			runningAgent.mainContextState = "separate";
-			return;
-		}
-		const resultMessage = buildAgentResultMessage(
-			runningAgent,
-			{ ok: false, error: message },
-			{ display: runningAgent.notifyMainAgent },
-		);
-		widget.addCompleted(runningAgent, resultMessage, { squashable: !runningAgent.notifyMainAgent });
-		if (postUserAgentResult(pi, isShuttingDown, runningAgent.notifyMainAgent, resultMessage))
-			runningAgent.status = "posted";
+		reportAgentFailure(pi, isShuttingDown, runningAgent, widget, error);
 	} finally {
 		unsubscribe?.();
 		if (session) {
@@ -481,16 +485,51 @@ async function runAgentLifecycle(
 	}
 }
 
-/** Run turns on an initialized child session until it posts, retires, or shuts down. */
+/** Record a failed lifecycle in the widget and deliver it only when squash was requested. */
+export function reportAgentFailure(
+	pi: ExtensionAPI,
+	isShuttingDown: () => boolean,
+	runningAgent: RunningAgent,
+	widget: UserAgentWidget,
+	error: unknown,
+): void {
+	if (runningAgent.aborted) {
+		logSteering(runningAgent.id, "agent-aborted");
+		return;
+	}
+	const message = errorMessage(error);
+	logSteering(runningAgent.id, "agent-error", { error: message });
+	runningAgent.status = "error";
+	runningAgent.completedAt = Date.now();
+	runningAgent.error = message;
+	if (runningAgent.notifyMainAgent && isShuttingDown()) {
+		runningAgent.mainContextState = "separate";
+		return;
+	}
+	const resultMessage = buildAgentResultMessage(
+		runningAgent,
+		{ ok: false, error: message },
+		{ display: false },
+	);
+	widget.addCompleted(runningAgent, resultMessage, { squashable: !runningAgent.notifyMainAgent });
+	if (postUserAgentResult(pi, isShuttingDown, runningAgent.notifyMainAgent, resultMessage))
+		runningAgent.status = "posted";
+}
+
+/** Every dispatch prefixes its task with this; attach recognizes it as the child's dispatch boundary. */
+export const DISPATCH_PREAMBLE =
+	"You are running in an ephemeral, forked background process now, concurrently with the main session. ";
+
+/** Run turns on an initialized child session until it posts, retires, or shuts down. The initial instruction is sent verbatim. */
 export async function runChildTurns(
 	pi: ExtensionAPI,
 	isShuttingDown: () => boolean,
-	task: string,
+	initialInstruction: string,
 	session: AgentSession,
 	runningAgent: RunningAgent,
 	widget: UserAgentWidget,
 ): Promise<void> {
-	let instruction = `You are running in an ephemeral, forked background process now, concurrently with the main session. ${task}`;
+	let instruction = initialInstruction;
 	while (true) {
 		const turnMessageStart = session.agent.state.messages.length;
 		if (!runningAgent.interruptRequested) {
@@ -512,7 +551,6 @@ export async function runChildTurns(
 				{ ok: true, response },
 				{ display: false },
 			);
-			postUserAgentResult(pi, isShuttingDown, false, resultMessage);
 			runningAgent.pendingSquashMessage = runningAgent.notifyMainAgent
 				? undefined
 				: resultMessage;
@@ -537,7 +575,7 @@ export async function runChildTurns(
 		const resultMessage = buildAgentResultMessage(
 			runningAgent,
 			{ ok: true, response },
-			{ display: runningAgent.notifyMainAgent },
+			{ display: false },
 		);
 		if (runningAgent.notifyMainAgent) {
 			if (isShuttingDown()) {
@@ -550,7 +588,6 @@ export async function runChildTurns(
 			runningAgent.status = posted ? "posted" : runningAgent.status;
 			return;
 		}
-		postUserAgentResult(pi, isShuttingDown, false, resultMessage);
 		runningAgent.pendingSquashMessage = resultMessage;
 		if (isShuttingDown()) return;
 		runningAgent.status = "idle";
@@ -745,7 +782,7 @@ export function subscribeToChildSession(
 	});
 }
 
-function assistantText(message: Extract<AgentMessage, { role: "assistant" }>): string {
+export function assistantText(message: Extract<AgentMessage, { role: "assistant" }>): string {
 	return message.content
 		.filter((part) => part.type === "text")
 		.map((part) => part.text)

package/shared.ts

@@ -15,7 +15,7 @@ export type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
 export type Theme = ExtensionCommandContext["ui"]["theme"];
 export type UIContext = ExtensionCommandContext["ui"];
 
-export type AgentCommandName = "agent";
+export type AgentCommandName = "agent" | "agent-attach";
 export type MainContextState = "separate" | "will-squash" | "squashed" | "rebased";
 export type AgentStatus =
 	| "starting"
@@ -44,6 +44,19 @@ export type DetachedEntryData = {
 	sessionId: string;
 };
 
+export type AttachedEntryData = {
+	sessionId: string;
+};
+
+/** Persisted in the child session at dispatch: the facts attach cannot recover from messages alone. */
+export type DispatchRecordData = {
+	/** The pi CLI tokens the dispatch forwarded, e.g. ["--tools", "read,grep"]. */
+	forwardedArgs: string[];
+	/** The plain task, without the dispatch preamble. */
+	task: string;
+	isolate: boolean;
+};
+
 export type RebaseStats = {
 	messageCount: number;
 	tokenEstimate: number;
@@ -75,7 +88,8 @@ export type AgentCommandDetails = {
 	agentId?: string;
 	command: AgentCommandName;
 	mainContextState?: MainContextState;
-	inheritedContext: boolean;
+	/** Absent on command-error cards: an error has no inherited-or-isolated notion. */
+	inheritedContext?: boolean;
 	model: string;
 	modelLabel: string;
 	task: string;
@@ -84,8 +98,6 @@ export type AgentCommandDetails = {
 	toolUses?: number;
 	turnCount?: number;
 	responseText?: string;
-	/** Retained for completed entries written before responseText was persisted. */
-	responsePreview?: string;
 	error?: string;
 };
 
@@ -207,6 +219,8 @@ export class TimedConfirmation<Target> {
 export const MESSAGE_TYPE = "pi-user-agents";
 export const DETACHED_ENTRY_TYPE = "pi-user-agents-detached";
 export const REBASED_ENTRY_TYPE = "pi-user-agents-rebased";
+export const ATTACHED_ENTRY_TYPE = "pi-user-agents-attached";
+export const DISPATCH_ENTRY_TYPE = "pi-user-agents-dispatch";
 export const WIDGET_KEY = "pi-user-agents";
 export const STEERING_LOG_PATH = `${tmpdir()}/pi-user-agents-steer.log`;
 
@@ -278,14 +292,6 @@ export function truncatePlain(text: string, length: number): string {
 	return `${line.slice(0, Math.max(0, length - 1))}…`;
 }
 
-export function extractTag(
-	content: string,
-	tag: "task" | "response" | "error" | "duration_ms",
-): string | undefined {
-	const match = content.match(new RegExp(`<${tag}>\\n?([\\s\\S]*?)\\n?</${tag}>`));
-	return match?.[1]?.trim();
-}
-
 export function escapeAttribute(value: string): string {
 	return value
 		.replace(/&/g, "&amp;")

package/transcript.ts

@@ -1,30 +1,25 @@
-import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { type Component, Container, Markdown, Text } from "@earendil-works/pi-tui";
+import { type Component, Text } from "@earendil-works/pi-tui";
 import type {
 	AgentCommandDetails,
 	AgentCommandName,
 	AgentEntryData,
 	AgentMessage,
 	AgentResultMessage,
+	AttachedEntryData,
 	DetachedEntryData,
 	ExtensionAPI,
 	ExtensionCommandContext,
 	RebasedEntryData,
 	RunningAgent,
-	Theme,
 } from "./shared.js";
 import {
+	ATTACHED_ENTRY_TYPE,
 	contextLabel,
 	DETACHED_ENTRY_TYPE,
 	escapeAttribute,
-	extractTag,
-	formatMs,
-	formatToolUses,
-	formatTurns,
 	mainContextLabel,
 	MESSAGE_TYPE,
 	REBASED_ENTRY_TYPE,
-	truncatePlain,
 } from "./shared.js";
 
 export function reportCommandError(
@@ -44,7 +39,6 @@ export function reportCommandError(
 		display: true,
 		details: {
 			command,
-			inheritedContext: command === "agent",
 			model: "",
 			modelLabel: "",
 			task: args.trim(),
@@ -194,34 +188,25 @@ export function formatStartNotification(agent: RunningAgent): string {
 }
 
 export function registerUserAgentRenderer(pi: ExtensionAPI): void {
-	pi.registerMessageRenderer<AgentCommandDetails>(
-		MESSAGE_TYPE,
-		(message, { expanded }, theme) =>
-			liveAgentCard(
-				() => customMessageContentText(message.content),
-				() => message.details,
-				expanded,
-				theme,
-			),
-	);
-	pi.registerEntryRenderer<AgentEntryData>(
-		MESSAGE_TYPE,
-		(entry, { expanded }, theme) =>
-			entry.data
-				? liveAgentCard(
-						() => entry.data!.content,
-						() => entry.data!.details,
-						expanded,
-						theme,
-					)
-				: undefined,
-	);
+	const hiddenResult: Component = { render: () => [], invalidate: () => undefined };
+	pi.registerMessageRenderer<AgentCommandDetails>(MESSAGE_TYPE, (message, _state, theme) => {
+		const details = message.details;
+		if (!details || details.agentId || details.inheritedContext !== undefined || details.ok)
+			return hiddenResult;
+		return new Text(theme.fg("error", `/${details.command}: ${details.error}`), 1, 0);
+	});
+	pi.registerEntryRenderer<AgentEntryData>(MESSAGE_TYPE, () => hiddenResult);
 	// Pi's chat container does not pad renderer components; its own chat lines self-pad with paddingX 1.
 	pi.registerEntryRenderer<DetachedEntryData>(DETACHED_ENTRY_TYPE, (entry, _state, theme) =>
 		entry.data
 			? new Text(theme.fg("dim", `Detached session ${entry.data.sessionId}`), 1, 0)
 			: undefined,
 	);
+	pi.registerEntryRenderer<AttachedEntryData>(ATTACHED_ENTRY_TYPE, (entry, _state, theme) =>
+		entry.data
+			? new Text(theme.fg("dim", `Attached session ${entry.data.sessionId}`), 1, 0)
+			: undefined,
+	);
 	pi.registerEntryRenderer<RebasedEntryData>(REBASED_ENTRY_TYPE, (entry, _state, theme) =>
 		entry.data ? new Text(theme.fg("dim", formatRebasedLine(entry.data)), 1, 0) : undefined,
 	);
@@ -249,90 +234,3 @@ function formatTokenCount(tokens: number): string {
 	return tokens < 1000 ? `${tokens}` : `${Math.round(tokens / 1000)}K`;
 }
 
-function liveAgentCard(
-	content: () => string,
-	details: () => AgentCommandDetails | undefined,
-	expanded: boolean,
-	theme: Theme,
-): Component {
-	const body = renderAgentCardBody(content(), details(), expanded, theme);
-	return {
-		render: (width) => renderAgentCard(content(), details(), body, theme).render(width),
-		invalidate: () => body.invalidate(),
-	};
-}
-
-function renderAgentCard(
-	content: string,
-	details: AgentCommandDetails | undefined,
-	body: Component,
-	theme: Theme,
-): Container {
-	const ok = details?.ok ?? !content.includes("<user_agent_error");
-	const command = details ? `/${details.command}` : "/agent";
-	const icon = ok ? theme.fg("success", "✓") : theme.fg("error", "✗");
-	const statusText = ok ? theme.fg("dim", "completed") : theme.fg("error", "failed");
-	const parts = buildRendererParts(content, details);
-	const task = details?.task ?? extractTag(content, "task");
-
-	let text = `${icon} ${theme.bold(command)} ${statusText}`;
-	if (parts.length > 0) text += ` ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}`;
-	if (task) text += `\n  ${theme.fg("dim", `task: ${truncatePlain(task, 88)}`)}`;
-	const card = new Container();
-	card.addChild(new Text(text, 1, 0));
-	card.addChild(body);
-	return card;
-}
-
-function renderAgentCardBody(
-	content: string,
-	details: AgentCommandDetails | undefined,
-	expanded: boolean,
-	theme: Theme,
-): Component {
-	const ok = details?.ok ?? !content.includes("<user_agent_error");
-	const output =
-		details?.responseText ??
-		details?.error ??
-		extractTag(content, ok ? "response" : "error") ??
-		"No output.";
-	if (expanded)
-		return ok
-			? new Markdown(output, 3, 0, getMarkdownTheme())
-			: new Text(theme.fg("error", output), 3, 0);
-
-	const previewText = `⎿  ${truncatePlain(details?.responsePreview ?? output, 110)}`;
-	if (!ok) return new Text(`  ${theme.fg("error", previewText)}`, 1, 0);
-	return new Markdown(previewText, 3, 0, getMarkdownTheme(), {
-		color: (value) => theme.fg("dim", value),
-	});
-}
-
-function customMessageContentText(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return String(content ?? "");
-	return content
-		.filter(
-			(part): part is { type: "text"; text: string } =>
-				part?.type === "text" && typeof part.text === "string",
-		)
-		.map((part) => part.text)
-		.join("\n");
-}
-
-function buildRendererParts(content: string, details: AgentCommandDetails | undefined): string[] {
-	const parts: string[] = [];
-	if (details?.modelLabel) parts.push(details.modelLabel);
-	else if (details?.model) parts.push(details.model);
-	if (details) parts.push(contextLabel(details.inheritedContext));
-	const mainContext = mainContextLabel(details?.mainContextState);
-	if (mainContext) parts.push(mainContext);
-	if (details?.turnCount) parts.push(formatTurns(details.turnCount));
-	if (details?.toolUses) parts.push(formatToolUses(details.toolUses));
-	if (details?.durationMs !== undefined) parts.push(formatMs(details.durationMs));
-	else {
-		const duration = extractTag(content, "duration_ms");
-		if (duration) parts.push(formatMs(Number(duration)));
-	}
-	return parts;
-}

package/widget.ts

@@ -17,6 +17,7 @@ import {
 import { renderAgentContextMeter } from "./context-meter.js";
 import { selectRebaseMessages } from "./rebase.js";
 import type {
+	AgentMessage,
 	AgentResultMessage,
 	CompletedAgent,
 	RebaseDelivery,
@@ -42,6 +43,15 @@ type UserAgentWidgetEntry =
 	| { kind: "running"; startedAt: number; agent: RunningAgent }
 	| { kind: "completed"; startedAt: number; agent: CompletedAgent };
 
+type CachedActivityPreview = {
+	source: AgentMessage | string | undefined;
+	status: RunningAgent["status"] | boolean;
+	error: string | undefined;
+	width: number;
+	theme: Theme;
+	text: string;
+};
+
 export class UserAgentWidget {
 	private ui: UIContext | undefined;
 	private frame = 0;
@@ -52,6 +62,7 @@ export class UserAgentWidget {
 	private active = false;
 	private selectedIndex = 0;
 	private viewerOpen = false;
+	private activityPreviews = new WeakMap<ViewableAgent, CachedActivityPreview>();
 	/** One confirmation slot for detaching the selected agent. */
 	private readonly detachConfirmation = new TimedConfirmation<ViewableAgent>(() => this.update());
 	private readonly completedAgents: CompletedAgent[] = [];
@@ -67,6 +78,7 @@ export class UserAgentWidget {
 		if (ui === this.ui) return;
 		this.inputUnsub?.();
 		this.ui = ui;
+		this.activityPreviews = new WeakMap();
 		this.widgetRegistered = false;
 		this.tui = undefined;
 		this.detachConfirmation.cancel();
@@ -101,12 +113,18 @@ export class UserAgentWidget {
 	}
 
 	ensureTimer(): void {
-		if (!this.ui || this.interval) return;
-		this.interval = setInterval(() => this.update(), 100);
+		const active = [...this.runningAgents].some(isLiveAgent);
+		if (!active && this.interval) {
+			clearInterval(this.interval);
+			this.interval = undefined;
+		}
+		if (!this.ui || !active || this.interval) return;
+		this.interval = setInterval(() => this.update(), 200);
 	}
 
 	update(): void {
 		if (!this.ui) return;
+		this.ensureTimer();
 		const entries = this.entries();
 		if (entries.length === 0) {
 			this.clear();
@@ -123,8 +141,7 @@ export class UserAgentWidget {
 					return {
 						render: (width: number) => this.renderWidget(width, theme),
 						invalidate: () => {
-							this.widgetRegistered = false;
-							this.tui = undefined;
+							this.activityPreviews = new WeakMap();
 						},
 					};
 				},
@@ -148,6 +165,7 @@ export class UserAgentWidget {
 		this.widgetRegistered = false;
 		this.tui = undefined;
 		this.active = false;
+		this.activityPreviews = new WeakMap();
 		this.detachConfirmation.cancel();
 	}
 
@@ -266,6 +284,21 @@ export class UserAgentWidget {
 		this.update();
 	}
 
+	/** Session ids with a live row or completed card, matched by exact id or prefix. */
+	matchAttachedSessionIds(query: string): string[] {
+		return this.entries()
+			.map((entry) => entry.agent.sessionId)
+			.filter((sessionId) => sessionId.startsWith(query));
+	}
+
+	/** Open the overlay of the row holding this session, as if the user selected it. */
+	openViewer(sessionId: string): boolean {
+		const entry = this.entries().find((candidate) => candidate.agent.sessionId === sessionId);
+		if (!entry) return false;
+		this.openSelected(entry.agent);
+		return true;
+	}
+
 	private clampSelection(): void {
 		const total = this.entries().length;
 		if (total === 0) {
@@ -568,16 +601,30 @@ export class UserAgentWidget {
 			.join(" ");
 		const activityPrefix = `${indent}   ⎿  `;
 		const activityWidth = Math.max(0, width - visibleWidth(activityPrefix));
+		const preview = this.renderActivityPreview(agent, activityWidth, theme);
+		const activityText = ok ? preview : theme.fg("error", preview);
+		const activity = `${theme.fg("dim", indent)}   ${theme.fg("dim", "⎿  ")}${activityText}`;
+		return [truncateToWidth(header, width), truncateToWidth(activity, width)];
+	}
+
+	private renderActivityPreview(agent: ViewableAgent, width: number, theme: Theme): string {
+		const running = isRunningAgent(agent);
+		const source = isLiveAgent(agent) ? agent.latestFinalizedMessage : agent.responseText;
+		const status = running ? agent.status : agent.ok;
+		const cached = this.activityPreviews.get(agent);
+		if (
+			cached && cached.source === source && cached.status === status &&
+			cached.error === agent.error && cached.width === width && cached.theme === theme
+		) return cached.text;
 		const description = running
 			? describeActivity(agent)
 			: {
 					text: agent.ok ? agent.responseText : `Error: ${agent.error ?? "unknown"}`,
 					truncation: "tail" as const,
 				};
-		const preview = renderActivity(description, activityWidth, theme);
-		const activityText = ok ? preview : theme.fg("error", preview);
-		const activity = `${theme.fg("dim", indent)}   ${theme.fg("dim", "⎿  ")}${activityText}`;
-		return [truncateToWidth(header, width), truncateToWidth(activity, width)];
+		const text = renderActivity(description, width, theme);
+		this.activityPreviews.set(agent, { source, status, error: agent.error, width, theme, text });
+		return text;
 	}
 }