@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/orchestration/sdk.ts

@@ -5,8 +5,9 @@
  * exact same surface as future user-authored strategy files.
  */
 
+import type { ThinkingLevel } from "../core/types.ts";
 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";
@@ -22,6 +23,8 @@ export interface AgentRunSpec {
 	name?: string;
 	task: string;
 	model?: string;
+	/** Requested per-leg effort, before Pi applies the selected model's capability clamp. */
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	/** Skills the sub-agent must load first (dynamic specialisation). */
 	skills?: string[];
@@ -49,11 +52,27 @@ export interface AgentRunSpec {
 	peers?: boolean;
 	/** Declared ownership (from delegate `writeSet`), used only to annotate the files-changed report. */
 	writeSet?: string[];
+	/** INTERNAL (flow reference handoff): the archived `result:<UUID>` refs granted to THIS leg
+	 *  — exactly its phase's DIRECT upstream needs, nothing more. Not a public delegate
+	 *  argument: the SDK strips any strategy-supplied value (strategies cannot enlarge a
+	 *  grant); only the trusted engine-seam wrapper (`withResultRefs`, set by the flow wiring)
+	 *  or an equivalently trusted host path may set it. Both engines preflight + scope the
+	 *  `read_result` tool on it. */
+	resultRefs?: readonly string[];
+}
+
+/** Pin a leg's granted result refs at the ENGINE seam — the trusted wiring path for flow
+ *  reference mode. Overrides (never unions) whatever the caller passed, so a strategy cannot
+ *  smuggle extra refs past the SDK's strip. An empty array is an explicit "none". */
+export function withResultRefs(engine: StrategyEngine, resultRefs: readonly string[]): StrategyEngine {
+	return {
+		run: (spec, onProgress, signal, onSteer) => engine.run({ ...spec, resultRefs }, onProgress, signal, onSteer),
+	};
 }
 
 /** 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,10 +84,10 @@ 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;
-	/** Timestamp of newly streamed tool output; no tool output text crosses this seam. */
-	toolOutputAt?: number;
 	/** One authoritative runtime tool lifecycle transition; never contains tool args or output. */
 	toolEvent?: ToolEvent;
 }
@@ -107,7 +126,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`). */
@@ -146,6 +166,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>;
@@ -171,6 +202,8 @@ export interface SDKDeps {
 	 *  runs several times in one roster) — key the UI node by it, not by `agent`, or three
 	 *  same-agent roster-role members collapse into one node. Falls back to `agent`. */
 	onAgentStatus?: (agent: string, status: AgentStatus, result?: AgentResult, key?: string) => void;
+	/** One final logical leg after model recovery, never intermediate attempts. Storage is non-fatal. */
+	onAgentResult?: (result: AgentResult, key: string) => void;
 	/** Per-agent streaming progress (rolling output), for live UI. See `onAgentStatus.key`. */
 	onAgentProgress?: (agent: string, progress: AgentProgress, key?: string) => void;
 	/** Called as each agent starts with a handle to abort just that agent (for UI stop). */
@@ -229,6 +262,13 @@ function abortedLeg(agent: string): AgentResult {
 	return { agent, output: "", usage: emptyUsage(), ok: false, error: "agent aborted", failureKind: "abort" };
 }
 
+/** Copy of a spec with its `resultRefs` removed — the SDK's one strip point, so a strategy's
+ *  own value never reaches an engine (only `withResultRefs`-style trusted wiring sets it). */
+function stripResultRefs(spec: AgentRunSpec): AgentRunSpec {
+	const { resultRefs: _untrusted, ...rest } = spec;
+	return rest;
+}
+
 export function makeSDK(deps: SDKDeps): StrategySDK {
 	// Run-scoped enforcement of the declared limits — applied here so NO strategy can
 	// exceed them, however it calls agent() (I2: safety from runtime limits, not isolation).
@@ -257,18 +297,26 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 	};
 
 	return {
-		agent: async (spec, options) => {
+		agent: async (requested, options) => {
+			// Reference-handoff grants are trusted wiring, never strategy input: drop any
+			// strategy-supplied `resultRefs` here (the flow path re-pins them at the engine
+			// seam via `withResultRefs`, which runs BELOW this layer).
+			const spec = requested.resultRefs === undefined ? requested : stripResultRefs(requested);
+			const key = uiKeyFor(spec);
+			const finish = (result: AgentResult): AgentResult => {
+				try { deps.onAgentResult?.(result, key); } catch { /* storage must not discard a completed leg */ }
+				return result;
+			};
 			if (deps.canSpawn && !deps.canSpawn(spec.agent)) {
-				return {
+				return finish({
 					agent: spec.agent,
 					output: "",
 					usage: emptyUsage(),
 					ok: false,
 					error: `persona may not spawn "${spec.agent}"`,
 					failureKind: "contract",
-				};
+				});
 			}
-			const key = uiKeyFor(spec);
 			const pending = Symbol();
 			pendingAgents.add(pending);
 			let started = false;
@@ -403,11 +451,13 @@ export function makeSDK(deps: SDKDeps): StrategySDK {
 				}
 			};
 			try {
-				return await agentSlots.with(run, deps.signal);
+				return finish(await agentSlots.with(run, deps.signal));
 			} catch (error) {
 				// A queued leg has no engine result to report. Settle it as an abort when the
 				// run signal removed its waiter; all other errors retain their terminal semantics.
-				if (!started && deps.signal?.aborted) return abortedLeg(spec.agent);
+				if (!started && deps.signal?.aborted) {
+					return finish(abortedLeg(spec.agent));
+				}
 				throw error;
 			} finally {
 				pendingAgents.delete(pending);

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) {

package/src/orchestration/strategies/magi.ts

@@ -5,11 +5,13 @@
  * 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
+ * core sees the PANEL's positions **anonymised** — its own among them, unmarked, because the
+ * reflecting leg is a fresh session and that list is its only memory of round 1 — 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.
+ * iterate-to-consensus — that is `council-rounds`), and dissent is always preserved. A core whose
+ * reflection leg fails keeps the valid vote it already cast (disclosed in the ruling footer).
  * Set `reflect: false` for a pure independent poll (uncorrelated errors, cheapest).
  */
 
@@ -55,6 +57,8 @@ function rescuedModel(c: AgentResult | undefined): string | undefined {
 
 export const magi: Strategy = {
 	name: "magi",
+	when: "contested fork: voters pick on a closed-choice question (yes/no, A/B); majority plus dissent",
+	team: "magi",
 	params: {
 		aggregate: { type: "string", default: "majority", doc: '"majority" | "unanimity"' },
 		reflect: { type: "boolean", default: true, doc: "one anonymised reflection round" },
@@ -88,7 +92,6 @@ export const magi: Strategy = {
 			return cancelled(round1.map((c) => c.usage));
 		}
 
-		let candidates = opening;
 		const okCount = opening.filter((c) => c.ok).length;
 		const tokensBeforeReflection = round1.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
@@ -97,19 +100,19 @@ export const magi: Strategy = {
 		// goes for children: a rescue already spent a child per recovered core, and exceeding
 		// `maxChildren` THROWS out of sdk.agent() — turning a poll that has a ruling into no ruling.
 		const childrenUsed = round1.length + round1.filter((c) => c.modelRecovery).length;
-		const reflectionHasTokenRoom =
-			sdk.limits.budgetTokens <= 0 || tokensBeforeReflection + team.length <= sdk.limits.budgetTokens;
-		const reflectionHasChildRoom = childrenUsed + team.length <= sdk.limits.maxChildren;
-		const didReflect = reflect && okCount >= 2 && reflectionHasTokenRoom && reflectionHasChildRoom;
-		if (reflect && okCount >= 2 && !reflectionHasTokenRoom) {
-			sdk.log(`magi: reflection skipped — token budget cannot fund the full panel (${sdk.limits.budgetTokens})`);
-		}
-		if (reflect && okCount >= 2 && !reflectionHasChildRoom) {
-			sdk.log(`magi: reflection skipped — child budget cannot fund the full panel (maxChildren ${sdk.limits.maxChildren}, ${childrenUsed} used)`);
-		}
+		const wantsReflection = reflect && okCount >= 2;
+		const skip = !wantsReflection ? undefined
+			: sdk.limits.budgetTokens > 0 && tokensBeforeReflection + team.length > sdk.limits.budgetTokens
+				? { why: "token budget", detail: `cannot fund the full panel (${sdk.limits.budgetTokens})` }
+			: childrenUsed + team.length > sdk.limits.maxChildren
+				? { why: "child budget", detail: `cannot fund the full panel (maxChildren ${sdk.limits.maxChildren}, ${childrenUsed} used)` }
+			: undefined;
+		const didReflect = wantsReflection && !skip;
+		if (skip) sdk.log(`magi: reflection skipped — ${skip.why} ${skip.detail}`);
 
+		let reflected: AgentResult[] = [];
 		if (didReflect) {
-			// Round 2 — each core sees the others' positions ANONYMISED (no author identity, so a
+			// Round 2 — each core sees the panel's 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
@@ -123,7 +126,7 @@ export const magi: Strategy = {
 			// 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(
+			reflected = await sdk.parallel(
 				team.map((m, i) => () => {
 					const model = rescuedModel(opening[i]);
 					return sdk.agent({ ...rosterSpec(m), ...(model ? { model } : {}), task: reflectTask, outputContract: "default" });
@@ -134,11 +137,23 @@ export const magi: Strategy = {
 			// 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, ...candidates].map((c) => c.usage));
+			if (sdk.signal?.aborted || reflected.every((c) => c.failureKind === "abort")) {
+				return cancelled([...round1, ...reflected].map((c) => c.usage));
 			}
 		}
-		const decision = sdk.reduce.vote(candidates, { aggregate, keepBestFallback: true });
+		// A reflection leg that FAILED (timeout, provider, contract...) is a missing second opinion, not a
+		// missing voter: the core keeps the valid vote it already cast, so a 3-core poll stays a 3-core
+		// poll. A STOPPED leg is never substituted. The substituted vote is not billed again (`allRuns`).
+		const ballots = didReflect
+			? reflected.map((r, i) => {
+					const first = opening[i];
+					return !r.ok && r.failureKind !== "abort" && first?.ok ? first : r;
+				})
+			: opening;
+		const kept = didReflect ? ballots.filter((b, i) => b !== reflected[i]).length : 0;
+		// "Reflected" means at least one core cast a second-round vote; a round that failed everywhere changed nothing.
+		const reflectedAny = didReflect && kept < ballots.length;
+		const decision = sdk.reduce.vote(ballots, { 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
@@ -156,8 +171,10 @@ export const magi: Strategy = {
 		const rescuedLine = rescued.length > 0
 			? ` · ${rescued.length} core${rescued.length === 1 ? "" : "s"} recovered on ${[...new Set(rescued.map((c) => c.modelRecovery?.to ?? ""))].filter(Boolean).join(", ")}`
 			: "";
+		const keptLine = kept > 0 ? ` · ${kept} core${kept === 1 ? "" : "s"} kept their round-1 vote (reflection failed)` : "";
+		const skipLine = skip ? ` · reflection skipped (${skip.why})` : "";
 		lines.push(
-			`\n— magi: ${decision.status}${didReflect ? " (after 1 reflection round)" : ""}${decision.usedFallback ? " · fell back to best-by-confidence" : ""} · tally ${tally}${invalid}${rescuedLine}`,
+			`\n— magi: ${decision.status}${reflectedAny ? " (after 1 reflection round)" : ""}${decision.usedFallback ? " · fell back to best-by-confidence" : ""} · tally ${tally}${invalid}${rescuedLine}${keptLine}${skipLine}`,
 		);
 
 		const winnerResult = decision.winner?.structured?.result;
@@ -170,16 +187,16 @@ export const magi: Strategy = {
 		// Usage sums EVERY run the poll actually paid for: the opening round (each logical result
 		// already carries its rescue's tokens exactly once) and the reflection round, kept separate
 		// from the opening one when reflection ran.
-		const allRuns: AgentResult[] = didReflect ? [...round1, ...candidates] : round1;
+		const allRuns: AgentResult[] = [...round1, ...reflected];
 		const result: AgentResult = {
 			agent: "magi",
 			output: lines.join("\n"),
-			structured: { status: decision.status, tally: decision.tally, usedFallback: decision.usedFallback, reflected: didReflect, headline },
+			structured: { status: decision.status, tally: decision.tally, usedFallback: decision.usedFallback, reflected: reflectedAny, headline },
 			usage: sumUsage(allRuns.map((c) => c.usage)),
 			ok: decision.winner !== undefined,
 		};
 		if (!result.ok) {
-			const cause = summarizeFailedResults(candidates, "magi produced no ruling");
+			const cause = summarizeFailedResults(ballots, "magi produced no ruling");
 			result.error = cause.error;
 			result.failureKind = cause.failureKind;
 		}

package/src/orchestration/strategies/map.ts

@@ -16,6 +16,7 @@ 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 { compactInlineText } from "../../ui/presentation.ts";
 import { itemLedger, type ItemLedgerEntry, sumUsage } from "../reducers.ts";
 import { parseAuxActor } from "../params.ts";
 import { rosterSpec, type RosterMember, type RosterSpec } from "../roster.ts";
@@ -144,10 +145,16 @@ async function splitIntoItems(
 	task: string,
 	maxItems: number,
 	reserveChildren: number,
+	declareWriteSets: boolean,
 ): Promise<SplitOutcome> {
+	// With ownership on, the splitter is the only party that can declare each item's write set, so it is asked
+	// for the object shape itself: one instruction, not a string array here and objects in the caller's prose.
+	const shape = declareWriteSets
+		? 'a JSON array of {"item": "<short description>", "writeSet": ["<every path a worker would edit>"]} objects (use [] for a read-only item)'
+		: "a JSON array of short strings";
 	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}`,
+		task: `Break this task into independent sub-items. Return ONLY ${shape} — one per sub-item, nothing else.\n\nTask: ${task}`,
 	}, { reserveChildren });
 	if (!split.ok) {
 		return {
@@ -263,6 +270,9 @@ function buildItemLedger(
 
 export const map: Strategy = {
 	name: "map",
+	when: "N items found at runtime: splitter lists, worker handles each in parallel",
+	roster: "[splitter, worker]",
+	team: "swarm",
 	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" },
@@ -304,7 +314,7 @@ export const map: Strategy = {
 		// conservative upper bound; the cap above already guarantees the reserved waves fit.
 		const maxWorkerItems = Math.max(0, Math.floor(maxItems));
 		const splitReserve = maxWorkerItems * (reviewer ? 2 : 1);
-		const split = await splitIntoItems(sdk, splitter, input.task, maxItems, splitReserve);
+		const split = await splitIntoItems(sdk, splitter, input.task, maxItems, splitReserve, ownership !== "off");
 		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)" : ""}`);
@@ -317,7 +327,7 @@ export const map: Strategy = {
 		if (ownership === "enforce") enforceOwnershipOrThrow(items);
 
 		const results = await runWorkers(sdk, worker, input.task, items, peers, reviewer ? items.length : 0);
-		const agg = sdk.reduce.aggregate(results);
+		const agg = sdk.reduce.aggregate(results, items.map((it, i) => `item ${i + 1}: ${compactInlineText(it.item, { maxChars: 60 })}`));
 		// 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.

package/src/orchestration/strategies/pair.ts

@@ -35,6 +35,8 @@ const NAVIGATOR_PROTOCOL = [
 
 export const pair: Strategy = {
 	name: "pair",
+	when: "one member works, a navigator reviews live",
+	roster: "[driver, navigator]",
 	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");

package/src/orchestration/strategies/pipeline.ts

@@ -44,6 +44,8 @@ function failed(results: AgentResult[], upstream: string, step: AgentResult): Ag
 
 export const pipeline: Strategy = {
 	name: "pipeline",
+	when: "ad-hoc ordered stages you name (no installed flow needed): each member refines the previous output; the last answer is the result",
+	roster: "stages, in order",
 	async run(input, sdk) {
 		const team = input.roster ? sdk.roster.team(input.roster) : [];
 		if (team.length === 0) throw new Error("pipeline: a non-empty roster is required");

package/src/orchestration/strategies/synthesize.ts

@@ -10,8 +10,9 @@
  *          peers?: boolean (gatherers share contradictions/corroborations live — default off) }
  */
 
-import { rosterSpec } from "../roster.ts";
+import { rosterNodeKeys, rosterSpec } from "../roster.ts";
 import { fenceUntrusted } from "../../core/fence.ts";
+import { sanitizeStatusLabel } from "../../core/display-label.ts";
 import { parseAuxActor } from "../params.ts";
 import { sumUsage, summarizeFailedResults } from "../reducers.ts";
 import type { Strategy } from "../sdk.ts";
@@ -28,6 +29,9 @@ const CROSS_TALK = [
 
 export const synthesize: Strategy = {
 	name: "synthesize",
+	when: "many angles into ONE deliverable: gatherers in parallel, one synthesiser merges",
+	roster: "gatherers",
+	team: "review",
 	params: {
 		// The default IS roster[0] — declared as `rosterIndex`, never as an agent name: the
 		// participant collector resolves "override, else roster[rosterIndex], else `default`",
@@ -61,10 +65,12 @@ export const synthesize: Strategy = {
 				}, { reserveChildren: 1 }), // leave the mandatory merge slot; SDK reserves queued gatherers
 			),
 		);
-		const usable = results.filter((r) => r.ok && r.output.trim());
+		// Lens-aware labels (`reviewer · SECURITY`): the synthesizer must see WHICH lens found what.
+		const labels = rosterNodeKeys(team);
+		const usable = results.flatMap((r, i) => (r.ok && r.output.trim() ? [{ label: labels[i], output: r.output.trim() }] : []));
 		if (usable.length === 0) {
 			const cause = summarizeFailedResults(results, "no gatherer produced output");
-			const reasons = results.map((r) => `[${r.agent}] ${r.error ?? "(no output)"}`).join("; ");
+			const reasons = results.map((r, i) => `[${labels[i]}] ${r.error ?? "(no output)"}`).join("; ");
 			return {
 				agent: "synthesize",
 				output: `(no gatherer produced output: ${reasons})`,
@@ -74,13 +80,27 @@ export const synthesize: Strategy = {
 				failureKind: cause.failureKind,
 			};
 		}
+		// A partial merge is useful, but a missing review lens is not a clean review. Carry the
+		// runtime coverage into BOTH the merger's input and its returned output, even if it omits it.
+		const missing = results.flatMap((r, i) => r.ok && r.output.trim() ? [] : [{
+			member: sanitizeStatusLabel(labels[i] ?? r.agent),
+			status: r.ok ? "empty" : "failed",
+			detail: sanitizeStatusLabel(r.ok ? "no output" : r.error ?? "no failure detail", "no failure detail", 200),
+		}]);
+		const coverage = missing.length > 0 ? { expected: team.length, usable: usable.length, missing } : undefined;
+		const coverageNote = coverage ? [
+			`Incomplete coverage: ${usable.length}/${team.length} gatherers returned usable findings. Missing members were not reviewed; do not present this as a complete review.`,
+			fenceUntrusted(missing.slice(0, 16).map((m) => `${m.member} — ${m.status}: ${m.detail}`).join("\n")),
+			...(missing.length > 16 ? [`${missing.length - 16} additional missing members are recorded in the result's coverage metadata.`] : []),
+		].join("\n") : "";
 
-		const sections = usable.map((r) => `--- [${r.agent}] ---\n${fenceUntrusted(r.output.trim())}`).join("\n\n");
+		const sections = usable.map((u) => `--- [${u.label}] ---\n${fenceUntrusted(u.output)}`).join("\n\n");
 		const final = await sdk.agent({
 			...synthesizer,
 			task:
 				`Synthesise the findings below into ONE coherent, de-duplicated answer to the task. ` +
 				`Resolve contradictions explicitly (say which finding you trusted and why) and keep every load-bearing detail.\n\n` +
+				(coverageNote ? `${coverageNote}\n\n` : "") +
 				`Task: ${input.task}\n\nFindings:\n${sections}`,
 		});
 
@@ -88,12 +108,12 @@ export const synthesize: Strategy = {
 		// the synthesiser's `result` field if it emitted one, else the first non-empty line.
 		const firstLine = final.output.split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
 		const structuredResult = final.structured?.result;
-		const headline = (typeof structuredResult === "string" && structuredResult.trim() ? structuredResult : firstLine).slice(0, 120);
+		const headline = `${coverage ? `Incomplete coverage: ${usable.length}/${team.length} · ` : ""}${typeof structuredResult === "string" && structuredResult.trim() ? structuredResult : firstLine}`.slice(0, 120);
 
 		const result: AgentResult = {
 			agent: "synthesize",
-			output: final.output,
-			structured: { ...(final.structured ?? {}), gatherers: usable.length, headline },
+			output: coverageNote ? `${coverageNote}\n\n${final.output}` : final.output,
+			structured: { ...(final.structured ?? {}), gatherers: usable.length, headline, ...(coverage ? { coverage } : {}) },
 			usage: sumUsage([...results, final].map((r) => r.usage)),
 			ok: final.ok,
 		};

package/src/orchestration/strategy.ts

@@ -47,3 +47,34 @@ export function knownParams(name: string): Record<string, StrategyParam> | undef
 	const strategy = BUILTINS[name];
 	return strategy ? (strategy.params ?? {}) : undefined;
 }
+
+/** One line per strategy for the council tool's description, generated from the registry:
+ *  `- name(params, required*) — when; roster: positions; default team X.` Guidance on which method fits a
+ *  problem class lives with the method, so it cannot drift from what the code does. */
+export function strategyCatalog(): string {
+	return strategyNames()
+		.map((name) => {
+			const s = BUILTINS[name] as Strategy;
+			const keys = Object.keys(s.params ?? {}).map((k) => (s.required?.includes(k) ? `${k}*` : k));
+			const head = `- ${name}${keys.length > 0 ? `(${keys.join(", ")})` : ""}`;
+			// `magi` is the fallback every call already gets, so only a different default team is worth a mention.
+			const team = s.team && s.team !== "magi" ? `; default team ${s.team}` : "";
+			return `${head}${s.when ? ` — ${s.when}` : ""}${s.roster ? `; roster: ${s.roster}` : ""}${team}.`;
+		})
+		.join("\n");
+}
+
+/** Refuse a council call that cannot run, BEFORE any run, tree row or model picker exists: a
+ *  `required` param that is missing or blank (blank counts as missing, exactly as the strategies'
+ *  own `parseAuxActor` reads it). `undefined` means the call is sound. An UNKNOWN strategy is not
+ *  judged here: the run itself fails with the installed list (an interactive council reports that in
+ *  its completion follow-up, not in the launching call). */
+export function missingRequiredParams(name: string, params: Record<string, unknown>): string | undefined {
+	const strategy = BUILTINS[name];
+	const missing = (strategy?.required ?? []).filter((key) => {
+		const value = params[key];
+		return value === undefined || value === null || (typeof value === "string" && !value.trim());
+	});
+	if (missing.length === 0) return undefined;
+	return `"${name}" requires ${missing.map((key) => `params.${key} — ${strategy?.params?.[key]?.doc ?? "required"}`).join("; ")}`;
+}

package/src/orchestration/types.ts

@@ -2,7 +2,9 @@
  * Orchestration-layer types shared by the SDK, strategies, and reducers.
  */
 
+import type { ThinkingLevel } from "../core/types.ts";
 import type { ChildUsage } from "../engine/stream.ts";
+import type { ResultReceipt } from "../results/retrieval.ts";
 
 export type { ChildUsage };
 
@@ -33,11 +35,19 @@ export interface AgentResult {
 	output: string;
 	/** Validated structured fields (when the agent ran against a contract). */
 	structured?: Record<string, unknown>;
+	/** Terminal archive observation; memory-only is not a durable receipt. */
+	resultReceipt?: ResultReceipt;
 	usage: ChildUsage;
 	ok: boolean;
 	error?: string;
 	/** The canonical `provider/id` the run actually used (drives provider fallback + UI). */
 	modelUsed?: string;
+	/** Selected effort before Pi's model-capability clamp, when a selection is known. */
+	thinkingRequested?: ThinkingLevel;
+	/** Observed Pi effort (session readback or final assistant-message thinkingLevel).
+	 * This is Pi's requested effort, NOT evidence of the provider's actual cognition.
+	 * Absent when the host exposes no validated observation; never inferred from the request. */
+	thinkingEffective?: ThinkingLevel;
 	/** Why it failed (set only when `ok` is false) — drives the model-fallback decision. */
 	failureKind?: FailureKind;
 	/** Set when this result comes from a recovered retry (see {@link ModelRecovery}). Its `usage`