@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/extension/identity.ts

@@ -1,7 +1,7 @@
 /** Session identity registration and Pi lifecycle adapter. */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 
@@ -15,6 +15,7 @@ import {
 	sanitizeIdentityName,
 } from "../core/session-identity.ts";
 import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 
 export interface IdentityHost {
 	capabilities(): EffectiveCapabilities | undefined;
@@ -34,50 +35,14 @@ const AgentNameParams = Type.Object({
 	name: Type.String({ minLength: 1, maxLength: 32, description: "A short personal handle, separate from persona and role." }),
 });
 
-type SessionManagerCompat = {
-	getSessionId?: () => string;
-	getHeader?: () => { id?: string } | null;
-	getBranch?: () => readonly unknown[];
-	getEntries?: () => readonly unknown[];
-};
-
-function sessionManager(ctx: ExtensionContext): SessionManagerCompat {
-	return (ctx as ExtensionContext & { sessionManager?: SessionManagerCompat }).sessionManager ?? {};
-}
-
-/** Read the real session id when available. Process fallback is intentionally start-only. */
-function readSessionId(ctx: ExtensionContext, allowProcessFallback: boolean): string | undefined {
-	const manager = sessionManager(ctx);
+/** Pi 1.4 supplies both methods. A failed host read is unavailable, never a different owner or branch. */
+function readSession(ctx: ExtensionContext): { id: string; entries: readonly SessionEntry[] } | undefined {
 	try {
-		const id = manager.getSessionId?.();
-		if (typeof id === "string" && id.trim()) return id;
+		const id = ctx.sessionManager.getSessionId();
+		return id.trim() ? { id, entries: ctx.sessionManager.getBranch() } : undefined;
 	} catch {
-		/* Compatibility with light-weight session-manager test doubles. */
+		return undefined;
 	}
-	try {
-		const id = manager.getHeader?.()?.id;
-		if (typeof id === "string" && id.trim()) return id;
-	} catch {
-		/* Compatibility with light-weight session-manager test doubles. */
-	}
-	return allowProcessFallback ? `process-${process.pid}` : undefined;
-}
-
-function readEntries(ctx: ExtensionContext): readonly unknown[] {
-	const manager = sessionManager(ctx);
-	try {
-		const branch = manager.getBranch?.();
-		if (Array.isArray(branch)) return branch;
-	} catch {
-		/* Fall through to getEntries when a mock or older host has no branch reader. */
-	}
-	try {
-		const entries = manager.getEntries?.();
-		if (Array.isArray(entries)) return entries;
-	} catch {
-		/* Missing persistence only means there is no stored chosen identity to restore. */
-	}
-	return [];
 }
 
 function setIdentityStatus(ctx: ExtensionContext, name: string): void {
@@ -90,9 +55,7 @@ function setIdentityStatus(ctx: ExtensionContext, name: string): void {
 
 function activeTools(pi: ExtensionAPI): readonly string[] {
 	try {
-		const getActiveTools = (pi as unknown as { getActiveTools?: () => string[] }).getActiveTools;
-		const names = getActiveTools?.call(pi);
-		return Array.isArray(names) ? names : [];
+		return pi.getActiveTools();
 	} catch {
 		return [];
 	}
@@ -112,7 +75,7 @@ function messageCustomType(message: AgentMessage): string | undefined {
 function hasInboundPeerRequest(messages: readonly AgentMessage[]): boolean {
 	return messages.some((message) => {
 		const customType = messageCustomType(message);
-		return customType === "exocom_received" || customType === "exocom-inbound" || customType === "pi-persona:exocom-inbound";
+		return customType === "exocom_received";
 	});
 }
 
@@ -137,39 +100,41 @@ function identityReceipt(name: string, changed: boolean): string {
 
 export function installIdentity(pi: ExtensionAPI, host: IdentityHost): SessionIdentity {
 	let currentSessionId: string | undefined;
-	let currentName = provisionalIdentityName(`process-${process.pid}`);
+	let currentName = "unavailable";
 	let currentChosen = false;
-	let currentSessionIsFallback = false;
-	let started = false;
+	const unavailable = (ctx: ExtensionContext): void => {
+		currentSessionId = undefined;
+		currentName = "unavailable";
+		currentChosen = false;
+		setIdentityStatus(ctx, currentName);
+	};
+	const selectSession = (session: NonNullable<ReturnType<typeof readSession>>): void => {
+		if (currentSessionId === session.id) return;
+		const stored = findStoredIdentity(session.entries, session.id, host.reservedNames());
+		currentSessionId = session.id;
+		currentName = stored ?? provisionalIdentityName(session.id);
+		currentChosen = stored !== undefined;
+	};
 
 	const identity: SessionIdentity = {
 		start(ctx) {
-			const detectedSessionId = readSessionId(ctx, false);
-			const sessionId = detectedSessionId ?? readSessionId(ctx, true)!;
-			if (started && currentSessionId === sessionId) {
-				setIdentityStatus(ctx, currentName);
-				return;
-			}
-			currentSessionId = sessionId;
-			currentSessionIsFallback = detectedSessionId === undefined;
-			const stored = findStoredIdentity(readEntries(ctx), sessionId, host.reservedNames());
-			currentName = stored ?? provisionalIdentityName(sessionId);
-			currentChosen = stored !== undefined;
-			started = true;
+			const session = readSession(ctx);
+			if (!session) { unavailable(ctx); return; }
+			selectSession(session);
 			setIdentityStatus(ctx, currentName);
 		},
 
 		rename(raw, ctx) {
 			const name = sanitizeIdentityName(raw, host.reservedNames());
 			if (!name) throw new Error("identity name is empty, unsafe, generic, or reserved by a persona/agent");
-			const sessionId = readSessionId(ctx, false) ?? (currentSessionIsFallback ? undefined : currentSessionId);
-			if (!sessionId) throw new Error("identity session is unavailable");
-			if (currentChosen && currentSessionId === sessionId && currentName === name) return currentName;
+			const session = readSession(ctx);
+			if (!session) { unavailable(ctx); throw new Error("identity session is unavailable"); }
+			selectSession(session);
+			if (currentChosen && currentName === name) return currentName;
 
 			// Persistence comes first. A failed append therefore cannot leave memory or telemetry
 			// claiming a name that is absent from the session history.
-			pi.appendEntry(IDENTITY_ENTRY_CUSTOM_TYPE, makeIdentityEntry(sessionId, name));
-			currentSessionId = sessionId;
+			pi.appendEntry(IDENTITY_ENTRY_CUSTOM_TYPE, makeIdentityEntry(session.id, name));
 			currentName = name;
 			currentChosen = true;
 			setIdentityStatus(ctx, currentName);
@@ -202,17 +167,18 @@ export function installIdentity(pi: ExtensionAPI, host: IdentityHost): SessionId
 			return { content: [{ type: "text", text }], details: { name, changed } };
 		},
 		renderCall(args, theme) {
-			const name = compactInlineText(args.name, { maxChars: 32 }) || "?";
+			const name = compactInlineText(args.name ?? "", { maxChars: 32 }) || "?";
 			return new Text(`${theme.fg("toolTitle", theme.bold("Agent Name "))}${theme.fg("accent", name)}`, 0, 0);
 		},
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, context) {
+			const failed = context?.isError ?? result.isError ?? false;
 			const details = result.details as unknown as { name?: unknown; changed?: unknown } | undefined;
-			const name = typeof details?.name === "string" ? compactInlineText(details.name, { maxChars: 32 }) : "";
-			const first = result.content.find((item) => item.type === "text");
-			const rendered = name
-				? identityReceipt(name, details?.changed !== false)
-				: first?.type === "text" ? compactInlineText(first.text, { maxChars: 96 }) : "Agent name failed";
-			return new Text(theme.fg(name ? (expanded ? "toolOutput" : "accent") : "error", rendered), 0, 0);
+			const name = !failed && typeof details?.name === "string" ? details.name : "";
+			// Failures share the one literal renderer (error heading, bounded preview, full expanded
+			// text); a chosen handle is a one-line purpose receipt collapsed and the complete literal
+			// receipt expanded.
+			if (!name || expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			return new Text(theme.fg("accent", compactInlineText(identityReceipt(name, details?.changed !== false), { maxChars: 80 })), 0, 0);
 		},
 	});
 
@@ -228,7 +194,7 @@ export function installIdentity(pi: ExtensionAPI, host: IdentityHost): SessionId
 			inboundPeer: hasInboundPeerRequest(event.messages),
 			...(namingTool === undefined ? {} : { namingTool }),
 		};
-		const content = buildIdentityContext(currentChosen, contextOptions);
+		const content = currentSessionId === undefined ? undefined : buildIdentityContext(currentChosen, contextOptions);
 		if (content === undefined) return { messages };
 		const contextMessage = {
 			role: "custom" as const,

package/src/extension/persona-model-settings.ts

@@ -4,10 +4,11 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelsRefreshResult } from "@earendil-works/pi-ai";
 
 import type { ModelParticipant } from "../persona/model-participants.ts";
 import { compactInlineText } from "../ui/presentation.ts";
-import { ModelPicker, orderModelRefs } from "../ui/model-picker.ts";
+import { ModelPicker, orderModelRefs, type ModelPickerMetadata } from "../ui/model-picker.ts";
 
 export interface PersonaModelOwner {
 	name: string;
@@ -34,6 +35,8 @@ export interface PersonaModelSettingsDeps {
 	write: (owner: string, patch: Record<string, string | null>) => void;
 	/** Session/persona liveness guard supplied by the extension. */
 	isCurrent?: (ctx: ExtensionContext) => boolean;
+	/** Refresh adapter supplied by the catalog owner to keep derived discovery caches consistent. */
+	refreshCatalog?: (signal: AbortSignal) => Promise<ModelsRefreshResult | undefined>;
 }
 
 const DONE = "Done";
@@ -124,7 +127,7 @@ export async function openPersonaModelSettings(ctx: ExtensionContext, deps: Pers
 			return;
 		}
 		if (choice === REFRESH) {
-			if (!(await refreshCatalog(ctx, isCurrent))) return;
+			if (!(await refreshCatalog(ctx, isCurrent, deps.refreshCatalog))) return;
 			continue;
 		}
 		if (otherAssignmentsOption && choice === otherAssignmentsOption) {
@@ -167,20 +170,26 @@ export async function openPersonaModelSettings(ctx: ExtensionContext, deps: Pers
 		}
 		if (action !== actions[0]) continue;
 
-		const modelRefs = availableModelRefs(ctx);
+		const models = availableModels(ctx);
+		const modelRefs = orderModelRefs(models.map((model) => `${model.provider}/${model.id}`), ctx.model?.provider);
 		if (modelRefs.length === 0) {
 			ctx.ui.notify("No authenticated models are available. Use /login, then choose Set or change again; saved assignments were kept.", "warning");
 			continue;
 		}
+		const current = rows[rowIndex]!;
 		const modelTitle = compactInlineText(
-			`Model for ${participant.label} · current: ${participant.model ?? "none"} (${participant.source})`,
+			`Model for ${participant.label} · current: ${current.model} (${current.source})`,
 			{ maxChars: 180 },
 		);
 		let modelChoice: string | undefined;
 		try {
 			modelChoice = ctx.mode === "tui"
 				? await ctx.ui.custom<string | undefined>(
-						(tui, theme, _keybindings, done) => new ModelPicker(tui, theme, modelTitle, modelRefs, ctx.model?.provider, done),
+						(tui, theme, keybindings, done) => new ModelPicker(tui, theme, modelTitle, modelRefs, ctx.model?.provider, done, {
+							models,
+							...(current.currentRef !== undefined ? { currentRef: current.currentRef } : {}),
+							...(keybindings ? { keybindings } : {}),
+						}),
 						{ overlay: false },
 					)
 				: await select(ctx, modelTitle, modelRefs);
@@ -199,7 +208,7 @@ function participantRow(
 	saved: Readonly<Record<string, string>>,
 	staged: Readonly<Record<string, string | null>>,
 	index: number,
-): { option: string } {
+): { option: string; model: string; source: string; currentRef?: string } {
 	const hasPendingDirect = Object.prototype.hasOwnProperty.call(staged, participant.key);
 	const pendingDirect = hasPendingDirect ? staged[participant.key] : undefined;
 	const hasPendingShared = participant.key !== participant.agent && Object.prototype.hasOwnProperty.call(staged, participant.agent);
@@ -208,22 +217,30 @@ function participantRow(
 	const sharedSaved = participant.key !== participant.agent ? effectiveSavedValue(participant.agent, saved, staged) : undefined;
 	let model: string;
 	let source: string;
+	let currentRef: string | undefined;
 	if (typeof pendingDirect === "string") {
 		model = pendingDirect;
+		currentRef = pendingDirect;
 		source = "assignment (pending)";
 	} else if (pendingDirect === null) {
 		if (sharedSaved) {
 			model = sharedSaved;
+			currentRef = sharedSaved;
 			source = "shared assignment (pending fallback)";
 		} else {
 			model = "resolve lower precedence next run";
 			source = "pending reset";
 		}
+	} else if (typeof pendingShared === "string" && !directSaved && participant.source !== "inline") {
+		model = pendingShared;
+		currentRef = pendingShared;
+		source = "shared assignment (pending)";
 	} else if (hasPendingShared && pendingShared === null && !directSaved) {
 		model = "resolve lower precedence next run";
 		source = "shared reset pending";
 	} else {
 		model = participant.model ?? "none";
+		currentRef = participant.model;
 		source = participant.source;
 	}
 	const sharedNote = !directSaved && sharedSaved
@@ -235,7 +252,8 @@ function participantRow(
 		: hasPendingShared && pendingShared === null ? " · shared reset pending"
 			: "";
 	const option = `${index + 1}. ${safeInline(participant.label, 80)} · ${safeInline(model, 90)} (${safeInline(source, 24)})${sharedNote}${pendingNote}`;
-	return { option: compactInlineText(option, { maxChars: 200 }) };
+	return { option: compactInlineText(option, { maxChars: 200 }), model, source,
+		...(currentRef !== undefined ? { currentRef } : {}) };
 }
 
 function effectiveSavedValue(
@@ -247,20 +265,20 @@ function effectiveSavedValue(
 	return saved[key];
 }
 
-function availableModelRefs(ctx: ExtensionContext): string[] {
+function availableModels(ctx: ExtensionContext): ModelPickerMetadata[] {
 	try {
-		const unique = new Set<string>();
+		const unique = new Map<string, ModelPickerMetadata>();
 		for (const model of ctx.modelRegistry.getAvailable()) {
 			if (typeof model.provider !== "string" || !model.provider.trim() || typeof model.id !== "string" || !model.id.trim()) continue;
-			unique.add(`${model.provider}/${model.id}`);
+			unique.set(`${model.provider}/${model.id}`, model);
 		}
-		return orderModelRefs([...unique], ctx.model?.provider);
+		return [...unique.values()];
 	} catch {
 		return [];
 	}
 }
 
-async function refreshCatalog(ctx: ExtensionContext, isCurrent: () => boolean): Promise<boolean> {
+async function refreshCatalog(ctx: ExtensionContext, isCurrent: () => boolean, refresh?: PersonaModelSettingsDeps["refreshCatalog"]): Promise<boolean> {
 	if (!ctx.modelRegistry.refresh) {
 		ctx.ui.notify("This Pi host cannot explicitly refresh the model catalog; existing assignments were kept.", "warning");
 		return true;
@@ -268,7 +286,7 @@ async function refreshCatalog(ctx: ExtensionContext, isCurrent: () => boolean):
 	const deadline = AbortSignal.timeout(20_000);
 	const signal = ctx.signal ? AbortSignal.any([ctx.signal, deadline]) : deadline;
 	try {
-		const result = await ctx.modelRegistry.refresh({ signal });
+		const result = await (refresh ? refresh(signal) : ctx.modelRegistry.refresh({ signal }));
 		if (ctx.signal?.aborted) {
 			ctx.ui.notify("Model catalog refresh was cancelled; saved assignments were kept.", "info");
 			return false;

package/src/extension/results.ts

@@ -0,0 +1,136 @@
+/** Session-native terminal archive ownership. Owners are frozen before asynchronous work starts. */
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { TerminalResultArchive } from "../results/archive.ts";
+import { resultReceipt, type ResultReceipt } from "../results/retrieval.ts";
+import type { TerminalResultInput, TerminalStatus } from "../results/types.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import { type AsyncRun, type AsyncRunTracker } from "../engine/async.ts";
+
+export interface CaptureMetadata {
+	originRunId?: string;
+	label?: string;
+	status?: TerminalStatus;
+	partial?: string;
+}
+export type CaptureResult = (origin: string, result: AgentResult, meta?: CaptureMetadata) => ResultReceipt;
+interface Owner {
+	id: string;
+	file: string | undefined;
+	manager: ExtensionContext["sessionManager"];
+	generation: string;
+	archive: TerminalResultArchive;
+}
+
+export class SessionResults {
+	private owner: Owner | undefined;
+	private disposed = false;
+	private readonly captures = new Map<AsyncRun, CaptureResult>();
+	private readonly detach: Array<() => void> = [];
+
+	constructor(privateApi: Pick<ExtensionAPI, "appendEntry">) {
+		this.append = (type, data) => privateApi.appendEntry(type, data);
+	}
+	private readonly append: (type: string, data: unknown) => void;
+
+	activate(ctx: ExtensionContext): TerminalResultArchive {
+		// A session_shutdown revokes the previous owner; a later session_start in the same process
+		// (the documented multi-activation lifecycle) starts a FRESH owner, never a zombie.
+		if (this.disposed) {
+			this.disposed = false;
+			for (const off of this.detach.splice(0)) {
+				try { off(); } catch { /* teardown must not block a new activation */ }
+			}
+		}
+		const manager = ctx.sessionManager;
+		// A context without a session manager (e.g. --no-session / UI-less runs) still gets an
+		// honest MEMORY-ONLY owner: bounded runtime retention, no persistence claims.
+		const id = manager ? manager.getSessionId() : `memory:${randomUUID()}`;
+		const file = manager ? manager.getSessionFile() : undefined;
+		const previous = this.owner;
+		// File identity owns persisted history. A memory owner additionally needs manager identity.
+		if (previous && previous.id === id && previous.file === file && (file !== undefined || previous.manager === manager)) return previous.archive;
+		const generation = randomUUID();
+		// Freeze all-branch history now. A storage read failure belongs to archive accounting,
+		// not to the ordinary work being launched; never retry through a mutable future context.
+		let entries: readonly unknown[] = [];
+		let historyError: unknown;
+		let historyFailed = false;
+		try { entries = manager ? manager.getEntries() : []; } catch (error) { historyError = error; historyFailed = true; }
+		const owner: Owner = {
+			id, file, manager, generation,
+			archive: new TerminalResultArchive({
+				entries: () => { if (historyFailed) throw historyError; return entries; },
+				persistent: file !== undefined,
+				append: (type, data) => {
+					if (this.owner !== owner || (manager && (manager.getSessionId() !== id || manager.getSessionFile() !== file))) {
+						throw new Error("Terminal archive owner was revoked");
+					}
+					this.append(type, data);
+				},
+			}),
+		};
+		this.owner = owner;
+		return owner.archive;
+	}
+
+	get archive(): TerminalResultArchive | undefined { return this.owner?.archive; }
+
+	/** Bind at logical creation, not at settlement through lastCtx. Each scope has its own origin namespace. */
+	bind(scope: string): CaptureResult {
+		const owner = this.owner;
+		const prefix = `${owner?.generation ?? randomUUID()}:${scope}`;
+		return (origin, result, meta = {}) => {
+			if (!owner || this.owner !== owner || (owner.manager && (owner.manager.getSessionId() !== owner.id || owner.manager.getSessionFile() !== owner.file))) {
+				return { warning: "Terminal report not archived: owning session activation is no longer current." };
+			}
+			const status = meta.status ?? (result.ok ? "done" : result.failureKind === "abort" ? "stopped" : "failed");
+			const output = result.output.trim() ? result.output : meta.partial?.trim() ? meta.partial : result.error ?? "(no output)";
+			const input: TerminalResultInput = {
+				originKey: `${prefix}:${origin}`, status, agent: result.agent.slice(0, 128), body: output,
+				provenance: result.output.trim() ? "result-output" : meta.partial?.trim() ? "partial-output" : result.error ? "error" : "result-output",
+				...(meta.originRunId ? { originRunId: meta.originRunId.slice(0, 128) } : {}),
+				...(meta.label ? { label: meta.label.slice(0, 256) } : {}),
+				...(result.modelUsed ? { model: result.modelUsed.slice(0, 512) } : {}),
+				...(result.thinkingRequested ? { thinkingRequested: result.thinkingRequested } : {}),
+				...(result.thinkingEffective ? { thinkingEffective: result.thinkingEffective } : {}),
+				...(result.error ? { error: result.error.slice(0, 2048) } : {}),
+				usage: { input: result.usage.input, output: result.usage.output,
+					...(result.usage.cacheRead !== undefined ? { cacheRead: result.usage.cacheRead } : {}),
+					...(result.usage.cacheWrite !== undefined ? { cacheWrite: result.usage.cacheWrite } : {}),
+					...(result.usage.cost !== undefined ? { cost: result.usage.cost } : {}),
+					...(result.usage.turns !== undefined ? { turns: result.usage.turns } : {}),
+				},
+			};
+			try { return resultReceipt(owner.archive.save(input)); }
+			catch { return { warning: "Terminal report not archived: storage callback failed." }; }
+		};
+	}
+
+	/** Register before the ordinary completion listener. onCreate precedes even a synchronous thunk failure. */
+	track(tracker: AsyncRunTracker): void {
+		this.detach.push(tracker.onCreate((run) => this.captures.set(run, this.bind("tracker"))));
+		this.detach.push(tracker.onComplete((run) => {
+			const capture = this.captures.get(run);
+			this.captures.delete(run);
+			if (!capture) return;
+			const result = run.result ?? { agent: run.agent, output: "", usage: emptyUsage(), ok: false, ...(run.error ? { error: run.error } : {}) };
+			run.resultReceipt = capture(run.id, result, {
+				originRunId: run.id, ...(run.label ? { label: run.label } : {}),
+				status: run.status === "running" ? "failed" : run.status,
+				partial: run.progress.output,
+			});
+			if (run.result) run.result.resultReceipt = { ...run.resultReceipt };
+		}));
+	}
+
+	dispose(): void {
+		this.disposed = true;
+		this.owner = undefined;
+		this.captures.clear();
+		for (const off of this.detach.splice(0)) {
+			try { off(); } catch { /* best-effort teardown */ }
+		}
+	}
+}

package/src/extension/shared.ts

@@ -9,8 +9,6 @@ import { boundCompletionSurface, MAX_COMPLETION_REPORT_CHARS } from "../engine/a
 import type { InboundDecision } from "../exocom/inbound.ts";
 import { EXOCOM } from "../exocom/limits.ts";
 import type { DisplayPeer, ExocomInboundResult } from "../exocom/plane.ts";
-import type { DelegateView } from "../tools/delegate.ts";
-import type { AgentNodeStatus } from "../ui/agent-tree.ts";
 import { compactInlineText } from "../ui/presentation.ts";
 
 const PI_PERSONA_TOOL_ERROR = "__piPersonaToolError";
@@ -113,10 +111,20 @@ export function exocomInboundBatchSize(items: readonly string[]): number {
 
 export const EXOCOM_INBOX_MAX = 3 * EXOCOM.SENDER_MAX_MSGS;
 
-export function agentNodeStatusForDelegate(view: Pick<DelegateView, "running" | "ok"> & { failureKind?: DelegateView["failureKind"] }): AgentNodeStatus {
-	if (view.running) return "running";
-	if (view.failureKind === "abort") return "stopped";
-	return view.ok ? "done" : "failed";
+/** A headless session (`pi -p`): a launching tool joins its run before returning, because nothing would
+ *  deliver a follow-up once the process exits. Interactive (TUI/RPC) sessions launch and return a receipt. */
+export function isInline(ctx: { hasUI?: boolean }): boolean {
+	return ctx.hasUI !== true;
+}
+
+/**
+ * The closing advice of a `timer`/`monitor` arm result. Headless `pi -p` exits when the turn settles,
+ * so a wake lands only if it fires first: ending the turn to wait for one would drop it.
+ */
+export function armWakeAdvice(ctx: { hasUI?: boolean } | undefined, noun: string, pending: string, interactive: string): string {
+	return ctx?.hasUI === false
+		? `Headless pi -p: the process exits when this turn settles, so this ${noun} wakes you only if it fires before then. Do not end your turn expecting it; finish inline, or report the ${pending} as pending.`
+		: interactive;
 }
 
 export function sendPersonaFollowUp(
@@ -164,6 +172,23 @@ export function shouldReportHeartbeatFailure(consecutiveFailures: number): boole
 	return consecutiveFailures === 1 || consecutiveFailures % 10 === 0;
 }
 
+/** One bounded, terminal-safe cause line for an operator toast. Error `message`s interpolate raw
+ *  provider/filesystem text (multi-line, ANSI-capable) — every toast that embeds one goes through
+ *  this so the notification stays a single sanitized line. The untruncated text keeps its other
+ *  surface (stderr, /doctor, the tool result). */
+export function toastCause(message: string, maxChars = 160): string {
+	return compactInlineText(message, { maxChars });
+}
+
+/** A fair prefix of a name list, bounded for one toast line: `"a, b, c, +N more"`. Discovery
+ *  reports (collisions, seeded files, installed personas) grow with the user's own directory, so
+ *  an unbounded `join(", ")` would let the toast wrap over many terminal rows. */
+export function compactNameList(names: readonly string[], max = 8): string {
+	const clean = names.map((name) => compactInlineText(name, { maxChars: 80 })).filter((name) => name.length > 0);
+	if (clean.length <= max) return clean.join(", ");
+	return `${clean.slice(0, max).join(", ")}, +${clean.length - max} more`;
+}
+
 export function fenceIntercomOutcome(out: { text: string; details: { action: string; messages?: unknown[] } }, fence: (t: string) => string): string {
 	const untrusted = out.details.action === "inbox" && (out.details.messages?.length ?? 0) > 0;
 	return untrusted ? fence(out.text) : out.text;
@@ -171,5 +196,5 @@ export function fenceIntercomOutcome(out: { text: string; details: { action: str
 
 export function coachingDisabledHint(personaName: string | undefined): string {
 	const who = sanitizeDisplayLabel(personaName ?? "default", "default");
-	return `(coaching is OFF for persona "${who}" — sub-agents get no contact_supervisor tool, so the message bus is empty. To just watch or redirect them use action "peek"/"steer"; to exchange messages, add \`coaching: true\` or switch to a coaching persona.)`;
+	return `(coaching is OFF for persona "${who}" — sub-agents get no contact_supervisor tool, so the message bus is empty. To redirect one use action "steer"; results return on their own. To exchange messages, add \`coaching: true\` or switch to a coaching persona.)`;
 }