@aeondave/pi-persona 1.17.1 → 1.17.3

package/src/core/config.ts

@@ -7,6 +7,10 @@
 
 import { isThinkingLevel } from "./types.ts";
 
+/** Settled-but-uncollected async runs retained by default. Equal to the `tasks` cap (RUN_LIMITS.maxChildren,
+ *  64), so one maximum-width call can never evict its own first results before the batch is delivered. */
+export const DEFAULT_ASYNC_RETAIN = 64;
+
 export interface PiPersonaConfig {
 	disabled: boolean;
 	extraDirs: string[];
@@ -24,14 +28,14 @@ export interface PiPersonaConfig {
 	/** Engine backend for sub-agents: "inproc" (run in-process via `createAgentSession`,
 	 *  the default) or "child" (spawn `pi -p`, the baseline). */
 	engine?: "child" | "inproc";
-	/** Fast stall/message wakeup interval (ms): while async children run, a tick checks progress but
-	 *  stays SILENT unless a leg NEWLY looks stalled or a sub-agent messaged the supervisor — so a
+	/** Fast stall/message tick (ms): while async children run, a tick stays SILENT unless a leg NEWLY
+	 *  looks stalled (operator-only card) or a sub-agent messaged the supervisor (model wake), so a
 	 *  healthy run never interrupts. On by default (30000); PI_PERSONA_PEEK_MS=0 opts out (the routine
 	 *  check-in below is independent). */
 	peekEveryMs: number;
 	/** Routine check-in interval (ms): how often, while async children run, the operator gets a durable,
 	 *  expandable compact progress entry. It is status-only and does not start a model turn. Deliberately
-	 *  slow and independent of the fast stall/message wakeup. 300000 (5 min) by default;
+	 *  slow and independent of the fast stall/message tick. 300000 (5 min) by default;
 	 *  PI_PERSONA_CHECKIN_MS=0 opts out. */
 	checkInEveryMs: number;
 	/** Per-agent hard wall-clock cap (ms): an OPT-IN lifetime ceiling. When set (>0) it settles even
@@ -54,8 +58,9 @@ export interface PiPersonaConfig {
 	 *  300000 (5 min) by default; PI_PERSONA_AGENT_STARTUP_MS=0 disables it. */
 	agentStartupTimeoutMs: number;
 	/** Delegation nudge: when a delegating supervisor grinds a RUN of hands-on commands by hand (a
-	 *  by-hand sweep) without a hand-off, append a reminder to the offending tool's result. On by
-	 *  default; PI_PERSONA_NUDGE=off opts out. */
+	 *  by-hand sweep) without a hand-off, append a reminder to the offending tool's result. The same
+	 *  switch gates the call-time wake guards (the repeated peek/result refusal and the long-sleep
+	 *  block). On by default; PI_PERSONA_NUDGE=off opts out of all of them. */
 	nudge: boolean;
 	/** Cross-process broker (spec B1-B7): on by default so child-engine legs (MCP, worktree,
 	 *  `PI_PERSONA_ENGINE=child`) expose the same steer/contact_supervisor plane in-process
@@ -67,9 +72,9 @@ export interface PiPersonaConfig {
 	 *  additionally gated by the persona's canUseBus. */
 	exocom: boolean;
 	/** How many settled-but-uncollected async runs {@link AsyncRunTracker} retains before
-	 *  FIFO-evicting the oldest completed ones. 25 by default (today's hardcoded bound); set
-	 *  PI_PERSONA_ASYNC_RETAIN=<n> (a finite value >= 1) to raise it under heavy fan-out. A
-	 *  value < 1 (junk, negative, or 0 — not a meaningful retention bound) keeps the default. */
+	 *  FIFO-evicting the oldest completed ones. {@link DEFAULT_ASYNC_RETAIN} by default; set
+	 *  PI_PERSONA_ASYNC_RETAIN=<n> (a finite value >= 1) to change it. A value < 1 (junk,
+	 *  negative, or 0 — not a meaningful retention bound) keeps the default. */
 	asyncRetain: number;
 	/** Opt-in wider {@link DelegationLedger} veto key: OFF (default) keys purely on
 	 *  `agent+model+task` (today's veto *behavior* — unchanged; the key bytes themselves have
@@ -171,7 +176,7 @@ export function resolveConfig(env: Env): PiPersonaConfig {
 		// steerable without a hidden env pin. Off-words restore pre-broker spawn env.
 		broker: !isOff(env.PI_PERSONA_BROKER ?? "on"),
 		exocom: false,
-		asyncRetain: 25,
+		asyncRetain: DEFAULT_ASYNC_RETAIN,
 		ledgerV2: false,
 		spine: "",
 		spineLegs: "",
@@ -199,7 +204,7 @@ export function resolveConfig(env: Env): PiPersonaConfig {
 		if (Number.isFinite(startup) && startup >= 0) config.agentStartupTimeoutMs = startup;
 	}
 	// A finite value >= 1 sets the retention bound; 0 isn't meaningful here (unlike the interval
-	// knobs above, where 0 opts out) so it — like junk/negative — falls back to the default 25.
+	// knobs above, where 0 opts out) so it — like junk/negative — falls back to the default.
 	const asyncRetainRaw = env.PI_PERSONA_ASYNC_RETAIN?.trim();
 	if (asyncRetainRaw !== undefined && asyncRetainRaw !== "") {
 		const retain = Number(asyncRetainRaw);

package/src/core/model-catalog.ts

@@ -0,0 +1,171 @@
+/** Compact discovery only: version-shaped ids are a display heuristic, not release dates,
+ * account entitlement or model quality. Keep the full catalog for queries and exact-pin resolution. */
+import type { ModelLite } from "./models.ts";
+import { modelCostRank, modelCostTiers, type ModelCostMetadata } from "./model-tier.ts";
+
+interface CatalogEntry {
+	model: ModelLite;
+	root: string;
+	lane: string;
+	version: string[];
+	snapshot: string | undefined;
+}
+
+const textOrder = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0;
+const refKey = (model: ModelLite): string => `${model.provider}\0${model.id}`;
+
+function entry(model: ModelLite): CatalogEntry {
+	let base = model.id.toLowerCase();
+	let snapshot: string | undefined;
+	// Snapshot tokens can precede adapter suffixes (e.g. -20250514-v1:0). Dots stay
+	// version separators; validate the calendar so arbitrary eight-digit versions survive.
+	base = base.replace(/(^|[-_@/:])((?:19|20)\d{2})-?(\d{2})-?(\d{2})(?=$|[-_@/:])/g, (match: string, prefix: string, yearText: string, monthText: string, dayText: string) => {
+		const year = Number(yearText);
+		const month = Number(monthText);
+		const day = Number(dayText);
+		const parsed = new Date(Date.UTC(year, month - 1, day));
+		if (parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day) {
+			const date = `${yearText}${monthText}${dayText}`;
+			if (snapshot === undefined || date > snapshot) snapshot = date;
+			return prefix;
+		}
+		return match;
+	});
+	// Keep quantity tokens such as 8b/70b/128k as distinct lanes; they are not release versions.
+	const tokens = base.match(/\d+(?:\.\d+)?[bkmt]\b|[\p{L}]+|\d+(?:[._]\d+)*/gu) ?? [];
+	const words = tokens.filter((token) => /\p{L}/u.test(token));
+	const version = tokens.filter((token) => !/\p{L}/u.test(token)).flatMap((token) => token.split(/[._]/).map((part) => part.replace(/^0+(?=\d)/, "")));
+	return {
+		model,
+		root: words[0] ?? base,
+		lane: words.length > 0 && version.length > 0 ? words.join("-") : `opaque:${base}`,
+		version,
+		snapshot,
+	};
+}
+
+/** Descending numeric tuples, without floating-point loss on unusual catalog ids. */
+function versionOrder(a: CatalogEntry, b: CatalogEntry): number {
+	for (let i = 0; i < Math.max(a.version.length, b.version.length); i++) {
+		const left = a.version[i] ?? "0";
+		const right = b.version[i] ?? "0";
+		const order = right.length - left.length || textOrder(right, left);
+		if (order) return order;
+	}
+	return 0;
+}
+
+function representativeOrder(a: CatalogEntry, b: CatalogEntry): number {
+	return versionOrder(a, b)
+		|| Number(a.snapshot !== undefined) - Number(b.snapshot !== undefined)
+		|| textOrder(b.snapshot ?? "", a.snapshot ?? "")
+		|| textOrder(a.model.id, b.model.id);
+}
+
+function candidateOrder(a: CatalogEntry, b: CatalogEntry, session?: ModelLite): number {
+	const active = session ? refKey(session) : undefined;
+	return Number(refKey(a.model) !== active) - Number(refKey(b.model) !== active)
+		|| Number(a.model.provider !== session?.provider) - Number(b.model.provider !== session?.provider)
+		|| textOrder(a.model.provider, b.model.provider)
+		|| textOrder(a.root, b.root)
+		|| versionOrder(a, b)
+		|| textOrder(a.lane, b.lane)
+		|| representativeOrder(a, b);
+}
+
+/** Share a truncated provider's slots across roots; names identify groups, not capabilities. */
+function rotateRoots(candidates: readonly CatalogEntry[], preferredRoot?: string): CatalogEntry[] {
+	const byRoot = new Map<string, CatalogEntry[]>();
+	for (const candidate of candidates) {
+		const group = byRoot.get(candidate.root) ?? [];
+		group.push(candidate);
+		byRoot.set(candidate.root, group);
+	}
+	const groups = [...byRoot.entries()].sort(([a], [b]) =>
+		Number(a !== preferredRoot) - Number(b !== preferredRoot) || textOrder(a, b),
+	).map(([, group]) => group);
+	const rotated: CatalogEntry[] = [];
+	for (let row = 0; rotated.length < candidates.length; row++) {
+		for (const group of groups) {
+			const candidate = group[row];
+			if (candidate) rotated.push(candidate);
+		}
+	}
+	return rotated;
+}
+
+/** Rank full-catalog search matches without collapsing versions or snapshots. */
+export function orderModelCandidates(models: readonly ModelLite[], session?: ModelLite): ModelLite[] {
+	const unique = new Map(models.map((model) => [refKey(model), model]));
+	return [...unique.values()].map(entry).sort((a, b) => candidateOrder(a, b, session)).map((candidate) => candidate.model);
+}
+
+/** One representative per provider/version-line/tier, plus the exact active model even when older.
+ * Named tiers remain separate without a table of model releases. Opaque ids retain lexical order;
+ * within a textual root, numeric generations precede older generations across all its lanes.
+ * Only a provider that exceeds its remaining slots rotates roots, with the active root first. */
+export function shortlistModels(models: readonly ModelLite[], session?: ModelLite, max = 40): ModelLite[] {
+	const limit = Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 40;
+	if (limit === 0) return [];
+	const unique = new Map(models.map((model) => [refKey(model), model]));
+	const active = session ? unique.get(refKey(session)) : undefined;
+	const representatives = new Map<string, CatalogEntry>();
+	for (const model of unique.values()) {
+		const candidate = entry(model);
+		const key = `${model.provider}\0${candidate.lane}`;
+		const previous = representatives.get(key);
+		if (!previous || representativeOrder(candidate, previous) < 0) representatives.set(key, candidate);
+	}
+	const ordered = [...representatives.values()].sort((a, b) => candidateOrder(a, b, session));
+	const byProvider = new Map<string, CatalogEntry[]>();
+	for (const candidate of ordered) {
+		if (active && refKey(candidate.model) === refKey(active)) continue;
+		const group = byProvider.get(candidate.model.provider) ?? [];
+		group.push(candidate);
+		byProvider.set(candidate.model.provider, group);
+	}
+	const selected = active ? [active] : [];
+	for (const [provider, candidates] of byProvider) {
+		const remaining = limit - selected.length;
+		if (remaining === 0) break;
+		const balanced = candidates.length > remaining
+			? rotateRoots(candidates, provider === active?.provider ? entry(active).root : undefined)
+			: candidates;
+		selected.push(...balanced.slice(0, remaining).map((candidate) => candidate.model));
+	}
+	return selected;
+}
+
+/** Recommendation families use the model name after a namespace, unlike rotation's vendor root.
+ * Dots before letters delimit namespace segments; numeric version dots stay in the model name. */
+function recommendationGroup(model: ModelLite): { family: string; major: string | undefined } {
+	const id = model.id.toLowerCase();
+	let nameStart = 0;
+	for (const separator of id.matchAll(/\/|\.(?=\p{L})/gu)) nameStart = separator.index + 1;
+	const name = entry({ provider: model.provider, id: id.slice(nameStart) });
+	return { family: `${id.slice(0, nameStart)}\0${name.root}`, major: name.version[0] };
+}
+
+/** Advisory neighbors of the current model; full queries and exact pins use the full catalog. */
+export function recommendModels(models: readonly ModelCostMetadata[], session?: ModelLite, max = 40): ModelCostMetadata[] {
+	if (!session) return shortlistModels(models, undefined, max);
+	const limit = Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 40;
+	if (limit === 0) return [];
+	const anchor = recommendationGroup(session);
+	const neighbors = models.filter((model) => {
+		if (model.provider !== session.provider) return false;
+		const candidate = recommendationGroup(model);
+		return candidate.family === anchor.family && (anchor.major === undefined || candidate.major === anchor.major);
+	});
+	// Filter before latest-per-lane selection: a newer generation must not erase a neighbor
+	// of an older working supervisor. Price bands keep the full uncapped provider reference.
+	const selected = shortlistModels(neighbors, session, Number.MAX_SAFE_INTEGER).map(entry);
+	const tiers = modelCostTiers(models, shortlistModels(models, undefined, Number.MAX_SAFE_INTEGER));
+	const active = refKey(session);
+	selected.sort((a, b) =>
+		Number(refKey(a.model) !== active) - Number(refKey(b.model) !== active)
+		|| modelCostRank(tiers.get(`${a.model.provider}/${a.model.id}`)) - modelCostRank(tiers.get(`${b.model.provider}/${b.model.id}`))
+		|| candidateOrder(a, b, session),
+	);
+	return selected.slice(0, limit).map((candidate) => candidate.model);
+}

package/src/core/model-tier.ts

@@ -0,0 +1,89 @@
+/** Relative advertised cost within one provider; never capability, throughput, or effort. */
+export type ModelTier = "low" | "medium" | "high";
+
+/** Presentation order only: unknown prices follow known provider-relative bands. */
+export function modelCostRank(tier: ModelTier | undefined): number {
+	return tier === "low" ? 0 : tier === "medium" ? 1 : tier === "high" ? 2 : 3;
+}
+
+export interface ModelCostMetadata {
+	provider: string;
+	id: string;
+	name?: string;
+	reasoning?: boolean;
+	contextWindow?: number;
+	cost?: { input: number; output: number };
+	thinkingLevelMap?: Partial<Record<string, unknown>>;
+}
+
+/**
+ * Rank distinct positive input+output prices within each provider, using an equal-token
+ * input/output proxy. The first ceil(n/3) prices are low, through ceil(2n/3) medium,
+ * and the rest high. Aliases cannot change the cutoffs. At least three distinct prices
+ * are required; missing/zero prices remain unknown. No model names or ids imply a tier.
+ * An uncapped reference keeps labels stable across searches; outside prices clamp to
+ * its low/high bands. These are catalog comparisons, not account billing estimates.
+ */
+export function modelCostTiers(models: readonly ModelCostMetadata[], reference: readonly ModelCostMetadata[] = models): Map<string, ModelTier> {
+	const pricesByProvider = new Map<string, Set<number>>();
+	for (const model of reference) {
+		const price = priceProxy(model);
+		if (price === undefined) continue;
+		let prices = pricesByProvider.get(model.provider);
+		if (!prices) {
+			prices = new Set();
+			pricesByProvider.set(model.provider, prices);
+		}
+		prices.add(price);
+	}
+	const cutoffs = new Map<string, { low: number; medium: number }>();
+	for (const [provider, prices] of pricesByProvider) {
+		if (prices.size < 3) continue;
+		const sorted = [...prices].sort((a, b) => a - b);
+		const low = sorted[Math.ceil(sorted.length / 3) - 1];
+		const medium = sorted[Math.ceil(2 * sorted.length / 3) - 1];
+		if (low !== undefined && medium !== undefined) cutoffs.set(provider, { low, medium });
+	}
+	const tiers = new Map<string, ModelTier>();
+	for (const model of models) {
+		const price = priceProxy(model);
+		const bands = cutoffs.get(model.provider);
+		if (price === undefined || !bands) continue;
+		tiers.set(`${model.provider}/${model.id}`, price <= bands.low ? "low" : price <= bands.medium ? "medium" : "high");
+	}
+	return tiers;
+}
+
+function positiveFinite(value: number | undefined): value is number {
+	return value !== undefined && Number.isFinite(value) && value > 0;
+}
+
+function priceProxy(model: ModelCostMetadata): number | undefined {
+	if (!positiveFinite(model.cost?.input) || !positiveFinite(model.cost?.output)) return undefined;
+	const price = model.cost.input + model.cost.output;
+	if (!positiveFinite(price)) return undefined;
+	// Decimal catalog prices can sum to adjacent binary floats; do not invent a new price rank.
+	const normalized = Number(price.toPrecision(12));
+	return positiveFinite(normalized) ? normalized : undefined;
+}
+
+function shortNumber(value: number): string {
+	return value.toPrecision(3).replace(/(?:\.0+|(\.\d+?)0+)(?=e|$)/, "$1");
+}
+
+function contextLabel(value: number): string {
+	if (value >= 1_000_000) return `${shortNumber(value / 1_000_000)}M`;
+	if (value >= 1_000) return `${shortNumber(value / 1_000)}k`;
+	return shortNumber(value);
+}
+
+/** Host catalog hints; API prices are advertised values, not an OAuth billing estimate. */
+export function modelCandidateDetails(model: ModelCostMetadata, tier?: ModelTier): string {
+	const details: string[] = [`cost:${tier ?? "unknown"}`];
+	if (model.reasoning === true) details.push("reasoning");
+	if (positiveFinite(model.contextWindow)) details.push(`ctx ${contextLabel(model.contextWindow)}`);
+	if (positiveFinite(model.cost?.input) && positiveFinite(model.cost?.output)) {
+		details.push(`API $${shortNumber(model.cost.input)}/$${shortNumber(model.cost.output)} per 1M in/out`);
+	}
+	return `[${details.join("; ")}]`;
+}

package/src/core/models.ts

@@ -46,6 +46,8 @@ export type ModelResolution =
 	| { ok: false; reason: "unknown" | "ambiguous" | "blocked"; candidates: string[] };
 
 const full = (m: ModelLite): string => `${m.provider}/${m.id}`;
+/** Loose-match form of a model ref: lower-case, version dots folded to dashes. */
+const looseKey = (s: string): string => s.toLowerCase().replace(/(\d)\.(?=\d)/g, "$1-");
 
 function dedupe(models: ModelLite[]): ModelLite[] {
 	const seen = new Set<string>();
@@ -118,16 +120,23 @@ export function resolveModelRef(
 	policy?: ModelRoutingPolicy,
 ): ModelResolution {
 	const wanted = ref.trim();
-	const all = models.map(full);
 	const exact = models.find((m) => full(m) === wanted);
 	// An exact provider-qualified pin is an explicit user choice. Never rewrite or reject it
 	// because the current routing policy is intended only for loose automatic selection.
 	if (exact) return { ok: true, ref: wanted };
 
-	// Candidate set: a unique exact id (no provider), else a case-insensitive substring.
+	// Candidate set: a unique exact id (no provider), else a loose match — case-insensitive, dots
+	// and dashes interchangeable in versions ('opus-4.6' ≡ 'opus-4-6'), and a `provider/` prefix
+	// scoping the loose id to that provider's ids ('claude-pro-max-native/opus-4-6').
 	const byId = models.filter((m) => m.id === wanted);
-	const lower = wanted.toLowerCase();
-	const rawCandidates = dedupe(byId.length > 0 ? byId : models.filter((m) => full(m).toLowerCase().includes(lower)));
+	const slash = wanted.indexOf("/");
+	const scopedProvider = slash > 0 ? wanted.slice(0, slash) : undefined;
+	const scoped = scopedProvider ? models.filter((m) => m.provider === scopedProvider) : [];
+	const loose = looseKey(scoped.length > 0 ? wanted.slice(slash + 1) : wanted);
+	const pool = scoped.length > 0 ? scoped : models;
+	const rawCandidates = dedupe(byId.length > 0 ? byId : pool.filter((m) => looseKey(scoped.length > 0 ? m.id : full(m)).includes(loose)));
+	// With nothing to match, the catalog itself is the answer — session provider first.
+	const all = [...models.filter((m) => m.provider === preferProvider), ...models.filter((m) => m.provider !== preferProvider)].map(full);
 	const candidates = policy ? rawCandidates.filter((m) => isModelProviderAllowed(m, policy)) : rawCandidates;
 	if (policy) {
 		const allCandidatesArePolicyBlocked = rawCandidates.length > 0 && rawCandidates.every((m) => allowedModelProviders(m.id, policy) !== undefined && !isModelProviderAllowed(m, policy));

package/src/core/monitor-output.ts

@@ -0,0 +1,85 @@
+/** Pure, bounded terminal-output projection. Raw output must never be replayed as terminal commands. */
+export const MONITOR_OUTPUT_TAIL_CHARS = 4_000;
+
+/** Neutralize display-direction/line controls in complete monitor text; never mutate raw captures. */
+export function neutralizeMonitorUnicode(text: string): string {
+	return text.replace(/[\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").replace(/[\u2028\u2029]/g, " ");
+}
+
+type ControlState = "text" | "escape" | "escapeIntermediate" | "csi" | "osc" | "oscEscape" | "string" | "stringEscape";
+
+/**
+ * One stream's sanitized tail. A fixed-size ring bounds storage even for a giant unterminated
+ * line. Escape parsing keeps only a finite state (no pending payload), independently per stream,
+ * so split/unterminated OSC, CSI and DCS cannot leak into the surrounding display structure.
+ * CR replaces the current progress line; CRLF completes it. This is not a terminal emulator.
+ */
+export class MonitorOutputTail {
+	private readonly chars: string[] = [];
+	private start = 0;
+	private length = 0;
+	private state: ControlState = "text";
+	private carriageReturn = false;
+
+	append(chunk: string): void {
+		for (let i = 0; i < chunk.length; i++) {
+			const char = chunk[i]!;
+			const code = chunk.charCodeAt(i);
+			if (this.state === "osc" || this.state === "string") {
+				if (code === 0x9c || (code === 0x07 && this.state === "osc")) this.state = "text";
+				else if (code === 0x1b) this.state = this.state === "osc" ? "oscEscape" : "stringEscape";
+				continue;
+			}
+			if (this.state === "oscEscape" || this.state === "stringEscape") {
+				if (char === "\\" || code === 0x9c || (code === 0x07 && this.state === "oscEscape")) this.state = "text";
+				else if (code !== 0x1b) this.state = this.state === "oscEscape" ? "osc" : "string";
+				continue;
+			}
+			if (code === 0x1b) { this.state = "escape"; continue; }
+			if (this.state === "escape") {
+				if (char === "[") this.state = "csi";
+				else if (char === "]") this.state = "osc";
+				else if (char === "P" || char === "X" || char === "^" || char === "_") this.state = "string";
+				else this.state = code >= 0x20 && code <= 0x2f ? "escapeIntermediate" : "text";
+				continue;
+			}
+			if (this.state === "escapeIntermediate" || this.state === "csi") {
+				if (code >= (this.state === "csi" ? 0x40 : 0x30) && code <= 0x7e) this.state = "text";
+				continue;
+			}
+			if (code === 0x9b) { this.state = "csi"; continue; }
+			if (code === 0x9d) { this.state = "osc"; continue; }
+			if (code === 0x90 || code === 0x98 || code === 0x9e || code === 0x9f) { this.state = "string"; continue; }
+			if (char === "\r") { this.carriageReturn = true; continue; }
+			if (char === "\n") { this.carriageReturn = false; this.push("\n"); continue; }
+			if (code < 0x20 && code !== 0x09 || code >= 0x7f && code <= 0x9f) continue;
+			// Inert display text must not carry bidi direction overrides or Unicode line separators.
+			if (code >= 0x202a && code <= 0x202e || code >= 0x2066 && code <= 0x2069 || code === 0x200e || code === 0x200f) continue;
+			if (this.carriageReturn) {
+				while (this.length > 0 && this.chars[(this.start + this.length - 1) % MONITOR_OUTPUT_TAIL_CHARS] !== "\n") this.length--;
+				this.carriageReturn = false;
+			}
+			this.push(code === 0x09 || code === 0x2028 || code === 0x2029 ? " " : char);
+		}
+	}
+
+	get text(): string {
+		let text = Array.from({ length: this.length }, (_, i) => this.chars[(this.start + i) % MONITOR_OUTPUT_TAIL_CHARS]!).join("");
+		// Eviction/chunk splits can expose half a surrogate pair: never render that half alone.
+		if (text.charCodeAt(0) >= 0xdc00 && text.charCodeAt(0) <= 0xdfff) text = text.slice(1);
+		const last = text.charCodeAt(text.length - 1);
+		if (last >= 0xd800 && last <= 0xdbff) text = text.slice(0, -1);
+		return text;
+	}
+
+	get preview(): string {
+		const text = this.text.trimEnd();
+		return text.slice(text.lastIndexOf("\n") + 1).trim();
+	}
+
+	private push(char: string): void {
+		this.chars[(this.start + this.length) % MONITOR_OUTPUT_TAIL_CHARS] = char;
+		if (this.length < MONITOR_OUTPUT_TAIL_CHARS) this.length++;
+		else this.start = (this.start + 1) % MONITOR_OUTPUT_TAIL_CHARS;
+	}
+}

package/src/core/monitor.ts

@@ -38,6 +38,13 @@ export interface MonitorEvent {
 	terminal: boolean;
 }
 
+/** Raw process output for UI/log observers only; never a semantic wake event. */
+export interface MonitorOutput {
+	id: string;
+	stream: "stdout" | "stderr";
+	text: string;
+}
+
 export interface MonitorProcessHandlers {
 	onStdout: (chunk: string) => void;
 	onStderr: (chunk: string) => void;
@@ -50,11 +57,22 @@ export interface MonitorProcess {
 }
 
 export interface MonitorManagerDeps {
+	/** Internal activation namespace for persisted ids; not a user-facing monitor parameter. */
+	idPrefix?: string;
 	now: () => number;
 	setTimer: (fn: () => void, ms: number) => unknown;
 	clearTimer: (handle: unknown) => void;
 	start: (spec: MonitorSpec, handlers: MonitorProcessHandlers) => MonitorProcess;
 	onEvent: (event: MonitorEvent) => void;
+	/** Accepted nonempty chunks, BEFORE semantic processing. Never called after terminal/removal.
+	 *  Observer failures are isolated: display/logging cannot change wakes or process lifetime. */
+	onOutput?: (output: MonitorOutput) => void;
+	/** Called once per admitted monitor, BEFORE its process starts (never for a rejected spec).
+	 *  Every announced monitor later reaches exactly one of: a terminal `onEvent`, or `onRemoved`. */
+	onArmed?: (entry: MonitorEntry) => void;
+	/** Called once per monitor dropped WITHOUT a wake event: `cancel`, `cancelAll`, or a start that
+	 *  failed before it ran. A terminal event is never followed by this. */
+	onRemoved?: (entry: MonitorEntry) => void;
 }
 
 export type MonitorArmResult =
@@ -143,7 +161,7 @@ export class MonitorManager {
 		const timeoutMs = request.timeoutMs ?? MONITOR_DEFAULT_TIMEOUT_MS;
 		const maxEvents = request.maxEvents ?? MONITOR_DEFAULT_MAX_EVENTS;
 		const now = this.deps.now();
-		const id = `monitor-${++this.sequence}`;
+		const id = `${this.deps.idPrefix ?? "monitor"}-${++this.sequence}`;
 		const entry: MonitorEntry = {
 			id,
 			label: request.label.trim(),
@@ -169,6 +187,7 @@ export class MonitorManager {
 			lineLength: 0,
 		};
 		this.monitors.set(id, active);
+		this.deps.onArmed?.(copyEntry(entry));
 
 		const handlers: MonitorProcessHandlers = {
 			onStdout: (chunk) => this.receiveStdout(id, chunk),
@@ -282,6 +301,8 @@ export class MonitorManager {
 	private receiveStdout(id: string, chunk: string): void {
 		const active = this.monitors.get(id);
 		if (!active || active.terminal || !chunk) return;
+		this.observeOutput(id, "stdout", chunk);
+		if (active.terminal) return;
 		if (active.entry.mode === "exit") {
 			active.stdoutTail = appendTail(active.stdoutTail, chunk, MONITOR_MAX_DIAGNOSTIC_CHARS);
 			return;
@@ -318,10 +339,20 @@ export class MonitorManager {
 
 	private receiveStderr(id: string, chunk: string): void {
 		const active = this.monitors.get(id);
-		if (!active || active.terminal) return;
+		if (!active || active.terminal || !chunk) return;
+		this.observeOutput(id, "stderr", chunk);
+		if (active.terminal) return;
 		active.stderrTail = appendTail(active.stderrTail, chunk, MONITOR_MAX_DIAGNOSTIC_CHARS);
 	}
 
+	private observeOutput(id: string, stream: MonitorOutput["stream"], text: string): void {
+		try {
+			this.deps.onOutput?.({ id, stream, text });
+		} catch {
+			/* UI/log observers cannot suppress a semantic event or interrupt process cleanup. */
+		}
+	}
+
 	private receiveExit(id: string, code: number | null, signal?: string): void {
 		const active = this.monitors.get(id);
 		if (!active || active.terminal) return;
@@ -411,5 +442,6 @@ export class MonitorManager {
 		} catch {
 			/* best effort; cancellation remains terminal */
 		}
+		this.deps.onRemoved?.(copyEntry(active.entry));
 	}
 }