@aeondave/pi-persona 1.17.1 → 1.17.3

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/persona/persona.ts

@@ -11,6 +11,7 @@ import { asBoolean, asPermission, asStringArray, parseYamlSubset, splitFrontmatt
 import type { Permission } from "../core/permissions.ts";
 import { asSystemPromptMode, type SystemPromptMode } from "../core/types.ts";
 import { parseRuntimeRosterMember, type RosterMember } from "../orchestration/roster.ts";
+import { getStrategy } from "../orchestration/strategy.ts";
 
 export type OrchestrationMode = "solo" | "parallel" | "pipeline" | "strategy" | "flow";
 const ORCHESTRATION_MODES: readonly OrchestrationMode[] = ["solo", "parallel", "pipeline", "strategy", "flow"];
@@ -323,16 +324,19 @@ export function resolveCouncilInvocation(
 		if (!parsed.ok) return { ok: false, error: parsed.error };
 		members = parsed.members;
 	}
+	// A call that switches to another method starts from THAT method's team and params: the profile's roster and
+	// params belong to the profile's own strategy (dev's `repair` pair would otherwise be seated as magi voters).
+	const switched = strategy !== (base?.strategy || "magi");
 	const roster = members
 		? ""
 		: request.roster?.trim() ||
+			(switched ? getStrategy(strategy)?.team : undefined) ||
 			base?.roster ||
 			sourcePersona?.orchestration?.roster ||
 			(!requestedName ? activePersona?.orchestration?.roster : undefined) ||
 			"magi";
-	// Profile params belong to the profile's strategy. A per-call strategy switch starts
-	// with that strategy's own defaults; only explicitly supplied params cross the switch.
-	const inheritedParams = strategy !== (base?.strategy || "magi") ? {} : base?.params ?? {};
+	// Only explicitly supplied params cross a strategy switch.
+	const inheritedParams = switched ? {} : base?.params ?? {};
 	const value: ResolvedCouncilInvocation = {
 		strategy,
 		roster,

package/src/telemetry/contract.ts

@@ -4,7 +4,7 @@ export const TELEMETRY_EVENT_NAME = "pi:telemetry" as const;
 export const LEGACY_TELEMETRY_EVENT_NAME = "pi-persona:telemetry" as const;
 export const LEGACY_TELEMETRY_VERSION = 1 as const;
 export const TELEMETRY_PRODUCER_ID = "pi-persona" as const;
-export const TELEMETRY_PRODUCER_VERSION = "1.17.1" as const;
+export const TELEMETRY_PRODUCER_VERSION = "1.17.3" as const;
 
 export type InstanceStatus = "active" | "idle" | "stopped" | "stale" | (string & {});
 export type AgentKind = "subagent" | "delegate" | "council" | "flow" | "phase" | (string & {});

package/src/tools/background-run.ts

@@ -0,0 +1,151 @@
+/**
+ * `council` and `flow` as ONE tracked run (the same machinery `delegate` uses): a visible strategy or
+ * flow is launched into the {@link AsyncRunTracker}, rooted in the agent tree at `async:<runId>`, and
+ * reachable through the stop key `async:<runId>`: `intercom stop`, stop all, and `x` on the run's root row
+ * in the f9 overlay all end the whole run. Interactive sessions get a receipt at once and ONE completion
+ * follow-up (`renderCompletion`); headless sessions join the same run before the tool returns, so the
+ * single turn carries the result.
+ *
+ * Which semaphore gates what:
+ *  - `slots` is the launch pool `delegate` already uses (`maxConcurrency`). A council or flow takes ONE
+ *    slot for the whole run, exactly like one delegate leg, and shows `queued` until it has it.
+ *  - The strategy SDK's own per-run semaphore (`orchestration/sdk.ts`) gates the legs INSIDE the run, so
+ *    a council's members never compete with delegate legs for these slots and cannot deadlock on them.
+ *    A flow parked at a human checkpoint keeps its slot for the wait: the operator owns that wait, and
+ *    stopping the run releases it.
+ *  - Token budgets, the child limit and the fork-bomb guard live in that SDK and the engine, untouched.
+ */
+import { END_TURN_NOTE } from "../core/brief.ts";
+import type { ChildUsage } from "../engine/stream.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import type { Semaphore } from "../orchestration/parallel.ts";
+import { madeHeadway, type AsyncRun, type AsyncRunTracker, type IdleCoalescingNotifier, type ProgressReading } from "../engine/async.ts";
+import type { AgentTree } from "../ui/agent-tree.ts";
+import type { ChildUsageLedger } from "../ui/usage.ts";
+
+/** What a visible runner is handed when it works for a tracked run (absent ⇒ it roots and stops itself). */
+export interface TrackedRun {
+	/** The tree root of this run: `async:<runId>`. Its nodes hang under it. */
+	rootId: string;
+	/** Fires when the run is stopped — by key, by `intercom stop`, or by the headless tool call's abort. */
+	signal: AbortSignal;
+	/** Interactive: the launching turn has ended and the supervisor is idle, so a coached leg may block on an
+	 *  ask (the run's engines are built `async`). Headless: the call is parked in the turn and could not answer. */
+	background: boolean;
+	/** One leg progressed: feeds the run's cumulative tokens, and its stall clock when the leg made headway. */
+	onProgress(leg: string, progress: ProgressReading): void;
+	/** The run is blocked on the operator (a flow checkpoint) — or released again (`undefined`). */
+	onAwaiting(label: string | undefined): void;
+}
+
+export interface BackgroundRunDeps {
+	tracker: AsyncRunTracker;
+	agentTree: AgentTree;
+	stopRegistry: Map<string, () => void>;
+	/** The launch pool shared with `delegate` (see the module comment). */
+	slots: Semaphore;
+	completionNotifier: Pick<IdleCoalescingNotifier<AsyncRun>, "discard">;
+	startPeek(): void;
+	childUsage: ChildUsageLedger;
+	publishPersonaCost(): void;
+}
+
+/** `inline` (headless) skips the status monitor: the launching call joins the run and nobody reads a status card. */
+export interface LaunchMeta { kind: "council" | "flow"; label: string; task: string; inline: boolean }
+
+type RunWork = (run: TrackedRun) => Promise<AgentResult>;
+
+/** The receipt an interactive `council`/`flow` launch returns. `wake` finishes "you will be woken ONCE ...". */
+export function launchReceipt(kind: LaunchMeta["kind"], id: string, subject: string, wake: string): string {
+	return `Launched ${kind} ${id} (${subject}) in the background — you will be woken ONCE ${wake} (${END_TURN_NOTE}).`;
+}
+
+export interface BackgroundRuns {
+	/** Launch `work` as one tracked run and return its id. */
+	launch(meta: LaunchMeta, work: RunWork): string;
+	/** Join launched runs (headless): wait for all of them, stop them if `signal` aborts, drop the follow-ups
+	 *  this return replaces, and bill their usage once. `onSettled` sees each settle as (done, total). */
+	settle(ids: readonly string[], signal: AbortSignal | undefined, onSettled?: (done: number, total: number) => void): Promise<{ runs: AsyncRun[]; usage: ChildUsage }>;
+}
+
+export function createBackgroundRuns(d: BackgroundRunDeps): BackgroundRuns {
+	function launch(meta: LaunchMeta, work: RunWork): string {
+		// `mutates`: a strategy's legs and their tool grants are decided leg by leg inside the run, so the run
+		// is classed as a potential writer — the fail-closed answer for a persona's fresh-verification policy
+		// (whose refusal says "may mutate", which is all this classification knows).
+		const id = d.tracker.launch({ agent: meta.label, task: meta.task, label: meta.label, mutates: true, queued: true }, (onProgress, runId) => {
+			const rootId = `async:${runId}`;
+			const ac = new AbortController();
+			d.stopRegistry.set(rootId, () => ac.abort());
+			const legSeen = new Map<string, ProgressReading>();
+			const legTokens = new Map<string, number>();
+			const snapshot = (output = ""): { output: string; turns: number; tokens: number } => ({ output, turns: 0, tokens: [...legTokens.values()].reduce((a, b) => a + b, 0) });
+			const run: TrackedRun = {
+				rootId,
+				signal: ac.signal,
+				background: !meta.inline,
+				onProgress: (leg, progress) => {
+					// Headway is judged per leg - the run's own snapshot is only their token sum - by the same rule a
+					// delegate leg is held to, so one chatty tool in one leg cannot keep the whole run looking alive.
+					if (madeHeadway(legSeen.get(leg), progress)) d.tracker.advance(runId);
+					legSeen.set(leg, progress);
+					legTokens.set(leg, progress.tokens ?? legTokens.get(leg) ?? 0);
+					onProgress(snapshot());
+				},
+				onAwaiting: (label) => {
+					d.tracker.setAwaiting(runId, label);
+				},
+			};
+			return d.slots
+				.with(async () => {
+					d.tracker.markAdmitted(runId);
+					const result = await work(run);
+					// A ruling or plan that did not complete lives in `result.output`, but a failed or stopped run's
+					// report salvages the tracker's `progress.output` — hand it over so that work is not lost.
+					if (!result.ok && result.output) onProgress(snapshot(result.output));
+					return result;
+				}, ac.signal)
+				.catch((error: unknown): AgentResult => {
+					if (!ac.signal.aborted) throw error;
+					return { agent: meta.label, output: "", usage: emptyUsage(), ok: false, error: "run aborted", failureKind: "abort" };
+				});
+		});
+		// Visible while queued, so `x` and the tree's stop work before the pool grants a slot; the visible runner
+		// upserts this same row when it starts.
+		d.agentTree.add({ id: `async:${id}`, label: meta.label, kind: meta.kind, status: "running", detail: "queued" });
+		if (!meta.inline) d.startPeek();
+		return id;
+	}
+
+	async function settle(ids: readonly string[], signal: AbortSignal | undefined, onSettled?: (done: number, total: number) => void): Promise<{ runs: AsyncRun[]; usage: ChildUsage }> {
+		const runs = ids.flatMap((id) => d.tracker.peek(id) ?? []); // launch() registers each, and a running entry is never evicted
+		const stopAll = (): void => {
+			for (const id of ids) d.stopRegistry.get(`async:${id}`)?.();
+		};
+		if (signal?.aborted) stopAll();
+		else signal?.addEventListener("abort", stopAll, { once: true });
+		try {
+			if (runs.some((run) => !run.settled)) {
+				await new Promise<void>((resolve) => {
+					const off = d.tracker.onComplete(() => {
+						const done = runs.filter((run) => run.settled).length;
+						onSettled?.(done, runs.length);
+						if (done === runs.length) {
+							off();
+							resolve();
+						}
+					});
+				});
+			}
+		} finally {
+			signal?.removeEventListener("abort", stopAll);
+		}
+		d.completionNotifier.discard((pending) => ids.includes(pending.id)); // this return IS the delivery
+		const usage = d.childUsage.accountMany(runs.map((run) => ({ key: run.id, usage: run.result?.usage ?? emptyUsage() })));
+		d.publishPersonaCost();
+		return { runs, usage };
+	}
+
+	return { launch, settle };
+}