@aeondave/pi-persona 1.17.0 → 1.17.3

package/src/extension.ts

@@ -11,16 +11,18 @@
  * isolation; see docs/ARCHITECTURE.md).
  */
 
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
 
 import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { registerSessionCards } from "./ui/session-cards.ts";
 
 import type { AgentConfig } from "./agents/agent.ts";
 import { installBridge, isBridgeMode } from "./bridge.ts";
 import { resolveConfig } from "./core/config.ts";
+import { resolvePersonaConfig } from "./core/settings.ts";
 import { type ContractDef, installedContractNames } from "./core/contract.ts";
 import { type DataRootMigrationResult, migrateLegacyDataRoot } from "./core/data-root.ts";
 import {
@@ -34,11 +36,14 @@ import {
 	type SpineLegacyResult,
 	type SpineLegacySelection,
 } from "./core/seed.ts";
-import { buildDelegationBrief } from "./core/brief.ts";
+import { type BriefFlow, buildDelegationBrief } from "./core/brief.ts";
 import { canCallTool, canDelegateTo, canFanOut, type RunLimits } from "./core/capabilities.ts";
 import { fenceUntrusted } from "./core/fence.ts";
 import { sanitizeDisplayLabel } from "./core/display-label.ts";
-import { DelegationNudge, PersistenceNudge } from "./core/nudge.ts";
+import { DelegationNudge, orderByMention, PersistenceNudge, PollGuard, renderNudgeModels, renderNudgeRoster } from "./core/nudge.ts";
+import { orderModelCandidates, recommendModels, shortlistModels } from "./core/model-catalog.ts";
+import { summarizeFailure } from "./ui/failure-summary.ts";
+import { modelCandidateDetails, modelCostTiers, type ModelCostMetadata } from "./core/model-tier.ts";
 import { installedPiVersion, MIN_PI_VERSION, satisfiesFloor } from "./core/pi-compat.ts";
 import { type EngineAdapterBroker } from "./engine/adapter.ts";
 import { SupervisorBroker } from "./extension/broker-host.ts";
@@ -52,7 +57,6 @@ import {
 	type PendingAsk,
 } from "./extension/shared.ts";
 export {
-	agentNodeStatusForDelegate,
 	boundExocomInboundBatch,
 	canDeliverPersonaNotification,
 	canonicalExocomTelemetryTargets,
@@ -77,25 +81,31 @@ export {
 } from "./extension/shared.ts";
 import { installExocom } from "./exocom/install.ts";
 import { installIdentity } from "./extension/identity.ts";
+import { registerPersonaSettings } from "./extension/persona-settings.ts";
+import { openPersonaModelSettings } from "./extension/persona-model-settings.ts";
+import { collectCompanionSettings } from "./extension/companion-settings.ts";
 import { parseExocomArgv } from "./exocom/activation.ts";
 import { formatLedgerStatus } from "./exocom/status.ts";
 import { registerDelegateTool } from "./tools/delegate-tool.ts";
-import { registerIntercomTool } from "./tools/intercom-tool.ts";
+import { describeRuns, registerIntercomTool } from "./tools/intercom-tool.ts";
 import { registerTimerTool } from "./tools/timer.ts";
-import { registerMonitorTool } from "./tools/monitor.ts";
+import { registerMonitorTool, renderMonitorLog } from "./tools/monitor.ts";
+import { MonitorArchive } from "./monitor/archive.ts";
 import { createMonitorSession, type MonitorSession } from "./monitor/session.ts";
+import { createBackgroundRuns, type TrackedRun } from "./tools/background-run.ts";
 import { registerCouncilTool } from "./tools/council.ts";
 import { registerFlowTool } from "./tools/flow.ts";
 import { registerModelsTool } from "./tools/models.ts";
-import { type AsyncRun, AsyncRunTracker, boundCompletionSurface, buildCheckIn, buildPeekAlert, buildPeekDigest, buildRetentionOverflowNote, IdleCoalescingNotifier, PeekWatcher, renderCompletion, STALL_FLAG_MS } from "./engine/async.ts";
+import { type AsyncRun, AsyncRunTracker, boundCompletionSurface, buildCheckIn, buildPeekDigest, buildRetentionOverflowNote, IdleCoalescingNotifier, PeekWatcher, renderCompletion, STALL_FLAG_MS } from "./engine/async.ts";
 import { emptyUsage, type ToolEvent } from "./engine/stream.ts";
 import { brokerEndpoint } from "./bus/broker/paths.ts";
 import { InProcessBus } from "./bus/inproc.ts";
 import { loadContracts, loadDefinitions, loadPresets, loadTeams, type LoadResult, type ScopedDir } from "./loader.ts";
-import { type FlowSpec, flowHash, parseFlow, verifyFlowRefs } from "./orchestration/flow.ts";
-import { journalFileName, journalWriter, readJournal } from "./orchestration/flow-journal.ts";
+import { type FlowSpec, flowRunHash, parseFlow, verifyFlowRefs } from "./orchestration/flow.ts";
+import { clearJournal, journalFileName, journalWriter, readJournal } from "./orchestration/flow-journal.ts";
 import { runFlow } from "./orchestration/flow-run.ts";
-import type { FlowOutcome } from "./orchestration/flow-run.ts";
+import { Semaphore } from "./orchestration/parallel.ts";
+import { flowDisposition, type FlowOutcome } from "./orchestration/flow-run.ts";
 import { type RosterMember, roleHint, rosterNodeKeys, rosterSpec } from "./orchestration/roster.ts";
 import type { AgentProgress, AgentStatus, SteerFn } from "./orchestration/sdk.ts";
 import { knownParams, strategyNames } from "./orchestration/strategy.ts";
@@ -110,27 +120,27 @@ import {
 } from "./persona/model-participants.ts";
 import { expandCouncilPreset, resolveCouncilInvocation, type OrchestrationGrammar, type Persona } from "./persona/persona.ts";
 import { bundledSpinePath, bundledWorkerSpinePath, readSpineFile, resolveSpine, type SpineSources } from "./persona/spine.ts";
-import { readLastPersona, writeLastPersona } from "./persona/state.ts";
+import { migratePersonaSettings, patchPersonaSettings, readPersonaSettings, type PersonaSettings } from "./persona/settings-store.ts";
 import { type AgentKind as TelemetryAgentKind, type AgentStatus as TelemetryAgentStatus } from "./telemetry/contract.ts";
 import { TelemetryProducer, type TelemetryAgentInput } from "./telemetry/producer.ts";
 import {
 	type PersonaConfigStore,
 	personaModels,
-	readPersonaConfigs,
 	withPersonaModels,
-	writePersonaConfigs,
 } from "./persona/config-store.ts";
 import { shortModel } from "./tools/delegate.ts";
 import { formatInbox } from "./tools/intercom.ts";
 import { renderTimerFire, TimerScheduler, type TimerEntry } from "./core/timer.ts";
 import { AgentOverlay } from "./ui/agent-overlay.ts";
-import { type AddNodeInput, type AgentNode, type AgentTreeChange, AgentTree, type AgentNodeStatus, deriveWaitingNodeIds, isQueuedMarker, progressPatch, renderAgentTreeSummary } from "./ui/agent-tree.ts";
+import { type AddNodeInput, type AgentNode, type AgentNodePatch, type AgentTreeChange, AgentTree, type AgentNodeStatus, deriveWaitingNodeIds, isQueuedMarker, isWakeSource, progressPatch, renderAgentTreeSummary } from "./ui/agent-tree.ts";
+import { WakeRows, type WakeRowChange } from "./ui/wake-rows.ts";
 import { LiveClock } from "./ui/live-clock.ts";
-import { filterModels, ModelPicker, orderModelRefs } from "./ui/model-picker.ts";
-import { compactInlineText, compactVisibleText, sanitizeTerminalText } from "./ui/presentation.ts";
+import { filterModels, ModelPicker, orderModelRefs, type ModelPickerMetadata } from "./ui/model-picker.ts";
+import { compactInlineText, gateReviewText } from "./ui/presentation.ts";
+import { compactWidget } from "./ui/compact-widget.ts";
 import { ChildUsageLedger, formatPersonaCostStatus, formatUsage, PERSONA_COST_STATUS_KEY } from "./ui/usage.ts";
 
-const RUN_LIMITS: RunLimits = {
+export const RUN_LIMITS: RunLimits = {
 	// A generous anti-runaway backstop, not a council-size cap: a declared ensemble
 	// (e.g. 9 members × several rounds) must fit; the token budget is the real cost guard.
 	maxChildren: 64,
@@ -173,6 +183,8 @@ interface CommandResultEntry {
 	label: string;
 	content: string;
 	ok: boolean;
+	/** A flow that paused at a rejected checkpoint: not a failure, so it is titled "stopped". */
+	stoppedAtGate?: string;
 	failureKind?: FailureKind;
 	error?: string;
 }
@@ -183,10 +195,20 @@ interface NudgeEntry {
 
 interface CheckInEntry {
 	content: string;
+	kind?: "routine" | "stall";
+}
+
+interface RunFailureEntry {
+	id: string;
+	label: string;
+	agent: string;
+	model?: string;
+	durationMs?: number;
+	error: string;
 }
 
 /**
- * Keep the immediate operator-facing settlement toast and the semantic completion delivery on one
+ * Keep the immediate operator-facing settlement feedback and the semantic completion delivery on one
  * path. A supervisor-requested abort is terminal, but it is not an execution error: the tracker
  * classifies it as `stopped`, so the UI reports it at info level while the completion still reaches
  * the supervisor exactly once through the normal notifier.
@@ -195,31 +217,51 @@ export function announceAsyncRunSettlement(
 	run: AsyncRun,
 	notify: ((message: string, level: "info" | "error") => void) | undefined,
 	enqueue: (run: AsyncRun) => void,
+	presentFailure?: (run: AsyncRun) => void,
 ): void {
 	const id = compactInlineText(run.id, { maxChars: 80 }) || "run";
 	const agent = compactInlineText(run.label ?? run.agent, { maxChars: 80 }) || compactInlineText(run.agent, { maxChars: 80 }) || "agent";
 	try {
 		if (run.status === "done") notify?.(`async run ${id} (${agent}) completed`, "info");
 		else if (run.status === "stopped") notify?.(`async run ${id} (${agent}) stopped`, "info");
-		else if (run.status === "failed") notify?.(`async run ${id} (${agent}) failed: ${compactInlineText(run.error ?? "(no detail)", { maxChars: 240 })}`, "error");
+		else if (run.status === "failed") {
+			const toast = () => notify?.(`async run ${id} (${agent}) failed: ${summarizeFailure(run.error ?? "(no detail)")}`, "error");
+			if (presentFailure) {
+				try { presentFailure(run); }
+				catch { toast(); }
+			} else toast();
+		}
 	} catch {
 		// Cosmetic notification only: a broken UI must never swallow the terminal report.
 	}
 	enqueue(run);
 }
 
+/** An operator-run `/flow` or `/orchestrate` result as the supervisor's NEXT turn sees it: one header
+ *  line, then the output fenced as data (it is sub-agent text) and bounded like a completion. */
+export function renderOperatorResult(label: string, output: string, ok: boolean, stoppedAtGate?: string): string {
+	const disposition = flowDisposition({ ok, stoppedAtGate });
+	const state = disposition === "done" ? "finished" : disposition === "stopped" ? `stopped at checkpoint "${compactInlineText(stoppedAtGate ?? "", { maxChars: 64 })}"` : "failed";
+	return boundCompletionSurface(
+		`[pi-persona] The operator ran ${compactInlineText(label, { maxChars: 96 })} (${state}); its output:\n${fenceUntrusted(output)}`,
+		"operator result truncated at 12000 characters; only the operator can see the rest (ask them to paste what you need)",
+	);
+}
+
 /** Agents actually IN FLIGHT: a RUNNING node with no children of its own. "Has a parent" is not the
  *  same as "is an agent" — a flow phase is a container that also has a parent, a root-level `async:`
  *  run is a leaf that has none, and a settled leg still sits in the tree until its root is torn
- *  down. Exported for direct unit testing (mirrors `listPeersForGroup` above). */
-export function inFlightAgentCount(nodes: ReadonlyArray<{ id: string; parentId?: string | undefined; status: AgentNodeStatus }>): number {
+ *  down. A fan-out's `delegate` header row is a container even in the beat after its last leg
+ *  left, so it never counts. A wake source (a timer or monitor row) is not an agent at all and
+ *  never counts, running or not. Exported for direct unit testing (mirrors `listPeersForGroup` above). */
+export function inFlightAgentCount(nodes: ReadonlyArray<{ id: string; parentId?: string | undefined; status: AgentNodeStatus; kind?: NonNullable<AgentNode["kind"]> }>): number {
 	const parents = new Set<string>();
 	for (const node of nodes) {
 		if (node.parentId !== undefined) parents.add(node.parentId);
 	}
 	let count = 0;
 	for (const node of nodes) {
-		if (node.status === "running" && !parents.has(node.id)) count++;
+		if (node.status === "running" && node.kind !== "delegate" && !isWakeSource(node) && !parents.has(node.id)) count++;
 	}
 	return count;
 }
@@ -279,99 +321,52 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		return;
 	}
 
-	const config = resolveConfig(process.env);
+	let config = resolveConfig(process.env);
 	if (config.disabled) return;
 	const exocomArgs = parseExocomArgv(options.exocomArgv ?? process.argv);
-	const registerFollowUpRenderer = (customType: "pi-persona" | "exocom_received", label: string): void => {
-		pi.registerMessageRenderer(customType, (message, { expanded, outputPad }, theme) => {
-			const raw = typeof message.content === "string"
-				? message.content
-				: message.content.map((part) => part.type === "text" ? part.text : "[image]").join("\n");
-			const full = sanitizeTerminalText(raw);
-			const preview = compactVisibleText(full, { maxLines: 4, maxLineChars: 100 });
-			const firstLine = full.split("\n", 1)[0] ?? "";
-			// External peer text is data and must never choose our UI chrome. Internal follow-ups own
-			// their first status line; parse only that line and do not turn a healthy "0 failed" red.
-			const isFailure = customType === "pi-persona"
-				&& !/\b0 failed\b/i.test(firstLine)
-				&& /\b(?:failed|failure|error|rejected|unresolved)\b/i.test(firstLine);
-			const titleColor = isFailure ? "error" : customType === "exocom_received" ? "accent" : "success";
-			const title = theme.fg(titleColor, theme.bold(label));
-			if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", full || "(no output)")}`, outputPad, 0);
-			const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
-			return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, outputPad, 0);
-		});
-	};
-	// These follow-ups remain complete in the model context, but the human-facing card starts as a
-	// bounded digest. This is the central progressive-disclosure boundary for async completions and
-	// external peer messages; expanding the card reveals the exact sanitized payload.
-	registerFollowUpRenderer("pi-persona", "pi-persona · update");
-	registerFollowUpRenderer("exocom_received", "exocom · inbound");
-	pi.registerEntryRenderer("pi-persona-result", (entry, { expanded }, theme) => {
-		const data = entry.data as CommandResultEntry;
-		const full = sanitizeTerminalText(data.content || "(no output)");
-		const cause = compactVisibleText(
-			[data.failureKind, data.error].filter((part): part is string => !!part).join(" · "),
-			{ maxLines: 1, maxLineChars: 80 },
-		).text;
-		const status = data.ok ? "complete" : "failed";
-		const label = compactInlineText(data.label, { maxChars: 96 }) || "result";
-		const title = theme.fg(data.ok ? "success" : "error", theme.bold(`${label} · ${status}${!data.ok && cause !== "(no output)" ? ` · ${cause}` : ""}`));
-		if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", full)}`, 0, 0);
-		const preview = compactVisibleText(full, { maxLines: 3, maxLineChars: 100 });
-		const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
-		return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
-	});
-	pi.registerEntryRenderer("pi-persona-nudge", (entry, { expanded }, theme) => {
-		const data = entry.data as NudgeEntry;
-		const full = sanitizeTerminalText(data.content || "⟢ pi-persona · checkpoint");
-		const lines = full.split("\n").map((line) => line.trim()).filter(Boolean);
-		const header = compactInlineText(lines[0]?.replace(/^⟢\s*/, "") ?? "", { maxChars: 96 }) || "pi-persona · checkpoint";
-		const details = lines.slice(1);
-		const title = theme.fg("warning", theme.bold(`⟢ ${header}`));
-		if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", details.join("\n") || "(no detail)")}`, 0, 0);
-		const trigger = details.find((line) => line.startsWith("Trigger:"));
-		const action = details.find((line) => /^(?:Action|Verify|Otherwise):/.test(line));
-		const selected = [trigger, action].filter((line): line is string => line !== undefined);
-		const previewLines = selected.length > 0 ? selected : details.slice(0, 2);
-		const preview = compactVisibleText(previewLines.join("\n"), { maxLines: 2, maxLineChars: 100 });
-		const hasMore = preview.truncated || details.some((line) => !previewLines.includes(line));
-		const hint = hasMore ? `\n${theme.fg("dim", expandDetailHint())}` : "";
-		return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
-	});
-	pi.registerEntryRenderer("pi-persona-status", (entry, { expanded }, theme) => {
-		const data = entry.data as CheckInEntry;
-		const full = sanitizeTerminalText(data.content || "Async activity · routine check-in");
-		const title = theme.fg("accent", theme.bold("pi-persona · async status"));
-		if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", full)}`, 0, 0);
-		// The entry title already labels this as async status. Spend the compact preview on the
-		// aggregate and first run row so the operator sees the selected alias and usage label.
-		const digestLines = full.split("\n").slice(1).filter((line) => line.trim().length > 0);
-		const preview = compactVisibleText(digestLines.slice(0, 2).join("\n") || full, { maxLines: 2, maxLineChars: 140 });
-		const hasMore = preview.truncated || digestLines.length > 2;
-		const hint = hasMore ? `\n${theme.fg("dim", expandDetailHint())}` : "";
-		return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+	registerSessionCards(pi, {
+		detailHint: expandDetailHint,
+		monitorLog: (record) => renderMonitorLog(record, true),
 	});
 	const appendNudgeEntry = (content: string): void => {
 		pi.appendEntry("pi-persona-nudge", { content } satisfies NudgeEntry);
 	};
-	const appendCheckInEntry = (content: string): void => {
-		pi.appendEntry("pi-persona-status", { content } satisfies CheckInEntry);
+	const appendCheckInEntry = (content: string, kind: "routine" | "stall" = "routine"): void => {
+		pi.appendEntry("pi-persona-status", { content, kind } satisfies CheckInEntry);
 	};
 	const appendCommandResult = (
 		label: string,
 		content: string,
 		ok: boolean,
-		meta: { failureKind?: FailureKind; error?: string } = {},
+		meta: { failureKind?: FailureKind; error?: string; stoppedAtGate?: string } = {},
 	): void => {
 		pi.appendEntry("pi-persona-result", {
 			label,
 			content,
 			ok,
+			...(meta.stoppedAtGate !== undefined ? { stoppedAtGate: meta.stoppedAtGate } : {}),
 			...(meta.failureKind ? { failureKind: meta.failureKind } : {}),
 			...(meta.error ? { error: meta.error } : {}),
 		} satisfies CommandResultEntry);
 	};
+	/** An operator-run `/flow` or `/orchestrate` result: the card for the operator, and the same text for the
+	 *  supervisor's NEXT turn — `nextTurn` is passive (it never starts one), so "now implement the plan" or
+	 *  "apply the winning diff" finds the result in context instead of nothing. */
+	const appendOperatorResult: typeof appendCommandResult = (label, content, ok, meta = {}) => {
+		appendCommandResult(label, content, ok, meta);
+		try {
+			pi.sendMessage({ customType: "pi-persona", content: renderOperatorResult(label, content, ok, meta.stoppedAtGate), display: false }, { deliverAs: "nextTurn" });
+		} catch {
+			/* the card above is the operator's copy; a host that cannot queue the hand-off must not fail the command */
+		}
+	};
+	/** `/flow` and `/orchestrate` result card; `ok` stays honest, a rejected checkpoint is "stopped". */
+	const appendFlowResult = (flow: string, outcome: FlowOutcome): void =>
+		appendOperatorResult(`flow ${flow}`, outcome.output || "(flow produced no output)", outcome.ok, {
+			...(outcome.stoppedAtGate !== undefined ? { stoppedAtGate: outcome.stoppedAtGate } : {}),
+			...(outcome.failureKind ? { failureKind: outcome.failureKind } : {}),
+			...(outcome.error ? { error: outcome.error } : {}),
+		});
 	const enabledSpineRoles = (): SpineLegacySelection => ({
 		supervisor: config.spine === "on",
 		worker: config.spineLegs === "on",
@@ -390,7 +385,37 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			return { moved: [], kept: [], warnings: [`data root migration failed: ${message}`] };
 		}
 	})();
+	// One persistent settings owner. The root migration must run before importing the two
+	// retired stores; fork-guarded children returned before any filesystem access above.
+	const settingsFile = join(personaDataDir(), "settings.json");
+	let savedSettings: PersonaSettings = { version: 1, preferences: {}, personas: {}, lastPersona: null };
+	const settingsWarnings: string[] = [];
+	const reportedSettingsWarnings = new Set<string>();
+	try {
+		const result = migratePersonaSettings(settingsFile, {
+			legacyConfigFile: join(personaDataDir(), "config.json"),
+			legacyStateFile: config.stateFile ?? join(personaDataDir(), "state.json"),
+		});
+		savedSettings = result.settings;
+		settingsWarnings.push(...result.warnings);
+	} catch (error) {
+		settingsWarnings.push(`could not load settings: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	config = resolvePersonaConfig(savedSettings.preferences, process.env);
+	function reportSettingsWarning(ctx: ExtensionContext | undefined, message: string): void {
+		if (reportedSettingsWarnings.has(message)) return;
+		reportedSettingsWarnings.add(message);
+		const text = `pi-persona settings: ${compactInlineText(message, { maxChars: 500 })}`;
+		try {
+			if (ctx?.hasUI) ctx.ui.notify(text, "warning");
+			else process.stderr.write(`${text}\n`);
+		} catch {
+			// A failed UI must not turn recoverable configuration trouble into activation failure.
+			try { process.stderr.write(`${text}\n`); } catch { /* Non-fatal diagnostic. */ }
+		}
+	}
 	const reportDataRootMigration = (ctx: ExtensionContext): void => {
+		for (const warning of settingsWarnings) reportSettingsWarning(ctx, warning);
 		if (dataRootMigration.moved.length > 0) {
 			const message = `pi-persona: moved ${dataRootMigration.moved.length} file(s) from the legacy pi-persona storage root into ${personaDataDir()}`;
 			if (ctx.hasUI) ctx.ui.notify(message, "info");
@@ -539,6 +564,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	// The unified live tree of every in-flight agent — strategy cores, delegate
 	// sub-agents, dynamic specialists — rendered as one sticky widget above the input.
 	const agentTree = new AgentTree();
+	const wakeRows = new WakeRows();
 	// Explicit telemetry is the public observability seam consumed by pi-persona-flow. It is
 	// session-scoped and starts only after persona + exocom reconciliation in session_start.
 	let telemetry: TelemetryProducer | undefined;
@@ -561,7 +587,6 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		if (node.kind) return node.kind;
 		if (node.id.startsWith("flow:")) return "flow";
 		if (node.id.startsWith("strategy:") || node.id.startsWith("council:")) return "council";
-		if (node.id.startsWith("delegate:")) return "delegate";
 		return "subagent";
 	}
 	function telemetryStatus(node: AgentNode): TelemetryAgentStatus {
@@ -627,6 +652,9 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	function publishAgentTreeChange(change: AgentTreeChange): void {
 		const producer = telemetry;
 		if (!producer) return;
+		// Wake rows (timers, monitors) are not agents, and their labels are free text the telemetry
+		// contract never persists: they stay on the local widget and never reach the bus.
+		if ((change.type === "added" || change.type === "updated") && isWakeSource(change.node)) return;
 		if (change.type === "added") {
 			lastAgentProjection.set(change.node.id, JSON.stringify(telemetryAgent(change.node)));
 			producer.publishAgentAdded(telemetryAgent(change.node));
@@ -637,7 +665,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			return;
 		}
 		if (change.type === "removed") {
-			for (const node of change.nodes) {
+			for (const node of change.nodes.filter((n) => !isWakeSource(n))) {
 				lastAgentProjection.delete(node.id);
 				const status = node.status === "running" ? "stopped" : telemetryStatus(node);
 				producer.publish("agent.removed", { id: node.id, status });
@@ -650,10 +678,17 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	agentTree.onChange(publishAgentTreeChange);
 	// Delegation nudge: watches the supervisor's OWN tool-result stream and reminds it to hand off
 	// when it grinds heavy work by hand (config.nudge; gated to delegating personas at the hook).
-	const delegationNudge = new DelegationNudge();
+	// Its reminder cites the live delegate targets and the session provider's models (read when it
+	// fires: agents change on /persona reload, the session model on a switch).
+	const delegationNudge = new DelegationNudge(undefined, {
+		roster: () => renderNudgeRoster(orderByMention(delegateTargets(), controller.activePersona?.body)),
+		models: () => (canDiscoverModels() && lastCtx?.model ? currentModelCatalog(lastCtx).candidates : undefined),
+	});
 	// Persistence nudge: the counterweight — when a delegated leg comes back BLOCKED/UNKNOWN, remind
 	// the supervisor not to bank a premature surrender (same config.nudge gate + hook as above).
 	const persistenceNudge = new PersistenceNudge();
+	// Poll guard: refuses an unchanged repeat of intercom peek/result (same kill switch).
+	const pollGuard = config.nudge ? new PollGuard() : undefined;
 	// Every visible run (strategy, council, flow) gets its own tree root — see makeRootIdAllocator.
 	const nextRootId = makeRootIdAllocator();
 	// node id → abort that one agent (so the overlay can STOP a single sub-agent).
@@ -675,7 +710,9 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		fn();
 		agentTree.update(nodeId, { detail: "stopping…" }); // visible at once; the run's own settle path writes the terminal status
 		flushAgentWidgetRender();
-		stopRequested.add(nodeId);
+		// A wake source settles synchronously inside `fn()` and clears its own handle, so there is no
+		// pending stop to remember (tracker runs keep their handle until they settle, so they are unchanged).
+		if (stopRegistry.has(nodeId)) stopRequested.add(nodeId);
 		steerRegistry.delete(nodeId); // a hard-stopped agent is no longer steerable (mirror the strategy path)
 		return true;
 	}
@@ -684,7 +721,10 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		return deriveWaitingNodeIds(nodes, (id) => steerRegistry.get(id)?.isWaitingForSupervisor?.() === true);
 	}
 	function waitingAsyncRunIds(): Set<string> {
-		return new Set(tracker.running().filter((run) => steerRegistry.get(`async:${run.id}`)?.isWaitingForSupervisor?.() === true).map((run) => run.id));
+		// Through the tree, so a council/flow run (a root whose LEGS hold the steer handles) reads as waiting
+		// exactly when every live leg does, the same rule a delegate leg answers directly.
+		const waiting = waitingTreeIds();
+		return new Set(tracker.running().filter((run) => waiting.has(`async:${run.id}`)).map((run) => run.id));
 	}
 	const clearSteers = (prefix: string): void => {
 		for (const k of [...steerRegistry.keys()]) if (k === prefix || k.startsWith(`${prefix}/`)) steerRegistry.delete(k);
@@ -707,6 +747,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	const WIDGET_RENDER_DELAY_MS = 16;
 	let widgetTimer: ReturnType<typeof setTimeout> | undefined;
 	let widgetRenderPending = false;
+	let publishingMonitorOutput = false;
 	let widgetLinesInitialized = false;
 	let lastWidgetLines: readonly string[] | undefined;
 	let widgetStatusInitialized = false;
@@ -717,14 +758,29 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		if (!a || !b || a.length !== b.length) return false;
 		return a.every((line, i) => line === b[i]);
 	}
-	function renderAgentWidget(nodes: readonly AgentNode[] = agentTree.snapshot()): void {
+	/** The "N agents" status answers how many agents are working, so a tree holding only wake rows
+	 *  (timers, monitors) publishes none, while the widget lines still show them. */
+	function agentCountStatus(nodes: readonly AgentNode[]): string | undefined {
+		const agents = nodes.filter((node) => !isWakeSource(node));
+		return agents.length === 0 ? undefined : String(inFlightAgentCount(agents));
+	}
+	function renderAgentWidget(): void {
 		if (!lastCtx) return;
+		// Publish dirty monitor tails into the tree BEFORE this frame takes its snapshot. The tree's
+		// overlay listeners still see the patches, but our own listener must not request a second frame.
+		if (!disposed) {
+			publishingMonitorOutput = true;
+			try {
+				for (const change of wakeRows.flushMonitorOutput()) agentTree.update(change.id, change.patch);
+			} finally { publishingMonitorOutput = false; }
+		}
+		const nodes = agentTree.snapshot();
 		const empty = nodes.length === 0;
 		const lines = empty ? undefined : renderAgentTreeSummary([...nodes], 8, { now: Date.now(), stallMs: STALL_FLAG_MS, waitingForSupervisor: waitingTreeIds(nodes) });
-		const status = empty ? undefined : String(inFlightAgentCount(nodes));
+		const status = agentCountStatus(nodes);
 		try {
 			if (!widgetLinesInitialized || !sameWidgetLines(lastWidgetLines, lines)) {
-				lastCtx.ui.setWidget("persona-agents", lines, { placement: "aboveEditor" });
+				lastCtx.ui.setWidget("persona-agents", lines ? compactWidget(lines) : undefined, { placement: "aboveEditor" });
 				lastWidgetLines = lines;
 				widgetLinesInitialized = true;
 			}
@@ -743,8 +799,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	}
 	function renderAgentStatus(): void {
 		if (!lastCtx) return;
-		const nodes = agentTree.snapshot();
-		const status = nodes.length === 0 ? undefined : String(inFlightAgentCount(nodes));
+		const status = agentCountStatus(agentTree.snapshot());
 		try {
 			if (!widgetStatusInitialized || lastWidgetStatus !== status) {
 				lastCtx.ui.setStatus("persona-agents", status);
@@ -806,6 +861,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	// elapsed time and the stall badge moving without a progress event, and stops itself when idle.
 	const widgetClock = new LiveClock({ intervalMs: 1_000, isLive: () => agentTree.hasRunning(), onTick: renderAgentWidget });
 	agentTree.onChange((change) => {
+		if (publishingMonitorOutput) return;
 		const refreshStatus = widgetStatusMayHaveChanged(change);
 		if (disposed) {
 			// session_shutdown clears the tree after marking this activation disposed. Keep teardown
@@ -849,21 +905,36 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	let seedSourceCollisions: string[] = [];
 
 	// Remembered selection lives in the persona data folder; only user gestures write it.
-	const stateFile = config.stateFile ?? join(personaDataDir(), "state.json");
 	const readRememberedPersona = (): string | undefined => {
 		if (!config.persist) return undefined;
-		return readLastPersona(stateFile);
+		try {
+			savedSettings = readPersonaSettings(settingsFile);
+			return savedSettings.lastPersona ?? undefined;
+		} catch (error) {
+			reportSettingsWarning(lastCtx, `could not read remembered persona: ${error instanceof Error ? error.message : String(error)}`);
+			return undefined;
+		}
 	};
 	const persist = (name: string | undefined): void => {
-		if (config.persist) writeLastPersona(stateFile, name);
+		if (!config.persist) return;
+		try {
+			savedSettings = patchPersonaSettings(settingsFile, { lastPersona: name ?? null });
+		} catch (error) {
+			reportSettingsWarning(lastCtx, `could not save remembered persona: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	};
 
-	// Per-persona config (model assignments today, open-ended), indexed by persona name.
-	const configFile = join(personaDataDir(), "config.json");
+	// Model preferences share the canonical file with extension preferences and selection.
 	const readConfigStore = (): PersonaConfigStore => {
-		return readPersonaConfigs(configFile);
+		try {
+			savedSettings = readPersonaSettings(settingsFile);
+			return savedSettings.personas;
+		} catch (error) {
+			reportSettingsWarning(lastCtx, `could not read model settings: ${error instanceof Error ? error.message : String(error)}`);
+			return savedSettings.personas;
+		}
 	};
-	let personaConfigs: PersonaConfigStore = {};
+	let personaConfigs: PersonaConfigStore = savedSettings.personas;
 	// A participant is asked for a model at most ONCE per session — dismissal included, so a
 	// closed picker never becomes a nag. Keyed by persona + assignment key, NOT by persona: a new
 	// roster (or a new strategy's arbiter) is a genuinely new participant and may ask the first time
@@ -918,6 +989,11 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		definitionWarnings = [...result.warnings, ...contractsLoad.warnings];
 	}
 
+	// Empty by design on a fresh install (see above): point at the install gesture from every
+	// surface that would otherwise be silent or read as broken — `/persona list`, /doctor, F8.
+	const NO_PERSONAS_HINT =
+		"No personas installed. pi-persona does not auto-install — run `/persona seed` to copy the bundled defaults into your agent dir (edit them freely; `/persona restore` re-installs the originals).";
+
 	// Install the bundled defaults into the user's agent dir — this is the ONLY way personas/agents
 	// become active (they are not a live builtin layer). `/persona seed` pulls in missing defaults,
 	// `/persona restore` force-overwrites them back to the originals. First-run auto-install is
@@ -1069,12 +1145,13 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	};
 	// Async runs outlive the turn that launched them; on completion we surface the result(s) back as
 	// ONE coalesced notice so the (idle) supervisor can react — e.g. retry a failure with another model.
-	// With delegate now background-by-default (interactive), this is the COMMON delivery path, so the
-	// premature-surrender counterweight must ride it too: a settled leg whose report carries a
-	// [BLOCKED]/FLAG:UNKNOWN marker gets the persistence note appended (the sync tool_result hook can't
-	// see a background run — its report arrives here as a fresh follow-up, not a delegate result).
+	// Interactive delegate ALWAYS runs in the background, so this is the COMMON delivery path: the
+	// premature-surrender counterweight rides it (the sync tool_result hook can't see a background run),
+	// and a `tasks` fan-out is held until its LAST leg settles so the supervisor is woken once with every
+	// result instead of once per leg. Single legs are never held.
 	const completionNotifier = new IdleCoalescingNotifier<AsyncRun>({
 		...idleDelivery,
+		isReady: (run) => tracker.batchSettled(run),
 		render: (runs) => {
 			const report = renderCompletion(runs, fenceUntrusted, (t) => scanForSurrender(t));
 			// Retention is a bound, not a promise: a fan-out wider than it settles more payloads than the
@@ -1107,6 +1184,21 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		...idleDelivery,
 		render: (entries) => renderTimerFire(entries),
 	});
+	// Wake sources (timers, monitors) are rows beside the sub-agents: added when armed, updated on
+	// events, settled like an async run. The final update and the removal are synchronous and the
+	// widget composition is coalesced, so the final status reaches the tree change stream, never the
+	// screen; the row simply leaves, together with its stop handle.
+	function settleWakeRow(change: WakeRowChange): void {
+		// session_shutdown clears the tree and both registries itself right after cancelAll, so
+		// settling rows one by one would only repaint a widget it is about to clear (the tree
+		// listener repaints synchronously once disposed). The leftover timer:/monitor: stop handles
+		// are harmless: cancelling an unknown id is a no-op.
+		if (disposed) return;
+		agentTree.update(change.id, change.patch);
+		agentTree.remove(change.id);
+		stopRegistry.delete(change.id);
+		stopRequested.delete(change.id);
+	}
 	const timerScheduler = new TimerScheduler({
 		now: () => Date.now(),
 		setTimer: (fn, ms) => {
@@ -1115,7 +1207,13 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			return h;
 		},
 		clearTimer: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
-		onFire: (entry) => timerNotifier.notify(entry),
+		onArmed: (entry) => {
+			const row = wakeRows.timerArmed(entry);
+			stopRegistry.set(row.id, () => { timerScheduler.cancel(entry.id); });
+			agentTree.add(row);
+		},
+		onCancelled: (entry) => settleWakeRow(wakeRows.timerCancelled(entry)),
+		onFire: (entry) => { settleWakeRow(wakeRows.timerFired(entry)); timerNotifier.notify(entry); },
 	});
 	const canRunMonitor = () => {
 		if (disposed) return false;
@@ -1124,26 +1222,66 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		return active.includes("monitor") && active.includes("bash")
 			&& (!caps || (canCallTool(caps, "monitor") && canCallTool(caps, "bash")));
 	};
+	// Session-native custom entries own the bounded logs: they are not model messages and
+	// deleting the session removes them without orphan sidecars. Shutdown persists, never deletes.
+	const monitorArchive = new MonitorArchive({
+		entries: () => lastCtx?.sessionManager?.getEntries?.() ?? [],
+		append: (customType, data) => pi.appendEntry(customType, data),
+	});
 	monitors = createMonitorSession({
+		idPrefix: `monitor-${randomUUID().slice(0, 8)}`,
 		isIdle: idleDelivery.isIdle,
 		deliver: (text) => sendPersonaFollowUp(pi, text),
 		canRun: canRunMonitor,
+		observe: {
+			armed: (entry) => {
+				monitorArchive.armed(entry);
+				if (disposed) return;
+				const row = wakeRows.monitorArmed(entry);
+				stopRegistry.set(row.id, () => { monitors?.cancel(entry.id); });
+				agentTree.add(row);
+			},
+			output: (output) => {
+				monitorArchive.output(output);
+				if (disposed) return;
+				if (wakeRows.monitorOutput(output)) requestAgentWidgetRender(false);
+			},
+			event: (event) => {
+				monitorArchive.event(event);
+				if (disposed) return;
+				const change = wakeRows.monitorEvent(event);
+				if (change.settled) settleWakeRow(change);
+				else agentTree.update(change.id, change.patch);
+			},
+			removed: (entry) => {
+				monitorArchive.removed(entry);
+				if (disposed) return;
+				settleWakeRow(wakeRows.monitorRemoved(entry));
+			},
+		},
 	});
 	const tracker = new AsyncRunTracker({ maxRetained: config.asyncRetain });
 	// The premature-surrender counterweight rides the SAME kill switch as the by-hand nudge
-	// (PI_PERSONA_NUDGE=off). Both completion surfaces — the background follow-up and `intercom wait` —
-	// go through here, so "off" means off wherever a settled leg is collected, not just on the
-	// synchronous tool_result hook.
+	// (PI_PERSONA_NUDGE=off). The background completion follow-up goes through here, so "off" means
+	// off there too, not just on the synchronous tool_result hook.
 	const scanForSurrender = (text: string): string | undefined => (config.nudge ? persistenceNudge.scan(text) : undefined);
 	// A run id that is neither live nor retained has two very different meanings: it never existed, or
 	// its payload was evicted under retention pressure. Only the second deserves an explanation — and a
 	// bare "no such run" for a result the supervisor was just TOLD to fetch is exactly the dead end
 	// this distinction exists to prevent.
 	function missingRunMessage(id: string, display: string | undefined): string {
-		if (!tracker.wasDropped(id)) return `No retained async run "${display}".`;
+		if (tracker.wasDropped(id)) {
+			return (
+				`Async run "${display}" settled, but its full payload is gone: more runs settled than the ${tracker.retention}-run retention bound keeps. ` +
+				"Its summary is, or will be, in the completion follow-up. Raise PI_PERSONA_ASYNC_RETAIN, or fan out in narrower waves and collect as you go, to keep more."
+			);
+		}
+		// Never existed, or ended with the session that launched it (a call-sign is not an address either):
+		// list what does exist — running first, then the newest settled — so the next call can be right.
+		const settled = tracker.list().filter((run) => run.status !== "running").reverse().sort((a, b) => (b.settledAt ?? 0) - (a.settledAt ?? 0));
 		return (
-			`Async run "${display}" settled, but its full payload is gone: more runs settled than the ${tracker.retention}-run retention bound keeps. ` +
-			"Its summary was delivered in the completion follow-up. Raise PI_PERSONA_ASYNC_RETAIN, or fan out in narrower waves and collect as you go, to keep more."
+			`No retained async run "${display}". Runs live only in the session that launched them (a restart, /new or reload ends them; collected results are evicted first once retention is full). ` +
+			`Known runs: ${describeRuns([...tracker.running(), ...settled], { status: true })}.`
 		);
 	}
 	// Turns the periodic peek from a poll into an exception signal: it surfaces a leg only when it
@@ -1157,11 +1295,21 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		stopRequested.delete(`async:${run.id}`);
 		if (disposed) return; // instance torn down — don't notify the next session or re-arm a cancelled timer
 		// Immediate human feedback + one semantic completion. Explicit stops are informational,
-		// while natural failures retain the error toast and every terminal result is still delivered.
+		// while failures get an expandable TUI card (a toast elsewhere). Every result is still delivered.
 		announceAsyncRunSettlement(
 			run,
 			lastCtx ? (message, level) => lastCtx?.ui.notify(message, level) : undefined,
 			(settled) => completionNotifier.notify(settled),
+			lastCtx?.hasUI && lastCtx.mode === "tui" ? (failed) => {
+				const model = failed.result?.modelUsed ?? failed.model;
+				const durationMs = failed.startedAt !== undefined && failed.settledAt !== undefined
+					? Math.max(0, failed.settledAt - failed.startedAt) : undefined;
+				pi.appendEntry("pi-persona-run-failure", {
+					id: failed.id, label: failed.label ?? failed.agent, agent: failed.agent,
+					...(model ? { model } : {}), ...(durationMs !== undefined ? { durationMs } : {}),
+					error: failed.error ?? "(no detail)",
+				} satisfies RunFailureEntry);
+			} : undefined,
 		);
 		if (tracker.running().length === 0) stopPeek(); // no live runs → stop the idle peek
 	});
@@ -1196,9 +1344,10 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		});
 	});
 
-	// Async-run watchdog: the fast PI_PERSONA_PEEK_MS cadence wakes the supervisor only for a newly-stalled
-	// leg or unread message. The slower PI_PERSONA_CHECKIN_MS cadence appends a durable operator-only status
-	// card; it does not start a model turn. Bounded: unref'd, self-stops when no runs remain.
+	// Async-run watchdog: the fast PI_PERSONA_PEEK_MS cadence appends an operator-only card for a
+	// newly-stalled leg and wakes the supervisor only for an unread message. The slower
+	// PI_PERSONA_CHECKIN_MS cadence appends a durable operator-only status card; it does not start a
+	// model turn. Bounded: unref'd, self-stops when no runs remain.
 	let peekTimer: ReturnType<typeof setInterval> | undefined;
 	// Last time progress status was surfaced (a new stall alert or routine card), for the slow cadence.
 	let lastPeekAt = 0;
@@ -1209,7 +1358,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		}
 	}
 	function startPeek(): void {
-		// Fast wakeups and routine cards opt out independently. The carrier timer runs while EITHER is on
+		// Fast ticks and routine cards opt out independently. The carrier timer runs while EITHER is on
 		// and ticks at the faster of the two (a disabled one is Infinity, so it never drives).
 		const fastMs = config.peekEveryMs > 0 ? config.peekEveryMs : Number.POSITIVE_INFINITY;
 		const checkMs = config.checkInEveryMs > 0 ? config.checkInEveryMs : Number.POSITIVE_INFINITY;
@@ -1223,13 +1372,12 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				return;
 			}
 			const now = Date.now();
-			const dueCheckIn = config.checkInEveryMs > 0 && now - lastPeekAt >= config.checkInEveryMs;
-			// Routine status is durable operator history, not a model notification: append it on cadence even
-			// while a turn is busy or human input is queued. This keeps visibility independent of wake eligibility.
-			if (dueCheckIn) {
-				lastPeekAt = now;
+			const waitingRuns = waitingAsyncRunIds();
+			const fast = config.peekEveryMs > 0;
+			const stuck = fast ? peekWatcher.poll(runs, now, STALL_FLAG_MS, waitingRuns) : [];
+			const appendStatus = (content: string, kind: "routine" | "stall"): void => {
 				try {
-					appendCheckInEntry(buildCheckIn(runs, { now, stallMs: STALL_FLAG_MS, waitingForSupervisor: waitingAsyncRunIds() }));
+					appendCheckInEntry(content, kind);
 				} catch (error) {
 					const detail = compactInlineText(error instanceof Error ? error.message : String(error), { maxChars: 120 });
 					const warning = `pi-persona: could not append async status entry${detail ? ` (${detail})` : ""}`;
@@ -1241,28 +1389,22 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 						try { process.stderr.write(`[pi-persona] ${warning}\n`); } catch { /* diagnostics must not block an actionable wake */ }
 					}
 				}
+			};
+			// Every new stall episode is durable operator history, including while the model is busy.
+			if (stuck.length > 0) appendStatus(buildCheckIn(stuck, { now, stallMs: STALL_FLAG_MS, reason: "stall", waitingForSupervisor: waitingRuns }), "stall");
+			const dueCheckIn = config.checkInEveryMs > 0 && now - lastPeekAt >= config.checkInEveryMs;
+			if (dueCheckIn) {
+				lastPeekAt = now;
+				appendStatus(buildCheckIn(runs, { now, stallMs: STALL_FLAG_MS, waitingForSupervisor: waitingRuns }), "routine");
 			}
-			// Poll actionable model wakes only for a free supervisor. A busy/queued session keeps messages
-			// unread and leaves stall state untouched for the next tick, rather than stacking sticky follow-ups.
+			// A stall is operator-only (appended above) and never costs a model turn; unread non-ask
+			// messages keep their actionable route.
 			if (!canDeliverPersonaNotification(orchestrating, processingDeferredOrchestration, lastCtx?.isIdle?.() === true) || lastCtx?.hasPendingMessages?.() === true) return;
-			// The watchdog is not a model polling loop: the FAST path wakes on newly-stalled legs or unread
-			// progress messages. Completions arrive separately through completionNotifier; `/peek` remains on demand.
-			const fast = config.peekEveryMs > 0;
-			const waitingRuns = waitingAsyncRunIds();
-			const stuck = fast ? peekWatcher.poll(runs, now, STALL_FLAG_MS, waitingRuns) : [];
-			// Drain only progress messages; blocking asks (expectsReply) are surfaced by the intercom
-			// notifier and left for the `intercom inbox` tool — so peek never double-shows them.
 			const unread = fast ? bus.takeWhere(SUPERVISOR, (e) => !e.expectsReply) : [];
-			if (stuck.length === 0 && unread.length === 0) return; // healthy + quiet ⇒ stay silent
-			const parts: string[] = [];
-			if (stuck.length > 0) parts.push(buildPeekAlert(stuck, { now }));
-			if (unread.length > 0) parts.push(`📨 from sub-agents:\n${fenceUntrusted(formatInbox(unread))}`);
-			if (stuck.length > 0) lastPeekAt = now; // message-only wakes do not postpone the routine status cadence
+			if (unread.length === 0) return;
 			try {
-				sendPersonaFollowUp(pi, `[pi-persona] ${parts.join("\n\n")}`);
-			} catch {
-				/* ignore */
-			}
+				sendPersonaFollowUp(pi, `[pi-persona] 📨 from sub-agents:\n${fenceUntrusted(formatInbox(unread))}`);
+			} catch { /* best-effort wake: the session may be tearing down */ }
 		}, tickMs);
 		peekTimer.unref?.();
 	}
@@ -1360,8 +1502,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	 * Every participant a run really spawns — roster members (inline ones included) plus the
 	 * auxiliary actors its strategy declares — with the model each one resolves to.
 	 */
-	function runParticipants(ctx: ExtensionContext, opts: { strategy: string; params?: Record<string, unknown>; members: RosterMember[] }): ModelParticipant[] {
-		const persona = controller.activePersona?.name;
+	function runParticipants(ctx: ExtensionContext, opts: { strategy: string; params?: Record<string, unknown>; members: RosterMember[] }, persona = controller.activePersona?.name): ModelParticipant[] {
 		return collectModelParticipants({
 			members: opts.members,
 			strategy: opts.strategy,
@@ -1382,15 +1523,34 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	 * Only a live UI ever sees a dialog (`ctx.hasUI`), and only when there is more than one
 	 * authenticated model to choose between.
 	 */
-	async function ensurePersonaModels(ctx: ExtensionContext, participants: ModelParticipant[]): Promise<void> {
+	async function ensurePersonaModels(ctx: ExtensionContext, participants: ModelParticipant[], signal: AbortSignal, rootId: string, tracked?: TrackedRun): Promise<void> {
 		const scope = modelSelectionScope(ctx);
-		if (!scope || !ctx.hasUI) return;
+		if (!scope || !ctx.hasUI || signal.aborted) return;
 		const missing = pendingParticipants(participants, { prompted: promptedFor(scope.persona, participants) });
 		if (missing.length === 0) return;
 		const available = configuredModels(ctx);
 		if (available.length < 2) return; // automatic setup cannot diversify a single model
-		const chosen = await choosePersonaModels(ctx, missing, available, scope);
-		if (chosen && Object.keys(chosen).length > 0) savePersonaModels(ctx, scope.persona, chosen);
+		// A tracked run parked at this picker is waiting on the OPERATOR: say so, or it reads "queued" and,
+		// past the stall window, "possibly stuck".
+		tracked?.onAwaiting("waiting for operator to pick models");
+		agentTree.update(rootId, { detail: "waiting for operator to pick models" });
+		try {
+			const choose = async (): Promise<void> => {
+				if (signal.aborted || !scope.isCurrent()) return;
+				// A concurrent run may have assigned or dismissed these participants while this one waited.
+				const assigned = personaModels(personaConfigs, scope.persona);
+				const pending = pendingParticipants(participants, { prompted: promptedFor(scope.persona, participants) })
+					.filter((p) => !assigned[p.key] && !assigned[p.agent]);
+				const chosen = await choosePersonaModels(ctx, pending, available, scope, signal);
+				if (!signal.aborted && chosen && Object.keys(chosen).length > 0) savePersonaModels(ctx, scope.persona, chosen);
+			};
+			// Every automatic setup shares the checkpoint dialog line, including commands and mandatory
+			// orchestration. The run's stop closes the active picker or removes it from the line.
+			await inGateLine(signal, undefined, choose);
+		} finally {
+			tracked?.onAwaiting(undefined);
+			agentTree.update(rootId, { detail: "", lastAdvanceAt: Date.now() });
+		}
 	}
 
 	type ModelSelectionScope = { persona: string; isCurrent(): boolean };
@@ -1427,15 +1587,20 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	}
 
 	/** UI adapter shared by setup and editing; callers own eligibility and availability policy. */
-	async function choosePersonaModels(ctx: ExtensionContext, participants: ModelParticipant[], available: Array<{ provider: string; id: string }>, scope: ModelSelectionScope): Promise<Record<string, string> | undefined> {
+	async function choosePersonaModels(ctx: ExtensionContext, participants: ModelParticipant[], available: ModelPickerMetadata[], scope: ModelSelectionScope, signal?: AbortSignal): Promise<Record<string, string> | undefined> {
 		const { persona } = scope;
 		const options = orderModelRefs(available.map((m) => `${m.provider}/${m.id}`), ctx.model?.provider);
 		const chosen: Record<string, string> = {};
+		const addedPromptKeys = new Set<string>();
 		try {
 			for (const p of participants) {
+				if (signal?.aborted) return;
 				// Recorded BEFORE the prompt: a dismissal (or a picker that dies) must not be retried
-				// for this session, exactly like an answer is not asked twice.
-				promptedParticipants.add(`${persona}\0${p.key}`);
+				// for this session, exactly like an answer is not asked twice. Aborted setup discards
+				// all its picks, so only its newly added markers are rolled back below.
+				const promptKey = `${persona}\0${p.key}`;
+				if (!promptedParticipants.has(promptKey)) addedPromptKeys.add(promptKey);
+				promptedParticipants.add(promptKey);
 				// Name the core's verticalization in the picker too: choosing a model for "the
 				// Conservatore" is a different judgement than choosing one for a bare "balthasar".
 				// An auxiliary actor names the param that declared it ("arbiter judge").
@@ -1448,14 +1613,29 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				// In the TUI: a searchable picker (type to filter) whose viewport follows the
 				// selection — the built-in select can't scroll a hundreds-long provider list
 				// usefully. Outside the TUI (RPC), fall back to the built-in select.
-				const pick =
-					ctx.mode === "tui"
+				let pick: string | undefined;
+				let cancelPicker: (() => void) | undefined;
+				try {
+					pick = ctx.mode === "tui"
 						? await ctx.ui.custom<string | undefined>(
-								(tui, theme, _kb, done) =>
-									new ModelPicker(tui, theme, title, options, ctx.model?.provider, (ref) => done(ref)),
+								(tui, theme, keybindings, done) => {
+									// custom() has no signal option: its factory's done callback owns dismissal.
+									cancelPicker = () => done(undefined);
+									if (signal?.aborted) cancelPicker();
+									else signal?.addEventListener("abort", cancelPicker, { once: true });
+									return new ModelPicker(tui, theme, title, options, ctx.model?.provider, (ref) => done(ref), {
+										models: available,
+										...(p.model !== undefined ? { currentRef: p.model } : {}),
+										...(keybindings ? { keybindings } : {}),
+									});
+								},
 								{ overlay: true },
-							)
-						: await ctx.ui.select(title, options);
+								)
+						: await ctx.ui.select(title, options, signal ? { signal } : undefined);
+				} finally {
+					if (cancelPicker) signal?.removeEventListener("abort", cancelPicker);
+				}
+				if (signal?.aborted) return;
 				if (!scope.isCurrent()) {
 					ctx.ui.notify("persona models: persona or session changed; no assignments changed.", "warning");
 					return;
@@ -1464,7 +1644,10 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			}
 		} catch {
 			/* dismissed / no UI → fall back to the default model */
+		} finally {
+			if (signal?.aborted) for (const key of addedPromptKeys) promptedParticipants.delete(key);
 		}
+		if (signal?.aborted) return;
 		if (!scope.isCurrent()) {
 			ctx.ui.notify("persona models: persona or session changed; no assignments changed.", "warning");
 			return;
@@ -1478,7 +1661,8 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		// future session with no hint that the assignment never landed.
 		personaConfigs = withPersonaModels(personaConfigs, persona, chosen);
 		try {
-			writePersonaConfigs(configFile, personaConfigs);
+			savedSettings = patchPersonaSettings(settingsFile, { models: { [persona]: chosen } });
+			personaConfigs = savedSettings.personas;
 		} catch (err) {
 			ctx.ui.notify(
 				`pi-persona: could not save the model assignment for "${persona}" (${err instanceof Error ? err.message : String(err)}) — it applies to this session only.`,
@@ -1599,7 +1783,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	// The SDK lifecycle callbacks that drive the unified tree for one strategy run rooted at
 	// `rootId` — shared by /orchestrate, the council tool, and each flow phase. Seeds running
 	// cores, flips ⏳ → ✓/✗ with usage, streams progress, and registers stop/steer handles.
-	function strategyTreeDeps(ctx: ExtensionContext, rootId: string, nodeParticipants: ReadonlyMap<string, ModelParticipant | null> = new Map()) {
+	function strategyTreeDeps(ctx: ExtensionContext, rootId: string, nodeParticipants: ReadonlyMap<string, ModelParticipant | null> = new Map(), tracked?: TrackedRun) {
 		return {
 			onAgentStart: (agent: string, abort: () => void, key?: string) => {
 				stopRegistry.set(`${rootId}/${key ?? agent}`, abort);
@@ -1638,6 +1822,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				agentTree.update(id, progressPatch(p, now));
 				// Child engine events refresh liveness, not proof of useful work; repaint alone never advances it.
 				agentTree.update(rootId, { lastAdvanceAt: now });
+				tracked?.onProgress(id, p); // …and the tracked run's own clock and token total, if it has one
 			},
 		};
 	}
@@ -1647,6 +1832,23 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		return caps ? { canSpawn: (agent) => canDelegateTo(caps, agent) } : {};
 	}
 
+	/** The tree root and run-level stop of one visible run. A tracked run (the `council`/`flow` tools) arrives
+	 *  with both: `async:<runId>` and the signal its stop key aborts. Anything else (a mandated orchestration,
+	 *  `/orchestrate`, `/flow`) is rooted here and registers its OWN stop under the root's id, so `stopAgent`,
+	 *  the overlay's `canStop` and shutdown reach the whole run — Pi's `ctx.signal` is undefined while the agent
+	 *  is idle, which is exactly when those run, so there is no host signal to lean on. `live` is what going
+	 *  live adds to the root row: a tracked root already exists, "queued", and restarts its clock here. */
+	function visibleRoot(prefix: string, tracked: TrackedRun | undefined): { rootId: string; signal: AbortSignal; live: AgentNodePatch } {
+		if (tracked) {
+			const now = Date.now();
+			return { rootId: tracked.rootId, signal: tracked.signal, live: { detail: "", startedAt: now, lastAdvanceAt: now } };
+		}
+		const ac = new AbortController();
+		const rootId = nextRootId(prefix);
+		stopRegistry.set(rootId, () => ac.abort());
+		return { rootId, signal: ac.signal, live: {} };
+	}
+
 	// Run a persona strategy with the unified tree wired in: assign models on first run,
 	// seed the roster (cores show by name at once), flip ⏳ → ✓/✗ live, clear when done.
 	async function runStrategyVisible(
@@ -1654,34 +1856,39 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		orch: OrchestrationGrammar,
 		task: string,
 		idPrefix: string,
-		signal?: AbortSignal,
+		tracked?: TrackedRun,
 	) {
 		const label = resolveStrategyName(orch) ?? "strategy";
 		const roster = resolveOrchestrationMembers(orch, teams);
 		const participants = runParticipants(ctx, { strategy: label, ...(orch.params ? { params: orch.params } : {}), members: roster });
-		await ensurePersonaModels(ctx, participants);
 		const participantsByNode = participantByNode(participants);
-		const rootId = nextRootId(`${idPrefix}:${label}`);
-		agentTree.add({ id: rootId, label, status: "running", kind: "council" });
-		// Seed the whole roster at once (cores show by name immediately); "queued" until the
-		// engine actually starts each one — an honest view under the concurrency limit.
-		const seedKeys = rosterNodeKeys(roster);
-		roster.forEach((m, i) => {
-			const a = rosterSpec(m).agent;
-			const key = seedKeys[i] ?? a;
-			const participant = participantForNode(participantsByNode, key);
-			const assignmentKey = participant?.key ?? bareAssignmentKey(key);
-			agentTree.add({ id: `${rootId}/${key}`, label: coreLabel(ctx, a, key, assignmentKey, participant), parentId: rootId, status: "running", kind: "subagent", ...coreTelemetryMeta(ctx, a, assignmentKey, participant), detail: "queued" });
-		});
+		const { rootId, signal, live } = visibleRoot(`${idPrefix}:${label}`, tracked);
+		agentTree.add({ id: rootId, label, status: "running", kind: "council", ...live });
 		try {
+			await ensurePersonaModels(ctx, participants, signal, rootId, tracked);
+			if (signal.aborted) {
+				agentTree.update(rootId, { status: "stopped" });
+				const cancelled: AgentResult = { agent: label, output: "cancelled before orchestration started", usage: emptyUsage(), ok: false, error: "cancelled", failureKind: "abort" };
+				return cancelled;
+			}
+			// Seed the whole roster at once (cores show by name immediately); "queued" until the
+			// engine actually starts each one — an honest view under the concurrency limit.
+			const seedKeys = rosterNodeKeys(roster);
+			roster.forEach((m, i) => {
+				const a = rosterSpec(m).agent;
+				const key = seedKeys[i] ?? a;
+				const participant = participantForNode(participantsByNode, key);
+				const assignmentKey = participant?.key ?? bareAssignmentKey(key);
+				agentTree.add({ id: `${rootId}/${key}`, label: coreLabel(ctx, a, key, assignmentKey, participant), parentId: rootId, status: "running", kind: "subagent", ...coreTelemetryMeta(ctx, a, assignmentKey, participant), detail: "queued" });
+			});
 			// The signal goes to the STRATEGY as well as the engine: a multi-round strategy checks it
 			// cooperatively between rounds, so an aborted run stops convening instead of running every
 			// remaining round against an already-cancelled engine (docs/STRATEGIES.md).
-			const result = await runPersonaStrategy(orch, task, { engine: buildEngine(signal, undefined, { providerFallback: false }), teams, limits: RUN_LIMITS, ...sessionModelDep(ctx), ...(signal ? { signal } : {}), ...strategyTreeDeps(ctx, rootId, participantsByNode), ...strategySpawnGate(), ...modelFallbackDep(ctx) });
-			agentTree.update(rootId, { status: signal?.aborted ? "stopped" : result?.ok === false ? "failed" : "done" });
+			const result = await runPersonaStrategy(orch, task, { engine: buildEngine(signal, undefined, { providerFallback: false, async: tracked?.background === true }), teams, limits: RUN_LIMITS, ...sessionModelDep(ctx), signal, ...strategyTreeDeps(ctx, rootId, participantsByNode, tracked), ...strategySpawnGate(), ...modelFallbackDep(ctx) });
+			agentTree.update(rootId, { status: signal.aborted ? "stopped" : result?.ok === false ? "failed" : "done" });
 			return result ?? undefined;
 		} catch (error) {
-			agentTree.update(rootId, { status: signal?.aborted ? "stopped" : "failed" });
+			agentTree.update(rootId, { status: signal.aborted ? "stopped" : "failed" });
 			throw error;
 		} finally {
 			clearStops(rootId);
@@ -1720,12 +1927,45 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		if (found === undefined) return undefined;
 		return parseFlow(found);
 	}
+	// Installed flows with what a chooser needs: the description and whether a checkpoint pauses
+	// for a human. An unparseable file stays a bare name (running it reports the parse error).
+	function flowCatalog(cwd: string): BriefFlow[] {
+		return listFlows(cwd).map((name): BriefFlow => {
+			const parsed = loadFlow(cwd, name);
+			const flow = parsed?.ok ? parsed.flow : undefined;
+			return {
+				name,
+				...(flow?.description ? { description: flow.description } : {}),
+				...(flow?.phases.some((p) => p.gate) ? { gated: true } : {}),
+			};
+		});
+	}
+
+	// Pi's extension selector is ONE slot: a second concurrent `ctx.ui.select` displaces the first without ever
+	// resolving it, orphaning a run behind a prompt nobody can see. Background model setup and flow checkpoints
+	// share this line, so their prompts open one at a time in arrival order. A stopped run leaves it at once.
+	let gateLine: Promise<unknown> = Promise.resolve();
+	function inGateLine<T>(signal: AbortSignal, stopped: T, open: () => Promise<T>): Promise<T> {
+		const turn = gateLine.then(() => (signal.aborted ? stopped : open()));
+		gateLine = turn.catch(() => undefined);
+		let onAbort: (() => void) | undefined;
+		const left = new Promise<T>((resolve) => {
+			if (signal.aborted) resolve(stopped);
+			else {
+				onAbort = () => resolve(stopped);
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+		});
+		return Promise.race([turn, left]).finally(() => {
+			if (onAbort) signal.removeEventListener("abort", onAbort);
+		});
+	}
 
 	// Run a flow's DAG with the unified tree (phases as nodes, cores beneath) + journaled
-	// resume: a prior run's journal (keyed by flow@hash) skips already-done phases; the
+	// resume: a prior run's journal (keyed by flow + task + cwd) skips already-done phases; the
 	// journal is cleared on a fully-successful run.
-	async function runFlowVisible(ctx: ExtensionContext, spec: FlowSpec, baseTask: string, signal?: AbortSignal): Promise<FlowOutcome> {
-		const hash = flowHash(spec);
+	async function runFlowVisible(ctx: ExtensionContext, spec: FlowSpec, baseTask: string, tracked?: TrackedRun): Promise<FlowOutcome> {
+		const hash = flowRunHash(spec, baseTask, ctx.cwd);
 		const journalDir = join(personaDataDir(), "flows");
 		try {
 			mkdirSync(journalDir, { recursive: true });
@@ -1751,17 +1991,20 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				return [phase.id, { members, participants }] as const;
 			}),
 		);
-		await ensurePersonaModels(ctx, spec.phases.flatMap((p) => phasePlans.get(p.id)?.participants ?? []));
-
-		const flowRoot = nextRootId(`flow:${spec.name}`);
-		agentTree.add({ id: flowRoot, label: `flow ${spec.name}`, status: "running", kind: "flow" });
-		for (const p of spec.phases) {
-			const pid = `${flowRoot}/${p.id}`;
-			const node: AddNodeInput = { id: pid, label: `${p.id} · ${p.strategy}`, parentId: flowRoot, status: resume[p.id] ? "done" : "running", kind: "phase" };
-			if (resume[p.id]) node.detail = "resumed";
-			agentTree.add(node);
-		}
+		const { rootId: flowRoot, signal, live } = visibleRoot(`flow:${spec.name}`, tracked);
+		agentTree.add({ id: flowRoot, label: `flow ${spec.name}`, status: "running", kind: "flow", ...live });
 		try {
+			await ensurePersonaModels(ctx, spec.phases.flatMap((p) => phasePlans.get(p.id)?.participants ?? []), signal, flowRoot, tracked);
+			if (signal.aborted) {
+				agentTree.update(flowRoot, { status: "stopped" });
+				return { ok: false, results: {}, output: "cancelled before flow started", error: "cancelled", failureKind: "abort", cancelled: true };
+			}
+			for (const p of spec.phases) {
+				const pid = `${flowRoot}/${p.id}`;
+				const node: AddNodeInput = { id: pid, label: `${p.id} · ${p.strategy}`, parentId: flowRoot, status: resume[p.id] ? "done" : "running", kind: "phase" };
+				if (resume[p.id]) node.detail = "resumed";
+				agentTree.add(node);
+			}
 			// Yield so a concurrent flow can seed its own tree before we fail-closed on refs —
 			// the check still runs BEFORE any phase/engine work.
 			await Promise.resolve();
@@ -1784,7 +2027,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			const outcome = await runFlow(spec, baseTask, {
 				hash,
 				resume,
-				...(signal ? { signal } : {}),
+				signal,
 				journal: journalWriter(journalPath),
 				onPhase: (id, status, result) => {
 					const patch: { status: AgentNodeStatus; output?: string; detail?: string } = {
@@ -1810,12 +2053,12 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 					const orch: OrchestrationGrammar = { mode: "strategy", strategy: phase.strategy, params: phase.params ?? {} };
 					if (phase.roster) orch.roster = phase.roster;
 					const r = await runPersonaStrategy(orch, task, {
-						engine: buildEngine(signal, undefined, { providerFallback: false }),
+						engine: buildEngine(signal, undefined, { providerFallback: false, async: tracked?.background === true }),
 						teams,
 						limits: RUN_LIMITS,
 						...sessionModelDep(ctx),
-						...(signal ? { signal } : {}), // cooperative per-round abort inside the phase's strategy, not just the engine
-						...strategyTreeDeps(ctx, pid, participantsByNode),
+						signal, // cooperative per-round abort inside the phase's strategy, not just the engine
+						...strategyTreeDeps(ctx, pid, participantsByNode, tracked),
 						...strategySpawnGate(),
 						...modelFallbackDep(ctx),
 					});
@@ -1826,26 +2069,34 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				// boundary, never an informational prompt. Approval is journaled for resume.
 				approveGate: async (phase, result) => {
 					if (!ctx.hasUI) return false;
-					const preview = result.output.replace(/\s+/g, " ").slice(0, 160);
+					const next = spec.phases.filter((p) => p.needs?.includes(phase.id));
+					// The run is the OPERATOR's to release here, not the model's: say so on the tree row and, for a
+					// tracked run, on its peek line — silence at a modal is neither a stall nor a reason to wake anyone.
+					const waiting = `waiting for operator at checkpoint ${phase.id}`;
+					agentTree.update(flowRoot, { detail: waiting });
+					tracked?.onAwaiting(waiting);
 					try {
-						const pick = await ctx.ui.select(`Checkpoint "${phase.id}" — approve and continue the flow?\n${preview}`, ["Approve", "Reject"]);
+						// Reject first: a stray Enter on the default row fails closed. The run signal dismisses
+						// the prompt, so a stopped flow is not held open by a question nobody will answer.
+						const pick = await inGateLine(signal, undefined, () =>
+							ctx.ui.select(gateReviewText({ flow: spec.name, phase: phase.id, next, output: result.output }), ["Reject", "Approve"], { signal }),
+						);
 						return pick === "Approve";
 					} catch {
 						return false;
+					} finally {
+						tracked?.onAwaiting(undefined);
+						agentTree.update(flowRoot, { detail: "", lastAdvanceAt: Date.now() });
 					}
 				},
 			});
-			if (outcome.ok) {
-				try {
-					rmSync(journalPath, { force: true }); // clean journal once the whole flow succeeds
-				} catch {
-					/* ignore */
-				}
-			}
-			agentTree.update(flowRoot, { status: signal?.aborted ? "stopped" : outcome.ok ? "done" : "failed" });
+			if (outcome.ok) clearJournal(journalPath, hash); // this run is finished; other tasks' progress stays
+			// A rejected checkpoint is a pause the operator chose, not a failure (same call as the flow tool).
+			const disposition = flowDisposition(outcome);
+			agentTree.update(flowRoot, { status: disposition === "failed" && signal.aborted ? "stopped" : disposition });
 			return outcome;
 		} catch (error) {
-			agentTree.update(flowRoot, { status: signal?.aborted ? "stopped" : "failed" });
+			agentTree.update(flowRoot, { status: signal.aborted ? "stopped" : "failed" });
 			throw error;
 		} finally {
 			clearStops(flowRoot);
@@ -1854,15 +2105,53 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		}
 	}
 
-	// Search/list available models (provider/id), session provider first (★).
-	function searchModels(ctx: ExtensionContext, query?: string): { lines: string[]; total: number; capped: boolean } {
+	// Discovery is acquired once per base model/session. Repeated turns and nudges reuse it;
+	// explicit discovery/refresh replaces it. Execution preflights still consult the live registry.
+	let modelCatalog: { key: string; models: ModelCostMetadata[]; candidates: string | undefined } | undefined;
+	function modelCatalogKey(ctx: ExtensionContext): string {
+		return `${ctx.sessionManager?.getSessionId?.() ?? ""}\0${ctx.model?.provider ?? ""}\0${ctx.model?.id ?? ""}`;
+	}
+	async function refreshModelCatalog(ctx: ExtensionContext, signal: AbortSignal) {
+		// Pi contexts have live getters: capture before awaiting so an old refresh cannot
+		// discard the snapshot acquired after a session or base-model switch.
+		const key = modelCatalogKey(ctx);
+		try {
+			return await ctx.modelRegistry.refresh?.({ signal });
+		} finally {
+			// A failed/aborted refresh may still have updated some providers.
+			if (modelCatalog?.key === key) modelCatalog = undefined;
+		}
+	}
+	function canDiscoverModels(): boolean {
+		const caps = controller.capabilities;
+		return pi.getActiveTools().includes("models") && (!caps || canCallTool(caps, "models"));
+	}
+	function currentModelCatalog(ctx: ExtensionContext, refresh = false) {
+		const key = modelCatalogKey(ctx);
+		if (refresh || modelCatalog?.key !== key) {
+			const models = configuredModels(ctx);
+			modelCatalog = { key, models, candidates: renderNudgeModels(models, ctx.model) };
+		}
+		return modelCatalog;
+	}
+
+	// Default discovery stays near the base model; explicit searches keep the full eligible catalog.
+	function searchModels(ctx: ExtensionContext, query?: string): { lines: string[]; total: number; capped: boolean; shortlist: boolean } {
 		const session = ctx.model?.provider;
 		const isSession = (ref: string): boolean => session !== undefined && ref.startsWith(`${session}/`);
-		const all = configuredModels(ctx).map((m) => `${m.provider}/${m.id}`);
-		const filtered = orderModelRefs(filterModels(all, query ?? ""), session);
+		const catalog = currentModelCatalog(ctx, true).models;
+		const metadata = new Map(catalog.map((m) => [`${m.provider}/${m.id}`, m]));
+		const tiers = modelCostTiers(catalog, shortlistModels(catalog, undefined, Number.MAX_SAFE_INTEGER));
+		const shortlist = !query?.trim();
+		const all = catalog.map((m) => `${m.provider}/${m.id}`);
+		const filtered = orderModelCandidates(filterModels(all, query ?? "").map((ref) => metadata.get(ref)!), ctx.model).map((m) => `${m.provider}/${m.id}`);
 		const cap = 40;
-		const lines = filtered.slice(0, cap).map((r) => `${isSession(r) ? "★ " : "  "}${r}`);
-		return { lines, total: filtered.length, capped: filtered.length > cap };
+		const shown = shortlist
+			? recommendModels(catalog, ctx.model, cap).map((m) => `${m.provider}/${m.id}`)
+			: filtered.slice(0, cap);
+		const self = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+		const lines = shown.map((r) => `${isSession(r) ? "★ " : "  "}${r} ${modelCandidateDetails(metadata.get(r)!, tiers.get(r))}${r === self ? " (you)" : ""}`);
+		return { lines, total: filtered.length, capped: filtered.length > lines.length, shortlist };
 	}
 
 	// The per-turn delegation brief (core/brief.ts): live roster + standing hand-off default,
@@ -1870,11 +2159,19 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	// persona line has no force, and regenerated from the live registry so it cannot desync.
 	// Capability-aware: a persona that denies `delegate` gets none, and the agent list is
 	// filtered to the persona's allowed targets.
+	/** The installed agents the active capabilities allow as delegate targets (all, with no persona). */
+	function delegateTargets(): AgentConfig[] {
+		const caps = controller.capabilities;
+		return caps ? agents.filter((a) => canDelegateTo(caps, a.name)) : agents;
+	}
+
 	function delegationBrief(ctx: ExtensionContext): string | undefined {
 		const caps = controller.capabilities;
 		if (caps && !canFanOut(caps)) return undefined;
-		const targets = caps ? agents.filter((a) => canDelegateTo(caps, a.name)) : agents;
+		const targets = delegateTargets();
 		const delegation = controller.activePersona?.delegation;
+		const canListModels = canDiscoverModels();
+		const candidates = canListModels && ctx.model ? currentModelCatalog(ctx).candidates : undefined;
 		const teamAgents: Record<string, string[]> = {};
 		for (const [name, members] of Object.entries(teams)) teamAgents[name] = members.map((m) => rosterSpec(m).agent);
 		return buildDelegationBrief({
@@ -1887,11 +2184,16 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				...(a.isolation ? { isolation: a.isolation } : {}),
 			})),
 			teams: teamAgents,
-			flows: listFlows(ctx.cwd),
+			// Methods are only taught to a persona that can call them: an allowlist without `council`/`flow` is not
+			// told to convene one (the call would be refused by the capability gate).
+			flows: !caps || canCallTool(caps, "flow") ? flowCatalog(ctx.cwd) : [],
+			...(caps && !canCallTool(caps, "council") ? { council: false } : {}),
+			canListModels,
+			...(candidates ? { modelCandidates: candidates } : {}),
 			standing: controller.activePersona !== undefined,
-			// Interactive sessions delegate in the background by default; headless (`pi -p`)
-			// stays sync (the single turn must carry the result) — mirror that in the copy.
-			asyncDefault: ctx.hasUI === true,
+			// Interactive sessions ALWAYS delegate in the background; headless (`pi -p`) always
+			// blocks (the single turn must carry the result) — mirror that in the copy.
+			background: ctx.hasUI === true,
 			...(delegation?.requireBrief !== undefined ? { requireBrief: delegation.requireBrief } : {}),
 			...(delegation?.outputContract ? { outputContract: delegation.outputContract } : {}),
 			...(delegation?.requireDisjointWrites !== undefined ? { requireDisjointWrites: delegation.requireDisjointWrites } : {}),
@@ -1915,6 +2217,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	function doctorReport(): string {
 		const lines: string[] = [];
 		lines.push(`pi-persona — active: ${controller.activePersona?.label ?? "none"}`);
+		lines.push(`settings: ${settingsFile} (/persona-settings; preferences: next session or Pi /reload)`);
 		lines.push(`engine backend: ${config.engine === "child" ? "child-process" : "in-process"}`);
 		const piVersion = installedPiVersion();
 		lines.push(`pi: ${piVersion ?? "unknown"} (requires ≥ ${MIN_PI_VERSION})${piVersion && !satisfiesFloor(piVersion, MIN_PI_VERSION) ? " — BELOW FLOOR" : ""}`);
@@ -1942,7 +2245,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			lines.push(`data root migration: moved ${dataRootMigration.moved.length}, kept ${dataRootMigration.kept.length} (legacy pi-persona root folded into ${personaDataDir()})`);
 		}
 		for (const warning of dataRootMigration.warnings) lines.push(warning);
-		lines.push(`personas (${personas.length}): ${personas.map((p) => p.name).join(", ") || "—"}`);
+		lines.push(`personas (${personas.length}): ${personas.map((p) => p.name).join(", ") || NO_PERSONAS_HINT}`);
 		lines.push(`agents (${agents.length}): ${agents.map((a) => a.name).join(", ") || "—"}`);
 		if (definitionCollisions.length > 0) {
 			lines.push(`definition collisions (${definitionCollisions.length}, omitted): ${definitionCollisions.map((collision) => collision.name).join(", ")}`);
@@ -1997,7 +2300,14 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		get lastCtx() { return lastCtx; },
 		set lastCtx(value) { lastCtx = value; },
 		get disposed() { return disposed; },
-		set disposed(value) { disposed = value; },
+		set disposed(value) {
+			disposed = value;
+			if (value) {
+				cancelAgentWidgetRender();
+				widgetClock.stop();
+				wakeRows.clearMonitors();
+			}
+		},
 		get orchestrating() { return orchestrating; },
 		set orchestrating(value) { orchestrating = value; },
 		get processingDeferredOrchestration() { return processingDeferredOrchestration; },
@@ -2017,6 +2327,8 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		telemetryAgent,
 		delegationNudge,
 		persistenceNudge,
+		pollGuard,
+		tracker,
 		appendNudgeEntry,
 		completionNotifier,
 		intercomNotifier,
@@ -2062,6 +2374,20 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 	};
 	installHooks(pi, hookHost, exocom);
 
+	// ONE launch pool for every background run: a delegate leg, a `council` and a `flow` each take a slot
+	// (maxConcurrency). The strategy SDK's own per-run semaphore gates the legs INSIDE a council or flow.
+	const launchPool = new Semaphore(RUN_LIMITS.maxConcurrency);
+	const backgroundRuns = createBackgroundRuns({
+		tracker,
+		agentTree,
+		stopRegistry,
+		slots: launchPool,
+		completionNotifier,
+		startPeek,
+		childUsage,
+		publishPersonaCost,
+	});
+
 	registerDelegateTool(pi, {
 		get lastCtx() { return lastCtx; },
 		set lastCtx(value) { lastCtx = value; },
@@ -2070,21 +2396,16 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		contractNames: () => installedContractNames(contractDefs),
 		buildEngine,
 		agentTree,
-		nextRootId,
 		tracker,
+		runs: backgroundRuns,
+		launchPool,
 		config: { ledgerV2: config.ledgerV2 },
 		RUN_LIMITS,
 		publishAgentTool,
 		stopRegistry,
 		steerRegistry,
-		stopRequested,
-		ensurePersonaModels,
-		clearStops,
-		clearSteers,
 		drainBusBlock,
 		startPeek,
-		childUsage,
-		publishPersonaCost,
 	});
 
 // ── f8 cycle ────────────────────────────────────────────────────────────────
@@ -2092,7 +2413,10 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		description: "Cycle persona (pi-persona)",
 		handler: async (ctx: ExtensionContext) => {
 			lastCtx = ctx;
-			if (personas.length === 0) return;
+			if (personas.length === 0) {
+				if (ctx.hasUI) ctx.ui.notify(NO_PERSONAS_HINT, "info");
+				return;
+			}
 			const current = controller.activePersona;
 			const idx = current ? personas.findIndex((p) => p.name === current.name) : -1;
 			const next = idx + 1;
@@ -2130,14 +2454,13 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		SUPERVISOR,
 		STALL_FLAG_MS,
 		waitingRunIds: waitingAsyncRunIds,
+		pollGuard,
 		missingRunMessage,
 		stopAgent,
 		steerAgent,
 		steerRegistry,
 		stopRequested,
-		drainBusBlock,
 		scanForSurrender,
-		get disposed() { return disposed; },
 		childUsage,
 		publishPersonaCost,
 	});
@@ -2152,6 +2475,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		set lastCtx(value) { lastCtx = value; },
 		canRun: canRunMonitor,
 		monitors,
+		archive: monitorArchive,
 	});
 
 	registerCouncilTool(pi, {
@@ -2160,9 +2484,8 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		controller,
 		get personas() { return personas; },
 		runStrategyVisible,
+		runs: backgroundRuns,
 		drainBusBlock,
-		childUsage,
-		publishPersonaCost,
 	});
 
 	registerFlowTool(pi, {
@@ -2171,8 +2494,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		loadFlow,
 		listFlows,
 		runFlowVisible,
-		childUsage,
-		publishPersonaCost,
+		runs: backgroundRuns,
 	});
 
 // ── f9: navigable agent overlay ──────────────────────────────────────────────
@@ -2191,6 +2513,67 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		},
 	});
 
+	// The dedicated settings surface never replaces Pi's /settings and never calls /reload.
+	registerPersonaSettings(pi, {
+		file: settingsFile,
+		companions: () => collectCompanionSettings(pi.events),
+		activeConfig: config,
+		env: process.env,
+		read: () => {
+			savedSettings = readPersonaSettings(settingsFile);
+			personaConfigs = savedSettings.personas;
+			return savedSettings;
+		},
+		write: (patch) => {
+			savedSettings = patchPersonaSettings(settingsFile, patch);
+			personaConfigs = savedSettings.personas;
+		},
+		isCurrent: (ctx) => !disposed && !ctx.signal?.aborted &&
+			(ctx.sessionManager?.getSessionId?.() === undefined ||
+				lastCtx?.sessionManager?.getSessionId?.() === ctx.sessionManager.getSessionId()),
+		diagnostics: doctorReport,
+		models: async (ctx) => {
+			lastCtx = ctx;
+			personaConfigs = readConfigStore();
+			const session = ctx.sessionManager?.getSessionId?.();
+			await openPersonaModelSettings(ctx, {
+				owners: () => personas.map((persona) => ({ name: persona.name, label: persona.label })),
+				activeOwner: () => controller.activePersona?.name,
+				profiles: (owner) => {
+					const persona = personas.find((p) => p.name === owner);
+					return [
+						...(persona?.orchestration?.strategy ? [{ name: "@orchestration", label: "Automatic orchestration" }] : []),
+						...personas.filter((p) => p.name !== owner && (p.council?.strategy || p.council?.members || p.council?.membersProblem))
+							.map((p) => ({ name: p.name, label: `Council: ${p.label}` })),
+					];
+				},
+				participants: (owner, profile) => {
+					const persona = personas.find((p) => p.name === owner);
+					if (!persona) throw new Error(`persona "${owner}" is no longer installed`);
+					const orchestrationStrategy = persona.orchestration?.strategy;
+					if (profile === "@orchestration" && orchestrationStrategy && persona.orchestration) {
+						const orchestration = persona.orchestration;
+						const panel = resolveOrchestrationMembers(orchestration, teams);
+						return runParticipants(ctx, { strategy: orchestrationStrategy, members: panel,
+							...(orchestration.params ? { params: orchestration.params } : {}) }, owner);
+					}
+					const resolved = resolveCouncilInvocation(personas, persona, profile ? { persona: profile } : {});
+					if (!resolved.ok) throw new Error(resolved.error);
+					const { strategy, roster, members, params } = resolved.value;
+					const panel = resolveOrchestrationMembers({ roster, ...(members ? { members } : {}) }, teams);
+					return runParticipants(ctx, { strategy, members: panel, params }, owner);
+				},
+				saved: (owner) => personaModels(personaConfigs, owner),
+				write: (owner, models) => {
+					savedSettings = patchPersonaSettings(settingsFile, { models: { [owner]: models } });
+					personaConfigs = savedSettings.personas;
+				},
+				isCurrent: () => !disposed && (session === undefined || lastCtx?.sessionManager?.getSessionId?.() === session),
+				refreshCatalog: (signal) => refreshModelCatalog(ctx, signal),
+			});
+		},
+	});
+
 	// ── /persona ─────────────────────────────────────────────────────────────────
 	pi.registerCommand("persona", {
 		description: "Switch persona or edit council models: /persona [name|off|list|reload|seed|restore|models [council-persona]]",
@@ -2219,7 +2602,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 					const panel = resolveOrchestrationMembers({ roster, ...(members ? { members } : {}) }, teams);
 					const deadline = AbortSignal.timeout(20_000);
 					const signal = ctx.signal ? AbortSignal.any([ctx.signal, deadline]) : deadline;
-					const result = await ctx.modelRegistry.refresh?.({ signal });
+					const result = await refreshModelCatalog(ctx, signal);
 					if (!scope.isCurrent()) {
 						ctx.ui.notify("persona models: persona or session changed; no assignments changed.", "warning");
 						return;
@@ -2291,14 +2674,8 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				return;
 			}
 			if (arg === "" || arg === "list") {
-				// Empty by design on a fresh install: personas load only from the user dir, which the
-				// user populates on purpose. Point them at the install gesture rather than leaving a
-				// bare "(none)" that reads like something is broken.
 				if (personas.length === 0) {
-					ctx.ui.notify(
-						"No personas installed. pi-persona does not auto-install — run `/persona seed` to copy the bundled defaults into your agent dir (edit them freely; `/persona restore` re-installs the originals).",
-						"info",
-					);
+					ctx.ui.notify(NO_PERSONAS_HINT, "info");
 					return;
 				}
 				const lines = personas.map(
@@ -2380,16 +2757,16 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 
 	// ── /models + a `models` tool — discover/search model ids ─────────────────────
 	pi.registerCommand("models", {
-		description: "List or search available models (provider/id): /models [query]",
+		description: "Show model candidates or search the full catalog (provider/id): /models [query]",
 		handler: async (args, ctx) => {
 			lastCtx = ctx;
-			const { lines, total, capped } = searchModels(ctx, args);
+			const { lines, total, capped, shortlist } = searchModels(ctx, args);
 			if (lines.length === 0) {
 				ctx.ui.notify(`models: no match for "${args.trim()}"`, "warning");
 				return;
 			}
-			const head = `models (${total}${capped ? ", showing 40" : ""})${ctx.model ? ` · session ★ ${ctx.model.provider}/${ctx.model.id}` : ""}`;
-			ctx.ui.notify(`${head}\n${lines.join("\n")}${capped ? "\n…refine with /models <query>" : ""}`, "info");
+			const head = `models (${total}${shortlist || capped ? `, showing ${lines.length}${shortlist ? " nearby family/version candidates" : " matches"}` : ""})${ctx.model ? ` · session ★ ${ctx.model.provider}/${ctx.model.id}` : ""}`;
+			ctx.ui.notify(`${head}\n${lines.join("\n")}\nAccount support may vary.${shortlist || capped ? " Search the full catalog with /models <query>." : ""}`, "info");
 		},
 	});
 
@@ -2437,11 +2814,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 					return;
 				}
 				try {
-					const outcome = await runFlowVisible(ctx, parsed.flow, task);
-					appendCommandResult(`flow ${orch.flow}`, outcome.output || "(flow produced no output)", outcome.ok, {
-						...(outcome.failureKind ? { failureKind: outcome.failureKind } : {}),
-						...(outcome.error ? { error: outcome.error } : {}),
-					});
+					appendFlowResult(orch.flow, await runFlowVisible(ctx, parsed.flow, task));
 				} catch (err) {
 					ctx.ui.notify(`orchestrate failed: ${err instanceof Error ? err.message : String(err)}`, "error");
 				}
@@ -2460,7 +2833,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			}
 			try {
 				const result = await runStrategyVisible(ctx, orch, task, "orchestrate");
-				appendCommandResult(
+				appendOperatorResult(
 					`orchestrate ${strategyName}`,
 					result?.output || "(no output)",
 					result?.ok ?? false,
@@ -2482,9 +2855,15 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 			lastCtx = ctx;
 			const trimmed = args.trim();
 			if (!trimmed || trimmed === "list") {
-				const flows = listFlows(ctx.cwd);
+				const flows = flowCatalog(ctx.cwd);
 				ctx.ui.notify(
-					flows.length ? `flows: ${flows.join(", ")}  ·  /flow <name> <task>` : "no flows — add a *.flow.json under .pi/flows/",
+					flows.length
+						? [
+							"flows — /flow <name> <task>",
+							...flows.map((f) =>
+								`  ${f.name}${f.description ? ` — ${compactInlineText(f.description, { maxChars: 96 })}` : ""}${f.gated ? " [pauses at a checkpoint for your approval]" : ""}`),
+						].join("\n")
+						: "no flows found — the bundled ones did not load (check the pi-persona install); your own go in .pi/flows/*.flow.json",
 					"info",
 				);
 				return;
@@ -2506,11 +2885,7 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				return;
 			}
 			try {
-				const outcome = await runFlowVisible(ctx, parsed.flow, task);
-				appendCommandResult(`flow ${name}`, outcome.output || "(flow produced no output)", outcome.ok, {
-					...(outcome.failureKind ? { failureKind: outcome.failureKind } : {}),
-					...(outcome.error ? { error: outcome.error } : {}),
-				});
+				appendFlowResult(name, await runFlowVisible(ctx, parsed.flow, task));
 			} catch (err) {
 				ctx.ui.notify(`flow failed: ${err instanceof Error ? err.message : String(err)}`, "error");
 			}