@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/tools/intercom-tool.ts

@@ -5,12 +5,13 @@ 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, buildPeekDigest,
 	dedupeRunsById, getFullRunOutput, IdleCoalescingNotifier,
-	isAsyncRunStalled, runDisplayName, runDurationLabel,
+	isAsyncRunStalled, observedRunModel, runDisplayName, runDurationLabel,
 } from "../engine/async.ts";
 import type { PollGuard } from "../core/nudge.ts";
 import { fenceUntrusted } from "../core/fence.ts";
@@ -21,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;
@@ -131,6 +135,7 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			[
 				Type.Literal("peek"),
 				Type.Literal("result"),
+				Type.Literal("results"),
 				Type.Literal("steer"),
 				Type.Literal("stop"),
 				Type.Literal("list"),
@@ -141,10 +146,15 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			],
 			{
 				description:
-					"peek = status of async sub-agents · result = retrieve one complete settled result by run id · 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'); 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" })),
@@ -154,7 +164,10 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 		label: "Intercom",
 		description: [
 			"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 }` retrieves one complete settled payload by run id.",
+			"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`)",
@@ -180,8 +193,29 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				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);
@@ -199,14 +233,17 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				// 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 completion report does.
 				const took = runDurationLabel(run);
@@ -216,8 +253,8 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				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}${note ? `\n\n${note}` : ""}` }],
-					details: { action: "result", ok: true, status: run.status, ...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),
 				};
@@ -317,7 +354,12 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			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;
@@ -353,7 +395,20 @@ 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);
 			}
+			// 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 ?? "")) {
@@ -361,6 +416,35 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				}
 				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/models.ts

@@ -3,6 +3,7 @@ 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;
@@ -45,5 +46,19 @@ export function registerModelsTool(pi: ExtensionAPI, d: ModelsToolDeps): void {
 			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);
+		},
 	});
 }

package/src/tools/monitor.ts

@@ -4,8 +4,10 @@ import { Type } from "typebox";
 import { Text } from "@earendil-works/pi-tui";
 import type { MonitorManager } from "../core/monitor.ts";
 import { neutralizeMonitorUnicode } from "../core/monitor-output.ts";
+import { formatDuration } from "../core/time.ts";
 import { armWakeAdvice, failureDetails } from "../extension/shared.ts";
 import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import { fenceUntrusted, stripTerminalControls } from "../core/fence.ts";
 import type { MonitorArchive, MonitorLogRecord } from "../monitor/archive.ts";
 
@@ -88,12 +90,29 @@ export function registerMonitorTool(pi: ExtensionAPI, d: MonitorToolDeps): void
 				...(params.maxEvents !== undefined ? { maxEvents: params.maxEvents } : {}),
 			});
 			if (!result.ok) return fail(result.error);
-			return { content: [{ type: "text" as const, text: `Armed ${result.entry.id} (${compactInlineText(result.entry.label, { maxChars: 120 })}); ${params.mode === "exit" ? "wakes when this job exits" : "wakes on relevant stdout lines"}. Deadline ${new Date(result.entry.expiresAtEpochMs).toISOString()}. ${armWakeAdvice(ctx, "watch", "condition", "Keep this session open. Continue independent work, or end your turn; it wakes you by itself, so never sleep, poll, or arm a `timer` to wait for it.")}` }], details: { ok: true, id: result.entry.id, expiresAtEpochMs: result.entry.expiresAtEpochMs } };
+			return { content: [{ type: "text" as const, text: `Armed ${result.entry.id} (${compactInlineText(result.entry.label, { maxChars: 120 })}); ${params.mode === "exit" ? "wakes when this job exits" : "wakes on relevant stdout lines"}. Deadline ${new Date(result.entry.expiresAtEpochMs).toISOString()}. ${armWakeAdvice(ctx, "watch", "condition", "Keep this session open. Continue independent work, or end your turn; it wakes you by itself, so never sleep, poll, or arm a `timer` to wait for it.")}` }], details: { ok: true, id: result.entry.id, expiresAtEpochMs: result.entry.expiresAtEpochMs, label: compactInlineText(result.entry.label, { maxChars: 120 }), mode: params.mode } };
 		},
 		renderCall(args, theme) {
 			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
 			const label = compactInlineText(args.label ?? args.id ?? "", { maxChars: 96 });
 			return new Text(`${theme.fg("toolTitle", theme.bold(`monitor ${action}`))}${label ? ` ${theme.fg("dim", label)}` : ""}`, 0, 0);
 		},
+		renderResult(result, { expanded }, theme, context) {
+			const details = (result.details ?? {}) as { ok?: boolean; label?: string; mode?: string; expiresAtEpochMs?: number };
+			const failed = context?.isError ?? result.isError ?? false;
+			const isArm = !failed && typeof details.label === "string" && (details.mode === "output" || details.mode === "exit");
+			if (!isArm) {
+				// Failures and every list/cancel/result receipt share the one literal renderer:
+				// error heading, bounded sanitized preview, expansion hint.
+				return renderLiteralToolResult(result, { expanded }, theme, context);
+			}
+			if (expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const left = typeof details.expiresAtEpochMs === "number" && Number.isFinite(details.expiresAtEpochMs)
+				? details.expiresAtEpochMs - Date.now()
+				: undefined;
+			const deadline = left === undefined ? "" : left > 0 ? ` · deadline in ${formatDuration(left)}` : " · deadline reached";
+			const summary = compactInlineText(`${details.label} · ${details.mode}${deadline}`, { maxChars: 140 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("armed "))}${theme.fg("accent", summary)}`, 0, 0);
+		},
 	});
 }

package/src/tools/read-result.ts

@@ -0,0 +1,52 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { fenceUntrusted } from "../core/fence.ts";
+import { RESULT_READ_DEFAULT, RESULT_READ_MAX } from "../results/types.ts";
+import { isReadRequest, isReadReplyFor, readFailure, type ReadReply, type ScopedReader } from "../bus/result-reader.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+
+const Params = Type.Object({
+	ref: Type.String({ minLength: 43, maxLength: 43, description: "Granted opaque result:<UUID> reference, not a file path or run id." }),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "UTF-16 offset; use nextOffset from the previous page." })),
+	limit: Type.Optional(Type.Integer({ minimum: 2, maximum: RESULT_READ_MAX, default: RESULT_READ_DEFAULT, description: "Maximum UTF-16 characters to read." })),
+}, { additionalProperties: false });
+type PageDetails = Omit<Extract<ReadReply, { ok: true }>, "body">;
+
+/** Available only when the parent explicitly grants a scoped reader. No archive browsing,
+ * implicit fallback, polling, messages or model wakes. Fencing happens exactly once here.
+ * Wrapped in `defineTool` so callers that store the definition in a wider-typed variable
+ * (engine registration sites) keep renderer parameter inference. */
+export function makeReadResultTool(reader: Pick<ScopedReader, "read">) {
+	return defineTool<typeof Params, PageDetails>({
+		name: "read_result",
+		label: "Read result",
+		description: "Read one bounded page of a terminal result explicitly granted by your supervisor. Use only a supplied result:<UUID> reference. Follow nextOffset for another page; endOfStoredBody ends the retained report, which may be truncated. No search, paths, live runs or polling.",
+		parameters: Params,
+		async execute(_id, request, signal) {
+			if (signal?.aborted) throw new Error(readFailure("cancelled").message);
+			if (!isReadRequest(request)) throw new Error(readFailure("invalid").message);
+			let result: ReadReply;
+			try { result = await reader.read(request, signal); }
+			catch { throw new Error(readFailure(signal?.aborted ? "cancelled" : "unavailable").message); }
+			if (signal?.aborted) throw new Error(readFailure("cancelled").message);
+			try {
+				if (!isReadReplyFor(result, request)) throw new Error();
+			} catch { throw new Error(readFailure("protocol").message); }
+			if (!result.ok) throw new Error(result.message);
+			const { body, ...details } = result;
+			return { content: [{ type: "text", text: `${JSON.stringify(details)}\n${fenceUntrusted(body)}` }], details };
+		},
+		renderCall(args, theme) {
+			const ref = compactInlineText(args.ref ?? "", { maxChars: 48 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("read_result"))}${ref ? ` ${theme.fg("dim", ref)}` : ""}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme, context) {
+			// The granted page IS literal content: the shared renderer bounds it collapsed with an
+			// expansion hint and shows the complete sanitized receipt (details line + fenced body)
+			// expanded; native context.isError drives the failure heading.
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
+	});
+}

package/src/tools/timer.ts

@@ -1,9 +1,12 @@
 /** Session timer tool — arm a wall-clock wake. */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { armWakeAdvice, failureDetails } from "../extension/shared.ts";
 import { formatRemaining, type TimerScheduler } from "../core/timer.ts";
-import { parseInstant } from "../core/time.ts";
+import { formatDuration, parseInstant } from "../core/time.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import { readClockSnapshot } from "../extension/clock.ts";
 
 export interface TimerToolDeps {
@@ -97,7 +100,25 @@ export function registerTimerTool(pi: ExtensionAPI, d: TimerToolDeps): void {
 			}
 			const e = r.entry;
 			const text = `Armed ${e.id} (${e.label}) — fires in ${formatRemaining(r.remainingMs ?? e.fireAtEpochMs - e.armedAtEpochMs)} [${new Date(e.fireAtEpochMs).toISOString()}]. ${armWakeAdvice(ctx, "alarm", "time-gated step", "You can end this turn now; keep the session open for the alarm.")}`;
-			return { content: [{ type: "text", text }], details: { action: "arm", id: e.id, fireAtEpochMs: e.fireAtEpochMs, ok: true }, isError: false };
+			return { content: [{ type: "text", text }], details: { action: "arm", id: e.id, fireAtEpochMs: e.fireAtEpochMs, label: compactInlineText(e.label, { maxChars: 120 }), ok: true }, isError: false };
+		},
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
+			const label = compactInlineText(args.label ?? args.id ?? "", { maxChars: 96 });
+			return new Text(`${theme.fg("toolTitle", theme.bold(`timer ${action}`))}${label ? ` ${theme.fg("dim", label)}` : ""}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme, context) {
+			const details = (result.details ?? {}) as { action?: string; ok?: boolean; id?: string; label?: string; fireAtEpochMs?: number };
+			const failed = context?.isError ?? result.isError ?? false;
+			const fireAt = typeof details.fireAtEpochMs === "number" ? details.fireAtEpochMs : undefined;
+			const isArm = !failed && details.action === "arm" && details.ok === true && fireAt !== undefined;
+			// Failures and every now/list/cancel receipt share the one literal renderer:
+			// error heading, bounded sanitized preview, expansion hint.
+			if (!isArm || expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const left = fireAt - Date.now();
+			const due = left > 0 ? `fires in ${formatDuration(left)}` : "due now";
+			const summary = compactInlineText(`${details.label ?? details.id ?? "alarm"} · ${due}`, { maxChars: 140 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("armed "))}${theme.fg("accent", summary)}`, 0, 0);
 		},
 	});
 }

package/src/ui/activity-rows.ts

@@ -0,0 +1,34 @@
+/** Bounded local-work rows. A staged plan is waiting data, never a running agent. */
+import type { CompanionActivity } from "../core/companion.ts";
+import type { AddNodeInput } from "./agent-tree.ts";
+
+export const MAX_COMPANION_ACTIVITIES = 8;
+interface ActivityRecord { event: CompanionActivity; startedAt: number }
+
+function description(event: CompanionActivity): string {
+	const scope = `${event.target} memory`;
+	if (event.state === "staged") return `${scope} · proposal prepared; explicit apply required`;
+	if (event.state === "failed") return `${scope} · ${event.phase} failed; see the memory result`;
+	if (event.state === "done") return `${scope} · ${event.phase === "inspect" ? "inspection complete; ready for review" : event.phase === "apply" ? "staged plan applied" : "plan validation complete"}`;
+	return `${scope} · ${event.phase === "inspect" ? "inspecting" : event.phase === "stage" ? "validating consolidation" : "applying staged plan"}`;
+}
+
+export class ActivityRows {
+	private readonly records = new Map<string, ActivityRecord>();
+	accept(event: CompanionActivity, now: number): { node: AddNodeInput; removed: string[] } | undefined {
+		const id = `activity:pi-persona-mind:${event.activityId}`;
+		const existing = this.records.get(id);
+		if (existing && (existing.event.phase !== event.phase || existing.event.target !== event.target || existing.event.state !== "running")) return undefined;
+		const removed: string[] = [];
+		if (!existing && this.records.size >= MAX_COMPANION_ACTIVITIES) {
+			const victim = [...this.records].find(([, record]) => record.event.state !== "running");
+			if (!victim) return undefined; // never silently evict active local work
+			this.records.delete(victim[0]); removed.push(victim[0]);
+		}
+		const record = { event, startedAt: existing?.startedAt ?? now };
+		this.records.set(id, record);
+		const detail = description(event);
+		return { removed, node: { id, label: "Mind", kind: "activity", status: event.state === "running" ? "running" : event.state === "failed" ? "failed" : "done", detail, output: `${detail}.\nLocal memory operation; no sub-agent or model execution is implied.\nInspect the memory tool or command result for the full receipt.`, startedAt: record.startedAt, lastAdvanceAt: now } };
+	}
+	clear(): string[] { const ids = [...this.records.keys()]; this.records.clear(); return ids; }
+}

package/src/ui/agent-overlay.ts

@@ -23,7 +23,7 @@ import {
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 
-import { type AgentNode, type AgentTree, type FlatRow, deriveWaitingNodeIds, flattenTree, isWakeSource, nodeGlyph, runningAnnotation } from "./agent-tree.ts";
+import { type AgentNode, type AgentTree, type FlatRow, deriveWaitingNodeIds, effortTag, flattenTree, isWakeSource, isNonAgentNode, nodeGlyph, runningAnnotation, thinkingDetailLine } from "./agent-tree.ts";
 import { LiveClock } from "./live-clock.ts";
 import { visibleWindow } from "./model-picker.ts";
 import { compactInlineText, OPEN_SEQUENCE_TAIL, sanitizeTerminalText } from "./presentation.ts";
@@ -77,8 +77,12 @@ export function composeAgentRow(input: AgentRowInput): string {
 
 	const prefixCols = 2 + visibleWidth(indent); // "▸ " or "  ", then the indent
 	const avail = Math.max(0, bodyMax - prefixCols - 2); // 2 = glyph + space
-	const labelMax = Math.max(8, Math.floor(avail * 0.62));
-	const label = safeInline(node.label, labelMax) || "agent";
+	// The compact effort sigla rides the label (` · xh` / ` · xh→h`); its width comes out of the
+	// label budget so the appended field never becomes the part a tight row eats first. The final
+	// clamp below still guarantees the row fits either way.
+	const effort = effortTag(node.thinking, node.thinkingEffective);
+	const labelMax = Math.max(8, Math.floor(avail * 0.62) - visibleWidth(effort));
+	const label = (safeInline(node.label, labelMax) || "agent") + effort;
 	const detailMax = node.detail ? Math.max(0, avail - labelMax - 2) : 0;
 	const detail = detailMax > 0 ? safeInline(node.detail ?? "", detailMax) : "";
 	const detailText = detail ? t.fg("dim", `  ${detail}`) : "";
@@ -230,7 +234,7 @@ export class AgentOverlay extends Container {
 	 */
 	private selectedLeaf(leaves: FlatRow[]): FlatRow | undefined {
 		const anchored = this.selectedId !== undefined ? leaves.find((r) => r.node.id === this.selectedId) : undefined;
-		const leaf = anchored ?? leaves.find((r) => !isWakeSource(r.node)) ?? leaves[0];
+		const leaf = anchored ?? leaves.find((r) => !isNonAgentNode(r.node)) ?? leaves[0];
 		if (this.selectedId !== undefined && anchored === undefined && leaf !== undefined) this.aimLost = true;
 		this.selectedId = leaf?.node.id;
 		return leaf;
@@ -301,7 +305,7 @@ export class AgentOverlay extends Container {
 		}
 		this.addChild(new Spacer(1));
 		const stoppable = selected !== undefined && this.canStopNode(selected);
-		const steerable = selected !== undefined && selected.status === "running" && (this.actions.canSteer?.(selected.id) ?? false);
+		const steerable = selected !== undefined && !isNonAgentNode(selected) && selected.status === "running" && (this.actions.canSteer?.(selected.id) ?? false);
 		this.addChild(new Text(t.fg("dim", `↑↓ navigate   ⏎ open${this.hintLine("list", stoppable, steerable, this.stoppableIds(nodes).length)}   esc close`), 1, 0));
 		this.renderNotice();
 	}
@@ -379,10 +383,15 @@ export class AgentOverlay extends Container {
 		// A wake source is armed, not a live agent: it has no steer handle, so the agent-only "● live"
 		// badge and the steer-unavailable hint below would both be wrong for it.
 		const wake = isWakeSource(node);
+		const localActivity = node.kind === "activity";
 		this.addChild(
-			new Text(`${nodeGlyph(node)} ${t.fg("accent", t.bold(safeInline(node.label) || "agent"))}${live ? t.fg("success", wake ? "  ● armed" : "  ● live") : ""}`, 1, 0),
+			new Text(`${nodeGlyph(node)} ${t.fg("accent", t.bold(safeInline(node.label) || "agent"))}${live ? t.fg("success", localActivity ? "  ● local work" : wake ? "  ● armed" : "  ● live") : ""}`, 1, 0),
 		);
 		if (node.detail) this.addChild(new Text(t.fg("dim", safeInline(node.detail)), 1, 0));
+		// The drill-in has room for FULL effort names (the rows stay compact): an observed level
+		// appears only once a terminal result actually reported one.
+		const effortLine = thinkingDetailLine(node.thinking, node.thinkingEffective);
+		if (effortLine) this.addChild(new Text(t.fg("dim", effortLine), 1, 0));
 		this.addChild(new Spacer(1));
 
 		const raw = node.output?.trim()
@@ -401,7 +410,7 @@ export class AgentOverlay extends Container {
 		for (const line of all.slice(start, end)) this.addChild(new Text(t.fg("toolOutput", line), 1, 0));
 		if (this.detailScroll > 0) this.addChild(new Text(t.fg("dim", `▼ ${this.detailScroll} newer`), 1, 0));
 
-		const steerable = live && (this.actions.canSteer?.(node.id) ?? false);
+		const steerable = live && !isNonAgentNode(node) && (this.actions.canSteer?.(node.id) ?? false);
 		const stoppable = this.canStopNode(node);
 		if (this.steering && !steerable) this.steering = false; // agent finished mid-compose
 		this.addChild(new Spacer(1));
@@ -413,7 +422,7 @@ export class AgentOverlay extends Container {
 		} else {
 			this.addChild(new Text(t.fg("dim", `esc back   ·   ↑↓ scroll${this.hintLine("detail", stoppable, steerable)}`), 1, 0));
 			this.renderNotice();
-			if (live && !steerable && !wake) {
+			if (live && !steerable && !isNonAgentNode(node)) {
 				this.addChild(new Text(t.fg("dim", "(steer unavailable: no live handle yet, or this engine/broker does not expose one)"), 1, 0));
 			}
 		}
@@ -448,7 +457,8 @@ export class AgentOverlay extends Container {
 				} else if (hadNotice) this.refresh();
 				return;
 			}
-			if (keyData === "s" && (this.actions.canSteer?.(this.detailId) ?? false)) {
+			const detailNode = this.tree.snapshot().find((node) => node.id === this.detailId);
+			if (keyData === "s" && detailNode && !isNonAgentNode(detailNode) && (this.actions.canSteer?.(this.detailId) ?? false)) {
 				this.steering = true;
 				this.steerBuffer = "";
 				this.refresh();
@@ -484,7 +494,7 @@ export class AgentOverlay extends Container {
 			// Steer straight from the list: drill into the selected agent with the
 			// compose line already open (same gate as the detail view's `s`).
 			const leaf = this.aimedLeaf(leaves);
-			if (leaf && leaf.node.status === "running" && (this.actions.canSteer?.(leaf.node.id) ?? false)) {
+			if (leaf && !isNonAgentNode(leaf.node) && leaf.node.status === "running" && (this.actions.canSteer?.(leaf.node.id) ?? false)) {
 				this.detailId = leaf.node.id;
 				this.detailScroll = 0;
 				this.steering = true;
@@ -504,8 +514,8 @@ export class AgentOverlay extends Container {
 	/** Whether an agent can be stopped right now: it must be running, and the caller's `canStop`
 	 *  gate (defaulting to "yes" when omitted) must agree. Shared by both hints and `tryStop`, so
 	 *  the hint that advertises "x stop" and the handler that actually gates it never diverge. */
-	private canStopNode(node: Pick<AgentNode, "id" | "status">): boolean {
-		return node.status === "running" && (this.actions.canStop?.(node.id) ?? true);
+	private canStopNode(node: Pick<AgentNode, "id" | "status" | "kind">): boolean {
+		return node.kind !== "activity" && node.status === "running" && (this.actions.canStop?.(node.id) ?? true);
 	}
 
 	/** The agents `X` would stop: every leaf that `x` could stop, wake sources excluded. `X` means
@@ -513,7 +523,7 @@ export class AgentOverlay extends Container {
 	 *  only by an explicit `x` on its own row. One list feeds the hint count, the confirmation prompt
 	 *  and the bulk stop, so the three always agree. */
 	private stoppableIds(snap: AgentNode[] = this.tree.snapshot()): string[] {
-		return this.leafRows(snap).filter((r) => !isWakeSource(r.node) && this.canStopNode(r.node)).map((r) => r.node.id);
+		return this.leafRows(snap).filter((r) => !isNonAgentNode(r.node) && this.canStopNode(r.node)).map((r) => r.node.id);
 	}
 
 	/** The trailing "x stop"/"X stop all"/"s steer" hint fragment for an action line — the list's