@aeondave/pi-persona 1.15.2

package/src/telemetry/producer.ts

@@ -0,0 +1,390 @@
+import { appendFile, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+	TELEMETRY_PRODUCER_ID,
+	TELEMETRY_PRODUCER_VERSION,
+	TELEMETRY_VERSION,
+	type KnownTelemetryEventType,
+	projectTelemetryPayload,
+	type AgentDescriptor,
+	type InstanceDescriptor,
+	type TelemetryEvent,
+	type TelemetryPayload,
+} from "./contract.ts";
+import { telemetrySessionFileKey, telemetryWorkspaceId } from "./paths.ts";
+
+export interface TelemetryProducerOptions {
+	agentDir: string;
+	cwd: string;
+	sessionId: string;
+	producerId?: string;
+	producerVersion?: string;
+	emit: (event: TelemetryEvent) => void;
+	now?: () => number;
+	heartbeatMs?: number;
+	heartbeat?: () => Partial<InstanceDescriptor>;
+	onError?: (error: unknown) => void;
+	maxFileBytes?: number;
+}
+
+/** Richer caller input. Prompt/activity/output fields are accepted only so the sink can drop them. */
+export type TelemetryAgentInput = AgentDescriptor & { task?: string; detail?: string; output?: string };
+
+const DEFAULT_HEARTBEAT_MS = 5_000;
+const STRING_LIMIT = 512;
+const ARRAY_LIMIT = 256;
+const MAX_DEPTH = 8;
+const DEFAULT_MAX_FILE_BYTES = 4 * 1024 * 1024;
+
+const TERMINAL_AGENT_STATUSES = new Set(["done", "failed", "stopped"]);
+
+/** The replay seeds, split by what compaction is allowed to shed. `droppable` holds the seeds that
+ *  scale with LIVE WORK rather than with the cap — one group per live agent (its `added` plus the
+ *  updates that still describe it) and one per unfinished tool — ordered oldest first. Everything
+ *  else is a fixed handful of instance anchors and is never shed. */
+interface ReplaySeeds {
+	keep: Set<number>;
+	droppable: readonly (readonly number[])[];
+}
+
+/** Identify the minimum original records needed to rebuild current live state after log compaction.
+ * Recent history alone is insufficient when a long-running agent/tool began before the retained tail. */
+function replaySeedIndexes(lines: readonly string[]): ReplaySeeds {
+	type LiveAgent = { added: number; fields: Map<string, number> };
+	const keep = new Set<number>();
+	const instanceFields = new Map<string, number>();
+	const agents = new Map<string, LiveAgent>();
+	const tools = new Map<string, number>();
+	let firstInstance = -1;
+	let latestInstance = -1;
+	let latestStop = -1;
+	let latestPeers = -1;
+	for (let index = 0; index < lines.length; index += 1) {
+		let event: { type?: unknown; payload?: unknown };
+		try { event = JSON.parse(lines[index] ?? "") as { type?: unknown; payload?: unknown }; }
+		catch { continue; }
+		const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+			? event.payload as Record<string, unknown>
+			: {};
+		if (event.type === "instance.started") {
+			if (firstInstance < 0) firstInstance = index;
+			latestInstance = index;
+			instanceFields.clear();
+			continue;
+		}
+		if (event.type === "instance.updated" || event.type === "instance.heartbeat") {
+			for (const field of Object.keys(payload)) instanceFields.set(field, index);
+			continue;
+		}
+		if (event.type === "instance.stopped") { latestStop = index; continue; }
+		if (event.type === "peers.snapshot") { latestPeers = index; continue; }
+		if (event.type === "agent.added") {
+			const id = typeof payload.id === "string" ? payload.id : undefined;
+			if (!id) continue;
+			if (typeof payload.status === "string" && TERMINAL_AGENT_STATUSES.has(payload.status)) agents.delete(id);
+			else agents.set(id, { added: index, fields: new Map() });
+			continue;
+		}
+		if (event.type === "agent.updated") {
+			const id = typeof payload.id === "string" ? payload.id : undefined;
+			const patch = payload.patch && typeof payload.patch === "object" && !Array.isArray(payload.patch)
+				? payload.patch as Record<string, unknown>
+				: undefined;
+			const active = id ? agents.get(id) : undefined;
+			if (!id || !patch || !active) continue;
+			if (typeof patch.status === "string" && TERMINAL_AGENT_STATUSES.has(patch.status)) { agents.delete(id); continue; }
+			for (const field of Object.keys(patch)) active.fields.set(field, index);
+			continue;
+		}
+		if (event.type === "agent.removed") {
+			if (typeof payload.id === "string") agents.delete(payload.id);
+			continue;
+		}
+		if (event.type === "agent.cleared") { agents.clear(); continue; }
+		if (event.type === "tool.started") {
+			if (typeof payload.callId === "string") tools.set(payload.callId, index);
+			continue;
+		}
+		if (event.type === "tool.finished" && typeof payload.callId === "string") tools.delete(payload.callId);
+	}
+	if (firstInstance >= 0) keep.add(firstInstance);
+	else if (lines.length > 0) keep.add(0);
+	if (latestInstance >= 0) keep.add(latestInstance);
+	if (latestStop >= 0) keep.add(latestStop);
+	if (latestPeers >= 0) keep.add(latestPeers);
+	for (const index of instanceFields.values()) keep.add(index);
+	// Snapshot the anchors before the live seeds join them: a log with no instance.started falls back
+	// to line 0, which may itself be a live tool or agent, and shedding it would take the anchor too.
+	const pinned = new Set(keep);
+	const droppable: number[][] = [];
+	const shedGroup = (indexes: number[]) => {
+		// Dedupe first: an agent's `fields` map is keyed by FIELD NAME, so one `agent.updated`
+		// patching N fields contributes N references to the SAME line. Sized once per reference the
+		// budget below over-estimates the group and sheds live agents whose seeds actually fit.
+		const group = [...new Set(indexes)].filter((index) => !pinned.has(index));
+		if (group.length > 0) droppable.push(group);
+	};
+	for (const agent of agents.values()) {
+		keep.add(agent.added);
+		for (const index of agent.fields.values()) keep.add(index);
+		// One group per agent: its field updates are worthless without the `added` that introduced
+		// it, so the budget below sheds the whole agent or none of it — never orphan patches.
+		shedGroup([agent.added, ...agent.fields.values()]);
+	}
+	for (const index of tools.values()) { keep.add(index); shedGroup([index]); }
+	// Oldest live work first: the newest agents and tools are the ones a consumer is still watching.
+	// The instance anchors and field seeds stay out of this list — there is one per instance field, a
+	// count fixed by the descriptor's shape, so they never grow the seed set past the cap on their own.
+	droppable.sort((left, right) => (left[0] ?? 0) - (right[0] ?? 0));
+	return { keep, droppable };
+}
+
+async function appendBounded(file: string, line: string, maxBytes: number): Promise<void> {
+	await appendFile(file, line, { encoding: "utf8", mode: 0o600 });
+	const size = (await stat(file)).size;
+	if (size <= maxBytes) return;
+	const contents = await readFile(file);
+	const targetBytes = Math.max(128, Math.floor(maxBytes / 2));
+	// Keep the immutable instance anchor so replay after compaction still has stream identity.
+	// The cap is soft for one complete event (and the anchor) rather than truncating JSONL records.
+	const lines = contents.toString("utf8").split("\n").filter((item) => item.length > 0);
+	const { keep: kept, droppable } = replaySeedIndexes(lines);
+	const lineBytes = (index: number) => Buffer.byteLength(lines[index] ?? "") + 1;
+	let keptBytes = [...kept].reduce((total, index) => total + lineBytes(index), 0);
+	// Bound the live-work seeds against the target BEFORE writing them. They scale with the number of
+	// live agents and unfinished tools, not with the cap, so left alone they outgrow maxBytes on their
+	// own: the file then never comes back under the cap, every later append pays another full read +
+	// rewrite, and the loop below can retain nothing but the newest record. Shedding the stalest seed
+	// costs one agent's reconstruction, which is far cheaper than erasing the log. The instance
+	// anchors sit outside this budget so a live agent still replays under a cap a few records wide.
+	let liveSeedBytes = droppable.reduce((total, group) => total + group.reduce((sum, index) => sum + lineBytes(index), 0), 0);
+	for (const group of droppable) {
+		if (liveSeedBytes <= targetBytes) break;
+		for (const index of group) {
+			if (!kept.delete(index)) continue;
+			keptBytes -= lineBytes(index);
+			liveSeedBytes -= lineBytes(index);
+		}
+	}
+	for (let index = lines.length - 1; index >= 0; index -= 1) {
+		if (kept.has(index)) continue;
+		const candidateBytes = lineBytes(index);
+		if (keptBytes + candidateBytes > targetBytes) {
+			// Always retain the newest complete event even when one record is larger than the soft cap.
+			if (index === lines.length - 1) { kept.add(index); keptBytes += candidateBytes; }
+			break;
+		}
+		kept.add(index);
+		keptBytes += candidateBytes;
+	}
+	const retained = [...kept].sort((left, right) => left - right).map((index) => lines[index]).join("\n") + "\n";
+	const temp = `${file}.trim-${process.pid}-${Date.now()}`;
+	const backup = `${file}.previous`;
+	await writeFile(temp, retained, { encoding: "utf8", mode: 0o600 });
+	try {
+		await unlink(backup).catch(() => undefined);
+		await rename(file, backup);
+		await rename(temp, file);
+		await unlink(backup);
+	} catch (error) {
+		await unlink(temp).catch(() => undefined);
+		await rename(backup, file).catch(() => undefined);
+		throw error;
+	}
+}
+
+function boundedText(value: string, max = STRING_LIMIT): string {
+	return Array.from(value.normalize("NFKC").replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029<>]/g, " ").replace(/\s+/g, " ").trim())
+		.slice(0, max)
+		.join("");
+}
+
+function sanitizeValue(value: unknown, depth = 0): unknown {
+	if (depth > MAX_DEPTH) return "[depth bounded]";
+	if (typeof value === "string") return boundedText(value);
+	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+	if (typeof value === "boolean" || value === null) return value;
+	if (Array.isArray(value)) return value.slice(0, ARRAY_LIMIT).map((item) => sanitizeValue(item, depth + 1));
+	if (value && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [key, item] of Object.entries(value).slice(0, ARRAY_LIMIT)) {
+			if (item !== undefined) out[boundedText(key, 80)] = sanitizeValue(item, depth + 1);
+		}
+		return out;
+	}
+	return undefined;
+}
+
+/** The last persisted sequence, plus whether the log ends mid-record — a crash between an append's
+ *  open and its write leaves the final line unterminated, and the next append fuses onto it. */
+function lastSequence(file: string): { seq: number; needsNewline: boolean } {
+	try {
+		const contents = readFileSync(file, "utf8");
+		const needsNewline = contents.length > 0 && !contents.endsWith("\n");
+		const lines = contents.trimEnd().split("\n");
+		for (let i = lines.length - 1; i >= 0; i--) {
+			const line = lines[i];
+			if (!line) continue;
+			try {
+				const parsed = JSON.parse(line) as { seq?: unknown };
+				if (Number.isSafeInteger(parsed.seq) && (parsed.seq as number) >= 1) return { seq: parsed.seq as number, needsNewline };
+			} catch {
+				/* a torn final line is ignored; scan backwards to the last valid event */
+			}
+		}
+		return { seq: 0, needsNewline };
+	} catch {
+		/* first activation for this session */
+	}
+	return { seq: 0, needsNewline: false };
+}
+
+function sanitizeInstance(value: InstanceDescriptor): InstanceDescriptor {
+	return {
+		displayName: boundedText(value.displayName, 80) || "pi",
+		status: boundedText(value.status, 64) || "active",
+		...(value.persona !== undefined ? { persona: boundedText(value.persona, 64) } : {}),
+		...(value.model !== undefined ? { model: boundedText(value.model, 160) } : {}),
+		...(value.pid !== undefined ? { pid: Number.isInteger(value.pid) && value.pid > 0 ? value.pid : 0 } : {}),
+		...(value.contextPercent !== undefined ? { contextPercent: Math.max(0, Math.min(100, Number(value.contextPercent) || 0)) } : {}),
+		...(value.exocomEnabled !== undefined ? { exocomEnabled: value.exocomEnabled } : {}),
+		...(value.color && /^#[0-9A-Fa-f]{3,8}$/.test(value.color) ? { color: value.color } : {}),
+	};
+}
+
+function sanitizeAgent(value: TelemetryAgentInput): AgentDescriptor {
+	return {
+		id: boundedText(value.id, 160),
+		label: boundedText(value.label, 160) || "agent",
+		kind: boundedText(value.kind, 64) || "subagent",
+		status: boundedText(value.status, 64) || "running",
+		...(value.parentId ? { parentId: boundedText(value.parentId, 160) } : {}),
+		...(value.agent ? { agent: boundedText(value.agent, 80) } : {}),
+		...(value.persona ? { persona: boundedText(value.persona, 80) } : {}),
+		...(value.model ? { model: boundedText(value.model, 160) } : {}),
+	};
+}
+
+function sanitizeAgentPatch(value: Partial<TelemetryAgentInput>): Partial<AgentDescriptor> {
+	return {
+		...(value.label !== undefined ? { label: boundedText(value.label, 160) || "agent" } : {}),
+		...(value.kind !== undefined ? { kind: boundedText(value.kind, 64) || "subagent" } : {}),
+		...(value.status !== undefined ? { status: boundedText(value.status, 64) || "running" } : {}),
+		...(value.parentId !== undefined ? { parentId: boundedText(value.parentId, 160) } : {}),
+		...(value.agent !== undefined ? { agent: boundedText(value.agent, 80) } : {}),
+		...(value.persona !== undefined ? { persona: boundedText(value.persona, 80) } : {}),
+		...(value.model !== undefined ? { model: boundedText(value.model, 160) } : {}),
+	};
+}
+
+function producerSegment(value: string | undefined, fallback: string): string {
+	const safe = value?.trim().replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 96);
+	return safe || fallback;
+}
+
+export class TelemetryProducer {
+	readonly workspaceId: string;
+	readonly filePath: string;
+	private readonly options: TelemetryProducerOptions;
+	private seq: number;
+	private writeChain: Promise<void> = Promise.resolve();
+	private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+	private instance: InstanceDescriptor | undefined;
+	private stopped = false;
+	readonly producerId: string;
+	readonly producerVersion: string;
+
+	constructor(options: TelemetryProducerOptions) {
+		this.options = options;
+		this.producerId = producerSegment(options.producerId, TELEMETRY_PRODUCER_ID);
+		this.producerVersion = producerSegment(options.producerVersion, TELEMETRY_PRODUCER_VERSION);
+		if (options.maxFileBytes !== undefined && (!Number.isSafeInteger(options.maxFileBytes) || options.maxFileBytes < 512)) throw new RangeError("maxFileBytes must be at least 512");
+		this.workspaceId = telemetryWorkspaceId(options.cwd);
+		const dir = join(options.agentDir, "telemetry", "v2", this.workspaceId, this.producerId);
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		const fileKey = telemetrySessionFileKey(options.sessionId);
+		this.filePath = join(dir, `${fileKey}.jsonl`);
+		const backup = `${this.filePath}.previous`;
+		if (!existsSync(this.filePath) && existsSync(backup)) {
+			try { renameSync(backup, this.filePath); } catch { /* a concurrent activation will retry on its own */ }
+		} else if (existsSync(this.filePath) && existsSync(backup)) {
+			try { unlinkSync(backup); } catch { /* best effort */ }
+		}
+		try {
+			for (const name of readdirSync(dir)) if (name.startsWith(`${fileKey}.jsonl.trim-`)) unlinkSync(join(dir, name));
+		} catch { /* best effort cleanup of interrupted compaction scratch files */ }
+		const { seq, needsNewline } = lastSequence(this.filePath);
+		this.seq = seq;
+		// Close a torn tail ONCE, before the first append: otherwise the next record is concatenated
+		// onto the partial bytes and BOTH are unreadable, so a consumer replaying the file sees only
+		// a sequence gap — a tool started before the crash stays "running" forever.
+		if (needsNewline) {
+			try { appendFileSync(this.filePath, "\n", { encoding: "utf8", mode: 0o600 }); } catch { /* the write chain reports a real append failure */ }
+		}
+	}
+
+	start(instance: InstanceDescriptor): void {
+		if (this.instance || this.stopped) return;
+		this.instance = sanitizeInstance(instance);
+		this.publish("instance.started", this.instance);
+		const heartbeatMs = this.options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+		if (heartbeatMs > 0) {
+			this.heartbeatTimer = setInterval(() => {
+				const dynamic = this.options.heartbeat?.() ?? {};
+				this.publish("instance.heartbeat", dynamic);
+			}, heartbeatMs);
+			this.heartbeatTimer.unref?.();
+		}
+	}
+
+	publish<T extends KnownTelemetryEventType>(type: T, payload: TelemetryPayload<T>): TelemetryEvent<T> | undefined {
+		if (this.stopped) return undefined;
+		this.seq += 1;
+		const event = {
+			version: TELEMETRY_VERSION,
+			producerId: this.producerId,
+			producerVersion: this.producerVersion,
+			id: `${this.producerId}:${this.options.sessionId}:${this.seq}`,
+			seq: this.seq,
+			ts: this.options.now?.() ?? Date.now(),
+			sessionId: this.options.sessionId,
+			workspaceId: this.workspaceId,
+			type,
+			payload: projectTelemetryPayload(type, sanitizeValue(payload)) as TelemetryPayload<T>,
+		} as TelemetryEvent<T>;
+		try {
+			this.options.emit(event as TelemetryEvent);
+		} catch (error) {
+			this.options.onError?.(error);
+		}
+		const line = `${JSON.stringify(event)}\n`;
+		this.writeChain = this.writeChain
+			.catch(() => undefined)
+			.then(() => appendBounded(this.filePath, line, this.options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES))
+			.catch((error) => { this.options.onError?.(error); });
+		return event;
+	}
+
+	publishAgentAdded(agent: TelemetryAgentInput): TelemetryEvent<"agent.added"> | undefined {
+		return this.publish("agent.added", sanitizeAgent(agent));
+	}
+
+	publishAgentUpdated(id: string, patch: Partial<TelemetryAgentInput>): TelemetryEvent<"agent.updated"> | undefined {
+		return this.publish("agent.updated", { id: boundedText(id, 160), patch: sanitizeAgentPatch(patch) });
+	}
+
+	async flush(): Promise<void> {
+		await this.writeChain;
+	}
+
+	async stop(reason?: string): Promise<void> {
+		if (this.stopped) return;
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = undefined;
+		this.publish("instance.stopped", { reason: reason ? boundedText(reason, 120) : "shutdown" });
+		this.stopped = true;
+		await this.flush();
+	}
+}

package/src/tools/council.ts

@@ -0,0 +1,200 @@
+/** `council` tool — deliberate, vote, ruling. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { fenceUntrusted } from "../core/fence.ts";
+import { expandDetailHint, failureDetails, formatCouncilCallLabel } from "../extension/shared.ts";
+import { knownParams, strategyNames } from "../orchestration/strategy.ts";
+import { formatCouncilResult, humanizeAggregateResult } from "../orchestration/render.ts";
+import type { FailureKind } from "../orchestration/types.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import { resolveCouncilInvocation } from "../persona/persona.ts";
+import type { OrchestrationGrammar, Persona } from "../persona/persona.ts";
+import type { PersonaController } from "../persona/controller.ts";
+import { Text } from "@earendil-works/pi-tui";
+import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
+import { compactVisibleText } from "../ui/presentation.ts";
+import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import { emptyUsage } from "../engine/stream.ts";
+
+
+export interface CouncilToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	controller: PersonaController;
+	personas: Persona[];
+	runStrategyVisible(
+		ctx: ExtensionContext,
+		orch: OrchestrationGrammar,
+		task: string,
+		label: string,
+		signal?: AbortSignal,
+	): Promise<AgentResult | undefined>;
+	drainBusBlock(): string;
+	childUsage: ChildUsageLedger;
+	publishPersonaCost(): void;
+}
+
+export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void {
+	// ── council tool (deliberate → vote → ruling; the executor then applies it) ───
+	const CouncilParams = Type.Object({
+		question: Type.String({ description: "The decision or problem to deliberate — specific and self-contained" }),
+		persona: Type.Optional(
+			Type.String({
+				description:
+					'Installed persona whose declared council profile to use (for example "magi"). This borrows only its council strategy/roster/params; the active caller remains in control.',
+			}),
+		),
+		strategy: Type.Optional(
+			Type.String({ description: 'Per-call strategy override (default: the selected or active council profile\'s strategy, or built-in "magi")' }),
+		),
+		roster: Type.Optional(Type.String({ description: 'Per-call roster override (default: the selected or active profile\'s roster, then its orchestration roster, or built-in "magi")' })),
+		params: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description:
+					'Strategy params, merged over the persona\'s (e.g. { "reflect": false } to skip magi\'s reflection round, { "aggregate": "unanimity" }, { "rounds": 3 }). Reach for it when the user asks for a variant of the persona\'s default council this one time.',
+			}),
+		),
+	});
+	pi.registerTool({
+		name: "council",
+		label: "Council",
+		description: [
+			"Convene a council of specialists with controlled, complementary biases to deliberate a",
+			"decision — returns the selected strategy's result, preserving vote tally and dissent when produced.",
+			"Use it before any significant choice; then EXECUTE the ruling yourself and re-convene when",
+			"execution surfaces a new decision. Patterns: adversarial vote (magi, council-rounds), best-of-N",
+			"with an impartial arbiter (judge, compete), batch map, merged synthesis (synthesize).",
+			'Use `persona: "magi"` to invoke an installed persona\'s declared council without switching away',
+			"from the active caller; its prompt, model, tools, and permissions are never inherited.",
+			`Strategies: ${strategyNames()
+				.map((n) => {
+					const p = knownParams(n);
+					const keys = p ? Object.keys(p) : [];
+					return keys.length > 0 ? `${n}(${keys.join(", ")})` : n;
+				})
+				.join(" · ")}.`,
+			'Pass `params` to vary the persona\'s default council for one call — e.g. { "reflect": false }.',
+		].join(" "),
+		parameters: CouncilParams,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			const resolved = resolveCouncilInvocation(d.personas, d.controller.activePersona, {
+				persona: params.persona,
+				strategy: params.strategy,
+				roster: params.roster,
+				params: params.params as Record<string, unknown> | undefined,
+			});
+			if (!resolved.ok) {
+				return {
+					content: [{ type: "text", text: `council failed: ${resolved.error}` }],
+					details: failureDetails({ error: resolved.error, persona: params.persona }),
+					isError: true,
+				};
+			}
+			const { strategy, roster, params: mergedParams, persona } = resolved.value;
+			try {
+				// Fully persona-driven: a persona's `council:` block picks the strategy, roster,
+				// and params — a new ensemble (more members, supermajority, multi-round) needs no
+				// code, just a team + (optional) strategy file + a council block. Params override.
+				// Per-call params override the selected council profile (e.g. reflect:false this once).
+				// Lenient by design (I2: strategies are trusted project code) — an unknown param key
+				// only warns, it never blocks or alters the run. A correct call is untouched.
+				let paramNote = "";
+				const schema = knownParams(strategy);
+				if (schema) {
+					const unknown = Object.keys(mergedParams).filter((k) => !(k in schema));
+					if (unknown.length > 0) {
+						const note = `council: ignoring unknown param(s) [${unknown.join(", ")}] for "${strategy}" — known: ${Object.keys(schema).join(", ") || "(none)"}`;
+						if (process.env.PI_PERSONA_DEBUG) process.stderr.write(`[pi-persona] ${note}\n`);
+						ctx.ui.notify(note, "warning");
+						paramNote = `\n\n(${note})`;
+					}
+				}
+				const orch: OrchestrationGrammar = { mode: "strategy", strategy, roster, params: mergedParams };
+				const result = await d.runStrategyVisible(ctx, orch, params.question, `council:${_id}`, signal);
+				const s = (result?.structured ?? {}) as {
+					headline?: string;
+					status?: string;
+					tally?: Record<string, number>;
+					usedFallback?: boolean;
+					count?: number;
+					items?: unknown;
+				};
+				const ruling = result?.output ?? "(the council returned no ruling)";
+				const uiBody = result ? (humanizeAggregateResult(result) ?? result.output) : "";
+				const headline = s.headline ?? (typeof s.count === "number" ? `${s.count} member results` : s.status ?? "");
+				const ok = result?.ok ?? false;
+				const details = {
+					ok,
+					headline,
+					status: s.status,
+					tally: s.tally,
+					usedFallback: s.usedFallback,
+					items: s.items,
+					body: uiBody,
+					strategy,
+					roster,
+					persona,
+					...(result?.error ? { error: result.error } : {}),
+					...(result?.failureKind ? { failureKind: result.failureKind } : {}),
+				};
+				const usage = result?.usage ?? emptyUsage();
+				d.childUsage.account(usage);
+				d.publishPersonaCost();
+				return {
+					// The ruling is sub-agent (council member) text — fence it like every other
+					// path that hands sub-agent output to the supervisor.
+					content: [{ type: "text", text: `${fenceUntrusted(ruling)}${paramNote}${d.drainBusBlock()}` }],
+					details: ok ? details : failureDetails(details),
+					isError: !ok,
+					...toolUsageField(usage),
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `council failed: ${message}` }], details: failureDetails({ error: message, strategy, roster }), isError: true };
+			}
+		},
+		renderCall(args, theme) {
+			const resolved = resolveCouncilInvocation(d.personas, d.controller.activePersona, {
+				persona: args.persona,
+				strategy: args.strategy,
+				roster: args.roster,
+				params: args.params as Record<string, unknown> | undefined,
+			});
+			const strategy = resolved.ok ? resolved.value.strategy : (args.strategy ?? "?");
+			const roster = resolved.ok ? resolved.value.roster : (args.roster ?? args.persona ?? "?");
+			return new Text(theme.fg("toolTitle", theme.bold(formatCouncilCallLabel(strategy, roster))), 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const d = (result.details ?? {}) as {
+				ok?: boolean;
+				headline?: string;
+				status?: string;
+				tally?: Record<string, number>;
+				usedFallback?: boolean;
+				body?: string;
+				strategy?: string;
+				roster?: string;
+				error?: string;
+				failureKind?: FailureKind;
+			};
+			const first = result.content[0];
+			const body = sanitizeTerminalText(d.body || (first && first.type === "text" ? first.text : ""));
+			const failed = d.ok === false || !!d.error;
+			if (failed) {
+				const cause = compactInlineText([d.failureKind, d.error].filter((part): part is string => !!part).join(" · "), { maxChars: 160 });
+				const title = theme.fg("error", theme.bold(`council failed${cause ? ` · ${cause}` : ""}`));
+				if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", body || "(no ruling)")}`, 0, 0);
+				const preview = compactVisibleText(body || "(no ruling)", { maxLines: 3, maxLineChars: 100 });
+				const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
+				return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+			}
+			const text = formatCouncilResult(
+				{ headline: d.headline, status: d.status, tally: d.tally, usedFallback: d.usedFallback, body },
+				expanded,
+				expandDetailHint(),
+			);
+			return new Text(theme.fg(expanded ? "toolOutput" : "accent", text), 0, 0);
+		},
+	});
+}