@aeondave/pi-persona 1.15.2

package/src/persona/controller.ts

@@ -0,0 +1,173 @@
+/**
+ * PersonaController — applies a persona to the host session and restores
+ * baselines symmetrically. Drives an injected `PersonaHost` (a subset of the Pi
+ * ExtensionAPI) so the snapshot/restore discipline is unit-testable.
+ *
+ * Invariants (lose-nothing): model/thinking baseline is snapshotted ONCE on the
+ * first override and restored when a later persona omits the axis; a
+ * declared-but-unavailable model/invalid thinking keeps the current value with
+ * no override and no restore; tools are restored from the FULL registry.
+ */
+
+import { type CapabilityPermissions, type EffectiveCapabilities, resolveCapabilities } from "../core/capabilities.ts";
+import { sanitizeStatusLabel } from "../core/display-label.ts";
+import { isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
+import { type GateResult, gateToolCall } from "./gating.ts";
+import { composeSystemPrompt, type Persona } from "./persona.ts";
+
+/** Opaque model handle — the controller does not care about its internals. */
+export interface ModelHandle {
+	provider: string;
+	id: string;
+}
+
+/** The minimal host surface the controller drives (a subset of ExtensionAPI). */
+export interface PersonaHost {
+	allToolNames(): string[];
+	knownAgents(): string[];
+	setActiveTools(names: string[]): void;
+	getThinkingLevel(): ThinkingLevel;
+	setThinkingLevel(level: ThinkingLevel): void;
+	getModel(): ModelHandle | undefined;
+	findModel(ref: string): ModelHandle | undefined;
+	setModel(model: ModelHandle): void | Promise<void>;
+	setStatus(text: string | undefined): void;
+	/** Optional: a declared-but-unavailable model/thinking would otherwise fail silently. */
+	warn?(message: string): void;
+}
+
+export class PersonaController {
+	private active: Persona | undefined;
+	private toolsRestricted = false;
+	private baselineModel: ModelHandle | undefined;
+	private modelOverridden = false;
+	private baselineThinking: ThinkingLevel | undefined;
+	private thinkingOverridden = false;
+
+	private readonly host: PersonaHost;
+	private readonly delegateDefaultAllow: boolean;
+	private caps: EffectiveCapabilities | undefined;
+
+	constructor(host: PersonaHost, delegateDefaultAllow = true) {
+		this.host = host;
+		this.delegateDefaultAllow = delegateDefaultAllow;
+	}
+
+	get activePersona(): Persona | undefined {
+		return this.active;
+	}
+
+	async activate(persona: Persona): Promise<void> {
+		this.active = persona;
+		this.caps = this.resolveCaps(persona);
+		this.host.setStatus(sanitizeStatusLabel(persona.label, persona.name));
+		await this.applyModel(persona);
+		this.applyThinking(persona);
+		this.applyTools(persona);
+	}
+
+	async deactivate(): Promise<void> {
+		this.active = undefined;
+		this.caps = undefined;
+		this.host.setStatus(undefined);
+		this.restoreTools();
+		await this.restoreModel();
+		this.restoreThinking();
+	}
+
+	/** For the `before_agent_start` hook: the persona-composed prompt, or undefined.
+	 *  `spine` is the session's shared behavioral layer (docs/SPINE.md) — a persona-less
+	 *  turn returns undefined and the hook applies the layer itself. */
+	composePrompt(base: string, spine?: string): string | undefined {
+		return this.active ? composeSystemPrompt(base, this.active, spine) : undefined;
+	}
+
+	/** For the `tool_call` hook: a block result, or undefined to allow. */
+	gate(toolName: string, input: unknown): GateResult | undefined {
+		return this.active && this.caps ? gateToolCall(this.caps, this.active.label, toolName, input) : undefined;
+	}
+
+	/** The active persona's resolved capabilities (for diagnostics / `/doctor`). */
+	get capabilities(): EffectiveCapabilities | undefined {
+		return this.caps;
+	}
+
+	private resolveCaps(persona: Persona): EffectiveCapabilities {
+		const permissions: CapabilityPermissions = {};
+		if (persona.tools) permissions.tools = persona.tools;
+		if (persona.delegate) permissions.delegate = persona.delegate;
+		return resolveCapabilities({
+			allToolNames: this.host.allToolNames(),
+			knownAgents: this.host.knownAgents(),
+			permissions,
+			delegateDefaultAllow: this.delegateDefaultAllow,
+		});
+	}
+
+	private async applyModel(persona: Persona): Promise<void> {
+		if (persona.model) {
+			const model = this.host.findModel(persona.model);
+			if (model) {
+				if (!this.modelOverridden) {
+					this.baselineModel = this.host.getModel();
+					this.modelOverridden = true;
+				}
+				await this.host.setModel(model);
+			} else {
+				this.host.warn?.(
+					`persona "${persona.name}" declared model "${persona.model}" which is not configured; keeping the current model`,
+				);
+			}
+		} else {
+			await this.restoreModel();
+		}
+	}
+
+	private async restoreModel(): Promise<void> {
+		if (!this.modelOverridden) return;
+		this.modelOverridden = false;
+		const baseline = this.baselineModel;
+		this.baselineModel = undefined;
+		if (baseline) await this.host.setModel(baseline);
+	}
+
+	private applyThinking(persona: Persona): void {
+		if (persona.thinking !== undefined) {
+			if (isThinkingLevel(persona.thinking)) {
+				if (!this.thinkingOverridden) {
+					this.baselineThinking = this.host.getThinkingLevel();
+					this.thinkingOverridden = true;
+				}
+				this.host.setThinkingLevel(persona.thinking);
+			}
+			// declared-but-invalid → keep current (no override, no restore)
+		} else {
+			this.restoreThinking();
+		}
+	}
+
+	private restoreThinking(): void {
+		if (!this.thinkingOverridden) return;
+		this.thinkingOverridden = false;
+		const baseline = this.baselineThinking;
+		this.baselineThinking = undefined;
+		if (baseline) this.host.setThinkingLevel(baseline);
+	}
+
+	private applyTools(persona: Persona): void {
+		if (persona.tools) {
+			// Use the resolved capability set so a tools-restricted persona still keeps
+			// `delegate` active (unless it explicitly denied it) — delegation is preserved.
+			this.host.setActiveTools([...(this.caps?.tools ?? new Set<string>())]);
+			this.toolsRestricted = true;
+		} else {
+			this.restoreTools();
+		}
+	}
+
+	private restoreTools(): void {
+		if (!this.toolsRestricted) return;
+		this.host.setActiveTools(this.host.allToolNames());
+		this.toolsRestricted = false;
+	}
+}

package/src/persona/gating.ts

@@ -0,0 +1,82 @@
+/**
+ * Persona delegation/tool gating — pure. The `tool_call` hook consults the
+ * persona's resolved `EffectiveCapabilities` (built once on activation) so every
+ * tool call / delegate target passes the same unified, deny-wins gate (I4).
+ * Delegate target extraction reads structured params (`agent` / `tasks[].agent`),
+ * never fragile text parsing.
+ */
+
+import { canCallTool, canDelegateTo, type EffectiveCapabilities } from "../core/capabilities.ts";
+
+/** Pull the delegate target agent names out of a delegate tool call's input. */
+export function extractDelegateTargets(input: unknown): string[] {
+	if (!input || typeof input !== "object") return [];
+	const o = input as Record<string, unknown>;
+	const targets: string[] = [];
+	if (typeof o.agent === "string") targets.push(o.agent);
+	if (Array.isArray(o.tasks)) {
+		for (const t of o.tasks) {
+			if (t && typeof t === "object" && typeof (t as Record<string, unknown>).agent === "string") {
+				targets.push((t as Record<string, unknown>).agent as string);
+			}
+		}
+	}
+	return targets;
+}
+
+/** The tool overrides a delegate call requests for its sub-agents (single + tasks[]). */
+export function extractDelegateTools(input: unknown): string[] {
+	const out: string[] = [];
+	const collect = (o: Record<string, unknown>): void => {
+		if (Array.isArray(o.tools)) for (const t of o.tools) if (typeof t === "string") out.push(t);
+	};
+	if (input && typeof input === "object") {
+		const o = input as Record<string, unknown>;
+		collect(o);
+		if (Array.isArray(o.tasks)) {
+			for (const t of o.tasks) if (t && typeof t === "object") collect(t as Record<string, unknown>);
+		}
+	}
+	return [...new Set(out)];
+}
+
+export interface GateResult {
+	block: true;
+	reason: string;
+}
+
+/** Decide whether a tool call is blocked by the active capabilities; undefined = allow. */
+export function gateToolCall(
+	caps: EffectiveCapabilities,
+	personaLabel: string,
+	toolName: string,
+	input: unknown,
+	delegateTool = "delegate",
+): GateResult | undefined {
+	if (!canCallTool(caps, toolName)) {
+		return { block: true, reason: `Persona "${personaLabel}" may not use tool: ${toolName}.` };
+	}
+	if (toolName !== delegateTool) return undefined;
+
+	const blocked = extractDelegateTargets(input).filter((t) => !canDelegateTo(caps, t));
+	if (blocked.length > 0) {
+		// Self-correcting: name what IS allowed, so a persona-gated refusal teaches the fix
+		// instead of reading like "delegation doesn't work here".
+		const allowed = [...caps.delegateTargets];
+		const hint =
+			allowed.length > 0
+				? ` Allowed targets: ${allowed.slice(0, 12).join(", ")}${allowed.length > 12 ? ", …" : ""}.`
+				: " This persona has no delegate targets.";
+		return { block: true, reason: `Persona "${personaLabel}" may not delegate to: ${blocked.join(", ")}.${hint}` };
+	}
+	// I4: a sub-agent's tool override cannot exceed the persona's own capabilities —
+	// otherwise a tools-restricted persona could escalate via `delegate({ tools: [...] })`.
+	const escalated = extractDelegateTools(input).filter((t) => !canCallTool(caps, t));
+	if (escalated.length > 0) {
+		return {
+			block: true,
+			reason: `Persona "${personaLabel}" cannot grant a sub-agent tools it lacks: ${escalated.join(", ")}.`,
+		};
+	}
+	return undefined;
+}

package/src/persona/orchestrate.ts

@@ -0,0 +1,83 @@
+/**
+ * Running the active persona's strategy — shared by the `/orchestrate` command
+ * and the mandatory turn-interception (input hook). Testable: the engine is
+ * injected, so no real `pi` spawn is needed to verify the wiring.
+ */
+
+import type { RunLimits } from "../core/capabilities.ts";
+import { makeRoster, type RosterMember } from "../orchestration/roster.ts";
+import {
+	type AgentProgress,
+	type AgentStatus,
+	makeSDK,
+	type SDKDeps,
+	type SteerFn,
+	type StrategyEngine,
+	type StrategyInput,
+} from "../orchestration/sdk.ts";
+import { getStrategy, strategyNames } from "../orchestration/strategy.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import type { OrchestrationGrammar } from "./persona.ts";
+
+/** The strategy a persona's grammar runs: explicit strategy, or `parallel` → fanout. */
+export function resolveStrategyName(orch: OrchestrationGrammar): string | undefined {
+	if (orch.strategy) return orch.strategy;
+	if (orch.mode === "parallel") return "fanout";
+	if (orch.mode === "pipeline") return "pipeline";
+	// A mode that names *what* to run without naming it is a misconfiguration, not "nothing to
+	// run" — the persona's mandatory orchestration would otherwise silently never fire.
+	if (orch.mode === "strategy") throw new Error('orchestration "mode: strategy" needs a "strategy:" name');
+	if (orch.mode === "flow" && !orch.flow) throw new Error('orchestration "mode: flow" needs a "flow:" name');
+	return undefined;
+}
+
+export interface RunStrategyDeps {
+	engine: StrategyEngine;
+	teams: Record<string, RosterMember[]>;
+	limits: RunLimits;
+	signal?: AbortSignal;
+	/** The session's own model (`provider/id`) — a strategy's last-resort recovery model for a
+	 *  member whose own model broke with no healthy peer to borrow from. */
+	sessionModel?: string;
+	log?: (message: string) => void;
+	/** Per-agent lifecycle, for live UI (which roster agent is running/done + its result).
+	 *  `key` is a run-unique display id (disambiguates same-agent roster-role members). */
+	onAgentStatus?: (agent: string, status: AgentStatus, result?: AgentResult, key?: string) => void;
+	/** Per-agent streaming progress (rolling output), for live UI. */
+	onAgentProgress?: (agent: string, progress: AgentProgress, key?: string) => void;
+	/** Called as each agent starts with a handle to abort just that agent (UI stop). */
+	onAgentStart?: (agent: string, abort: () => void, key?: string) => void;
+	/** Called once an agent is live with a handle to steer it (in-process engine only). */
+	onAgentSteerable?: (agent: string, steer: SteerFn, key?: string) => void;
+	/** See `SDKDeps.canSpawn` — every strategy spawn, not only `delegate`. */
+	canSpawn?: (agent: string) => boolean;
+}
+
+/** Run the persona's strategy on a task, or return null if it has no runnable strategy. */
+export async function runPersonaStrategy(
+	orch: OrchestrationGrammar,
+	task: string,
+	deps: RunStrategyDeps,
+): Promise<AgentResult | null> {
+	const name = resolveStrategyName(orch);
+	if (!name) return null; // no mode/strategy → nothing to run (e.g. a solo persona); caller runs normally
+	const strategy = getStrategy(name);
+	// A NAMED-but-unknown strategy is a misconfiguration, not "nothing to run" — fail loudly
+	// so the council/flow surfaces it instead of an opaque "no ruling".
+	if (!strategy) throw new Error(`unknown strategy "${name}" (available: ${strategyNames().join(", ")})`);
+
+	const sdkDeps: SDKDeps = { engine: deps.engine, roster: makeRoster(deps.teams), limits: deps.limits };
+	if (deps.signal) sdkDeps.signal = deps.signal;
+	if (deps.sessionModel) sdkDeps.sessionModel = deps.sessionModel;
+	if (deps.log) sdkDeps.log = deps.log;
+	if (deps.onAgentStatus) sdkDeps.onAgentStatus = deps.onAgentStatus;
+	if (deps.onAgentProgress) sdkDeps.onAgentProgress = deps.onAgentProgress;
+	if (deps.onAgentStart) sdkDeps.onAgentStart = deps.onAgentStart;
+	if (deps.onAgentSteerable) sdkDeps.onAgentSteerable = deps.onAgentSteerable;
+	if (deps.canSpawn) sdkDeps.canSpawn = deps.canSpawn;
+
+	const input: StrategyInput = { task, params: orch.params ?? {} };
+	if (orch.roster) input.roster = orch.roster;
+
+	return strategy.run(input, makeSDK(sdkDeps));
+}

package/src/persona/persona.ts

@@ -0,0 +1,294 @@
+/**
+ * Persona definition + parsing — the supervisor identity and its orchestration
+ * grammar. Pure module (uses only the core helpers, no Pi imports).
+ *
+ * A persona file is Markdown: YAML-subset frontmatter + a body (the supervisor
+ * system prompt). `persona: true` marks it switchable. The optional
+ * `orchestration:` block is the control surface; absent ⇒ L0 (opportunistic).
+ */
+
+import { asBoolean, asPermission, asStringArray, parseYamlSubset, splitFrontmatter } from "../core/frontmatter.ts";
+import type { Permission } from "../core/permissions.ts";
+import { asSystemPromptMode, type SystemPromptMode } from "../core/types.ts";
+
+export type OrchestrationMode = "solo" | "parallel" | "pipeline" | "strategy" | "flow";
+const ORCHESTRATION_MODES: readonly OrchestrationMode[] = ["solo", "parallel", "pipeline", "strategy", "flow"];
+
+/** The declarative orchestration grammar carried by a persona (§4.2 of the spec). */
+export interface OrchestrationGrammar {
+	mode: OrchestrationMode;
+	strategy?: string;
+	flow?: string;
+	roster?: string;
+	/** Strategy parameters (e.g. rounds, aggregate, critic). */
+	params?: Record<string, unknown>;
+}
+
+/**
+ * A tool-driven council: which strategy + roster + params the `council` tool runs
+ * on demand. Unlike `orchestration` it does NOT trigger the mandatory input-hook —
+ * the supervisor calls the council, then executes the ruling. Fully data-driven: a
+ * new ensemble (more members, a different vote, a multi-round strategy) is just a
+ * new team + (optional) strategy + a persona declaring them here.
+ */
+export interface CouncilSpec {
+	strategy: string;
+	roster?: string;
+	params?: Record<string, unknown>;
+}
+
+/** A council block as authored — `strategy` may be supplied by a `preset` (expanded at load). */
+export interface CouncilDraft {
+	strategy?: string;
+	roster?: string;
+	params?: Record<string, unknown>;
+	/** A named preset (presets/<name>.preset.json) providing defaults; authored fields override. */
+	preset?: string;
+}
+
+/** Optional, fully data-driven runtime discipline for any persona. No persona name has special
+ * behavior: a project/user persona opts into the same packet, contract, and write-set gates by
+ * declaring this block in frontmatter. */
+export interface DelegationPolicy {
+	/** Require every delegate leg to carry the complete structured `brief`. */
+	requireBrief?: boolean;
+	/** Default output contract applied to delegate legs that omit one. */
+	outputContract?: string;
+	/** Require ownership declarations for parallel writers and reject overlapping paths. */
+	requireDisjointWrites?: boolean;
+	/** Require declared verifier agents to start after, not concurrently with, a mutation. */
+	requireFreshVerification?: boolean;
+	/** Agents treated as verifiers for the runtime stale-verification concurrency gate. */
+	verificationAgents?: string[];
+}
+
+export interface Persona {
+	name: string;
+	label: string;
+	/** `persona: true` marks a file as a switchable supervisor persona. */
+	isPersona: boolean;
+	description?: string;
+	model?: string;
+	thinking?: string;
+	systemPromptMode: SystemPromptMode;
+	delegate?: Permission;
+	tools?: Permission;
+	/** Absent ⇒ L0 opportunistic delegation. */
+	orchestration?: OrchestrationGrammar;
+	/** Tool-driven council the `council` tool runs (no mandatory firing). After load, any
+	 *  `preset` is expanded so `strategy`/`roster`/`params` are concrete. */
+	council?: CouncilDraft;
+	/** Optional delegation runtime/brief policy; usable by any custom persona. */
+	delegation?: DelegationPolicy;
+	/** Opt into the comm plane: give async children a `contact_supervisor` tool (§4.9). */
+	coaching?: boolean;
+	/** `spine: false` opts this persona out of the shared behavioral layer (docs/SPINE.md) —
+	 *  for short verdict personas that do not need the baseline. Only an explicit false is
+	 *  recorded; absent ⇒ the session-level setting decides. */
+	spine?: boolean;
+	/** The Markdown body — the supervisor system prompt. */
+	body: string;
+	/** Where it was loaded from (for diagnostics / `/doctor`). */
+	source: string;
+}
+
+function parseOrchestration(raw: unknown): OrchestrationGrammar | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const o = raw as Record<string, unknown>;
+	const mode: OrchestrationMode =
+		typeof o.mode === "string" && (ORCHESTRATION_MODES as readonly string[]).includes(o.mode)
+			? (o.mode as OrchestrationMode)
+			: "solo";
+	const grammar: OrchestrationGrammar = { mode };
+	if (typeof o.strategy === "string" && o.strategy.trim()) grammar.strategy = o.strategy.trim();
+	if (typeof o.flow === "string" && o.flow.trim()) grammar.flow = o.flow.trim();
+	if (typeof o.roster === "string" && o.roster.trim()) grammar.roster = o.roster.trim();
+	if (o.params && typeof o.params === "object" && !Array.isArray(o.params)) {
+		grammar.params = o.params as Record<string, unknown>;
+	}
+	return grammar;
+}
+
+/**
+ * Parse a persona file. Returns `null` when `name` is missing (required).
+ * `systemPromptMode` defaults to `append` (a persona augments Pi's base prompt).
+ */
+export function parsePersona(content: string, source: string): Persona | null {
+	const { frontmatter, body } = splitFrontmatter(content);
+	const fm = parseYamlSubset(frontmatter);
+	const name = typeof fm.name === "string" ? fm.name.trim() : "";
+	if (!name) return null;
+
+	const label = typeof fm.label === "string" && fm.label.trim() ? fm.label : name;
+	const persona: Persona = {
+		name,
+		label,
+		isPersona: fm.persona === true,
+		systemPromptMode: asSystemPromptMode(fm.systemPromptMode, "append"),
+		body,
+		source,
+	};
+	if (typeof fm.description === "string" && fm.description.trim()) persona.description = fm.description.trim();
+	if (typeof fm.model === "string" && fm.model.trim()) persona.model = fm.model.trim();
+	if (typeof fm.thinking === "string" && fm.thinking.trim()) persona.thinking = fm.thinking.trim();
+
+	const delegate = asPermission(fm.delegate);
+	if (delegate) persona.delegate = delegate;
+	const tools = asPermission(fm.tools);
+	if (tools) persona.tools = tools;
+
+	const orchestration = parseOrchestration(fm.orchestration);
+	if (orchestration) persona.orchestration = orchestration;
+	const council = parseCouncil(fm.council);
+	if (council) persona.council = council;
+	const delegation = parseDelegationPolicy(fm.delegation);
+	if (delegation) persona.delegation = delegation;
+	if (asBoolean(fm.coaching) === true) persona.coaching = true;
+	if (asBoolean(fm.spine) === false) persona.spine = false;
+
+	return persona;
+}
+
+function parseDelegationPolicy(value: unknown): DelegationPolicy | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const o = value as Record<string, unknown>;
+	const policy: DelegationPolicy = {};
+	const requireBrief = asBoolean(o.requireBrief);
+	if (requireBrief !== undefined) policy.requireBrief = requireBrief;
+	const requireDisjointWrites = asBoolean(o.requireDisjointWrites);
+	if (requireDisjointWrites !== undefined) policy.requireDisjointWrites = requireDisjointWrites;
+	const requireFreshVerification = asBoolean(o.requireFreshVerification);
+	if (requireFreshVerification !== undefined) policy.requireFreshVerification = requireFreshVerification;
+	const verificationAgents = asStringArray(o.verificationAgents);
+	if (verificationAgents) policy.verificationAgents = verificationAgents;
+	if (typeof o.outputContract === "string" && o.outputContract.trim()) policy.outputContract = o.outputContract.trim();
+	return Object.keys(policy).length > 0 ? policy : undefined;
+}
+
+/** Parse a persona's `council:` block (strategy + roster + params, or just a `preset`). */
+function parseCouncil(value: unknown): CouncilDraft | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const o = value as Record<string, unknown>;
+	const strategy = typeof o.strategy === "string" && o.strategy.trim() ? o.strategy.trim() : "";
+	const preset = typeof o.preset === "string" && o.preset.trim() ? o.preset.trim() : "";
+	if (!strategy && !preset) return undefined; // a council needs at least a strategy or a preset
+	const spec: CouncilDraft = {};
+	if (strategy) spec.strategy = strategy;
+	if (preset) spec.preset = preset;
+	if (typeof o.roster === "string" && o.roster.trim()) spec.roster = o.roster.trim();
+	if (o.params && typeof o.params === "object" && !Array.isArray(o.params)) {
+		spec.params = o.params as Record<string, unknown>;
+	}
+	return spec;
+}
+
+/** Expand a council `preset` (presets/<name>.preset.json) into concrete fields: the preset
+ *  supplies defaults, authored fields win, and `params` shallow-merge (authored over preset).
+ *  The `preset` key is consumed. An unknown preset just drops the key (authored fields kept). */
+export function expandCouncilPreset(draft: CouncilDraft, presets: Record<string, Partial<CouncilSpec>>): CouncilDraft {
+	if (!draft.preset) return draft;
+	const base = presets[draft.preset];
+	const { preset: _consumed, ...authored } = draft;
+	if (!base) return authored;
+	const merged: CouncilDraft = { ...base, ...authored };
+	if (base.params || authored.params) merged.params = { ...base.params, ...authored.params };
+	return merged;
+}
+
+/** Per-call council selection. `persona` borrows only that persona's expanded
+ * council declaration; it never activates the persona or imports its prompt,
+ * model, tools, or permissions. Explicit strategy/roster/params remain local
+ * overrides for backward compatibility. */
+export interface CouncilInvocation {
+	persona?: string | undefined;
+	strategy?: string | undefined;
+	roster?: string | undefined;
+	params?: Record<string, unknown> | undefined;
+}
+
+export interface ResolvedCouncilInvocation {
+	strategy: string;
+	roster: string;
+	params: Record<string, unknown>;
+	/** Persona whose council declaration supplied the defaults, when any. */
+	persona?: string;
+}
+
+export type CouncilInvocationResolution =
+	| { ok: true; value: ResolvedCouncilInvocation }
+	| { ok: false; error: string };
+
+/** Resolve a council call without mutating the active persona.
+ *
+ * An explicit persona is intentionally strict: it must exist and declare a
+ * usable council. Silently falling back to MAGI would make `persona: "solo"`
+ * look authoritative while actually running an unrelated ensemble.
+ */
+export function resolveCouncilInvocation(
+	personas: readonly Persona[],
+	activePersona: Persona | undefined,
+	request: CouncilInvocation,
+): CouncilInvocationResolution {
+	const requestedName = request.persona?.trim();
+	let sourcePersona: Persona | undefined;
+
+	if (requestedName) {
+		sourcePersona = personas.find((persona) => persona.isPersona && persona.name === requestedName);
+		if (!sourcePersona) {
+			const available = personas
+				.filter((persona) => persona.isPersona && Boolean(persona.council?.strategy))
+				.map((persona) => persona.name)
+				.sort();
+			return {
+				ok: false,
+				error: `no persona named "${requestedName}". Council personas: ${available.join(", ") || "(none)"}`,
+			};
+		}
+		if (!sourcePersona.council?.strategy) {
+			return {
+				ok: false,
+				error: `persona "${requestedName}" declares no usable council`,
+			};
+		}
+	} else if (activePersona?.council?.strategy) {
+		sourcePersona = activePersona;
+	}
+
+	const base = sourcePersona?.council;
+	const strategy = request.strategy?.trim() || base?.strategy || "magi";
+	const roster =
+		request.roster?.trim() ||
+		base?.roster ||
+		sourcePersona?.orchestration?.roster ||
+		(!requestedName ? activePersona?.orchestration?.roster : undefined) ||
+		"magi";
+	const value: ResolvedCouncilInvocation = {
+		strategy,
+		roster,
+		params: { ...(base?.params ?? {}), ...(request.params ?? {}) },
+	};
+	if (sourcePersona) value.persona = sourcePersona.name;
+	return { ok: true, value };
+}
+
+/** Compose the turn's system prompt from the base prompt, the spine, and a persona.
+ *  The spine is the shared behavioral layer (docs/SPINE.md); absent/empty — the default —
+ *  leaves the composition byte-identical to the pre-spine one. */
+export function composeSystemPrompt(base: string, persona: Persona, spine?: string): string {
+	const layer = persona.spine === false ? "" : (spine ?? "").trim();
+	// No layer (the default, and `spine: false`) ⇒ the pre-spine composition, byte for byte.
+	// The `replace` test HAS to come first here, exactly as it did pre-spine: a replace persona
+	// with an empty body yielded an empty prompt, and quietly promoting that to Pi's base prompt
+	// would be a behavior change on the OFF path — which docs/SPINE.md promises there isn't one.
+	if (!layer) {
+		if (persona.systemPromptMode === "replace") return persona.body;
+		if (!persona.body.trim()) return base;
+		return `${base}\n\n${persona.body}`;
+	}
+	// An empty body has nothing to append — and nothing to replace with: the turn keeps Pi's
+	// base prompt, lifted by the spine exactly like a persona-less turn.
+	if (!persona.body.trim()) return `${base}\n\n${layer}`;
+	// `replace` drops Pi's base, so the spine becomes the only scaffolding that persona gets.
+	const head = persona.systemPromptMode === "replace" ? layer : `${base}\n\n${layer}`;
+	return `${head}\n\n${persona.body}`;
+}