@aeondave/pi-persona 1.17.0 → 1.17.3

package/src/monitor/archive.ts

@@ -0,0 +1,235 @@
+import {
+	MONITOR_MAX_ARGS, MONITOR_MAX_ARG_CHARS, MONITOR_MAX_ARGV_CHARS,
+	MONITOR_MAX_COMMAND_CHARS, MONITOR_MAX_EVENTS, MONITOR_MAX_LABEL_CHARS,
+	type MonitorEntry, type MonitorEvent, type MonitorOutput,
+} from "../core/monitor.ts";
+
+export const MONITOR_LOG_ENTRY = "pi-persona-monitor-log";
+export const MONITOR_LOG_MAX_STREAM_CHARS = 16 * 1024;
+export const MONITOR_LOG_MAX_TEXT_CHARS = 16 * 1024;
+export const MONITOR_LOG_MAX_RECORDS = 64;
+export const MONITOR_LOG_MAX_BYTES = 2 * 1024 * 1024;
+
+export interface MonitorLogRecord {
+	version: 1;
+	entry: MonitorEntry;
+	outcome: "running" | "exit" | "error" | "timeout" | "cancelled" | "ended";
+	/** Last semantic event's text (not an interleaved raw stream). */
+	text: string;
+	stdout: string;
+	stderr: string;
+	truncated: boolean;
+	storageWarning?: string;
+}
+
+export interface MonitorArchiveDeps {
+	/** Only the owning session's entries; never a global session/history lookup. */
+	entries: () => readonly unknown[];
+	/** Session-native custom data, NOT a model-visible custom message. */
+	append: (customType: string, data: unknown) => void;
+}
+
+const BUDGET_WARNING = "Monitor log persistence unavailable: session archive budget exhausted; this log is retained only in bounded runtime history.";
+const APPEND_WARNING = "Monitor log persistence unavailable: appending the session entry failed; this log is retained only in bounded runtime history.";
+const HISTORY_WARNING = "Monitor log history unavailable: owning-session entries could not be read; persistence is disabled to preserve the session budget.";
+
+function object(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonempty(value: unknown, limit: number): value is string {
+	return typeof value === "string" && value.trim().length > 0 && value.length <= limit && !value.includes("\0");
+}
+
+function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function validEntry(value: unknown): value is MonitorEntry {
+	if (!object(value) || !onlyKeys(value, ["id", "label", "command", "args", "cwd", "mode", "startedAtEpochMs", "expiresAtEpochMs", "maxEvents"])) return false;
+	return nonempty(value.id, 512)
+		&& nonempty(value.label, MONITOR_MAX_LABEL_CHARS)
+		&& nonempty(value.command, MONITOR_MAX_COMMAND_CHARS)
+		&& nonempty(value.cwd, 32_768)
+		&& (value.mode === "output" || value.mode === "exit")
+		&& Array.isArray(value.args) && value.args.length <= MONITOR_MAX_ARGS
+		&& Array.from(value.args).every((arg: unknown) => typeof arg === "string" && arg.length <= MONITOR_MAX_ARG_CHARS && !arg.includes("\0"))
+		&& value.args.reduce((sum: number, arg: string) => sum + arg.length, 0) <= MONITOR_MAX_ARGV_CHARS
+		&& typeof value.startedAtEpochMs === "number" && Number.isFinite(value.startedAtEpochMs) && value.startedAtEpochMs >= 0
+		&& typeof value.expiresAtEpochMs === "number" && Number.isFinite(value.expiresAtEpochMs) && value.expiresAtEpochMs >= value.startedAtEpochMs
+		&& typeof value.maxEvents === "number" && Number.isInteger(value.maxEvents) && value.maxEvents >= 1 && value.maxEvents <= MONITOR_MAX_EVENTS;
+}
+
+function copyEntry(entry: MonitorEntry): MonitorEntry {
+	return {
+		id: entry.id, label: entry.label, command: entry.command, args: [...entry.args],
+		cwd: entry.cwd, mode: entry.mode, startedAtEpochMs: entry.startedAtEpochMs,
+		expiresAtEpochMs: entry.expiresAtEpochMs, maxEvents: entry.maxEvents,
+	};
+}
+
+function copyRecord(record: MonitorLogRecord): MonitorLogRecord {
+	return {
+		version: 1, entry: copyEntry(record.entry), outcome: record.outcome,
+		text: record.text, stdout: record.stdout, stderr: record.stderr, truncated: record.truncated,
+		...(record.storageWarning === undefined ? {} : { storageWarning: record.storageWarning }),
+	};
+}
+
+/** Validate custom-entry DATA for historical operator rendering; never returns input references.
+ * Unknown fields are rejected so serialized metadata cannot hide outside the archive budget. */
+export function parseMonitorLogRecord(value: unknown): MonitorLogRecord | undefined {
+	try {
+		return parseRecord(value);
+	} catch {
+		return undefined;
+	}
+}
+
+function parseRecord(value: unknown): MonitorLogRecord | undefined {
+	if (!object(value) || !onlyKeys(value, ["version", "entry", "outcome", "text", "stdout", "stderr", "truncated", "storageWarning"])
+		|| value.version !== 1 || !validEntry(value.entry)) return undefined;
+	if (value.outcome !== "exit" && value.outcome !== "error" && value.outcome !== "timeout"
+		&& value.outcome !== "cancelled" && value.outcome !== "ended") return undefined;
+	if (typeof value.text !== "string" || value.text.length > MONITOR_LOG_MAX_TEXT_CHARS
+		|| typeof value.stdout !== "string" || value.stdout.length > MONITOR_LOG_MAX_STREAM_CHARS
+		|| typeof value.stderr !== "string" || value.stderr.length > MONITOR_LOG_MAX_STREAM_CHARS
+		|| typeof value.truncated !== "boolean"
+		|| (value.storageWarning !== undefined && (typeof value.storageWarning !== "string" || value.storageWarning.length > 1024))) return undefined;
+	return copyRecord(value as unknown as MonitorLogRecord);
+}
+
+/** UTF-8 uses at most three bytes per UTF-16 code unit, AFTER JSON escaping.
+ * Reserve extra space for the host's custom-entry envelope. Deliberately conservative:
+ * this bounds the archive's serialized records, not arbitrary host/session metadata. */
+function storageCost(record: unknown): number {
+	return (JSON.stringify(record) ?? "null").length * 3 + 256;
+}
+
+/** Bounded, session-native raw logs. No files, processes, timers, wakes, or model messages.
+ * Feed only admitted MonitorManager lifecycles (at most MONITOR_MAX_ACTIVE running entries).
+ * Completed records are oldest-first; the most recent 64 survive in runtime memory.
+ * Hydration runs once, so construct a fresh archive when the owning session changes.
+ * History never restores running monitors. A removed observer has no cause information:
+ * cancellation, permission revocation, shutdown and synchronous start failure all map to cancelled.
+ */
+export class MonitorArchive {
+	private readonly deps: MonitorArchiveDeps;
+	private readonly active = new Map<string, MonitorLogRecord>();
+	private readonly completed = new Map<string, MonitorLogRecord>();
+	private hydrated = false;
+	private persistedCount = 0;
+	private persistedBytes = 0;
+	private historyWarning: string | undefined;
+
+	constructor(deps: MonitorArchiveDeps) {
+		this.deps = deps;
+	}
+
+	armed(entry: MonitorEntry): void {
+		this.hydrate();
+		if (this.active.has(entry.id) || this.completed.has(entry.id)) return;
+		this.active.set(entry.id, {
+			version: 1, entry: copyEntry(entry), outcome: "running", text: "", stdout: "", stderr: "", truncated: false,
+			...(this.historyWarning === undefined ? {} : { storageWarning: this.historyWarning }),
+		});
+	}
+
+	output({ id, stream, text }: MonitorOutput): void {
+		const record = this.active.get(id);
+		if (!record || !text) return;
+		const current = record[stream];
+		if (current.length + text.length > MONITOR_LOG_MAX_STREAM_CHARS) record.truncated = true;
+		// Slice the chunk BEFORE concatenation: a huge callback must not create a huge copy.
+		record[stream] = text.length >= MONITOR_LOG_MAX_STREAM_CHARS
+			? text.slice(-MONITOR_LOG_MAX_STREAM_CHARS)
+			: (current + text).slice(-MONITOR_LOG_MAX_STREAM_CHARS);
+	}
+
+	event(event: MonitorEvent): void {
+		const record = this.active.get(event.id);
+		if (!record) return;
+		record.text = event.text.slice(0, MONITOR_LOG_MAX_TEXT_CHARS);
+		if (event.text.length > MONITOR_LOG_MAX_TEXT_CHARS) record.truncated = true;
+		if (!event.terminal) return;
+		record.outcome = event.kind === "output" ? "ended" : event.kind;
+		this.finish(record);
+	}
+
+	removed(entry: MonitorEntry): void {
+		const record = this.active.get(entry.id);
+		if (!record) return;
+		record.outcome = "cancelled";
+		this.finish(record);
+	}
+
+	result(id: string): MonitorLogRecord | undefined {
+		this.hydrate();
+		const record = this.active.get(id) ?? this.completed.get(id);
+		return record ? copyRecord(record) : undefined;
+	}
+
+	list(): MonitorLogRecord[] {
+		this.hydrate();
+		return [...this.completed.values(), ...this.active.values()].map(copyRecord);
+	}
+
+	private hydrate(): void {
+		if (this.hydrated) return;
+		this.hydrated = true;
+		try {
+			const entries = this.deps.entries();
+			if (!Array.isArray(entries)) throw new Error("invalid session entries");
+			for (const entry of entries) {
+				try {
+					if (!object(entry) || entry.type !== "custom" || entry.customType !== MONITOR_LOG_ENTRY) continue;
+					// Charge even unknown/malformed versions and duplicate ids: ignoring a record
+					// for retrieval does not remove its bytes from an append-only session.
+					this.persistedCount++;
+					this.persistedBytes += storageCost(entry.data);
+					const record = parseMonitorLogRecord(entry.data);
+					if (record) this.remember(record);
+				} catch {
+					// An unaccountable entry cannot safely reset the lifetime budget.
+					this.historyWarning = HISTORY_WARNING;
+				}
+			}
+		} catch {
+			// Without a trustworthy baseline, appending could silently overrun the session quota.
+			this.historyWarning = HISTORY_WARNING;
+		}
+	}
+
+	private finish(record: MonitorLogRecord): void {
+		// Settle BEFORE calling injected persistence; duplicate/reentrant callbacks are inert.
+		this.active.delete(record.entry.id);
+		this.remember(record);
+		if (this.historyWarning !== undefined) {
+			record.storageWarning = this.historyWarning;
+			return;
+		}
+		const cost = storageCost(record);
+		if (this.persistedCount >= MONITOR_LOG_MAX_RECORDS || this.persistedBytes + cost > MONITOR_LOG_MAX_BYTES) {
+			record.storageWarning = BUDGET_WARNING;
+			return;
+		}
+		// Reserve even when append throws: it may have committed before reporting failure.
+		// This also bounds repeated failing append attempts over the runtime's lifetime.
+		this.persistedCount++;
+		this.persistedBytes += cost;
+		try {
+			this.deps.append(MONITOR_LOG_ENTRY, copyRecord(record));
+		} catch {
+			record.storageWarning = APPEND_WARNING;
+		}
+	}
+
+	private remember(record: MonitorLogRecord): void {
+		this.completed.delete(record.entry.id);
+		this.completed.set(record.entry.id, record);
+		while (this.completed.size > MONITOR_LOG_MAX_RECORDS) {
+			const oldest = this.completed.keys().next().value;
+			if (oldest !== undefined) this.completed.delete(oldest);
+		}
+	}
+}

package/src/monitor/session.ts

@@ -1,14 +1,28 @@
 /** Monitor events use the same idle follow-up delivery as timer and Intercom. */
-import { MonitorManager, type MonitorEvent } from "../core/monitor.ts";
+import { MonitorManager, type MonitorEntry, type MonitorEvent, type MonitorOutput } from "../core/monitor.ts";
 import { fenceUntrusted, stripTerminalControls } from "../core/fence.ts";
 import { IdleCoalescingNotifier } from "../engine/async.ts";
 import { startMonitorProcess } from "./process.ts";
 
+/** A passive view of the monitor lifecycle (the agent tree's monitor rows). Every `armed` is followed
+ *  by exactly one of: a terminal `event`, or `removed` (cancel, permission loss, shutdown, start failure).
+ *  Observation never changes admission or delivery. */
+export interface MonitorObserver {
+	armed(entry: MonitorEntry): void;
+	event(event: MonitorEvent): void;
+	removed(entry: MonitorEntry): void;
+	/** Raw process output for bounded local views/storage only; never a wake. */
+	output?(output: MonitorOutput): void;
+}
+
 interface MonitorSessionDeps {
+	/** Activation-unique prefix when results are persisted across reloads. */
+	idPrefix?: string;
 	isIdle(): boolean;
 	canRun(): boolean;
 	deliver(text: string): void;
 	start?: typeof startMonitorProcess;
+	observe?: MonitorObserver;
 }
 
 export function createMonitorSession(d: MonitorSessionDeps) {
@@ -31,7 +45,13 @@ export function createMonitorSession(d: MonitorSessionDeps) {
 	});
 	const manager = new MonitorManager({
 		...timerDeps, now: () => Date.now(), start: d.start ?? startMonitorProcess,
+		...(d.idPrefix ? { idPrefix: d.idPrefix } : {}),
+		...(d.observe ? { onArmed: (entry: MonitorEntry) => d.observe?.armed(entry), onRemoved: (entry: MonitorEntry) => d.observe?.removed(entry) } : {}),
+		onOutput: (output) => { d.observe?.output?.(output); },
 		onEvent: (event) => {
+			// Observed BEFORE the permission gate: a terminal event has already left the manager, so the
+			// `cancelAll` below could never announce it, and its row would stay on screen forever.
+			d.observe?.event(event);
 			if (!d.canRun()) { cancelAll(); return; }
 			const oldest = notifier.peekPending()[0];
 			if (notifier.peekPending().length >= 64 && oldest) {

package/src/orchestration/flow-journal.ts

@@ -1,8 +1,9 @@
 /**
  * Flow journal (v0.5) — JSONL resume. Each completed phase appends one line; on a later
  * run the journal is read back into a resume map (phase id → output) so done phases are
- * skipped. Lines whose `hash` doesn't match the current `flow@hash` are ignored (the flow
- * changed), and a phase recorded `ok:false` is NOT resumed (it re-runs). `parseJournal`
+ * skipped. Lines whose `hash` doesn't match the current run hash (`flowRunHash`: flow + task +
+ * cwd) are ignored (another flow version, task or project), and a phase recorded `ok:false` is
+ * NOT resumed (it re-runs). `parseJournal`
  * and the filename derivation are pure (tested); the read/write helpers are thin `fs` glue.
  */
 
@@ -24,8 +25,9 @@ const PATH_HOSTILE = /[/\\<>:"|?*\x00-\x1f]/g;
  *  name as a filename can be; the `flow@hash` half is what actually keeps journals apart, since
  *  it covers the whole spec (the name included). Two names that encode alike — `ci:quick` and
  *  `ci?quick` — are therefore still two different specs with two different hashes and two
- *  different files, and so is a name long enough to be truncated here. Should a truncated hash
- *  ever collide anyway, every LINE still carries the full one, so a resume reads only its own. */
+ *  different files, and so is a name long enough to be truncated here. Runs of ONE flow on another
+ *  task or project share this file, and a truncated hash could collide: either way every LINE
+ *  carries the full run hash (`flowRunHash`), so a resume reads only its own. */
 export function journalFileName(spec: FlowSpec): string {
 	return `${encodeFlowName(spec.name)}.${flowHash(spec).slice(0, 8)}.journal.jsonl`;
 }
@@ -38,7 +40,7 @@ function encodeFlowName(name: string): string {
 	return encoded || "flow";
 }
 
-/** Fold a JSONL journal into a resume map for the given `flow@hash`. Later lines win, so a
+/** Fold a JSONL journal into a resume map for the given run hash. Later lines win, so a
  *  phase that failed then succeeded ends up resumed; a phase still failed is left to re-run.
  *  A `gateApproved` line marks a checkpoint already approved so a resume doesn't re-prompt. */
 export function parseJournal(content: string, hash: string): Record<string, ResumedResult> {
@@ -74,6 +76,25 @@ export function readJournal(path: string, hash: string): Record<string, ResumedR
 	}
 }
 
+/** A finished run leaves the file: drop ITS lines (unreadable ones too), keep every other run's
+ *  resumable progress, and remove the file once nothing is left. Best-effort. */
+export function clearJournal(path: string, hash: string): void {
+	try {
+		const others = fs.readFileSync(path, "utf8").split("\n").filter((line) => {
+			try {
+				const e = JSON.parse(line) as FlowJournalEntry | null;
+				return !!e && typeof e === "object" && e.hash !== hash;
+			} catch {
+				return false;
+			}
+		});
+		if (others.length === 0) fs.rmSync(path, { force: true });
+		else fs.writeFileSync(path, `${others.join("\n")}\n`);
+	} catch {
+		/* best effort — a journal that cannot be cleaned is only a stale resume candidate */
+	}
+}
+
 /** An appending writer — one JSONL line per completed phase. Best-effort. */
 export function journalWriter(path: string): (entry: FlowJournalEntry) => void {
 	return (entry) => {

package/src/orchestration/flow-run.ts

@@ -40,7 +40,7 @@ export type ResumedResult = AgentResult & { gateApproved?: boolean };
 export interface FlowRunDeps {
 	/** Run one phase's strategy → its result (wraps `runPersonaStrategy` in prod). */
 	runPhase: RunPhaseFn;
-	/** The pinned `flow@hash` for this run (I3) — recorded in every journal line. */
+	/** The pinned run identity (I3: `flowRunHash` = flow + task + cwd) — recorded in every journal line. */
 	hash: string;
 	signal?: AbortSignal;
 	/** Grace an aborted wave gets to unwind cooperatively before its still-running phases are
@@ -71,6 +71,17 @@ export interface FlowOutcome {
 	/** The run signal fired before every phase settled ok. A cancelled flow is NOT the same as one
 	 *  that merely finished without an answer, and callers report it differently. */
 	cancelled?: boolean;
+	/** The first checkpoint (in spec order) that was not approved, when that is the ONLY reason the
+	 *  flow did not finish: a stop the operator chose, not a failure. `ok` stays false and `error`
+	 *  stays "blocked: …" (a mandatory flow must keep failing closed); `output` is the gated
+	 *  phase's own answer plus a stop note. */
+	stoppedAtGate?: string;
+}
+
+/** What a finished flow IS to a reader. A checkpoint the operator declined is a STOP, their choice, never a
+ *  failure: the one predicate the tool result, the tree row and the cards share. */
+export function flowDisposition(outcome: { ok: boolean; stoppedAtGate?: string | undefined }): "done" | "stopped" | "failed" {
+	return outcome.ok ? "done" : outcome.stoppedAtGate !== undefined ? "stopped" : "failed";
 }
 
 /** How long an aborted wave is given to unwind COOPERATIVELY before its still-running phases are
@@ -270,6 +281,12 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 	const failure = cancellation
 		? failures.find((entry) => entry.result.failureKind === "abort")
 		: rootFailures[0] ?? failures[0];
+	// A rejected checkpoint is a STOP, not a failure, only when nothing else went wrong: a real phase
+	// failure or a cancellation is the more important fact and keeps its ordinary report. A rejected
+	// gate with no dependents blocks nothing, so the flow is still `ok` and was not stopped.
+	const stoppedAtGate = !cancellation && !ok && rootFailures.length === 0
+		? spec.phases.find((p) => gateState.get(p.id) === "rejected")?.id
+		: undefined;
 	const failedPhase = failure?.phase.id;
 	const error = cancellation ? (failure?.result.error ?? CANCELLED_ERROR) : failure?.result.error;
 	const failureKind = cancellation ? "abort" as const : failure?.result.failureKind;
@@ -278,24 +295,32 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 		: `Flow failed: ${error ?? "the flow did not complete successfully"}`;
 	const cancellationText = `Flow cancelled${failedPhase ? ` at phase "${failedPhase}"` : ""}: ${error ?? CANCELLED_ERROR}`;
 	const outputAlreadySignalsCancellation = /\b(?:cancel(?:led|lation)?|abort(?:ed)?|stopp?ed)\b/i.test(terminalOutput);
-	const output = cancellation
-		? terminalOutput.trim()
-			? outputAlreadySignalsCancellation
-				? terminalOutput
-				: `${terminalOutput}\n\n${cancellationText}`
-			: cancellationText
-		: terminalOutput.trim()
-			? terminalOutput
-			: failure
-				? failureText
-				: terminalOutput;
+	const terminalReport = (): string => {
+		// A rejected checkpoint answers with the gated phase's own output: that is what the operator was
+		// asked to approve, and dropping it on a "no" would throw away work already paid for. Another
+		// branch that finished keeps its answer beside it.
+		if (stoppedAtGate !== undefined) {
+			return [
+				done.get(stoppedAtGate)?.output ?? "",
+				terminalOutput,
+				`- flow stopped at checkpoint "${stoppedAtGate}": not approved (declined, dismissed, or no interactive session). Later phases did not run.`,
+			].filter((part) => part.trim()).join("\n\n");
+		}
+		if (cancellation) {
+			if (!terminalOutput.trim()) return cancellationText;
+			return outputAlreadySignalsCancellation ? terminalOutput : `${terminalOutput}\n\n${cancellationText}`;
+		}
+		if (terminalOutput.trim()) return terminalOutput;
+		return failure ? failureText : terminalOutput;
+	};
 	return {
 		ok,
 		results,
-		output,
+		output: terminalReport(),
 		...(failedPhase ? { failedPhase } : {}),
 		...(error ? { error } : {}),
 		...(failureKind ? { failureKind } : {}),
 		...(cancelled ? { cancelled: true } : {}),
+		...(stoppedAtGate !== undefined ? { stoppedAtGate } : {}),
 	};
 }

package/src/orchestration/flow.ts

@@ -28,12 +28,19 @@ export interface FlowSpec {
 export type FlowParse = { ok: true; flow: FlowSpec } | { ok: false; error: string };
 export type TopoResult = { ok: true; order: string[] } | { ok: false; error: string };
 
-/** The pinned `flow@hash` for a run (I3): a stable sha256 over the spec, so a hot reload
- *  of the file can't change an in-flight run and a resume only matches the same flow. */
+/** A stable sha256 over the spec — the flow half of a run's identity, and the journal file name's
+ *  hash (`journalFileName`): a hot reload of the file can't change an in-flight run. */
 export function flowHash(spec: FlowSpec): string {
 	return stableHash(spec);
 }
 
+/** The pinned run identity (I3) recorded in every journal line: flow + task + cwd. A resume
+ *  skips finished phases only for the SAME flow on the SAME task in the SAME project; a failed
+ *  `flow X` on task A must never feed its phases' output to `flow X` on task B. */
+export function flowRunHash(spec: FlowSpec, task: string, cwd: string): string {
+	return stableHash({ flow: flowHash(spec), task: task.trim(), cwd });
+}
+
 function isObject(x: unknown): x is Record<string, unknown> {
 	return typeof x === "object" && x !== null && !Array.isArray(x);
 }

package/src/orchestration/reducers.ts

@@ -89,21 +89,25 @@ export function itemLedger(
 	});
 }
 
-/** Combine fan-out results into one labeled-section result; ok iff all ok. */
-export function aggregateResults(results: AgentResult[]): AgentResult {
-	const sections = results.map((r) => {
+/** Combine fan-out results into one labeled-section result; ok iff all ok. `labels` (aligned to
+ *  `results`) name each section by lens or item instead of the bare agent; the label is kept as
+ *  `member` only when it adds something, so a label-free call is byte-identical to before. */
+export function aggregateResults(results: AgentResult[], labels?: readonly string[]): AgentResult {
+	const labelOf = (r: AgentResult, i: number): string => labels?.[i] ?? r.agent;
+	const sections = results.map((r, i) => {
 		const status = r.ok ? "ok" : `failed${r.failureKind ? ` (${r.failureKind})` : ""}`;
 		const body = r.output || r.error || "(no output)";
 		const cause = !r.ok && r.error && r.output && r.error !== r.output ? `\n\nError: ${r.error}` : "";
-		return `### [${r.agent}] ${status}\n\n${body}${cause}`;
+		return `### [${labelOf(r, i)}] ${status}\n\n${body}${cause}`;
 	});
 	const aggregate: AgentResult = {
 		agent: "aggregate",
 		output: sections.join("\n\n---\n\n"),
 		structured: {
 			count: results.length,
-			results: results.map((r) => ({
+			results: results.map((r, i) => ({
 				agent: r.agent,
+				...(labelOf(r, i) !== r.agent ? { member: labelOf(r, i) } : {}),
 				ok: r.ok,
 				output: r.output,
 				error: r.error ?? null,

package/src/orchestration/render.ts

@@ -72,7 +72,7 @@ export function humanizeAggregateResult(r: AgentResult): string | undefined {
 	for (const value of members) {
 		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
 		const member = value as Record<string, unknown>;
-		const agent = typeof member.agent === "string" && member.agent.trim() ? member.agent.trim() : "member";
+		const agent = field(member, "member") ?? field(member, "agent") ?? "member";
 		const ok = member.ok === true;
 		const output = typeof member.output === "string" ? member.output : "";
 		const structured = member.structured && typeof member.structured === "object" && !Array.isArray(member.structured)

package/src/orchestration/sdk.ts

@@ -6,7 +6,7 @@
  */
 
 import type { RunLimits } from "../core/capabilities.ts";
-import { emptyUsage, type ToolEvent } from "../engine/stream.ts";
+import { type ChildUsage, emptyUsage, type ToolEvent } from "../engine/stream.ts";
 import { type JudgePrep, prepareJudge } from "./judge.ts";
 import { planModelRecovery } from "./model-retry.ts";
 import { mapWithConcurrency, Semaphore } from "./parallel.ts";
@@ -53,7 +53,7 @@ export interface AgentRunSpec {
 
 /** Is `x` a genuine positive, finite `timeoutMs` override — vs. absent/junk (undefined, NaN,
  *  Infinity, ≤0), which means "no override, fall back to the run's existing default"? The
- *  ONE predicate every `timeoutMs` site gates on (`specOf`, the single-async delegate path,
+ *  ONE predicate every `timeoutMs` site gates on (`specOf`, the single-leg delegate path,
  *  and both engine adapters), so they can't drift into checking it differently. */
 export function isPositiveFiniteMs(x: number | undefined): x is number {
 	return x !== undefined && Number.isFinite(x) && x > 0;
@@ -65,6 +65,8 @@ export interface AgentProgress {
 	output: string;
 	/** Tokens consumed so far (best-effort). */
 	tokens?: number;
+	/** Copied cumulative counters for display, when supplied by the engine. */
+	usage?: ChildUsage;
 	/** The tool the agent is currently running (e.g. "grep src/…"), if any. */
 	activity?: string;
 	/** One authoritative runtime tool lifecycle transition; never contains tool args or output. */
@@ -105,7 +107,8 @@ export interface StrategySDK {
 	agent(spec: AgentRunSpec, options?: AgentCallOptions): Promise<AgentResult>;
 	parallel<T>(thunks: Array<() => Promise<T>>, opts?: { concurrency?: number }): Promise<T[]>;
 	reduce: {
-		aggregate(results: AgentResult[]): AgentResult;
+		/** `labels` (aligned to `results`) name each section by lens or item instead of the agent. */
+		aggregate(results: AgentResult[], labels?: readonly string[]): AgentResult;
 		vote(candidates: AgentResult[], opts: VoteOpts): ReducerResult;
 		/** Anonymise + label candidates for an impartial judge (run `agent(judge, …)` on
 		 *  the returned ballot, then map the verdict via `pick`). */
@@ -144,6 +147,17 @@ export interface StrategyParam {
 
 export interface Strategy {
 	name: string;
+	/** The problem class this method answers, in one line — rendered into the council tool's
+	 *  description from the registry, so the guidance cannot drift from the code. */
+	when?: string;
+	/** What the roster positions MEAN, where order or role matters (`[splitter, worker]`). */
+	roster?: string;
+	/** The team this method is built for. A call that switches TO this method and names no roster seats it,
+	 *  instead of the profile's roster (the wrong panel for it) or the `magi` fallback (read-only voters). */
+	team?: string;
+	/** Param keys the run cannot proceed without; a call that omits one is refused up front,
+	 *  before any run, tree row or model picker exists. Each must also be declared in `params`. */
+	required?: readonly string[];
 	/** Declared, discoverable params (name → type/default/doc). Consumed by the council tool
 	 *  (warn on unknown keys) and `/doctor`. A strategy with no params omits this. */
 	params?: Record<string, StrategyParam>;

package/src/orchestration/strategies/compete.ts

@@ -62,8 +62,12 @@ function clip(diff: string, max: number): string {
 
 export const compete: Strategy = {
 	name: "compete",
+	when: "rival implementations in worktrees, blind-judged; returns the winning diff (clean git repo)",
+	roster: "competitors",
+	team: "build",
+	required: ["judge"],
 	params: {
-		judge: { type: "agent", doc: "(required) the arbiter agent, or an inline { agent, role?, model?, skills? }" },
+		judge: { type: "agent", doc: "the arbiter agent, or an inline { agent, role?, model?, skills? }" },
 		ballotDiffChars: { type: "number", default: 6000, doc: "ballot-only diff clip length; the winner's diff is always full" },
 	},
 	async run(input, sdk) {

package/src/orchestration/strategies/council-rounds.ts

@@ -78,6 +78,8 @@ function cancelled(rounds: number, usages: AgentResult["usage"][]): AgentResult
 
 export const councilRounds: Strategy = {
 	name: "council-rounds",
+	when: "hard fork needing iterated debate: re-vote each round to a bestOf majority",
+	team: "magi",
 	params: {
 		rounds: { type: "number", default: 3, doc: "max deliberation rounds" },
 		bestOf: { type: "number", doc: "default: majority of the roster" },

package/src/orchestration/strategies/critic-loop.ts

@@ -46,6 +46,9 @@ function cancelled(rounds: number, output: string, usages: AgentResult["usage"][
 
 export const criticLoop: Strategy = {
 	name: "critic-loop",
+	when: "ONE draft + adversarial critique, revised until the critic approves",
+	roster: "[generator, critic]",
+	team: "repair",
 	params: {
 		// `default` must name an agent that ACTUALLY runs (the collector resolves the participant
 		// as: the provided override, else roster[rosterIndex], else this agent) — never a phrase

package/src/orchestration/strategies/debate.ts

@@ -84,6 +84,8 @@ function cancelled(usages: AgentResult["usage"][]): AgentResult {
 
 export const debate: Strategy = {
 	name: "debate",
+	when: "2+ members argue live with each other, then a majority vote",
+	team: "magi",
 	params: {
 		bestOf: { type: "number", doc: "default: majority of the roster" },
 		aggregate: { type: "string", default: "majority", doc: '"majority" | "unanimity"' },

package/src/orchestration/strategies/fanout.ts

@@ -5,16 +5,17 @@
  * No peers: fanout is deliberately independent parallel work — use `debate` for a live exchange.
  */
 
-import { rosterSpec } from "../roster.ts";
+import { rosterNodeKeys, rosterSpec } from "../roster.ts";
 import type { Strategy } from "../sdk.ts";
 
 export const fanout: Strategy = {
 	name: "fanout",
+	when: "ONE question to a panel of distinct lenses/models, answers side by side, no vote (separate tasks → delegate)",
 	async run(input, sdk) {
 		const team = input.roster ? sdk.roster.team(input.roster) : [];
 		if (team.length === 0) throw new Error("fanout: a non-empty roster is required");
 		sdk.log(`fanout: ${team.length} agents on "${input.task.slice(0, 40)}"`);
 		const results = await sdk.parallel(team.map((m) => () => sdk.agent({ ...rosterSpec(m), task: input.task })));
-		return { ...sdk.reduce.aggregate(results), agent: "fanout" };
+		return { ...sdk.reduce.aggregate(results, rosterNodeKeys(team)), agent: "fanout" };
 	},
 };

package/src/orchestration/strategies/judge.ts

@@ -44,8 +44,12 @@ function cancelled(arbiter: string, display: AgentResult[], usage: AgentResult["
 
 export const judge: Strategy = {
 	name: "judge",
+	when: "rival COMPLETE answers: independent panel, one impartial arbiter picks",
+	roster: "the panel",
+	team: "magi",
+	required: ["judge"],
 	params: {
-		judge: { type: "agent", doc: "(required) the arbiter agent, or an inline { agent, role?, model?, skills? }" },
+		judge: { type: "agent", doc: "the arbiter agent, or an inline { agent, role?, model?, skills? }" },
 		contract: { type: "string", doc: "optional output contract the panel runs against" },
 	},
 	async run(input, sdk) {