@aeondave/pi-persona 1.15.2

package/src/orchestration/flow-run.ts

@@ -0,0 +1,301 @@
+/**
+ * Flow runner (v0.5) — execute a {@link FlowSpec} DAG: run every phase's strategy in
+ * dependency order, fanning out phases whose `needs` are all satisfied in parallel,
+ * threading each upstream phase's output into its dependents' task. Journals every
+ * completed phase (one JSONL line) so a later run can RESUME by skipping done phases. A
+ * failed phase blocks its dependents (they can't run without their input). The strategy
+ * runner is injected (`deps.runPhase`), so the DAG logic is engine-agnostic and tested
+ * with a stub.
+ */
+
+import { fenceUntrusted } from "../core/fence.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import type { FlowPhase, FlowSpec } from "./flow.ts";
+import type { AgentResult, FailureKind } from "./types.ts";
+
+export type PhaseStatus = "running" | "done" | "failed";
+
+/** One phase ready to run: its spec, the built task, and its upstream phases' results. */
+export interface FlowPhaseRun {
+	phase: FlowPhase;
+	task: string;
+	upstream: Record<string, AgentResult>;
+}
+
+export type RunPhaseFn = (run: FlowPhaseRun) => Promise<AgentResult>;
+
+/** One journal line — appended as each phase completes (for resume). */
+export interface FlowJournalEntry {
+	phase: string;
+	hash: string;
+	ok: boolean;
+	output: string;
+	/** A gated phase whose checkpoint was approved — so a resume doesn't re-prompt. */
+	gateApproved?: boolean;
+}
+
+/** A resume map value: a phase result plus whether its checkpoint gate was already approved. */
+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. */
+	hash: string;
+	signal?: AbortSignal;
+	/** Grace an aborted wave gets to unwind cooperatively before its still-running phases are
+	 *  force-settled (defaults to {@link ABORT_GRACE_MS}); shrinkable in tests. */
+	abortGraceMs?: number;
+	/** Append one entry as each phase completes. */
+	journal?: (entry: FlowJournalEntry) => void;
+	/** Phases already completed (from a prior run's journal) — skipped, output reused. */
+	resume?: Record<string, ResumedResult>;
+	/** Live UI: phase lifecycle. */
+	onPhase?: (id: string, status: PhaseStatus, result?: AgentResult) => void;
+	/** A gated phase's checkpoint: after it completes, approve before its dependents run.
+	 *  Absent ⇒ gates auto-approve (informational only — headless runs aren't blocked). */
+	approveGate?: (phase: FlowPhase, result: AgentResult) => Promise<boolean>;
+}
+
+export interface FlowOutcome {
+	ok: boolean;
+	results: Record<string, AgentResult>;
+	/** The terminal (sink) phases' combined output — the flow's answer. */
+	output: string;
+	/** The first phase that failed, when a settled result identifies one. */
+	failedPhase?: string;
+	/** The actionable cause of the flow's first failure, or the cancellation cause. */
+	error?: string;
+	/** The machine-readable cause of the flow failure. */
+	failureKind?: FailureKind;
+	/** 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;
+}
+
+/** How long an aborted wave is given to unwind COOPERATIVELY before its still-running phases are
+ *  force-settled as cancelled. A strategy that consults the run signal returns its own (more
+ *  informative) result — the last good draft, the upstream step's output, the usage already
+ *  billed — inside this window; a strategy that ignores the signal must not be able to hold the
+ *  whole run open. Sized for the cooperative path to actually WIN it: a strategy notices at a
+ *  round boundary, and only once its in-flight legs have settled through the engine's abort path
+ *  (an in-process session stop, or a child process tree kill), which is seconds rather than
+ *  milliseconds. The full wait is paid only by a phase that never unwinds at all. */
+const ABORT_GRACE_MS = 5_000;
+
+const CANCELLED_ERROR = "cancelled: the flow run was aborted";
+
+/** Resolves when `signal` aborts — never, when there is none. `dispose` drops the listener, so a
+ *  many-wave run doesn't accumulate one per wave on a long-lived signal. */
+function whenAborted(signal: AbortSignal | undefined): { promise: Promise<void>; dispose: () => void } {
+	if (!signal) return { promise: new Promise<void>(() => { /* never */ }), dispose: () => { /* nothing to drop */ } };
+	let onAbort = (): void => { /* replaced below */ };
+	const promise = new Promise<void>((resolve) => {
+		onAbort = (): void => resolve();
+		if (signal.aborted) resolve();
+		else signal.addEventListener("abort", onAbort, { once: true });
+	});
+	return { promise, dispose: () => signal.removeEventListener("abort", onAbort) };
+}
+
+/** Await `p`, but give up after `ms`. The timer is unref'd: a pending grace must never be the
+ *  reason a process stays alive. */
+function within(p: Promise<unknown>, ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		const timer = setTimeout(resolve, ms);
+		timer.unref?.();
+		const settle = (): void => {
+			clearTimeout(timer);
+			resolve();
+		};
+		void p.then(settle, settle);
+	});
+}
+
+/** Build a phase's task: the base task plus each upstream phase's output as context. */
+function buildPhaseTask(baseTask: string, spec: FlowSpec, phase: FlowPhase, upstream: Record<string, AgentResult>): string {
+	const parts = [`Flow "${spec.name}" — phase "${phase.id}" (strategy: ${phase.strategy}).`, baseTask];
+	const ups = Object.entries(upstream);
+	if (ups.length > 0) {
+		parts.push("\nUpstream results to build on:");
+		for (const [id, r] of ups) parts.push(`\n--- ${id} ---\n${fenceUntrusted(r.output)}`);
+	}
+	return parts.join("\n");
+}
+
+export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDeps): Promise<FlowOutcome> {
+	const byId = new Map(spec.phases.map((p) => [p.id, p]));
+	// A gated phase only satisfies its dependents once its checkpoint is "passed" (or it blocks
+	// them once "rejected"). Resume pre-seeds gates the journal already recorded as approved.
+	const gateState = new Map<string, "passed" | "rejected">();
+	const done = new Map<string, AgentResult>();
+	for (const [id, r] of Object.entries(deps.resume ?? {})) {
+		const gated = byId.get(id)?.gate === true;
+		// A gated phase resumed as ok but WITHOUT a recorded approval (the process died between
+		// journaling its completion and its gate decision) must RE-RUN, not be treated as done —
+		// otherwise it sits in `done` with an unresolved gate and its dependents can never run.
+		if (gated && r.ok && !(r as ResumedResult).gateApproved) continue;
+		done.set(id, r);
+		if (gated && (r as ResumedResult).gateApproved) gateState.set(id, "passed");
+	}
+	// A FAILED gated phase has no checkpoint to resolve — its gate must not keep dependents
+	// from being considered (needFailed then records them "blocked", exactly like a failed
+	// non-gated need; otherwise they'd never become ready and silently vanish, stuck ⏳).
+	const gateResolved = (id: string): boolean => !byId.get(id)?.gate || gateState.has(id) || done.get(id)?.ok === false;
+	const needFailed = (n: string): boolean => (done.has(n) && !done.get(n)?.ok) || gateState.get(n) === "rejected";
+	let remaining = spec.phases.filter((p) => !done.has(p.id));
+	let cancelled = false;
+	// Keep blocked dependents distinct from phases that actually ran and failed. The flow's
+	// declaration order is not necessarily topological, so a dependent can appear before the
+	// root failure in `spec.phases`; it must never hide that root cause in the final outcome.
+	const blockedPhaseIds = new Set<string>();
+
+	while (remaining.length > 0) {
+		if (deps.signal?.aborted) {
+			cancelled = true;
+			break;
+		}
+		// A phase can be considered once every need is done AND any gated need is resolved.
+		const ready = remaining.filter((p) => (p.needs ?? []).every((n) => done.has(n) && gateResolved(n)));
+		if (ready.length === 0) break; // acyclic + progress guarantees this can't happen
+
+		// A phase whose any need FAILED or whose gate was REJECTED is blocked — record, don't run.
+		const blocked = ready.filter((p) => (p.needs ?? []).some((n) => needFailed(n)));
+		for (const p of blocked) {
+			blockedPhaseIds.add(p.id);
+			const gateReject = (p.needs ?? []).some((n) => gateState.get(n) === "rejected");
+			const error = gateReject ? "blocked: a checkpoint gate was not approved" : "blocked: an upstream phase failed";
+			const r: AgentResult = { agent: p.id, output: "", usage: emptyUsage(), ok: false, error };
+			done.set(p.id, r);
+			deps.onPhase?.(p.id, "failed", r);
+			deps.journal?.({ phase: p.id, hash: deps.hash, ok: false, output: "" });
+		}
+
+		const runnable = ready.filter((p) => !blocked.includes(p));
+		// Phases that produced their own result. Anything still missing when an aborted wave's
+		// grace expires is force-settled below, so a run-level abort can cut a wave already in
+		// flight instead of waiting on strategies that never consult the signal.
+		const settled = new Map<string, AgentResult>();
+		let forced = false;
+		const wave = Promise.all(
+			runnable.map(async (p): Promise<void> => {
+				deps.onPhase?.(p.id, "running");
+				const upstream: Record<string, AgentResult> = {};
+				for (const n of p.needs ?? []) {
+					const u = done.get(n);
+					if (u) upstream[n] = u;
+				}
+				const task = buildPhaseTask(baseTask, spec, p, upstream);
+				// A throwing phase (e.g. a misconfigured strategy) is a phase FAILURE, not a
+				// crashed DAG — record it failed so its dependents block and the flow finishes.
+				let r: AgentResult;
+				try {
+					r = await deps.runPhase({ phase: p, task, upstream });
+				} catch (err) {
+					const error = err instanceof Error ? err.message : String(err);
+					r = { agent: p.id, output: "", usage: emptyUsage(), ok: false, error };
+				}
+				// The run already gave up on this phase and moved on. Its UI node is torn down and
+				// its outcome is already reported, so re-drive neither — but work that DID complete
+				// is still worth keeping: journal it so a RESUME reuses the output instead of paying
+				// for the same phase a second time. A late FAILURE is not journaled — there is
+				// nothing to reuse, and a resume has to re-run it anyway.
+				if (forced) {
+					if (r.ok) deps.journal?.({ phase: p.id, hash: deps.hash, ok: true, output: r.output });
+					return;
+				}
+				settled.set(p.id, r);
+				deps.onPhase?.(p.id, r.ok ? "done" : "failed", r);
+				deps.journal?.({ phase: p.id, hash: deps.hash, ok: r.ok, output: r.output });
+			}),
+		);
+
+		const abort = whenAborted(deps.signal);
+		try {
+			await Promise.race([wave, abort.promise]);
+			if (deps.signal?.aborted) await within(wave, deps.abortGraceMs ?? ABORT_GRACE_MS);
+		} finally {
+			abort.dispose();
+		}
+		if (deps.signal?.aborted) {
+			forced = true;
+			for (const p of runnable) {
+				if (settled.has(p.id)) continue;
+				// `failureKind: "abort"` is the distinction every other layer keys on (the strategies'
+				// own cancelled results carry it) — without it a phase the USER stopped reads to its
+				// consumers as one that simply failed.
+				const r: AgentResult = { agent: p.id, output: "", usage: emptyUsage(), ok: false, error: CANCELLED_ERROR, failureKind: "abort" };
+				settled.set(p.id, r);
+				deps.onPhase?.(p.id, "failed", r);
+				// Deliberately NOT journaled: the phase produced nothing, so a resume has to re-run
+				// it rather than skip it as done.
+			}
+		}
+		for (const [id, r] of settled) done.set(id, r);
+		if (deps.signal?.aborted) {
+			// Gates are skipped on the way out — an aborted run must not stop to prompt for a
+			// checkpoint nobody is waiting on.
+			cancelled = spec.phases.some((p) => done.get(p.id)?.ok !== true);
+			break;
+		}
+
+		// Resolve checkpoint gates for phases that just completed OK — sequentially, so the
+		// next readiness pass sees each gate's verdict (a rejected gate blocks its dependents).
+		for (const [id, r] of settled) {
+			const phase = byId.get(id);
+			if (!phase?.gate || !r.ok || gateState.has(id)) continue;
+			const approved = deps.approveGate ? await deps.approveGate(phase, r) : true;
+			gateState.set(id, approved ? "passed" : "rejected");
+			if (approved) deps.journal?.({ phase: id, hash: deps.hash, ok: true, output: r.output, gateApproved: true });
+		}
+		remaining = remaining.filter((p) => !done.has(p.id));
+	}
+
+	const results: Record<string, AgentResult> = Object.fromEntries(done);
+	const needed = new Set(spec.phases.flatMap((p) => p.needs ?? []));
+	const terminals = spec.phases.filter((p) => !needed.has(p.id));
+	const terminalOutput = terminals
+		.map((p) => done.get(p.id)?.output ?? "")
+		.filter((s) => s.trim())
+		.join("\n\n---\n\n");
+	const ok = spec.phases.every((p) => done.get(p.id)?.ok ?? false);
+	const failures = spec.phases
+		.map((phase) => ({ phase, result: done.get(phase.id) }))
+		.filter((entry): entry is { phase: FlowPhase; result: AgentResult } => entry.result !== undefined && !entry.result.ok);
+	const rootFailures = failures.filter((entry) => !blockedPhaseIds.has(entry.phase.id));
+	const cancellation = cancelled;
+	// Cancellation is authoritative: a normal failure from an earlier phase must not replace the
+	// user's stop with an ordinary failure classification. Prefer an explicitly aborted phase when
+	// one settled, otherwise keep the cancellation at flow level without inventing a failed phase.
+	const failure = cancellation
+		? failures.find((entry) => entry.result.failureKind === "abort")
+		: rootFailures[0] ?? failures[0];
+	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;
+	const failureText = failedPhase
+		? `Flow failed at phase "${failedPhase}": ${error ?? "the phase failed"}`
+		: `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;
+	return {
+		ok,
+		results,
+		output,
+		...(failedPhase ? { failedPhase } : {}),
+		...(error ? { error } : {}),
+		...(failureKind ? { failureKind } : {}),
+		...(cancelled ? { cancelled: true } : {}),
+	};
+}

package/src/orchestration/flow.ts

@@ -0,0 +1,125 @@
+/**
+ * Flows (v0.5) — a declarative DAG over strategies. A `*.flow.json` file names phases,
+ * each running a strategy over a roster, wired by `needs` edges. JSON-first (the magi
+ * council's ruling): `JSON.parse` + a hand-rolled validator (no new deps), the DAG
+ * pinned per run via the contract hasher and journaled for resume. This module is the
+ * PURE core — schema, validation, and topological order; the runner (engine + journal
+ * injected) lives alongside in `flow-run.ts`.
+ */
+
+import { stableHash } from "../core/contract.ts";
+
+export interface FlowPhase {
+	id: string;
+	strategy: string;
+	roster?: string;
+	needs?: string[];
+	params?: Record<string, unknown>;
+	/** A checkpoint: after this phase completes, require approval before its dependents run. */
+	gate?: boolean;
+}
+
+export interface FlowSpec {
+	name: string;
+	description?: string;
+	phases: FlowPhase[];
+}
+
+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. */
+export function flowHash(spec: FlowSpec): string {
+	return stableHash(spec);
+}
+
+function isObject(x: unknown): x is Record<string, unknown> {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+/** Kahn's algorithm over `needs` edges → a dependency-respecting order, or a cycle error. */
+export function topoOrder(phases: FlowPhase[]): TopoResult {
+	const ids = new Set(phases.map((p) => p.id));
+	const indeg = new Map<string, number>();
+	const dependents = new Map<string, string[]>(); // a phase → the phases that need it
+	for (const p of phases) indeg.set(p.id, 0);
+	for (const p of phases) {
+		for (const n of p.needs ?? []) {
+			if (!ids.has(n)) return { ok: false, error: `phase "${p.id}" needs unknown phase "${n}"` };
+			indeg.set(p.id, (indeg.get(p.id) ?? 0) + 1);
+			dependents.set(n, [...(dependents.get(n) ?? []), p.id]);
+		}
+	}
+	const queue = phases.filter((p) => (indeg.get(p.id) ?? 0) === 0).map((p) => p.id);
+	const order: string[] = [];
+	while (queue.length > 0) {
+		const id = queue.shift() as string;
+		order.push(id);
+		for (const dep of dependents.get(id) ?? []) {
+			const d = (indeg.get(dep) ?? 0) - 1;
+			indeg.set(dep, d);
+			if (d === 0) queue.push(dep);
+		}
+	}
+	if (order.length !== phases.length) return { ok: false, error: "flow has a cycle" };
+	return { ok: true, order };
+}
+
+/** Parse + validate a `*.flow.json` into a runnable FlowSpec (or a clear error). The name is
+ *  taken as the flow's IDENTITY and kept verbatim, path-hostile characters and all: the journal
+ *  filename it becomes is derived from it (`journalFileName`, flow-journal.ts), not spelled by it. */
+export function parseFlow(content: string): FlowParse {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		return { ok: false, error: "flow is not valid JSON" };
+	}
+	if (!isObject(raw)) return { ok: false, error: "flow must be a JSON object" };
+	if (typeof raw.name !== "string" || !raw.name.trim()) return { ok: false, error: "flow.name is required" };
+	if (!Array.isArray(raw.phases) || raw.phases.length === 0) return { ok: false, error: "flow.phases must be a non-empty array" };
+
+	const phases: FlowPhase[] = [];
+	const seen = new Set<string>();
+	for (const [i, p] of (raw.phases as unknown[]).entries()) {
+		if (!isObject(p)) return { ok: false, error: `phase ${i} must be an object` };
+		if (typeof p.id !== "string" || !p.id.trim()) return { ok: false, error: `phase ${i} needs an id` };
+		if (seen.has(p.id)) return { ok: false, error: `duplicate phase id "${p.id}"` };
+		if (typeof p.strategy !== "string" || !p.strategy.trim()) return { ok: false, error: `phase "${p.id}" needs a strategy` };
+		seen.add(p.id);
+		const phase: FlowPhase = { id: p.id, strategy: p.strategy };
+		if (typeof p.roster === "string" && p.roster.trim()) phase.roster = p.roster;
+		if (Array.isArray(p.needs)) {
+			if (!p.needs.every((n): n is string => typeof n === "string")) return { ok: false, error: `phase "${p.id}" needs must be strings` };
+			phase.needs = p.needs;
+		}
+		if (isObject(p.params)) phase.params = p.params;
+		if (p.gate === true) phase.gate = true;
+		phases.push(phase);
+	}
+
+	const topo = topoOrder(phases);
+	if (!topo.ok) return { ok: false, error: topo.error };
+
+	const flow: FlowSpec = { name: raw.name, phases };
+	if (typeof raw.description === "string") flow.description = raw.description;
+	return { ok: true, flow };
+}
+
+/** Bind a parsed flow to the live strategy registry + team names. `parseFlow` is
+ *  structural (JSON + DAG); this is the discovery check so a typo cannot start a run. */
+export function verifyFlowRefs(
+	flow: FlowSpec,
+	known: { strategies: readonly string[]; teams: ReadonlySet<string> },
+): FlowParse {
+	for (const phase of flow.phases) {
+		if (!known.strategies.includes(phase.strategy)) {
+			return { ok: false, error: `unknown strategy "${phase.strategy}"` };
+		}
+		if (phase.roster && !known.teams.has(phase.roster)) {
+			return { ok: false, error: `unknown roster "${phase.roster}"` };
+		}
+	}
+	return { ok: true, flow };
+}

package/src/orchestration/judge.ts

@@ -0,0 +1,78 @@
+/**
+ * Judge preparation (§4.3) — the impartial-judge counterpart to `vote`. Voting tallies
+ * the candidates' own votes; judging hands the candidates to ONE judge agent that picks.
+ * The bias guard is that the judge must see them **anonymised** (no author identity) and,
+ * for production, **reordered** (so position can't bias the pick). This module is the PURE
+ * part: render an anonymised, labelled ballot and resolve the judge's chosen label back to
+ * the real candidate. A judge strategy then runs `agent(judge, { task: prep.ballot })` and
+ * maps its verdict via `prep.pick(...)` — no new engine surface needed.
+ */
+
+import { fenceUntrusted } from "../core/fence.ts";
+import type { AgentResult } from "./types.ts";
+
+export interface JudgePrep {
+	/** The candidates rendered anonymised + reordered, each under a `[A]`/`[B]`… label. */
+	ballot: string;
+	/** Resolve a judge's chosen label (case-insensitive) back to the original candidate. */
+	pick(label: string): AgentResult | undefined;
+}
+
+const LABELS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+/**
+ * The judge's vote reduced to a ballot label. Models routinely answer "Candidate B" or "B."
+ * where the ballot asked for "B", so a bare single-letter token is read as the pick.
+ *
+ * The candidate letters are filtered against the labels ACTUALLY on this ballot, and an
+ * ambiguous vote (two different labels named, e.g. "A or B?") resolves to nothing. Guessing
+ * here is worse than failing: the no-pick path already returns the panel (or, for compete,
+ * every valid diff) — a refusal loses nothing, while a wrong guess applies the wrong work.
+ */
+export function ballotLabel(vote: string, onBallot: number): string {
+	const bare = vote.trim().toUpperCase();
+	if (bare.length <= 1) return bare;
+	const labels = new Set(LABELS.slice(0, Math.min(onBallot, LABELS.length)));
+	const named = [...new Set(bare.split(/[^A-Z]+/).filter((t) => t.length === 1 && labels.has(t)))];
+	return named.length === 1 ? named[0]! : bare;
+}
+
+function isPermutation(order: number[], n: number): boolean {
+	if (order.length !== n) return false;
+	const seen = new Set(order);
+	if (seen.size !== n) return false;
+	return order.every((i) => Number.isInteger(i) && i >= 0 && i < n);
+}
+
+/** Anonymise + label (+ optionally reorder) candidates for an impartial LLM judge. `order`
+ *  is a permutation of candidate indices (ballot position → candidate); production passes a
+ *  shuffle, tests pass a fixed permutation. Defaults to candidate order. A malformed `order`
+ *  (wrong length / not a permutation) is ignored rather than silently becoming identity —
+ *  identity would drop the reorder half of the bias guard. */
+export function prepareJudge(candidates: AgentResult[], order?: number[]): JudgePrep {
+	const perm = order && isPermutation(order, candidates.length) ? order : candidates.map((_, i) => i);
+	const byLabel = new Map<string, AgentResult>();
+	const sections: string[] = [];
+	perm.forEach((candIdx, pos) => {
+		const c = candidates[candIdx];
+		if (!c) return;
+		const label = LABELS[pos] ?? `#${pos + 1}`;
+		byLabel.set(label, c);
+		sections.push(`[${label}]\n${fenceUntrusted(c.output.trim())}`);
+	});
+	return {
+		ballot: sections.join("\n\n"),
+		pick: (label) => byLabel.get(ballotLabel(label, byLabel.size)),
+	};
+}
+
+/** A random permutation of [0..n) — so a judge can't be biased by candidate order.
+ *  Production ballots pass this to {@link prepareJudge}; tests pass a fixed permutation. */
+export function shuffleOrder(n: number): number[] {
+	const a = Array.from({ length: n }, (_, i) => i);
+	for (let i = n - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1));
+		[a[i], a[j]] = [a[j] as number, a[i] as number];
+	}
+	return a;
+}

package/src/orchestration/model-retry.ts

@@ -0,0 +1,85 @@
+/**
+ * Peer-model retry policy — when one council member fails for a MODEL reason, which model
+ * should it be re-run on?
+ *
+ * This is the roster-level complement to `engine/fallback.ts`. That decorator reroutes the SAME
+ * model id to a family-compatible provider (anthropic/x → bedrock/x) and knows nothing about the
+ * other members; this decides to hand a broken core a DIFFERENT model that a sibling just proved
+ * works in this very session. The two compose: the engine exhausts provider routes first, and only
+ * a run that still comes back `provider`/`unknown-model` reaches here.
+ *
+ * The order of preference is evidence, strongest first:
+ *   1. the session's own model, when a peer proved it — the user is running on it, so it is the
+ *      most likely to be authed, in budget, and available;
+ *   2. otherwise the first healthy peer's model in roster order (deterministic, not iteration order);
+ *   3. otherwise the session model unproven — the case where the failing core is the first or the
+ *      only one left, so no peer evidence exists at all.
+ *
+ * A council's whole value is UNCORRELATED errors from distinct reasoners, so this deliberately
+ * never runs as a preference: it is what keeps a broken core from silently dropping out of the
+ * vote, and callers are expected to surface it. Pure — no engine, no I/O, no clock.
+ */
+
+import type { AgentResult, FailureKind } from "./types.ts";
+
+/** The only failures a DIFFERENT model can fix. `provider` is the provider rejecting or breaking
+ *  (auth, outage, 5xx, model-not-supported); `unknown-model` is a ref that does not resolve at all.
+ *  Everything else — a user stop, an idle timeout, a contract violation, the agent's own error —
+ *  reproduces identically on any model, so retrying only burns tokens. `abort` above all must never
+ *  retry: a stop that silently respawned work would be a stop that does not stop. */
+export const RETRYABLE_MODEL_FAILURES = ["provider", "unknown-model"] as const satisfies readonly FailureKind[];
+
+const retryable = new Set<string>(RETRYABLE_MODEL_FAILURES);
+
+export interface ModelRetry {
+	/** Position in the round's results, so the caller can re-run exactly this member. */
+	index: number;
+	agent: string;
+	/** The model that just failed, when the engine resolved one. */
+	from?: string;
+	/** The model to re-run on — never the one that just failed. */
+	model: string;
+	/** Which evidence chose it, for an honest breadcrumb in the log and the tree. */
+	reason: "peer" | "session";
+}
+
+export interface ModelRetryDeps {
+	/** The model the user's own session runs on (`provider/id`), when known. */
+	sessionModel?: string;
+}
+
+/**
+ * Plan at most one retry per failed member. Returns an empty list when nothing is worth
+ * re-running — no model-caused failure, or no model available that differs from the one that
+ * already failed.
+ */
+export function planModelRetries(results: readonly AgentResult[], deps: ModelRetryDeps): ModelRetry[] {
+	const healthy = results.filter((r) => r.ok && r.modelUsed).map((r) => r.modelUsed as string);
+	const session = deps.sessionModel?.trim() || undefined;
+	// A peer's model is evidence; the session model is evidence too when a peer used it, and a
+	// reasonable guess when nothing survived to prove anything.
+	const candidates = session && healthy.includes(session)
+		? [session, ...healthy.filter((model) => model !== session)]
+		: healthy.length > 0
+			? healthy
+			: session
+				? [session]
+				: [];
+
+	const plan: ModelRetry[] = [];
+	results.forEach((result, index) => {
+		if (result.ok || !result.failureKind || !retryable.has(result.failureKind)) return;
+		// Re-running on the model that just failed cannot produce a different outcome. Keep walking:
+		// a later healthy peer may still provide a distinct model worth trying.
+		const candidate = candidates.find((model) => model !== result.modelUsed);
+		if (!candidate) return;
+		plan.push({
+			index,
+			agent: result.agent,
+			...(result.modelUsed ? { from: result.modelUsed } : {}),
+			model: candidate,
+			reason: healthy.includes(candidate) ? "peer" : "session",
+		});
+	});
+	return plan;
+}