@aeondave/pi-persona 1.15.2

package/src/orchestration/strategies/magi.ts

@@ -0,0 +1,239 @@
+/**
+ * magi — the MagiSystem. Run a roster of distinct-persona "systems" on the same
+ * question in parallel, each returning a structured vote, then decide by
+ * majority (or unanimity), surfacing the tally and a minority report. Diversity
+ * comes from the roster's personas; bias guards live in the vote reducer.
+ *
+ * Reflection round (params.reflect, default ON): after the independent round, each
+ * core sees the OTHER cores' positions **anonymised** and casts a FINAL vote —
+ * revising only if a genuinely new consideration moves it (holding is fine). This
+ * lets a core catch a blind spot without turning MAGI into groupthink: the positions
+ * are anonymised (no "defer to Casper" authority bias), it is exactly ONE round (not
+ * iterate-to-consensus — that is `council-rounds`), and dissent is always preserved.
+ * Set `reflect: false` for a pure independent poll (uncorrelated errors, cheapest).
+ */
+
+import { fenceUntrusted } from "../../core/fence.ts";
+import { planModelRetries } from "../model-retry.ts";
+import { sumUsage, summarizeFailedResults } from "../reducers.ts";
+import { dissentLine, readableRuling as readable } from "../render.ts";
+import type { Strategy, StrategySDK } from "../sdk.ts";
+import type { AgentResult } from "../types.ts";
+import { type RosterMember, rosterSpec } from "../roster.ts";
+
+const LABELS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+/** A poll the run cancelled — distinct from one that finished without a ruling, so a
+ *  journal or supervisor records it as cancelled rather than as a completed failure. */
+function cancelled(usages: AgentResult["usage"][]): AgentResult {
+	const output = "MAGI cancelled — the run was aborted before a ruling.";
+	return {
+		agent: "magi",
+		output,
+		structured: { status: "cancelled", reflected: false, headline: output },
+		usage: sumUsage(usages),
+		ok: false,
+		error: "the run was aborted",
+		failureKind: "abort",
+	};
+}
+
+interface Recovery {
+	/** Round 1 with each successful recovery spliced into its original roster position. */
+	results: AgentResult[];
+	/** Every retry leg that actually ran, so usage can bill what the run really spent. */
+	attempts: AgentResult[];
+	/** Roster index → the model that rescued it. MUST be carried into every LATER round: rebuilding a
+	 *  spec from the roster alone would put the core straight back on the model that just broke. */
+	models: Map<number, string>;
+}
+
+/**
+ * Re-run the cores whose MODEL broke on one that this run proved works, and splice the recoveries
+ * back into their original roster positions. Returns `round1` untouched when nothing qualifies.
+ *
+ * Exactly one pass: a core that fails again keeps its second failure and drops out of the vote
+ * honestly, rather than looping. The abort signal is checked first, so a stopped run recovers
+ * nothing.
+ */
+async function recoverBrokenModels(
+	round1: AgentResult[],
+	team: RosterMember[],
+	task: string,
+	sdk: StrategySDK,
+	affordable: number,
+): Promise<Recovery> {
+	const nothing = { results: round1, attempts: [], models: new Map<number, string>() };
+	if (sdk.signal?.aborted || affordable <= 0) return nothing;
+	const wanted = planModelRetries(round1, { ...(sdk.sessionModel ? { sessionModel: sdk.sessionModel } : {}) });
+	if (wanted.length === 0) return nothing;
+	// Recovery is an ENHANCEMENT and must not spend the budget the rounds themselves need: exceeding
+	// `maxChildren` throws out of sdk.agent(), which would turn a poll that had a ruling into no
+	// ruling at all. Take what the run can afford, oldest-first, and say what was left behind.
+	const plan = wanted.slice(0, affordable);
+	for (const dropped of wanted.slice(affordable)) {
+		sdk.log(`magi: ${dropped.agent} stays failed — no child budget left to retry it (maxChildren ${sdk.limits.maxChildren})`);
+	}
+	const recovered = [...round1];
+	const attempts: AgentResult[] = [];
+	const models = new Map<number, string>();
+	let observedTokens = round1.reduce((total, result) => total + result.usage.input + result.usage.output, 0);
+	for (let i = 0; i < plan.length; i++) {
+		const retry = plan[i] as (typeof plan)[number];
+		if (sdk.signal?.aborted) break;
+		if (sdk.limits.budgetTokens > 0 && observedTokens >= sdk.limits.budgetTokens) {
+			for (const dropped of plan.slice(i)) {
+				sdk.log(`magi: ${dropped.agent} stays failed — token budget exhausted (${sdk.limits.budgetTokens})`);
+			}
+			break;
+		}
+		sdk.log(`magi: ${retry.agent} failed on ${retry.from ?? "its model"} — retrying on ${retry.model} (${retry.reason === "peer" ? "worked for a peer" : "session model"})`);
+		const member = team[retry.index];
+		// A member is always present: the plan indexes the round the team produced. Retries are
+		// deliberately serial so each completed attempt updates the observable token remainder before
+		// another billed leg is allowed to start.
+		const attempt = await sdk.agent({ ...rosterSpec(member as RosterMember), model: retry.model, task, outputContract: "default" });
+		attempts.push(attempt);
+		observedTokens += attempt.usage.input + attempt.usage.output;
+		// Keep the ORIGINAL failure when the retry failed too: the first error is the one that
+		// describes the core's own model, which is what a reader needs to fix the roster — and a
+		// twice-failed core keeps NO override, so it re-runs on its own model and fails honestly.
+		if (!attempt.ok) continue;
+		recovered[retry.index] = attempt;
+		models.set(retry.index, retry.model);
+	}
+	// Every attempt is returned separately: a recovery REPLACES a failed result, so summing the
+	// final array alone would bill the run for less than it actually spent.
+	return { results: recovered, attempts, models };
+}
+
+export const magi: Strategy = {
+	name: "magi",
+	params: {
+		aggregate: { type: "string", default: "majority", doc: '"majority" | "unanimity"' },
+		reflect: { type: "boolean", default: true, doc: "one anonymised reflection round" },
+	},
+	async run(input, sdk) {
+		const team = input.roster ? sdk.roster.team(input.roster) : [];
+		if (team.length === 0) throw new Error("magi: a roster of voting personas is required");
+		if (sdk.signal?.aborted) return cancelled([]);
+		const aggregate = input.params.aggregate === "unanimity" ? "unanimity" : "majority";
+		const reflect = input.params.reflect !== false; // default ON — one informed round
+		sdk.log(`magi: ${team.length} systems, ${aggregate} vote${reflect ? " + reflection" : ""}`);
+
+		// Round 1 — each core answers INDEPENDENTLY (uncorrelated errors: the whole point).
+		const round1 = await sdk.parallel(
+			team.map((m) => () => sdk.agent({ ...rosterSpec(m), task: input.task, outputContract: "default" })),
+		);
+
+		// A core whose MODEL broke is not a dissenting voice, it is a missing one — and a poll of two
+		// is a materially weaker poll. Re-run just those cores, ONCE, on a model this run proved works
+		// (a healthy peer's, else the session's own). Only provider/unknown-model failures qualify:
+		// an abort or a contract violation reproduces on any model, and a retried abort would be a
+		// stop that does not stop. Diversity is the council's whole point, so this never runs as a
+		// preference — it is the difference between a degraded poll and a lost vote, and it is logged.
+		// Round 1 has spent one child per member, and the reflection round (when it runs) will spend
+		// another; whatever is left is what recovery may use.
+		const reserved = team.length * (reflect ? 2 : 1);
+		const recovery = await recoverBrokenModels(round1, team, input.task, sdk, sdk.limits.maxChildren - reserved);
+		const opening = recovery.results;
+
+		// An abort settles every core as ok:false/'abort' instead of throwing, so a stop that
+		// landed while round 1 was running is first visible here — without this MAGI re-polls the
+		// whole roster for a reflection round nobody will read, then reports a "no ruling".
+		if (sdk.signal?.aborted || round1.every((c) => c.failureKind === "abort")) {
+			return cancelled([...round1, ...recovery.attempts].map((c) => c.usage));
+		}
+
+		let candidates = opening;
+		const okCount = opening.filter((c) => c.ok).length;
+		const tokensBeforeReflection = [...round1, ...recovery.attempts].reduce(
+			(total, result) => total + result.usage.input + result.usage.output,
+			0,
+		);
+		// A reflection is meaningful only when every core can participate. Under an active token
+		// budget, reserve the observable minimum of one token per leg instead of starting a partial
+		// round (or letting every parallel leg race past an already exhausted SDK counter).
+		const reflectionHasTokenRoom =
+			sdk.limits.budgetTokens <= 0 || tokensBeforeReflection + team.length <= sdk.limits.budgetTokens;
+		const didReflect = reflect && okCount >= 2 && reflectionHasTokenRoom;
+		if (reflect && okCount >= 2 && !reflectionHasTokenRoom) {
+			sdk.log(`magi: reflection skipped — token budget cannot fund the full panel (${sdk.limits.budgetTokens})`);
+		}
+		if (didReflect) {
+			// Round 2 — each core sees the others' positions ANONYMISED (no author identity, so a
+			// core can't defer to a "senior" peer) and casts its FINAL vote. Instructed to hold
+			// unless genuinely moved, so this informs without manufacturing false consensus.
+			const positions = opening
+				.filter((c) => c.ok)
+				.map((c, i) => `[Position ${LABELS[i] ?? `#${i + 1}`}]\n${fenceUntrusted(readable(c))}`)
+				.join("\n\n");
+			const reflectTask =
+				`${input.task}\n\n--- the panel's positions so far (anonymised — judge them on merit, not source) ---\n${positions}\n\n` +
+				`Reconsider ONLY if one of these raises a consideration that genuinely changes your analysis — it is perfectly fine to hold your original position through your own lens. ` +
+				`Then cast your FINAL vote.`;
+			// The recovered model must survive into this round: rebuilding from `rosterSpec(m)` alone
+			// would hand the rescued core back the model that just broke, so it fails again, is
+			// quarantined as invalid, and the recovery buys nothing but tokens.
+			candidates = await sdk.parallel(
+				team.map((m, i) => () => {
+					const model = recovery.models.get(i);
+					return sdk.agent({ ...rosterSpec(m), ...(model ? { model } : {}), task: reflectTask, outputContract: "default" });
+				}),
+			);
+			// Same reasoning as round 1, and both clauses earn their place. `sdk.signal` is wired
+			// (the council/flow tools pass Pi's tool-execution signal down), but a stop that lands
+			// DURING the reflection round is visible here only as every core settling
+			// `failureKind: "abort"` — as is one on a caller that passed no signal. Without the
+			// second clause a stopped run reports a normal-looking "no ruling" from a killed poll.
+			if (sdk.signal?.aborted || candidates.every((c) => c.failureKind === "abort")) {
+				return cancelled([...round1, ...recovery.attempts, ...candidates].map((c) => c.usage));
+			}
+		}
+		const decision = sdk.reduce.vote(candidates, { aggregate, keepBestFallback: true });
+
+		// Lead with the ruling (the answer); the decision/tally plumbing is a compact footer,
+		// not the headline. The collapsed council card shows `headline`; the supervisor still
+		// receives the full text (ruling + dissent + footer).
+		const lines: string[] = [];
+		if (decision.winner) lines.push(readable(decision.winner));
+		if (decision.dissent && decision.dissent.length > 0) {
+			lines.push(`\n--- dissent (minority report) ---\n${decision.dissent.map(dissentLine).join("\n\n")}`);
+		}
+		const tally = Object.entries(decision.tally).map(([k, v]) => `${k}=${v}`).join(", ") || "—";
+		const invalid = decision.invalid && decision.invalid.length > 0 ? ` · ${decision.invalid.length} invalid excluded` : "";
+		// State the recovery in the RULING, not only through sdk.log — which no production caller
+		// sinks. A reader must be able to tell that a core argued on a borrowed model, because that
+		// is exactly the diversity the tally silently lost.
+		const rescued = recovery.models.size > 0
+			? ` · ${recovery.models.size} core${recovery.models.size === 1 ? "" : "s"} recovered on ${[...new Set(recovery.models.values())].join(", ")}`
+			: "";
+		lines.push(
+			`\n— magi: ${decision.status}${didReflect ? " (after 1 reflection round)" : ""}${decision.usedFallback ? " · fell back to best-by-confidence" : ""} · tally ${tally}${invalid}${rescued}`,
+		);
+
+		const winnerResult = decision.winner?.structured?.result;
+		const headline = decision.winner
+			? typeof winnerResult === "string" && winnerResult.trim()
+				? winnerResult.trim()
+				: readable(decision.winner).split("\n")[0] ?? decision.status
+			: decision.status;
+
+		// Usage sums EVERY run the poll actually paid for: the opening round, any model recovery,
+		// and the reflection round (separate from the opening one when reflection ran).
+		const allRuns: AgentResult[] = didReflect ? [...round1, ...recovery.attempts, ...candidates] : [...round1, ...recovery.attempts];
+		const result: AgentResult = {
+			agent: "magi",
+			output: lines.join("\n"),
+			structured: { status: decision.status, tally: decision.tally, usedFallback: decision.usedFallback, reflected: didReflect, headline },
+			usage: sumUsage(allRuns.map((c) => c.usage)),
+			ok: decision.winner !== undefined,
+		};
+		if (!result.ok) {
+			const cause = summarizeFailedResults(candidates, "magi produced no ruling");
+			result.error = cause.error;
+			result.failureKind = cause.failureKind;
+		}
+		return result;
+	},
+};

package/src/orchestration/strategies/map.ts

@@ -0,0 +1,327 @@
+/**
+ * map — dynamic fan-out over a RUNTIME list (vs `fanout`'s fixed roster). A splitter agent
+ * breaks the task into independent sub-items, then a worker runs once per item in parallel
+ * (bounded by the run limits / `params.maxItems`), and the results aggregate. The map-reduce
+ * shape for "review each changed file", "summarise each doc", etc. Built on the SDK + the
+ * shared JSON extractor — no new engine surface.
+ *
+ * roster = [splitter, worker]  (worker defaults to the splitter if only one is given)
+ * params = { maxItems?: number, peers?: boolean (workers share load-bearing cross-item
+ *            discoveries live via contact_peer — default off), ownership?: "off"|"declare"|"enforce",
+ *            verify?: string (agent that re-checks each completed item; empty = off) }
+ */
+
+import { extractJsonCandidate } from "../../core/contract.ts";
+import { fenceUntrusted } from "../../core/fence.ts";
+import { cappedList } from "../../core/format.ts";
+import { validateParallelWriteSets } from "../../core/ownership.ts";
+import type { ChildUsage } from "../../engine/stream.ts";
+import { itemLedger, type ItemLedgerEntry, sumUsage } from "../reducers.ts";
+import { rosterSpec, type RosterMember, type RosterSpec } from "../roster.ts";
+import type { Strategy, StrategySDK } from "../sdk.ts";
+import type { AgentResult, FailureKind } from "../types.ts";
+
+// Cooperative cross-talk (params.peers): workers share load-bearing cross-item discoveries
+// live. Injected into the TASK text (not the role) so UI tree keys stay stable.
+const CROSS_TALK = [
+	"You have sibling workers on OTHER sub-items of this same batch. If you discover something",
+	"load-bearing that likely applies to their items too (a shared gotcha, a convention, a blocker),",
+	"share it once via `contact_peer` (action `list`, then `send`) — short and factual. Incorporate",
+	'any "[message from peer …]" notes you receive. No chatter: only load-bearing findings.',
+].join(" ");
+
+const NOT_RUN_NAME_CAP = 5;
+
+export interface ParsedItem {
+	item: string;
+	writeSet?: string[];
+}
+
+/** Every ```-fenced block's contents, last fence first (the model, told to "Return ONLY a JSON
+ *  array", most often either answers bare or wraps that same array in one ```/```json fence).
+ *  A miniature, map-local copy of `contract.ts`'s private `fencedBlocks` — that module's helpers
+ *  aren't exported, and this one only ever needs the fence, never the object-preferring picker
+ *  built on top of it there. */
+function fencedBlocks(text: string): string[] {
+	const out: string[] = [];
+	const re = /```[^\n`]*\n([\s\S]*?)```/g;
+	let m = re.exec(text);
+	while (m !== null) {
+		if (m[1] !== undefined) out.push(m[1].trim());
+		m = re.exec(text);
+	}
+	return out.reverse();
+}
+
+/** Parse a splitter's output into a list of items (tolerant of fences/prose). Each entry is
+ *  either a plain string sub-item, or an object declaring `{ item, writeSet? }` — any other
+ *  shape falls back to its JSON text as the item, exactly like before this field existed.
+ *
+ *  Tries a direct parse of the trimmed output, then of each fenced block, accepting only a
+ *  candidate that parses to an ARRAY — `extractJsonCandidate` (src/core/contract.ts) is built
+ *  for contracts, which always want an OBJECT, so among several parseable candidates it prefers
+ *  one that starts with `{`. That is the right call for a contract answer, but wrong here: an
+ *  `{item, writeSet}` element nested inside the requested top-level ARRAY would win and shadow
+ *  the whole list — including when that array sits inside a fence, the most likely shape a
+ *  model actually emits. `extractJsonCandidate` only comes in as a last-resort fallback, for
+ *  prose-wrapped output with no fence (where, absent a nested object item, its preference never
+ *  triggers). */
+function parseItems(output: string): ParsedItem[] {
+	let parsed: unknown;
+	let found = false;
+	for (const candidate of [output.trim(), ...fencedBlocks(output)]) {
+		try {
+			const value: unknown = JSON.parse(candidate);
+			if (Array.isArray(value)) {
+				parsed = value;
+				found = true;
+				break;
+			}
+		} catch {
+			// try the next candidate
+		}
+	}
+	if (!found) {
+		try {
+			parsed = JSON.parse(extractJsonCandidate(output));
+		} catch {
+			return [];
+		}
+	}
+	if (!Array.isArray(parsed)) return [];
+	return parsed
+		.map((x): ParsedItem => {
+			if (typeof x === "string") return { item: x };
+			if (x && typeof x === "object" && !Array.isArray(x)) {
+				const obj = x as Record<string, unknown>;
+				const writeSetOk = obj.writeSet === undefined || (Array.isArray(obj.writeSet) && obj.writeSet.every((p) => typeof p === "string"));
+				if (typeof obj.item === "string" && writeSetOk) {
+					return obj.writeSet !== undefined ? { item: obj.item, writeSet: obj.writeSet as string[] } : { item: obj.item };
+				}
+			}
+			return { item: JSON.stringify(x) };
+		})
+		.filter((p) => p.item.trim());
+}
+
+/** The verifier's run spec: the roster's own entry for that agent name (its role/model/tools
+ *  specialisation applies) when `params.verify` names a roster member, else a bare `rosterSpec`
+ *  for a stand-alone agent named directly in the param. */
+function verifierSpec(team: readonly RosterMember[], name: string) {
+	const member = team.find((m) => rosterSpec(m).agent === name);
+	return rosterSpec(member ?? name);
+}
+
+/** Read a verifier leg's verdict. Reuses the SAME `outputContract: "default"` machinery
+ *  `critic-loop` reads its critic's stance from (`structured.stance`) rather than inventing a
+ *  new parser — "approve" passes, anything else (an explicit "reject"/"revise", a missing
+ *  stance, or invalid structured output) fails the item. A verifier leg that itself couldn't
+ *  run (`ok: false` — provider/timeout/abort/contract) is a distinct case: that's not a verdict
+ *  at all, so its OWN `failureKind` carries through instead of `"verification"`, which is
+ *  reserved for an actual negative (or absent) verdict. Returns `undefined` on a pass. */
+function verifyOutcome(v: AgentResult): { failureKind: FailureKind; error: string } | undefined {
+	if (!v.ok) return { failureKind: v.failureKind ?? "agent", error: v.error || "the verifier failed to run" };
+	if (v.structured?.stance === "approve") return undefined;
+	const reason = (typeof v.structured?.result === "string" && v.structured.result.trim()) || v.output.trim() || "the verifier withheld approval";
+	return { failureKind: "verification", error: reason };
+}
+
+type SplitOutcome =
+	| { ok: true; allItems: ParsedItem[]; items: ParsedItem[]; dropped: number; usage: ChildUsage }
+	| { ok: false; result: AgentResult };
+
+/** Run the splitter agent and parse its output into the runtime item list, clamped to
+ *  `maxItems`. A splitter failure, or a split that produced no usable items, is a terminal
+ *  `AgentResult` — the whole run fails before any worker spawns. */
+async function splitIntoItems(sdk: StrategySDK, splitter: RosterSpec, task: string, maxItems: number): Promise<SplitOutcome> {
+	const split = await sdk.agent({
+		...splitter,
+		task: `Break this task into independent sub-items. Return ONLY a JSON array of short strings — one per sub-item, nothing else.\n\nTask: ${task}`,
+	});
+	if (!split.ok) {
+		return {
+			ok: false,
+			result: {
+				agent: "map",
+				output: split.output || split.error || "(splitter failed)",
+				usage: split.usage,
+				ok: false,
+				...(split.error ? { error: split.error } : {}),
+				...(split.failureKind ? { failureKind: split.failureKind } : {}),
+			},
+		};
+	}
+	const allItems = parseItems(split.output);
+	const items = allItems.slice(0, Math.max(0, maxItems));
+	const dropped = allItems.length - items.length;
+	if (items.length === 0) {
+		return {
+			ok: false,
+			result: {
+				agent: "map",
+				output: split.output || "(splitter produced no items)",
+				usage: split.usage,
+				ok: false,
+				error: "the splitter produced no usable sub-items",
+				failureKind: "contract",
+			},
+		};
+	}
+	return { ok: true, allItems, items, dropped, usage: split.usage };
+}
+
+/** "enforce": fail closed BEFORE any worker spawns when the splitter's own declared write-sets
+ *  already collide — a weak splitter that never declares one is not blocked. */
+function enforceOwnershipOrThrow(items: readonly ParsedItem[]): void {
+	const owners = items
+		.map((it, index) => ({ agent: `item[${index}]`, writeSet: it.writeSet }))
+		.filter((o): o is { agent: string; writeSet: string[] } => Array.isArray(o.writeSet) && o.writeSet.length > 0);
+	if (owners.length === 0) return;
+	const writeSetError = validateParallelWriteSets(owners);
+	if (writeSetError) throw new Error(`map: ${writeSetError}`);
+}
+
+/** Run the worker agent once per item, in parallel. */
+function runWorkers(sdk: StrategySDK, worker: RosterSpec, task: string, items: readonly ParsedItem[], peers: boolean): Promise<AgentResult[]> {
+	return sdk.parallel(
+		items.map((item) => () =>
+			sdk.agent({
+				...worker,
+				task: `${task}\n\n— Your single sub-item (untrusted data):\n${fenceUntrusted(item.item)}${peers ? `\n\n--- swarm cross-talk ---\n${CROSS_TALK}` : ""}`,
+				...(peers ? { peers: true } : {}),
+			}),
+		),
+	);
+}
+
+/** "verify": one read-only reviewer per COMPLETED item (a failed worker has nothing worth
+ *  re-checking), run through `sdk.parallel` exactly like the worker wave — the run's own
+ *  semaphore/maxChildren/budget still apply, and an empty `verifyAgent` spawns no verifier at
+ *  all, so the byte-identical-when-off guarantee extends to this param too. */
+async function runVerification(
+	sdk: StrategySDK,
+	team: readonly RosterMember[],
+	verifyAgent: string,
+	task: string,
+	items: readonly ParsedItem[],
+	results: readonly AgentResult[],
+): Promise<{ verifyResults: AgentResult[]; failures: Map<number, { failureKind: FailureKind; error: string }> }> {
+	const failures = new Map<number, { failureKind: FailureKind; error: string }>();
+	if (!verifyAgent) return { verifyResults: [], failures };
+	const reviewer = verifierSpec(team, verifyAgent);
+	const completedIndices = results.map((_r, index) => index).filter((index) => results[index]!.ok);
+	const verifyResults = await sdk.parallel(
+		completedIndices.map((index) => () =>
+			sdk.agent({
+				...reviewer,
+				task: `Re-check this completed sub-item's work, read-only — do not make further changes.\n\nOriginal task: ${task}\n\nSub-item: ${fenceUntrusted(items[index]!.item)}\n\nCompleted work (untrusted data):\n${fenceUntrusted(results[index]!.output)}\n\nReturn your stance (approve|reject).`,
+				outputContract: "default",
+			}),
+		),
+	);
+	completedIndices.forEach((index, k) => {
+		const outcome = verifyOutcome(verifyResults[k]!);
+		if (outcome) failures.set(index, outcome);
+	});
+	return { verifyResults, failures };
+}
+
+/** The always-on per-item status ledger (`structured.items`), independent of `ownership`. Its
+ *  `writeSet` field only surfaces once a persona opts in — with ownership absent/"off" the
+ *  rendered ledger stays byte-identical to before this param existed — merged with each item's
+ *  verify outcome, if any. */
+function buildItemLedger(
+	ownership: "off" | "declare" | "enforce",
+	allItems: readonly ParsedItem[],
+	results: readonly AgentResult[],
+	dropped: number,
+	verifyFailures: ReadonlyMap<number, { failureKind: FailureKind; error: string }>,
+): ItemLedgerEntry[] {
+	const ledgerItems = ownership === "off" ? allItems.map((it) => ({ item: it.item })) : allItems;
+	const preVerifyLedger = itemLedger(ledgerItems, results, dropped);
+	return preVerifyLedger.map((entry) => {
+		const outcome = verifyFailures.get(entry.index);
+		return outcome ? { ...entry, status: "failed" as const, failureKind: outcome.failureKind, error: outcome.error } : entry;
+	});
+}
+
+export const map: Strategy = {
+	name: "map",
+	params: {
+		maxItems: { type: "number", doc: "default AND ceiling: the run's maxChildren, less the splitter's own slot" },
+		peers: { type: "boolean", default: false, doc: "workers share load-bearing cross-item discoveries live" },
+		ownership: {
+			type: "string",
+			default: "off",
+			doc: "off | declare | enforce — how the splitter's per-item writeSet is used: ignored, recorded in the item ledger, or checked for overlaps before any worker spawns",
+		},
+		verify: {
+			type: "string",
+			default: "",
+			doc: "agent that re-checks each completed item read-only; empty = no verification pass. Costs one extra child per completed item",
+		},
+	},
+	async run(input, sdk) {
+		const team = input.roster ? sdk.roster.team(input.roster) : [];
+		const splitterMember = team[0];
+		if (!splitterMember) throw new Error("map: a roster with at least a splitter agent is required");
+		const splitter = rosterSpec(splitterMember);
+		const worker = team[1] ? rosterSpec(team[1]) : splitter;
+		const peers = input.params.peers === true;
+		// Unknown values behave as "off" — lenient (I2: strategies are trusted project code), a
+		// typo in a persona's params never blocks a run, it just skips the extra observability.
+		const ownershipParam = input.params.ownership;
+		const ownership = ownershipParam === "declare" || ownershipParam === "enforce" ? ownershipParam : "off";
+		const verifyAgent = typeof input.params.verify === "string" ? input.params.verify.trim() : "";
+		// The splitter spends one child slot before any worker runs, so the worker cap is one
+		// BELOW maxChildren — at the cap the last worker would trip the run's pre-spawn guard
+		// and take the whole (mostly finished) fan-out down with it. When `verify` is set, the
+		// verifier wave asks for ONE MORE child per completed item on top of that, so the cap is
+		// halved instead — splitter + workers + verifiers must all fit under the same ceiling.
+		const workerSlots = Math.max(1, sdk.limits.maxChildren - 1);
+		const cap = verifyAgent ? Math.max(1, Math.floor((sdk.limits.maxChildren - 1) / 2)) : workerSlots;
+		const maxItems = Math.min(typeof input.params.maxItems === "number" ? input.params.maxItems : cap, cap);
+
+		const split = await splitIntoItems(sdk, splitter, input.task, maxItems);
+		if (!split.ok) return split.result;
+		const { allItems, items, dropped, usage: splitUsage } = split;
+		sdk.log(`map: ${items.length} items → ${worker.agent}${peers ? " (cross-talk on)" : ""}`);
+		if (peers && items.length > sdk.limits.maxConcurrency) {
+			sdk.log(
+				`map: ${items.length} items exceeds maxConcurrency (${sdk.limits.maxConcurrency}) — the live exchange will be batched (workers beyond the concurrency window join late)`,
+			);
+		}
+
+		if (ownership === "enforce") enforceOwnershipOrThrow(items);
+
+		const results = await runWorkers(sdk, worker, input.task, items, peers);
+		const agg = sdk.reduce.aggregate(results);
+		// Say what was left out. The clamp is right — a worker per item past the cap would trip the
+		// pre-spawn guard and lose the whole fan-out — but an aggregate that silently covers part of
+		// the splitter's list reads as a complete answer over an incomplete input set.
+		const droppedNote =
+			dropped > 0
+				? `\n\n[pi-persona] ${dropped} sub-item(s) beyond the worker cap (${maxItems}) were not run — this covers ${items.length} of ${allItems.length} sub-items.`
+				: "";
+
+		const { verifyResults, failures: verifyFailures } = await runVerification(sdk, team, verifyAgent, input.task, items, results);
+		const ledger = buildItemLedger(ownership, allItems, results, dropped, verifyFailures);
+
+		const notRun = ledger.filter((e) => e.status === "not-run").map((e) => e.item);
+		const notRunNote = ownership !== "off" && notRun.length > 0 ? `\n\n[pi-persona] not run: ${cappedList(notRun, NOT_RUN_NAME_CAP)}` : "";
+		// Independent of `ownership` — verification runs (and costs a child) whenever `verify` is
+		// set, so its verdict must be visible whenever it runs, not only when a persona also opted
+		// into the ownership ledger. Without this the aggregate still reads as a complete "ok"
+		// answer even though a completed item's work was rejected.
+		const rejected = ledger.filter((e) => e.failureKind === "verification").map((e) => e.item);
+		const verifyNote = rejected.length > 0 ? `\n\n[pi-persona] verification failed: ${cappedList(rejected, NOT_RUN_NAME_CAP)}` : "";
+		const output = `${agg.output}${droppedNote}${notRunNote}${verifyNote}`;
+		return {
+			...agg,
+			agent: "map",
+			output,
+			usage: sumUsage([splitUsage, ...results.map((r) => r.usage), ...verifyResults.map((r) => r.usage)]),
+			structured: { ...agg.structured, items: ledger },
+		};
+	},
+};

package/src/orchestration/strategies/pair.ts

@@ -0,0 +1,72 @@
+/**
+ * pair — driver/navigator live pairing on the p2p comm plane. The driver executes the
+ * task; the navigator does an INDEPENDENT inspection of the same ground (real work that
+ * keeps it alive while milestones arrive), sends an early risk checklist, answers each
+ * milestone with a short correction, and ends with a final review. All over one-way
+ * `contact_peer` sends — the critic-loop's live counterpart, without sequential round
+ * costs. Timing is best-effort BY DESIGN (same as debate): a peer that already finalized
+ * is "gone" and the other proceeds solo.
+ *
+ * roster = [driver, navigator] · result = the driver's work + the navigator's review
+ */
+
+import { sumUsage, summarizeFailedResults } from "../reducers.ts";
+import type { AgentResult } from "../types.ts";
+import { rosterSpec } from "../roster.ts";
+import type { Strategy } from "../sdk.ts";
+
+const DRIVER_PROTOCOL = [
+	"You are the DRIVER of a live pair: a navigator is inspecting the same ground right now.",
+	"Announce your plan to it first (`contact_peer` action `list`, then `send`), send a short",
+	"milestone note after each significant step, and send a final \"done: <summary>\" before you",
+	"finish. Weigh the navigator's \"[message from peer …]\" corrections and take the genuinely",
+	"right ones — you own the work and the final call. If the navigator is gone, proceed solo.",
+].join(" ");
+
+const NAVIGATOR_PROTOCOL = [
+	"You are the NAVIGATOR of a live pair: a driver is executing this task right now — you do",
+	"NOT execute it yourself. First inspect the task's ground independently (the relevant code,",
+	"files, constraints) and `contact_peer send` the driver a short risk checklist (pitfalls,",
+	"edge cases). Keep inspecting deeper; whenever a driver \"[message from peer …]\" milestone",
+	"arrives, check it and send back ONE short correction or confirmation. Before you finish,",
+	"send the driver your final review, then OUTPUT that same review: a verdict plus the risks",
+	"that remain.",
+].join(" ");
+
+export const pair: Strategy = {
+	name: "pair",
+	async run(input, sdk) {
+		const team = input.roster ? sdk.roster.team(input.roster) : [];
+		if (team.length < 2) throw new Error("pair: a roster of [driver, navigator] is required");
+		const driver = rosterSpec(team[0]!);
+		const navigator = rosterSpec(team[1]!);
+		sdk.log(`pair: ${driver.agent} drives, ${navigator.agent} navigates`);
+		if (sdk.limits.maxConcurrency < 2) sdk.log("pair: maxConcurrency < 2 — the live exchange degrades to sequential runs");
+
+		const results = await sdk.parallel([
+			() => sdk.agent({ ...driver, task: `${input.task}\n\n--- pair protocol (driver) ---\n${DRIVER_PROTOCOL}`, peers: true }),
+			() => sdk.agent({ ...navigator, task: `${input.task}\n\n--- pair protocol (navigator) ---\n${NAVIGATOR_PROTOCOL}`, peers: true }),
+		]);
+		const work = results[0];
+		const review = results[1];
+		if (!work || !review) throw new Error("pair: a member run went missing");
+
+		// The driver's work IS the deliverable; the navigator's review is attached when it
+		// produced one, and its failure only degrades the pair to a solo run.
+		const lines = [work.output];
+		if (review.ok && review.output.trim()) lines.push(`\n--- navigator review (${navigator.agent}) ---\n${review.output.trim()}`);
+		const result: AgentResult = {
+			agent: "pair",
+			output: lines.join("\n"),
+			structured: { driver: driver.agent, navigator: navigator.agent, driverOk: work.ok, navigatorOk: review.ok },
+			usage: sumUsage([work, review].map((r) => r.usage)),
+			ok: work.ok,
+		};
+		if (!work.ok) {
+			const cause = summarizeFailedResults([work], "the driver failed");
+			result.error = cause.error;
+			result.failureKind = cause.failureKind;
+		}
+		return result;
+	},
+};