@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/tools/intercom-tool.ts

@@ -5,13 +5,15 @@ import { failureDetails } from "../extension/shared.ts";
 import { Text } from "@earendil-works/pi-tui";
 import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
 import { compactVisibleText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+import { createReportBody } from "../ui/report-body.ts";
 import { coachingDisabledHint, expandDetailHint, reconcileAnsweredAsk } from "../extension/shared.ts";
 import {
-	type AsyncRun, AsyncRunTracker, boundCompletionSurface, buildPeekDigest, buildWaitTimeoutNote,
-	MAX_ASYNC_STATUS_ROWS,
+	type AsyncRun, AsyncRunTracker, buildPeekDigest,
 	dedupeRunsById, getFullRunOutput, IdleCoalescingNotifier,
-	renderCompletion, runDisplayName, runDurationLabel,
+	isAsyncRunStalled, observedRunModel, runDisplayName, runDurationLabel,
 } from "../engine/async.ts";
+import type { PollGuard } from "../core/nudge.ts";
 import { fenceUntrusted } from "../core/fence.ts";
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
 import { type IntercomOutcome, type IntercomParams, MAX_INTERCOM_MESSAGE_CHARS, MAX_INTERCOM_REF_CHARS, runIntercom } from "./intercom.ts";
@@ -20,11 +22,14 @@ import type { InProcessBus } from "../bus/inproc.ts";
 import type { PersonaController } from "../persona/controller.ts";
 import { emptyUsage } from "../engine/stream.ts";
 import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import type { TerminalResultArchive } from "../results/archive.ts";
+import { pageLiveResult, projectResultPage, resultReceiptHint } from "../results/retrieval.ts";
 
 export interface IntercomToolDeps {
 	get lastCtx(): ExtensionContext | undefined;
 	set lastCtx(value: ExtensionContext | undefined);
 	tracker: AsyncRunTracker;
+	archive(ctx: ExtensionContext): TerminalResultArchive;
 	completionNotifier: IdleCoalescingNotifier<AsyncRun>;
 	intercomNotifier: IdleCoalescingNotifier<PendingAsk>;
 	controller: PersonaController;
@@ -32,35 +37,33 @@ export interface IntercomToolDeps {
 	SUPERVISOR: string;
 	STALL_FLAG_MS: number;
 	waitingRunIds?: () => ReadonlySet<string>;
+	/** Refuses an unchanged repeat of peek/result on a running run. Built only when `config.nudge`. */
+	pollGuard?: PollGuard | undefined;
 	missingRunMessage(id: string, display: string | undefined): string;
 	stopAgent(nodeId: string): boolean;
 	steerAgent(nodeId: string, text: string): boolean;
 	steerRegistry: Map<string, unknown>;
 	stopRequested: Set<string>;
-	drainBusBlock(): string;
+	/** The premature-surrender note for a settled report (config-gated), else undefined. */
 	scanForSurrender(text: string): string | undefined;
-	get disposed(): boolean;
 	childUsage: ChildUsageLedger;
 	publishPersonaCost(): void;
 }
 
-/** Keep an aborted wait honest: its signal may end the join well before the configured window. */
-export function buildIntercomWaitStillNote(ids: readonly string[], timeoutMs: number, interrupted: boolean): string {
-	if (!interrupted) return buildWaitTimeoutNote(ids, timeoutMs);
-	const visibleIds = ids.slice(0, MAX_ASYNC_STATUS_ROWS).map((id) => sanitizeDisplayLabel(id, "run"));
-	const omitted = ids.length - visibleIds.length;
-	const idSummary = `${visibleIds.join(", ")}${omitted > 0 ? `, … +${omitted} more` : ""}`;
-	return (
-		`⏹ wait interrupted before the configured ${timeoutMs}ms window elapsed; still running: ${idSummary}. ` +
-		"Continue useful supervisor work; completion will notify you automatically. Use intercom wait again when ready."
-	);
-}
-
 /** Fence only child-authored payloads; missing-message diagnostics remain actionable tool prose. */
 export function fenceIntercomToolOutcome(out: IntercomOutcome, action: string, fence: (text: string) => string): string {
 	return action === "message" && out.details.ok ? fence(out.text) : fenceIntercomOutcome(out, fence);
 }
 
+/** `run-4 (alpha · haiku) running, run-3 (scout) done, … (+2 more)` — the one bounded run listing
+ *  every id-to-call-sign teaching surface shares (a run miss, a bulk stop). `none` when empty. */
+export function describeRuns(runs: readonly AsyncRun[], opts: { status?: boolean; max?: number } = {}): string {
+	if (runs.length === 0) return "none";
+	const max = opts.max ?? 8;
+	const shown = runs.slice(0, max).map((run) => `${run.id} (${runDisplayName(run)})${opts.status ? ` ${run.status}` : ""}`);
+	return `${shown.join(", ")}${runs.length > max ? `, … (+${runs.length - max} more)` : ""}`;
+}
+
 /** Renderer-local state only. The persisted result, not this cache, owns display identity. */
 interface IntercomRenderState {
 	target?: { id: string; label: string };
@@ -77,13 +80,62 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 		const collision = d.tracker.list().some((other) => other.id !== id && runDisplayName(other) === name);
 		return collision ? `${name} [${sanitizeDisplayLabel(id, "run")}]` : name;
 	}
+	/** An id the tracker holds nothing for: teach what exists (and why a stale id dead-ends) instead of
+	 *  letting steer/stop fall through to a false "already finished" or "no live steer handle". */
+	function missingRun(action: "result" | "steer" | "stop", to: string, display: string | undefined, snapshot: object) {
+		return { content: [{ type: "text" as const, text: d.missingRunMessage(to, display) }], details: failureDetails({ action, ok: false, ...snapshot }), isError: true };
+	}
+	/** `stop { to: "all" }`: request cancellation of every running run, each with the per-run semantics of a
+	 *  single stop — except that a run already stopping is reported, never force-cleared, in bulk. */
+	function stopAllRuns() {
+		const snapshot = { runId: "all", target: "all" };
+		const requested: AsyncRun[] = [];
+		const already: AsyncRun[] = [];
+		const unreachable: AsyncRun[] = [];
+		for (const run of d.tracker.running()) {
+			const nodeId = `async:${run.id}`;
+			if (d.stopRequested.has(nodeId)) already.push(run);
+			else (d.stopAgent(nodeId) ? requested : unreachable).push(run);
+		}
+		const noHandle = unreachable.length > 0 ? `No live stop handle: ${describeRuns(unreachable)}.` : "";
+		if (requested.length === 0 && already.length === 0) {
+			return { content: [{ type: "text" as const, text: noHandle || "intercom stop: no running runs to stop." }], details: failureDetails({ action: "stop", ok: false, ...snapshot }), isError: true };
+		}
+		if (requested.length > 0) d.pollGuard?.reset();
+		const parts = [
+			...(requested.length > 0 ? [`Cancellation requested for ${requested.length} run${requested.length === 1 ? "" : "s"}: ${describeRuns(requested)}. Stopped reports arrive as completion follow-ups; partial output is kept; changes already made are not undone.`] : []),
+			...(already.length > 0 ? [`Already stopping: ${describeRuns(already)}.${requested.length === 0 ? " Repeat stop { to: <run id> } on one that stays running to force-clear it." : ""}`] : []),
+			...(noHandle ? [noHandle] : []),
+		];
+		return { content: [{ type: "text" as const, text: parts.join(" ") }], details: { action: "stop", ok: true, ...snapshot }, isError: false };
+	}
+	/**
+	 * An unchanged repeat of a status check learns nothing and holds the turn the idle-gated completion
+	 * wake needs: refuse it, and on the second repeat end the turn. The signature is every shown run's
+	 * state (status, queued, waiting, stalled), so anything newly informative passes.
+	 */
+	function pollRefusal(action: "peek" | "result", scope: string, runs: readonly AsyncRun[], waiting: ReadonlySet<string> | undefined, snapshot: object) {
+		const running = runs.filter((r) => r.status === "running");
+		if (!d.pollGuard || running.length === 0) return undefined;
+		const now = Date.now();
+		const sig = runs.map((r) => [r.id, r.status, r.queued === true, waiting?.has(r.id) === true, isAsyncRunStalled(r, now, d.STALL_FLAG_MS)].join("|")).sort().join(",");
+		const verdict = d.pollGuard.check(scope, sig);
+		if (verdict === "ok") return undefined;
+		const text = `intercom ${action}: no run settled, started, queued, began waiting or stalled since your last ${action} (${running.map((r) => r.id).join(", ")} still running). Checking again blocks your own completion follow-ups and the operator's steering — end your turn; a finished run or batch wakes you. Use steer or stop only to intervene.`;
+		return {
+			content: [{ type: "text" as const, text }],
+			details: failureDetails({ action, ok: false, ...snapshot }),
+			isError: true,
+			...(verdict === "terminate" ? { terminate: true } : {}),
+		};
+	}
 	// ── intercom tool (supervisor side of the comm plane: read/answer children) ───
 	const IntercomToolParams = Type.Object({
 		action: Type.Union(
 			[
 				Type.Literal("peek"),
 				Type.Literal("result"),
-				Type.Literal("wait"),
+				Type.Literal("results"),
 				Type.Literal("steer"),
 				Type.Literal("stop"),
 				Type.Literal("list"),
@@ -94,24 +146,28 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			],
 			{
 				description:
-					"peek = watch async sub-agents · result = retrieve one complete settled result by run id · wait = collect current reports; sync:true joins (default: nonblocking with UI, blocking headless) · steer = soft redirect into one by run id (it may ignore it) · stop = request engine cancellation by run id · message = retrieve one drained bus message by message id · list/inbox/reply/send = coaching messages (needs a coaching persona)",
+					"peek = status of async sub-agents · results = bounded archive summaries (cursor/limit) · result = page a settled live result by to:run-id or a saved report by ref:result-UUID · steer = soft redirect into one by run id (it may ignore it) · stop = request engine cancellation by run id · message = retrieve one drained bus message by message id · list/inbox/reply/send = coaching messages (needs a coaching persona)",
 			},
 		),
-		to: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "result/steer/stop/peek: the async run id (e.g. 'run-1') · wait: an async run id; omit it to collect all current/pending completions · send: the child handle (from `list`)" })),
+		to: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "result/steer/stop/peek: the async run id (e.g. 'run-1'); stop: \"all\" cancels every running run · send: the child handle (from `list`)" })),
+		ref: Type.Optional(Type.String({ maxLength: 43, description: "result: opaque result:<UUID> archive reference; never a run id. Mutually exclusive with to." })),
+		offset: Type.Optional(Type.Integer({ minimum: 0, description: "result: stored-body UTF-16 offset (default 0); use nextOffset, never split a surrogate pair." })),
+		limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000, description: "result: 2..16000 UTF-16 units (default 8000). results: 1..50 summaries (default 20)." })),
+		cursor: Type.Optional(Type.Integer({ minimum: 0, description: "results: nextCursor from the prior bounded summary page; omit for the first page." })),
+		collect: Type.Optional(Type.Boolean({ description: "result with live to only: true acknowledges the whole report and suppresses its pending completion. Paging alone does not collect." })),
 		messageId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "message: the drained bus message id shown by `inbox`" })),
 		askId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "reply: the message id of the child's pending question" })),
 		message: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_MESSAGE_CHARS, description: "steer/reply/send: the text to deliver" })),
-		sync: Type.Optional(Type.Boolean({ description: "wait: block for runs to settle; defaults to false in interactive/RPC sessions and true in headless sessions" })),
-		timeoutMs: Type.Optional(Type.Number({ description: "wait with sync:true: max ms to hold your turn (default 600000; values below 1000 clamp to 1000, values above 600000 clamp to 600000) — on timeout you get what settled + what's still running" })),
 	});
 	pi.registerTool({
 		name: "intercom",
 		label: "Intercom",
 		description: [
-			"See, steer, message, and JOIN your running sub-agents.",
-			"`peek` watches what your async sub-agents are doing; `result` retrieves one complete settled",
-			"payload by run id; `wait` collects current reports and is nonblocking by default with UI (interactive/RPC); set `sync: true` for an intentional bounded join. Headless defaults to joining; set `sync: false` for a snapshot. Do not automatically wait for all children.",
-			"Work independently while children run; when only children remain, end your turn and let completion follow-ups wake you; do not monitor or poll healthy children.",
+			"Steer, stop and inspect your background sub-agents; a finished run or batch wakes you with a completion follow-up.",
+			"Never `peek` healthy children; use it only for status you need. `result { to: runId }` pages a live settled payload by run id (8000 units default, 16000 maximum).",
+			"`results { cursor?, limit? }` lists saved terminal summaries across this session's branches (20 default, 50 maximum); pass nextCursor for the next page.",
+			"`result { ref: 'result:<UUID>', offset?, limit? }` reads a saved report, including after reload, without collecting, billing, restarting a worker or waking the model. Memory-only references last only for this activation. Run ids route only the current runtime; never guess a historical run by id.",
+			"Use nextOffset for more UTF-16 pages. Only a whole live body returned in one read, or explicit live collect:true, suppresses a pending completion. Archive ref reads reject collect.",
 			"`steer` sends a soft course-correction to one (by run id); in-process async runs can receive it mid-run,",
 			"while child-engine (MCP/worktree) async runs receive it as a brokered follow-up. After remaining tools return, Pi can consume steering; arbitrary active tool work is not promised to stop immediately.",
 			"`message` retrieves a drained bus message by its message id; `list`/`inbox`/`reply`/`send` exchange coaching messages (a child reaches you via `contact_supervisor`)",
@@ -124,7 +180,7 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			// interpolate it into trusted prose without reducing it to compact identifier metadata.
 			const displayTarget = params.to === undefined ? undefined : sanitizeDisplayLabel(params.to, "run");
 			const targetSnapshot = params.to === undefined ? {} : { runId: params.to, target: displayRunTarget(params.to) };
-			// peek + wait + steer + stop are supervisor→child controls over the async d.tracker /
+			// peek + result + steer + stop are supervisor→child controls over the async tracker /
 			// steer handles — available to EVERY persona (no dependency on the coaching bus).
 			if (params.action === "peek") {
 				// No `to` → running legs PLUS any settled-but-not-yet-delivered ones (the settle→deliver
@@ -132,112 +188,73 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				const runs = params.to
 					? [d.tracker.peek(params.to)].filter((r): r is AsyncRun => !!r)
 					: dedupeRunsById([...d.tracker.running(), ...d.completionNotifier.peekPending()]);
-				return { content: [{ type: "text", text: buildPeekDigest(runs, { now: Date.now(), stallMs: d.STALL_FLAG_MS, ...(d.waitingRunIds ? { waitingForSupervisor: d.waitingRunIds() } : {}) }) }], details: { action: "peek", ok: true, ...targetSnapshot }, isError: false };
+				const waiting = d.waitingRunIds?.();
+				const refusal = pollRefusal("peek", params.to ?? "*", runs, waiting, targetSnapshot);
+				if (refusal) return refusal;
+				return { content: [{ type: "text", text: buildPeekDigest(runs, { now: Date.now(), stallMs: d.STALL_FLAG_MS, ...(waiting ? { waitingForSupervisor: waiting } : {}) }) }], details: { action: "peek", ok: true, ...targetSnapshot }, isError: false };
+			}
+			if (params.action === "results" || (params.action === "result" && params.ref !== undefined)) {
+				const invalid = params.to !== undefined || params.collect !== undefined || (params.action === "results" && (params.ref !== undefined || params.offset !== undefined)) || (params.action === "result" && params.cursor !== undefined);
+				if (invalid) return { content: [{ type: "text", text: "Archive reads accept ref/offset/limit; results accepts cursor/limit. to and collect are live-only." }], details: failureDetails({ action: params.action }), isError: true };
+				const archive = d.archive(ctx);
+				if (params.action === "results") {
+					const page = archive.list({ ...(params.cursor !== undefined ? { cursor: params.cursor } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) });
+					const text = page.ok ? ["Saved terminal reports (not live workers):", ...page.results.map((r) => `${r.ref} · ${sanitizeDisplayLabel(r.label ?? r.agent)} · ${r.status} · ${r.storage}${r.truncated ? " · truncated" : ""}`), ...(page.nextCursor !== undefined ? [`nextCursor: ${page.nextCursor}`] : []), ...(page.warnings.length ? [`Storage warnings: ${page.warnings.join(", ")}`] : [])].join("\n") : page.message;
+					return { content: [{ type: "text", text }], details: { action: "results", ...page }, isError: !page.ok };
+				}
+				const page = archive.read({ ref: params.ref!, ...(params.offset !== undefined ? { offset: params.offset } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) });
+				if (!page.ok) {
+					return { content: [{ type: "text", text: page.message }], details: { action: "result", ...page }, isError: true };
+				}
+				// Bounded-page rule: the fenced body is delivered once, in content; details stay
+				// bounded metadata exactly like the live result path (no whole page hidden there).
+				const { body: _pageBody, ...pageMeta } = page;
+				return {
+					content: [{ type: "text", text: `${page.summary.ref} · ${page.summary.status} · ${page.summary.storage}${page.summary.truncated ? " · saved body truncated" : ""}\n${projectResultPage(page, page.summary.error)}` }],
+					details: { action: "result", ...pageMeta }, isError: false,
+				};
 			}
 			if (params.action === "result") {
-				if (!params.to) {
+				if (!params.to || params.cursor !== undefined) {
 					return { content: [{ type: "text", text: "intercom result needs { to: <run id> }." }], details: failureDetails({ action: "result", ok: false }), isError: true };
 				}
 				const run = d.tracker.peek(params.to);
-				if (!run) {
-					return { content: [{ type: "text", text: d.missingRunMessage(params.to, displayTarget) }], details: failureDetails({ action: "result", ok: false, ...targetSnapshot }), isError: true };
-				}
+				if (!run) return missingRun("result", params.to, displayTarget, targetSnapshot);
 				if (run.status === "running") {
+					const refusal = pollRefusal("result", `result:${params.to}`, [run], d.waitingRunIds?.(), targetSnapshot);
+					if (refusal) return refusal;
 					return {
-						content: [{ type: "text", text: `${targetSnapshot.target} is still running. Use intercom peek/wait, or request result after it settles.` }],
+						content: [{ type: "text", text: `${targetSnapshot.target} is still running; a finished run or batch wakes you with a completion follow-up. End your turn if nothing else remains.` }],
 						details: failureDetails({ action: "result", ok: false, status: run.status, ...targetSnapshot }),
 						isError: true,
 					};
 				}
 				// Explicit collection owns this delivery: remove a still-buffered passive completion so the
-				// same result cannot appear again as a follow-up a moment later. Telling the d.tracker too
+				// same result cannot appear again as a follow-up a moment later. Telling the tracker too
 				// makes this retained copy the first thing retention evicts — the supervisor has read it,
 				// so it is the cheapest payload in the map to lose.
-				d.completionNotifier.discard((pending) => pending.id === run.id);
-				d.tracker.markCollected(run.id);
 				const full = getFullRunOutput(run);
-				const body = full === "(no output)" ? full : fenceUntrusted(full);
-				// The cause is engine/child-authored text too. Keep the run id/status as trusted compact
-				// metadata, but put the diagnostic inside the same untrusted fence as the payload.
-				const cause = run.error ? `\nFailure detail:\n${fenceUntrusted(run.error)}` : "";
-				const displayRun = sanitizeDisplayLabel(run.label ?? run.agent);
+				const page = pageLiveResult(full, params.offset, params.limit);
+				if (!page) return { content: [{ type: "text", text: "Invalid result offset/limit; use nextOffset and 2..16000 units." }], details: failureDetails({ action: "result", ...targetSnapshot }), isError: true };
+				if (params.collect === true || (page.offset === 0 && page.endOfStoredBody)) {
+					d.completionNotifier.discard((pending) => pending.id === run.id);
+					d.tracker.markCollected(run.id);
+				}
+				const body = projectResultPage(page, run.error);
+				const receipt = resultReceiptHint(run.resultReceipt);
+				const displayRun = runDisplayName(run);
+				const modelUsed = observedRunModel(run);
 				// The wall time this leg took: an explicit collection is one of the paths a completion reaches
-				// the supervisor through, so it carries the same reading the passive/join reports do.
+				// the supervisor through, so it carries the same reading the passive completion report does.
 				const took = runDurationLabel(run);
+				// The follow-up discarded above is what would have carried the premature-surrender note, so
+				// a collected DONE report must carry it itself (a failed leg is already a failure report).
+				const note = run.status === "done" ? d.scanForSurrender(full) : undefined;
 				const billed = d.childUsage.accountMany([{ key: run.id, usage: run.result?.usage ?? emptyUsage() }]);
 				d.publishPersonaCost();
 				return {
-					content: [{ type: "text", text: `${run.id} (${displayRun}) · ${run.status}${took ? ` · ${took}` : ""}${cause}\n${body}` }],
-					details: { action: "result", ok: true, status: run.status, ...targetSnapshot },
-					isError: false,
-					...toolUsageField(billed),
-				};
-			}
-			if (params.action === "wait") {
-				// No `to` → wait on running legs AND collect settled legs still queued for follow-up
-				// delivery, so a wait in the settle→deliver gap returns their results (not "nothing").
-				if (params.to && !d.tracker.peek(params.to)) {
-					return { content: [{ type: "text", text: d.missingRunMessage(params.to, displayTarget) }], details: failureDetails({ action: "wait", ok: false, ...targetSnapshot }), isError: true };
-				}
-				const ids = params.to
-					? [params.to]
-					: dedupeRunsById([...d.tracker.running(), ...d.completionNotifier.peekPending()]).map((r) => r.id);
-				if (ids.length === 0) {
-					return { content: [{ type: "text", text: "No async runs to wait for." }], details: { action: "wait", ok: true }, isError: false };
-				}
-				// Interactive/RPC defaults to a snapshot: waiting inside a tool stalls queued user steering.
-				// Headless retains its historical join; callers can override either default with sync.
-				if (!(params.sync ?? ctx.hasUI !== true)) {
-					const current = ids.map((id) => d.tracker.peek(id)).filter((run): run is AsyncRun => !!run);
-					const settled = current.filter((run) => run.status !== "running");
-					const still = current.filter((run) => run.status === "running");
-					const settledIds = new Set(settled.map((run) => run.id));
-					d.completionNotifier.discard((run) => settledIds.has(run.id));
-					for (const id of settledIds) d.tracker.markCollected(id);
-					const report = settled.length > 0 ? renderCompletion(settled, fenceUntrusted, (t) => d.scanForSurrender(t)) : "";
-					const stillIds = still.map((run) => sanitizeDisplayLabel(run.id, "run"));
-					const omitted = stillIds.length > MAX_ASYNC_STATUS_ROWS;
-					const runningNote = still.length > 0
-						? `Background continues; automatic completion will notify you. End your turn when this is the only remaining work. Still running: ${stillIds.slice(0, MAX_ASYNC_STATUS_ROWS).join(", ")}${omitted ? `, … +${stillIds.length - MAX_ASYNC_STATUS_ROWS} more` : ""}.`
-						: "";
-					const text = boundCompletionSurface([report, runningNote].filter(Boolean).join("\n\n") || "Nothing to report (unknown run ids?).");
-					const billed = d.childUsage.accountMany(settled.map((run) => ({ key: run.id, usage: run.result?.usage ?? emptyUsage() })));
-					d.publishPersonaCost();
-					return {
-						content: [{ type: "text", text }],
-							details: { action: "wait", ok: true, settled: [...settledIds], running: still.map((run) => run.id), ...targetSnapshot },
-						isError: false,
-						...toolUsageField(billed),
-					};
-				}
-				// Bounded join: never longer than a child's ask timeout (bus `ask` default 600s),
-				// so a coaching child blocking on OUR reply can't deadlock us past its own timeout.
-				// Default matches that ceiling — heavy sub-agents (30+ turns) routinely outlast a
-				// short window, and a premature "still running" forces a needless re-wait.
-				const timeoutMs = Math.min(Math.max(params.timeoutMs ?? 600_000, 1_000), 600_000);
-				const runs = await d.tracker.waitFor(ids, timeoutMs, _signal);
-				const settled = runs.filter((r) => r.status !== "running");
-				const still = runs.filter((r) => r.status === "running");
-				// These results are delivered HERE — drop them from the pending follow-up
-				// notifier so they aren't reported a second time. Render through the SAME
-				// renderCompletion the passive path uses, so a leg that came back BLOCKED still
-				// carries the premature-surrender note when it is collected via `wait`.
-				const settledIds = new Set(settled.map((r) => r.id));
-				d.completionNotifier.discard((run) => settledIds.has(run.id));
-				for (const id of settledIds) d.tracker.markCollected(id);
-				const report = settled.length > 0 ? renderCompletion(settled, fenceUntrusted, (t) => d.scanForSurrender(t)) : "";
-				const stillNote = still.length > 0
-					? buildIntercomWaitStillNote(still.map((r) => r.id), timeoutMs, _signal?.aborted === true)
-					: "";
-				const joined = [report, stillNote].filter(Boolean).join("\n\n") || "Nothing to report (unknown run ids?).";
-				const text = boundCompletionSurface(joined);
-				const billed = d.childUsage.accountMany(
-					settled.map((r) => ({ key: r.id, usage: r.result?.usage ?? emptyUsage() })),
-				);
-				d.publishPersonaCost();
-				return {
-					content: [{ type: "text", text }],
-					details: { action: "wait", ok: true, settled: [...settledIds], running: still.map((r) => r.id), ...targetSnapshot },
+					content: [{ type: "text", text: `${run.id} (${displayRun}) · ${run.status}${took ? ` · ${took}` : ""}${modelUsed ? `\nObserved model: ${modelUsed}` : ""}\n${body}${receipt ? `\n${receipt}` : ""}${note ? `\n\n${note}` : ""}` }],
+					details: { action: "result", ok: true, status: run.status, ...targetSnapshot, ...(modelUsed ? { modelUsed } : {}), page: { offset: page.offset, nextOffset: page.nextOffset, endOfStoredBody: page.endOfStoredBody }, ...(run.resultReceipt ? { resultReceipt: { ...run.resultReceipt } } : {}) },
 					isError: false,
 					...toolUsageField(billed),
 				};
@@ -248,7 +265,8 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				}
 				const nodeId = `async:${params.to}`;
 				const knownRun = d.tracker.peek(params.to);
-				if (knownRun && knownRun.status !== "running") {
+				if (!knownRun) return missingRun("steer", params.to, displayTarget, targetSnapshot);
+				if (knownRun.status !== "running") {
 					return {
 						content: [{ type: "text", text: `Cannot steer "${targetSnapshot.target}" — this run is already settled (${knownRun.status}). Use intercom result with to="${displayTarget}" to inspect its retained result.` }],
 						details: failureDetails({ action: "steer", ok: false, status: knownRun.status, ...targetSnapshot }),
@@ -262,26 +280,31 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 						isError: true,
 					};
 				}
-				// Routed through the guarded d.steerAgent so a just-finished/d.disposed handle can't throw.
+				// Routed through the guarded steerAgent so a just-finished/disposed handle can't throw.
 				const steered = d.steerAgent(nodeId, params.message);
+				// An intervention changes the child's state without moving any flag the guard compares.
+				if (steered) d.pollGuard?.reset();
 				return steered
 					? { content: [{ type: "text", text: `Steering queued for ${targetSnapshot.target} (${displayTarget}).` }], details: { action: "steer", ok: true, ...targetSnapshot, message: params.message }, isError: false }
 					: { content: [{ type: "text", text: `Could not steer "${targetSnapshot.target}" — it may have just finished, or the message was empty.` }], details: failureDetails({ action: "steer", ok: false, ...targetSnapshot }), isError: true };
 			}
 			if (params.action === "stop") {
+				if (params.to === "all") return stopAllRuns();
 				if (!params.to) {
 					return { content: [{ type: "text", text: "intercom stop needs { to: <run id> }." }], details: failureDetails({ action: "stop", ok: false }), isError: true };
 				}
+				if (!d.tracker.peek(params.to)) return missingRun("stop", params.to, displayTarget, targetSnapshot);
 				// Abort the real run signal. The child backend can kill its process tree; the
 				// in-process backend requests host cancellation and settles its lifecycle separately.
 				const nodeId = `async:${params.to}`;
 				const repeated = d.stopRequested.has(nodeId);
 				const stopped = d.stopAgent(nodeId);
+				if (stopped) d.pollGuard?.reset();
 				if (stopped && !repeated) {
-					return { content: [{ type: "text", text: `Cancellation requested for ${targetSnapshot.target}. Check its terminal result; changes already made are not undone.` }], details: { action: "stop", ok: true, ...targetSnapshot }, isError: false };
+					return { content: [{ type: "text", text: `Cancellation requested for ${targetSnapshot.target}; its stopped report arrives with the completion follow-up (its batch's, if it has one). Changes already made are not undone.` }], details: { action: "stop", ok: true, ...targetSnapshot }, isError: false };
 				}
 				// A repeated stop has just invoked the REAL cancel handle again. Only now force-clear
-				// d.tracker state if engine settlement is still lagging; the handle remains registered
+				// tracker state if engine settlement is still lagging; the handle remains registered
 				// until onComplete so cancellation can never be replaced by UI-only bookkeeping.
 				if (stopped && repeated && d.tracker.forceSettle(params.to, "force-stopped by supervisor after repeated engine cancellation")) {
 					return {
@@ -304,7 +327,7 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			if (params.action === "reply" && out.details.ok && params.askId) {
 				reconcileAnsweredAsk(params.askId, d.intercomNotifier, d.bus, d.SUPERVISOR);
 			}
-			// Child-authored inbox bodies are untrusted, exactly like the d.drainBusBlock/peek copies.
+			// Child-authored inbox bodies are untrusted, exactly like the automatic drain and peek copies.
 			// A retrieved body is child-authored even though it is no longer an inbox batch; keep the
 			// same trust fence around it as inbox and automatic drain surfaces.
 			let text = fenceIntercomToolOutcome(out, params.action, fenceUntrusted);
@@ -320,26 +343,28 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			const runTarget = typeof args.to === "string"
 				? state?.target?.id === args.to ? state.target.label : displayRunTarget(args.to)
 				: undefined;
-			if (action === "wait" || action === "peek") target = runTarget ?? "all";
+			if (action === "peek") target = runTarget ?? "all";
 			else if (["result", "steer", "stop"].includes(action)) target = runTarget ?? "?";
 			else if (action === "send") target = compactInlineText(args.to ?? "?", { maxChars: 80 }) || "?";
 			else if (action === "message") target = compactInlineText(args.messageId ?? "?", { maxChars: 80 }) || "?";
 			else if (action === "reply") target = compactInlineText(args.askId ?? "?", { maxChars: 80 }) || "?";
-			const timeout = action === "wait" && Number.isFinite(args.timeoutMs) && args.timeoutMs !== undefined
-				? ` · ${Math.max(0, Math.floor(args.timeoutMs))}ms`
-				: "";
-			const formatCall = (label: string) => `${theme.fg("toolTitle", theme.bold("intercom "))}${theme.fg("accent", action)}${label ? theme.fg("dim", ` ${compactInlineText(label, { maxChars: 80 })}${timeout}`) : ""}`;
+			const formatCall = (label: string) => `${theme.fg("toolTitle", theme.bold("intercom "))}${theme.fg("accent", action)}${label ? theme.fg("dim", ` ${compactInlineText(label, { maxChars: 80 })}`) : ""}`;
 			const component = new Text(formatCall(target), 0, 0);
 			if (state) { state.callText = component; state.formatCall = formatCall; }
 			return component;
 		},
 		renderResult(result, { expanded }, theme, context) {
-			const details = (result.details ?? {}) as { action?: string; ok?: boolean; runId?: string; target?: string; message?: string };
+			const details = (result.details ?? {}) as {
+				action?: string; ok?: boolean; runId?: string; target?: string; message?: string;
+				results?: Array<{ truncated?: boolean }>;
+				summary?: { ref?: string; storage?: string; storedChars?: number; truncated?: boolean };
+				nextCursor?: number; nextOffset?: number; warnings?: readonly string[];
+			};
 			const state = context?.state as IntercomRenderState | undefined;
 			const action = details.action ?? context?.args?.action;
 			const savedId = details.runId ?? context?.args?.to;
 			const legacyCompleted = !details.target && context !== undefined && context.isPartial !== true
-				&& ["steer", "stop", "result", "peek", "wait"].includes(action ?? "");
+				&& ["steer", "stop", "result", "peek"].includes(action ?? "");
 			if (state && typeof savedId === "string" && (details.target || legacyCompleted)) {
 				// Old receipts have no display snapshot. A new session may reuse their run ID;
 				// the current tracker cannot supply a historical alias for that unrelated execution.
@@ -350,9 +375,9 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			}
 			const first = result.content[0];
 			const full = sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)");
-			const failed = details.ok === false;
+			const failed = (context?.isError ?? result.isError) || details.ok === false;
 			const prefix = failed ? `${theme.fg("error", theme.bold("failed"))}\n` : "";
-			if (details.action === "steer" && details.ok === true) {
+			if (!failed && details.action === "steer" && details.ok === true) {
 				const target = compactInlineText(details.target ?? state?.target?.label ?? (legacyCompleted && typeof savedId === "string" ? sanitizeDisplayLabel(savedId, "run") : details.runId ? displayRunTarget(details.runId) : ""), { maxChars: 80 });
 				const message = typeof details.message === "string" ? details.message : context?.args?.message;
 				// Old persisted receipts may predate message snapshots. Keep their original content
@@ -370,7 +395,56 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				const showTitle = !state?.callText || !preview;
 				return new Text(`${showTitle ? theme.fg("success", title) : ""}${preview ? `${showTitle ? "\n" : ""}${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}` : ""}`, 0, 0);
 			}
-			if (expanded) return new Text(`${prefix}${theme.fg("toolOutput", full)}`, 0, 0);
+			// Archive views are listings/diagnostics, never Markdown reports. A successful archive
+			// read carries no runId (live results do) and a summary (its own receipt); the invalid
+			// argument mix and failed reads fall through to the literal failure rendering below.
+			const listing = details.action === "results" && details.ok === true && Array.isArray(details.results) ? details.results : undefined;
+			const archivedPage = details.action === "result" && details.ok === true
+				&& typeof details.summary === "object" && details.summary !== null && details.runId === undefined
+				? details.summary
+				: undefined;
+			if (expanded) {
+				// Archive pages/listings stay literal via the shared renderer — complete sanitized
+				// content, no Markdown re-render of a quote-fenced page or a ref listing.
+				if (!failed && (listing || archivedPage)) {
+					return renderLiteralToolResult(result, { expanded }, theme, context);
+				}
+				// Explicit report/message actions only; missing/running diagnostics and control
+				// receipts remain literal. Older history with no action is not guessed from prose.
+				if (!failed && ["result", "message", "inbox"].includes(action ?? "")) {
+					return createReportBody(full, theme, {}, context?.lastComponent);
+				}
+				return new Text(`${prefix}${theme.fg("toolOutput", full)}`, 0, 0);
+			}
+			if (!failed && listing) {
+				// Purpose line first (count + paging/truncation/storage honesty), then a bounded
+				// listing preview; the payload's own header line is replaced by the purpose line.
+				const truncated = listing.filter((entry) => entry?.truncated === true).length;
+				const flags = [
+					...(details.nextCursor !== undefined ? [`next page: cursor ${details.nextCursor}`] : []),
+					...(truncated > 0 ? [`${truncated} truncated`] : []),
+					...(details.warnings?.length ? [`warnings: ${details.warnings.join(", ")}`] : []),
+				];
+				const purpose = compactInlineText(`results · ${listing.length} retained${flags.length ? ` · ${flags.join(" · ")}` : ""}`, { maxChars: 100 });
+				const preview = compactVisibleText(full.split("\n").slice(1).join("\n"), { maxLines: 3, maxLineChars: 100 });
+				return new Text(`${theme.fg("success", purpose)}\n${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}`, 0, 0);
+			}
+			if (!failed && archivedPage) {
+				// Page position reads against the STORED body (originals may be truncated); honesty
+				// flags surface collapsed so a memory-only or truncated receipt is never mistaken
+				// for a durable whole report without expanding.
+				const end = details.nextOffset ?? archivedPage.storedChars ?? 0;
+				const flags = [
+					...(archivedPage.truncated ? ["truncated"] : []),
+					...(archivedPage.storage === "memory-only" ? ["memory-only"] : []),
+					...(details.warnings?.length ? [`warnings: ${details.warnings.join(", ")}`] : []),
+				];
+				const purpose = compactInlineText(`result · ${archivedPage.ref ?? "?"} · page ${end}/${archivedPage.storedChars ?? "?"}${flags.length ? ` · ${flags.join(" · ")}` : ""}`, { maxChars: 100 });
+				// The payload's receipt header and paging diagnostic line are replaced by the purpose
+				// line; the fence wrapper is dropped by the preview, leaving the page body quoted.
+				const preview = compactVisibleText(full.split("\n").slice(2).join("\n"), { maxLines: 3, maxLineChars: 100 });
+				return new Text(`${theme.fg("success", purpose)}\n${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}`, 0, 0);
+			}
 			const preview = compactVisibleText(full, { maxLines: 4, maxLineChars: 100 });
 			const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
 			return new Text(`${prefix}${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);

package/src/tools/intercom.ts

@@ -120,7 +120,7 @@ export function runIntercom(params: IntercomParams, bus: InProcessBus, self: str
 		}
 		case "message": {
 			if (!params.messageId) {
-				return { text: "intercom message needs { messageId: <message id> }.", details: { action: "message", ok: false } };
+				return { text: "intercom message needs { messageId: <message id> }. To message a running child use steer { to: <run id>, message }.", details: { action: "message", ok: false } };
 			}
 			if (params.messageId.length > MAX_INTERCOM_REF_CHARS) {
 				return { text: `intercom messageId exceeds the ${MAX_INTERCOM_REF_CHARS}-character limit.`, details: { action: "message", ok: false } };

package/src/tools/models.ts

@@ -3,11 +3,12 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { Text } from "@earendil-works/pi-tui";
 import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 
 export interface ModelsToolDeps {
 	get lastCtx(): ExtensionContext | undefined;
 	set lastCtx(value: ExtensionContext | undefined);
-	searchModels(ctx: ExtensionContext, query?: string): { lines: string[]; total: number; capped: boolean };
+	searchModels(ctx: ExtensionContext, query?: string): { lines: string[]; total: number; capped: boolean; shortlist: boolean };
 }
 
 export function registerModelsTool(pi: ExtensionAPI, d: ModelsToolDeps): void {
@@ -16,24 +17,48 @@ export function registerModelsTool(pi: ExtensionAPI, d: ModelsToolDeps): void {
 		name: "models",
 		label: "Models",
 		description: [
-			"List or search the available model ids (provider/id). The same name exists under several",
-			"providers — use an EXACT id from here as a delegate task's `model`. ★ marks your session",
-			"provider; prefer it (it's the authenticated one).",
+			"Discover model candidates (provider/id). With no query: the current model first, then a compact",
+			"shortlist of nearby family/version candidates from the same provider, ordered cost:low → medium → high → unknown.",
+			"Family and version names are proximity hints, not verified release dates or account support. A query searches",
+			"the full eligible catalog, including older models and snapshots. Use exact refs; ★ marks your",
+			"session provider, not account support. Authentication does not guarantee access to every listed model.",
+			"cost:low/medium/high ranks advertised API prices relative to recent candidates of the same provider;",
+			"cost:unknown means insufficient price data. These are cost bands, not quality, speed or reasoning-effort ratings; choose task fit yourself.",
+			"Context, reasoning support and API prices are host catalog metadata; API prices do not describe subscription billing.",
+			"Prefer these nearby candidates before older or unrelated models merely because they are cheap. Omitting `model` preserves",
+			"saved per-persona role/agent assignments, then the agent frontmatter model and engine defaults; it does not necessarily select the supervisor model.",
+			"To intentionally choose the supervisor's current model over a configured choice, pass its exact provider/id as `model` only when explicitly authorized.",
+			"Never silently switch providers or billing routes.",
 		].join(" "),
 		parameters: Type.Object({
-			query: Type.Optional(Type.String({ description: "Filter by substring (provider or id), e.g. 'sonnet'" })),
+			query: Type.Optional(Type.String({ description: "Search the full catalog by substring (provider or id), e.g. 'sonnet'; omit for the current-first shortlist" })),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			d.lastCtx = ctx;
-			const { lines, total, capped } = d.searchModels(ctx, params.query);
+			const { lines, total, capped, shortlist } = d.searchModels(ctx, params.query);
+			const showing = shortlist || capped ? ` (showing ${lines.length} ${shortlist ? "nearby family/version candidates" : "matches"})` : "";
 			const text = lines.length
-				? `${total} model(s)${capped ? " (showing 40 — refine with a query)" : ""}; ★ = session provider:\n${lines.join("\n")}`
+				? `${total} catalog model(s)${showing}; ★ = session provider, (you) = current model. Account support may vary.${shortlist || capped ? " Query searches the full catalog." : ""}\n${lines.join("\n")}`
 				: `no models match "${params.query ?? ""}"`;
-			return { content: [{ type: "text", text }], details: { total }, isError: false };
+			return { content: [{ type: "text", text }], details: { total, shown: lines.length, shortlist }, isError: false };
 		},
 		renderCall(args, theme) {
-			const query = compactInlineText(args.query ?? "(all)", { maxChars: 96 }) || "(all)";
+			const query = compactInlineText(args.query ?? "(shortlist)", { maxChars: 96 }) || "(shortlist)";
 			return new Text(`${theme.fg("toolTitle", theme.bold("models "))}${theme.fg("dim", query)}`, 0, 0);
 		},
+		renderResult(result, { expanded }, theme, context) {
+			// The catalog itself is literal data: the shared renderer bounds it collapsed and
+			// shows the complete sanitized listing expanded.
+			if (expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const failed = context?.isError ?? result.isError ?? false;
+			if (failed) return renderLiteralToolResult(result, { expanded: false }, theme, context);
+			const details = (result.details ?? {}) as { total?: number; shown?: number; shortlist?: boolean };
+			const total = typeof details.total === "number" && Number.isFinite(details.total) ? details.total : 0;
+			const shown = typeof details.shown === "number" && Number.isFinite(details.shown) ? details.shown : 0;
+			const summary = shown === 0
+				? "no catalog matches"
+				: `${total} catalog models · showing ${shown}${details.shortlist ? " nearby candidates" : " matches"}`;
+			return new Text(`${theme.fg("toolTitle", theme.bold("models · "))}${theme.fg("accent", compactInlineText(summary, { maxChars: 96 }))}`, 0, 0);
+		},
 	});
 }