@aeondave/pi-persona 1.17.0 → 1.17.1

package/src/core/settings.ts

@@ -0,0 +1,251 @@
+/** Public, persistable pi-persona preferences and their resolved runtime config. */
+
+import { isThinkingLevel } from "./types.ts";
+import { resolveConfig, type PiPersonaConfig } from "./config.ts";
+
+export type CompanionId = "mind" | "flow";
+
+/** Preferences contributed by the optional companion extensions to the shared settings panel. */
+export interface CompanionPreferenceValues {
+	mindCapture: "auto" | "prompt" | "off";
+	mindNudge: boolean;
+	flowEnabled: boolean;
+	flowPort: number;
+	flowIdleMs: number;
+}
+
+export type PersonaPreferences = Partial<Omit<PiPersonaConfig, "disabled" | "stateFile"> & CompanionPreferenceValues>;
+export type SettingId = keyof PersonaPreferences;
+export type SettingKind = "boolean" | "number" | "string" | "string-list" | "choice";
+
+export interface PersonaSetting {
+	readonly id: SettingId;
+	readonly group: string;
+	readonly label: string;
+	readonly description: string;
+	readonly kind: SettingKind;
+	readonly choices?: readonly string[];
+	readonly env?: string;
+	readonly applyWhen: string;
+	readonly owner?: CompanionId;
+	readonly min?: number;
+	readonly max?: number;
+}
+
+const APPLY_WHEN = "next Pi restart or native extension reload";
+const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/** The one registry used by settings UI, validation, and environment precedence. */
+export const PERSONA_SETTINGS: readonly PersonaSetting[] = [
+	{ id: "extraDirs", group: "Discovery", label: "Extra persona directories", description: "Additional directories searched for persona and agent definitions.", kind: "string-list", env: "PI_PERSONA_DIRS", applyWhen: APPLY_WHEN },
+	{ id: "defaultPersona", group: "Startup", label: "Default persona", description: "Persona selected unless --persona is explicit; takes precedence over the remembered persona.", kind: "string", env: "PI_PERSONA_DEFAULT", applyWhen: APPLY_WHEN },
+	{ id: "keybinding", group: "Interface", label: "Persona cycle key", description: "Key used to cycle through installed personas.", kind: "string", env: "PI_PERSONA_KEY", applyWhen: APPLY_WHEN },
+	{ id: "persist", group: "Startup", label: "Remember last persona", description: "Restore the last explicitly selected persona in a later session.", kind: "boolean", env: "PI_PERSONA_PERSIST", applyWhen: APPLY_WHEN },
+	{ id: "delegateDefaultAllow", group: "Delegation", label: "Allow delegation by default", description: "Fallback for delegate targets when the persona declares neither an allow nor a deny list; explicit rules take precedence.", kind: "boolean", env: "PI_PERSONA_DELEGATE_DEFAULT", applyWhen: APPLY_WHEN },
+	{ id: "seed", group: "Discovery", label: "Install bundled defaults on first run", description: "Opt in to installing bundled personas and agents once.", kind: "boolean", env: "PI_PERSONA_SEED", applyWhen: APPLY_WHEN },
+	{ id: "childThinking", group: "Delegation", label: "Delegated thinking level", description: "Thinking level forced on delegated child agents.", kind: "choice", choices: ["off", "minimal", "low", "medium", "high", "xhigh", "max"], env: "PI_PERSONA_CHILD_THINKING", applyWhen: APPLY_WHEN },
+	{ id: "engine", group: "Delegation", label: "Sub-agent engine", description: "Run sub-agents in-process or as child Pi processes.", kind: "choice", choices: ["inproc", "child"], env: "PI_PERSONA_ENGINE", applyWhen: APPLY_WHEN },
+	{ id: "peekEveryMs", group: "Delegation", label: "Progress and stall check interval", description: "Milliseconds between async progress/stall checks; zero disables checks.", kind: "number", env: "PI_PERSONA_PEEK_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
+	{ id: "checkInEveryMs", group: "Delegation", label: "Progress check-in interval", description: "Milliseconds between operator-only progress entries; zero disables check-ins.", kind: "number", env: "PI_PERSONA_CHECKIN_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
+	{ id: "agentHardTimeoutMs", group: "Delegation", label: "Agent hard timeout", description: "Opt-in wall-clock limit in milliseconds for one agent run; zero means unlimited.", kind: "number", env: "PI_PERSONA_AGENT_MAX_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
+	{ id: "agentStartupTimeoutMs", group: "Delegation", label: "Agent startup deadline", description: "Milliseconds allowed without first progress while an agent starts; zero disables the deadline.", kind: "number", env: "PI_PERSONA_AGENT_STARTUP_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
+	{ id: "nudge", group: "Delegation", label: "Delegation nudges", description: "Delegation and persistence checkpoints; disabling silences both.", kind: "boolean", env: "PI_PERSONA_NUDGE", applyWhen: APPLY_WHEN },
+	{ id: "broker", group: "Collaboration", label: "Cross-process communication broker", description: "Connect child-engine agents to supervisor messaging and steering.", kind: "boolean", env: "PI_PERSONA_BROKER", applyWhen: APPLY_WHEN },
+	{ id: "exocom", group: "Collaboration", label: "External agent communication", description: "Enable communication between independent top-level Pi instances.", kind: "boolean", env: "PI_PERSONA_EXOCOM", applyWhen: APPLY_WHEN },
+	{ id: "asyncRetain", group: "Delegation", label: "Retained async results", description: "Number of settled async runs retained for later collection.", kind: "number", env: "PI_PERSONA_ASYNC_RETAIN", applyWhen: APPLY_WHEN, min: 1, max: MAX_SAFE_INTEGER },
+	{ id: "ledgerV2", group: "Delegation", label: "Expanded retry-loop identity", description: "Include role, tools, and isolation in the repeated-delegation guard key.", kind: "boolean", env: "PI_PERSONA_LEDGER_V2", applyWhen: APPLY_WHEN },
+	{ id: "spine", group: "Prompt", label: "Supervisor spine", description: "Shared prompt layer for the supervisor: off, on for the bundled layer, or a file path.", kind: "string", env: "PI_PERSONA_SPINE", applyWhen: APPLY_WHEN },
+	{ id: "spineLegs", group: "Prompt", label: "Delegated-leg spine", description: "Prompt layer for delegated agents; follows the supervisor selection unless set separately.", kind: "string", env: "PI_PERSONA_SPINE_LEGS", applyWhen: APPLY_WHEN },
+	{ id: "changeReport", group: "Delegation", label: "Report files changed by agents", description: "Include a git-based changed-files report for non-worktree agent runs.", kind: "boolean", env: "PI_PERSONA_LEG_CHANGE_REPORT", applyWhen: APPLY_WHEN },
+	{ id: "mindCapture", group: "Mind", label: "Memory capture mode", description: "Capture explicit user requests (auto), suggest only (prompt), or disable cue detection (off). The memory tool remains available.", kind: "choice", choices: ["auto", "prompt", "off"], env: "PI_PERSONA_MIND_CAPTURE", owner: "mind", applyWhen: "next Pi restart or native extension reload" },
+	{ id: "mindNudge", group: "Mind", label: "Mind suggestions", description: "Optional memory/backlog suggestions, not explicit user capture. Only the exact environment value off disables them.", kind: "boolean", env: "PI_PERSONA_MIND_NUDGE", owner: "mind", applyWhen: "next Pi restart or native extension reload" },
+	{ id: "flowEnabled", group: "Flow", label: "Attach Flow by default", description: "Enable this Pi's default dashboard attachment. --no-flow opts out for one run; other Pi sessions keep their shared service.", kind: "boolean", owner: "flow", applyWhen: "next Pi restart or native extension reload" },
+	{ id: "flowPort", group: "Flow", label: "Flow shared-service port", description: "Desired loopback port; 0 asks the operating system for an available port. Invalid extension environment values fall back to 7874.", kind: "number", env: "PI_PERSONA_FLOW_PORT", owner: "flow", applyWhen: "next shared-service start after Pi restart or native extension reload; an existing service is unchanged", min: 0, max: 65_535 },
+	{ id: "flowIdleMs", group: "Flow", label: "Flow idle grace (advanced)", description: "Milliseconds with no Pi registrations and no browser SSE clients before service shutdown (50–60000). Invalid environment values use 60000 with a Flow warning.", kind: "number", env: "PI_PERSONA_FLOW_IDLE_MS", owner: "flow", applyWhen: "next shared-service start after Pi restart or native extension reload; an existing service is unchanged", min: 50, max: 60_000 },
+];
+
+const SETTING_BY_ID = new Map<SettingId, PersonaSetting>(PERSONA_SETTINGS.map((setting) => [setting.id, setting]));
+
+function hasExplicitEnvOverride(setting: PersonaSetting, env: Record<string, string | undefined>): boolean {
+	if (!setting.env) return false;
+	const value = env[setting.env];
+	if (value === undefined) return false;
+	// The existing resolver deliberately treats an empty legs selector as "follow spine".
+	return setting.id === "spineLegs" && value.trim() === "" ? false : true;
+}
+
+/**
+ * Whether a defined environment key pins a setting using the existing resolver semantics.
+ * Even a value the resolver normalizes/rejects still pins its resulting default; the one
+ * deliberate exception is blank PI_PERSONA_SPINE_LEGS, which means "follow spine".
+ */
+export function settingHasEnvironmentOverride(
+	setting: PersonaSetting | SettingId,
+	env: Record<string, string | undefined>,
+): boolean {
+	const definition = typeof setting === "string" ? SETTING_BY_ID.get(setting) : setting;
+	return definition ? hasExplicitEnvOverride(definition, env) : false;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value) as unknown;
+	return prototype === Object.prototype || prototype === null;
+}
+
+function validateValue(setting: PersonaSetting, value: unknown): unknown {
+	switch (setting.kind) {
+		case "boolean":
+			if (typeof value !== "boolean") throw new Error(`invalid preference ${setting.id}: expected a boolean`);
+			return value;
+		case "number":
+			if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+				throw new Error(`invalid preference ${setting.id}: expected a safe integer`);
+			}
+			if (setting.min !== undefined && value < setting.min) throw new Error(`invalid preference ${setting.id}: must be at least ${setting.min}`);
+			if (setting.max !== undefined && value > setting.max) throw new Error(`invalid preference ${setting.id}: must be at most ${setting.max}`);
+			return value;
+		case "string":
+			if (typeof value !== "string") throw new Error(`invalid preference ${setting.id}: expected a string`);
+			if (setting.id === "defaultPersona" || setting.id === "keybinding") {
+				const normalized = value.trim();
+				if (!normalized) throw new Error(`invalid preference ${setting.id}: value must not be blank`);
+				return normalized;
+			}
+			return value;
+		case "string-list":
+			if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+				throw new Error(`invalid preference ${setting.id}: expected a list of strings`);
+			}
+			return [...value];
+		case "choice":
+			if (typeof value !== "string" || !setting.choices?.includes(value)) {
+				throw new Error(`invalid preference ${setting.id}: expected one of ${setting.choices?.join(", ") ?? "the listed choices"}`);
+			}
+			if (setting.id === "childThinking" && !isThinkingLevel(value)) {
+				throw new Error(`invalid preference ${setting.id}: unsupported thinking level`);
+			}
+			return value;
+	}
+}
+
+/** Validate JSON-sourced preferences strictly. Unknown keys are rejected so a typo cannot hide. */
+export function validatePreferences(value: unknown): PersonaPreferences {
+	if (!isPlainObject(value)) throw new Error("invalid persona preferences: expected an object");
+	const preferences: Record<string, unknown> = {};
+	for (const [key, item] of Object.entries(value)) {
+		if (!SETTING_BY_ID.has(key as SettingId)) {
+			throw new Error(`unknown persona preference: ${key}`);
+		}
+		const setting = SETTING_BY_ID.get(key as SettingId);
+		if (!setting) throw new Error(`unknown persona preference: ${key}`);
+		Object.defineProperty(preferences, key, {
+			value: validateValue(setting, item), enumerable: true, configurable: true, writable: true,
+		});
+	}
+	return preferences as PersonaPreferences;
+}
+
+/** Resolve startup settings: environment values remain explicit overrides over saved preferences. */
+export function resolvePersonaConfig(
+	preferences: PersonaPreferences,
+	env: Record<string, string | undefined>,
+): PiPersonaConfig {
+	const saved = validatePreferences(preferences);
+	const config = resolveConfig(env);
+	for (const setting of PERSONA_SETTINGS) {
+		if (setting.owner !== undefined) continue;
+		if (settingHasEnvironmentOverride(setting, env)) continue;
+		if (!Object.hasOwn(saved, setting.id)) continue;
+		const value = saved[setting.id];
+		if (value === undefined) continue;
+		if (setting.id === "spine") {
+			if (typeof value !== "string") throw new Error("invalid saved spine preference");
+			config.spine = resolveConfig({ PI_PERSONA_SPINE: value }).spine;
+		} else if (setting.id === "spineLegs") {
+			if (typeof value !== "string") throw new Error("invalid saved spineLegs preference");
+			config.spineLegs = resolveConfig({ PI_PERSONA_SPINE_LEGS: value }).spineLegs;
+		} else {
+			Object.assign(config, { [setting.id]: Array.isArray(value) ? [...value] : value });
+		}
+	}
+	const savedSpine = Object.hasOwn(saved, "spine") && env.PI_PERSONA_SPINE === undefined;
+	const savedLegs = Object.hasOwn(saved, "spineLegs") && !settingHasEnvironmentOverride("spineLegs", env);
+	const envLegsFollow = env.PI_PERSONA_SPINE_LEGS === undefined || env.PI_PERSONA_SPINE_LEGS.trim() === "";
+	if (savedSpine && !savedLegs && envLegsFollow) config.spineLegs = config.spine;
+	return config;
+}
+
+function resolveMindCapture(value: string | undefined): CompanionPreferenceValues["mindCapture"] {
+	const normalized = value?.trim().toLowerCase();
+	return normalized === "prompt" || normalized === "off" ? normalized : "auto";
+}
+
+function resolveFlowPort(value: string | undefined): number {
+	if (value === undefined || !/^\d+$/.test(value)) return 7874;
+	const port = Number(value);
+	return Number.isSafeInteger(port) && port >= 0 && port <= 65_535 ? port : 7874;
+}
+
+function resolveFlowIdleMs(value: string | undefined): number {
+	if (value === undefined || !/^\d+$/.test(value)) return 60_000;
+	const idleMs = Number(value);
+	return Number.isSafeInteger(idleMs) && idleMs >= 50 && idleMs <= 60_000 ? idleMs : 60_000;
+}
+
+/** Resolve pi-persona config plus companion previews using the companions' current env grammar. */
+export function resolveSettingsValues(
+	preferences: PersonaPreferences,
+	env: Record<string, string | undefined>,
+): PiPersonaConfig & CompanionPreferenceValues {
+	const saved = validatePreferences(preferences);
+	const config = resolvePersonaConfig(saved, env);
+	const values: CompanionPreferenceValues = {
+		mindCapture: resolveMindCapture(env.PI_PERSONA_MIND_CAPTURE),
+		mindNudge: env.PI_PERSONA_MIND_NUDGE !== "off",
+		flowEnabled: true,
+		flowPort: resolveFlowPort(env.PI_PERSONA_FLOW_PORT),
+		flowIdleMs: resolveFlowIdleMs(env.PI_PERSONA_FLOW_IDLE_MS),
+	};
+	for (const setting of PERSONA_SETTINGS) {
+		if (setting.owner === undefined || settingHasEnvironmentOverride(setting, env)) continue;
+		if (!Object.hasOwn(saved, setting.id)) continue;
+		const value = saved[setting.id];
+		if (value !== undefined) Object.assign(values, { [setting.id]: Array.isArray(value) ? [...value] : value });
+	}
+	return { ...config, ...values };
+}
+
+/** Parse the text field used by a settings editor according to registry metadata. */
+export function parseSettingInput(setting: PersonaSetting, text: string): unknown {
+	switch (setting.kind) {
+		case "boolean": {
+			const value = text.trim().toLowerCase();
+			if (["true", "on", "yes", "1"].includes(value)) return true;
+			if (["false", "off", "no", "0"].includes(value)) return false;
+			throw new Error(`invalid ${setting.id}: enter true or false`);
+		}
+		case "number": {
+			const trimmed = text.trim();
+			if (!trimmed) throw new Error(`invalid ${setting.id}: enter a number`);
+			const value = Number(trimmed);
+			return validateValue(setting, value);
+		}
+		case "string":
+			return validateValue(setting, text);
+		case "string-list":
+			if (text.trimStart().startsWith("[")) {
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(text) as unknown;
+				} catch {
+					throw new Error(`invalid ${setting.id}: expected a JSON string array or one item per line`);
+				}
+				return validateValue(setting, parsed);
+			}
+			return validateValue(setting, text.split(/\r?\n/).map((item) => item.trim()).filter(Boolean));
+		case "choice":
+			return validateValue(setting, text.trim());
+	}
+}

package/src/engine/adapter.ts

@@ -153,7 +153,7 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			if (isPositiveFiniteMs(spec.timeoutMs)) childOptions.timeoutMs = spec.timeoutMs;
 			if (onProgress) {
 				childOptions.onProgress = (snap) =>
-					onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
+					onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
 			}
 			// The run aborts if EITHER the whole-run signal or this agent's own (UI stop) fires.
 			const signal = combineSignals(deps.signal, callSignal);

package/src/engine/async.ts

@@ -50,6 +50,8 @@ export interface AsyncRun {
 	 *  rose) — NOT merely the last event. A worker looping without headway keeps emitting but
 	 *  never bumps this, so `now - lastAdvanceAt` is what tells "working" from "stuck". */
 	lastAdvanceAt?: number;
+	/** Waiting for semaphore admission; queued time is not agent execution time. */
+	queued?: boolean;
 	/** Internal bookkeeping: true once the completion listeners have fired for this entry. Guards a
 	 *  force-settle racing the run thunk's natural resolution so listeners fire exactly once. Lives on
 	 *  the entry (not a side Set) so it survives pruning and the `launch` closure still sees it. */
@@ -93,7 +95,7 @@ export class AsyncRunTracker {
 		this.maxRetained = opts?.maxRetained ?? 25;
 	}
 
-	launch(meta: { agent: string; task: string; label?: string; model?: string; mutates?: boolean }, run: RunThunk): string {
+	launch(meta: { agent: string; task: string; label?: string; model?: string; mutates?: boolean; queued?: boolean }, run: RunThunk): string {
 		this.seq += 1;
 		const id = `run-${this.seq.toString(36)}`;
 		const startedAt = this.now(); // one clock read, so the launch and stall stamps cannot disagree
@@ -104,7 +106,7 @@ export class AsyncRunTracker {
 			status: "running",
 			progress: { output: "", turns: 0, tokens: 0 },
 			startedAt,
-			lastAdvanceAt: startedAt,
+			...(meta.queued ? { queued: true } : { lastAdvanceAt: startedAt }),
 		};
 		if (meta.mutates) entry.mutates = true;
 		// Labels/models are rendered as trusted status metadata on several compact surfaces. Normalize
@@ -122,10 +124,12 @@ export class AsyncRunTracker {
 		try {
 			Promise.resolve(
 				run((s) => {
-					// Only a REAL advance (more output, or a higher turn/token count) resets the stall
-					// clock — a repeated identical snapshot from a spinning worker must not mask a stall.
+					// Newly emitted textual tool output is a progress advance. Use the injected clock,
+					// never the stream's event timestamp, for stall-age accounting.
 					const prev = entry.progress;
-					if (s.output.length > prev.output.length || s.tokens > prev.tokens || s.turns > prev.turns) {
+					const toolOutputAdvanced = s.toolOutputAt !== undefined && Number.isFinite(s.toolOutputAt)
+						&& s.toolOutputAt >= 0 && s.toolOutputAt !== prev.toolOutputAt;
+					if (!entry.queued && (s.output.length > prev.output.length || s.tokens > prev.tokens || s.turns > prev.turns || toolOutputAdvanced)) {
 						entry.lastAdvanceAt = this.now();
 					}
 					entry.progress = s;
@@ -179,6 +183,15 @@ export class AsyncRunTracker {
 		}
 	}
 
+	/** Start the stall window when a queued run actually acquires its concurrency slot. */
+	markAdmitted(id: string): boolean {
+		const entry = this.runs.get(id);
+		if (!entry || entry.status !== "running" || entry.settled || entry.queued !== true) return false;
+		delete entry.queued;
+		entry.lastAdvanceAt = this.now();
+		return true;
+	}
+
 	/**
 	 * Force a still-"running" run to settle as stopped and fire its completion listeners. Escape hatch
 	 * for a run whose hard-stop handle is gone (consumed by a prior abort, or never registered) while
@@ -445,6 +458,12 @@ export function clipRunOutput(text: string, id: string, maxChars: number, label
 	return `${text.slice(0, headChars)}${marker}${tailChars > 0 ? text.slice(-tailChars) : ""}`;
 }
 
+export function isAsyncRunStalled(run: AsyncRun, now: number, stallMs: number): boolean {
+	return run.status === "running" && run.queued !== true && stallMs > 0
+		&& run.lastAdvanceAt !== undefined && Number.isFinite(run.lastAdvanceAt) && run.lastAdvanceAt >= 0
+		&& now - run.lastAdvanceAt >= stallMs;
+}
+
 export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs?: number; waitingForSupervisor?: ReadonlySet<string> }): string {
 	if (runs.length === 0) return "No async runs.";
 	const running = runs.filter((r) => r.status === "running").length;
@@ -460,10 +479,11 @@ export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs
 		const head = `[${r.id}] ${name} — ${r.status}`;
 		if (r.status === "running") {
 			let line = `${head} (${r.progress.turns} turns, ${compactTokens(r.progress.tokens)} cumulative input + output tokens)`;
-			if (opts?.waitingForSupervisor?.has(r.id)) line += " · waiting for supervisor";
-			else if (now !== undefined && stallMs !== undefined && stallMs > 0 && r.lastAdvanceAt !== undefined) {
-				const stalledFor = now - r.lastAdvanceAt;
-				if (stalledFor >= stallMs) line += ` ⚠ possibly stuck (no progress for ${Math.round(stalledFor / 1000)}s)`;
+			if (r.queued) line += " · queued (waiting for concurrency slot)";
+			else if (opts?.waitingForSupervisor?.has(r.id)) line += " · waiting for supervisor";
+			else if (now !== undefined && stallMs !== undefined && isAsyncRunStalled(r, now, stallMs)) {
+				const stalledFor = now - r.lastAdvanceAt!;
+				line += ` ⚠ possibly stuck (no progress for ${Math.round(stalledFor / 1000)}s)`;
 			}
 			return line;
 		}
@@ -490,8 +510,22 @@ export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs
  * forgotten. Pure w.r.t. the injected `now`, so it is unit-tested without a real clock.
  */
 export class PeekWatcher {
-	/** runId → the `lastAdvanceAt` value at which we reported it stalled (a later advance re-arms). */
+	/** runId → the `lastAdvanceAt` value at which the operator episode was reported. */
 	private readonly reportedAt = new Map<string, number>();
+	/** Runs whose one lifetime model stall wake was successfully delivered. */
+	private readonly modelWoken = new Set<string>();
+
+	firstWakeCandidates(runs: AsyncRun[]): AsyncRun[] {
+		return runs.filter((run) => !this.modelWoken.has(run.id));
+	}
+
+	acknowledgeModelWake(runIds: readonly string[]): void {
+		for (const id of runIds) this.modelWoken.add(id);
+	}
+
+	retryReports(runs: readonly AsyncRun[]): void {
+		for (const run of runs) this.reportedAt.delete(run.id);
+	}
 
 	/** The running legs that have NEWLY crossed the stall window since we last reported them. */
 	poll(runs: AsyncRun[], now: number, stallMs: number, waitingForSupervisor: ReadonlySet<string> = new Set()): AsyncRun[] {
@@ -500,6 +534,10 @@ export class PeekWatcher {
 		for (const r of runs) {
 			if (r.status !== "running") continue;
 			live.add(r.id);
+			if (r.queued) {
+				this.reportedAt.delete(r.id);
+				continue;
+			}
 			if (waitingForSupervisor.has(r.id)) {
 				this.reportedAt.delete(r.id); // a live ask is not a stall; re-evaluate immediately when it settles
 				continue;
@@ -507,7 +545,7 @@ export class PeekWatcher {
 			if (r.lastAdvanceAt === undefined) continue;
 			const prev = this.reportedAt.get(r.id);
 			if (prev !== undefined && r.lastAdvanceAt > prev) this.reportedAt.delete(r.id); // advanced ⇒ re-arm
-			if (stallMs > 0 && now - r.lastAdvanceAt >= stallMs && !this.reportedAt.has(r.id)) {
+			if (isAsyncRunStalled(r, now, stallMs) && !this.reportedAt.has(r.id)) {
 				this.reportedAt.set(r.id, r.lastAdvanceAt);
 				newlyStuck.push(r);
 			}
@@ -519,6 +557,7 @@ export class PeekWatcher {
 	/** Forget all tracked state (session start / reload hygiene). */
 	reset(): void {
 		this.reportedAt.clear();
+		this.modelWoken.clear();
 	}
 }
 
@@ -548,8 +587,9 @@ export function buildPeekAlert(stuck: AsyncRun[], opts: { now: number }): string
 }
 
 /** The operator-only periodic status card. It carries the progress digest without model instructions. */
-export function buildCheckIn(runs: AsyncRun[], opts: { now: number; stallMs: number; waitingForSupervisor?: ReadonlySet<string> }): string {
-	return `Async activity · routine check-in\n\n${buildPeekDigest(runs, opts)}`;
+export function buildCheckIn(runs: AsyncRun[], opts: { now: number; stallMs: number; waitingForSupervisor?: ReadonlySet<string>; reason?: "routine" | "stall" }): string {
+	const reason = opts.reason ?? "routine";
+	return `Async activity · ${reason === "stall" ? "possible stall" : "routine check-in"}\n\n${buildPeekDigest(runs, opts)}`;
 }
 
 /**

package/src/engine/child.ts

@@ -242,7 +242,7 @@ export async function runChildAgent(
 			const onLine = (line: string) => {
 				if (!line.trim()) return;
 				try {
-					const toolEvent = applyEvent(state, JSON.parse(line));
+					const toolEvent = applyEvent(state, JSON.parse(line), Date.now());
 					// Ordinary stream progress stays coalesced to one snapshot per stdout chunk below.
 					// Tool lifecycle transitions are the exception: several can share one chunk and each
 					// authoritative transition must cross the progress seam exactly once.

package/src/engine/inproc.ts

@@ -666,7 +666,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			// One progress tick, routed exactly as the subscription routes them: the per-call sink
 			// takes the AgentProgress shape (no `turns`), else the construction-time sink.
 			const emitProgress = (snap: ProgressSnapshot): void => {
-				if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
+				if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
 				else if (deps.onProgress) deps.onProgress(snap);
 			};
 			let contractDef: ContractDef | undefined = requestedDef;
@@ -674,7 +674,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			try {
 				unsub = session.subscribe((ev) => {
 					armIdle(); // any event = activity → reset the idle clock
-					const toolEvent = applyEvent(state, ev);
+					const toolEvent = applyEvent(state, ev, Date.now());
 					// Track the open calls so an abandoned one can be closed once the run settles.
 					if (toolEvent) {
 						if (toolEvent.phase === "start") openToolCalls.set(toolEvent.callId, toolEvent.name);
@@ -735,7 +735,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 							// launch path (extension.ts) only has the latter.
 							const snap = snapshot(state);
 							const activity = `✉ from ${env.from}`;
-							if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, activity });
+							if (onProgress) onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), activity });
 							else if (deps.onProgress) deps.onProgress({ ...snap, activity });
 						}
 					};

package/src/engine/stream.ts

@@ -61,6 +61,8 @@ export interface StreamState {
 	/** Calls whose start was surfaced but whose end has not arrived. This is not a retention
 	 *  cache: active ids are never evicted merely because completed calls churn. */
 	activeToolCalls?: Set<string>;
+	/** Timestamp of the latest textual tool_execution_update, used only as a liveness signal. */
+	toolOutputAt?: number;
 	/** Recently completed call ids whose start/end phase was surfaced. Both caches are bounded;
 	 *  they suppress duplicate wire events without growing for the lifetime of a long run. */
 	seenToolStarts?: Set<string>;
@@ -236,7 +238,7 @@ function appendTranscript(state: StreamState, chunk: string, sep: string): void
 
 /** Fold one parsed stream event into the accumulating state (in place), returning a
  * deduplicated structured lifecycle transition when the runtime supplied a stable call id. */
-export function applyEvent(state: StreamState, event: unknown): ToolEvent | undefined {
+export function applyEvent(state: StreamState, event: unknown, observedAt?: number): ToolEvent | undefined {
 	if (!isObject(event)) return undefined;
 
 	// Track the current tool so the UI can show "running: grep src/…" while a
@@ -271,6 +273,20 @@ export function applyEvent(state: StreamState, event: unknown): ToolEvent | unde
 		return toolEvent;
 	}
 
+	if (event.type === "tool_execution_update") {
+		const callId = event.toolCallId;
+		const toolName = event.toolName;
+		const partialResult = event.partialResult;
+		const hasText = isObject(partialResult) && Array.isArray(partialResult.content)
+			&& partialResult.content.some((part) => isObject(part) && part.type === "text" && typeof part.text === "string" && part.text.length > 0);
+		if (typeof callId === "string" && callId.length > 0
+			&& typeof toolName === "string" && toolName.length > 0
+			&& state.activeToolCalls?.has(callId) === true && hasText && observedAt !== undefined) {
+			state.toolOutputAt = observedAt;
+		}
+		return undefined;
+	}
+
 	// Live partial: pi streams the growing message as `message_update` events. Surface
 	// its text (or reasoning) so a long-thinking agent shows progress, not just tokens.
 	// ONLY the assistant's own message counts: pi also emits message_start/message_end for
@@ -341,6 +357,8 @@ export interface ProgressSnapshot {
 	tokens: number;
 	/** The tool currently running (e.g. "grep src/…"), if any. */
 	activity?: string;
+	/** Timestamp of the latest textual tool output update, when available. */
+	toolOutputAt?: number;
 	/** One authoritative runtime tool lifecycle transition, when this snapshot is event-driven. */
 	toolEvent?: ToolEvent;
 }
@@ -354,6 +372,7 @@ export function snapshot(state: StreamState, toolEvent?: ToolEvent): ProgressSna
 		tokens: state.usage.input + state.usage.output,
 	};
 	if (state.activity !== undefined) snap.activity = state.activity;
+	if (state.toolOutputAt !== undefined) snap.toolOutputAt = state.toolOutputAt;
 	if (toolEvent !== undefined) snap.toolEvent = toolEvent;
 	return snap;
 }

package/src/extension/companion-settings.ts

@@ -0,0 +1,29 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import { PERSONA_SETTINGS, validatePreferences, type CompanionPreferenceValues } from "../core/settings.ts";
+
+export const COMPANION_SETTINGS_CHANNEL = "pi-persona:settings:collect:v1";
+export interface CompanionSettingsSnapshot {
+	mind?: Partial<Pick<CompanionPreferenceValues, "mindCapture" | "mindNudge">>;
+	flow?: Partial<Pick<CompanionPreferenceValues, "flowEnabled" | "flowPort" | "flowIdleMs">>;
+}
+
+/** Synchronous, optional discovery on Pi's public bus. No plugin import, model request or writer. */
+export function collectCompanionSettings(bus: Pick<EventBus, "emit"> | undefined): CompanionSettingsSnapshot {
+	const snapshot: CompanionSettingsSnapshot = {};
+	if (!bus) return snapshot;
+	try {
+		bus.emit(COMPANION_SETTINGS_CHANNEL, { add: (id: unknown, values: unknown): void => {
+			if (id !== "mind" && id !== "flow") return;
+			if (!values || typeof values !== "object" || Array.isArray(values)) return;
+			const keys = PERSONA_SETTINGS.filter((setting) => setting.owner === id).map((setting) => setting.id);
+			const reportedKeys = Object.keys(values);
+			if (reportedKeys.length === 0 || !reportedKeys.every((key) => keys.includes(key as keyof CompanionPreferenceValues))) return;
+			try {
+				const validated = validatePreferences(values);
+				if (id === "mind") snapshot.mind = validated as Partial<Pick<CompanionPreferenceValues, "mindCapture" | "mindNudge">>;
+				else snapshot.flow = validated as Partial<Pick<CompanionPreferenceValues, "flowEnabled" | "flowPort" | "flowIdleMs">>;
+			} catch { /* A malformed contribution is not an editable settings owner. */ }
+		} });
+	} catch { /* Keep valid responses if another extension listener throws. */ }
+	return snapshot;
+}