@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/loader.ts

@@ -120,8 +120,12 @@ export function loadDefinitions(dirs: ScopedDir[]): LoadResult {
 	const agents: AgentConfig[] = [];
 	for (const f of agentMerge.resolved) {
 		if (collisionNames.has(f.name)) continue;
-		const agent = parseAgent(content.get(f.path) ?? "", f.path);
-		if (agent) agents.push(agent);
+		try {
+			const agent = parseAgent(content.get(f.path) ?? "", f.path);
+			if (agent) agents.push(agent);
+		} catch (error) {
+			warnings.push(`${f.path}: ${error instanceof Error ? error.message : String(error)} — skipped`);
+		}
 	}
 
 	return { personas, agents, shadowed: [...personaMerge.shadowed, ...agentMerge.shadowed], collisions, warnings };
@@ -212,7 +216,11 @@ export function loadTeams(files: string[]): Record<string, RosterMember[]> {
 		} catch {
 			continue;
 		}
-		Object.assign(merged, parseTeams(content));
+		try {
+			Object.assign(merged, parseTeams(content));
+		} catch (error) {
+			throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	return merged;
 }

package/src/orchestration/flow-journal.ts

@@ -59,7 +59,13 @@ export function parseJournal(content: string, hash: string): Record<string, Resu
 		if (e.hash !== hash || typeof e.phase !== "string") continue;
 		if (e.ok) {
 			const prior = out[e.phase];
-			out[e.phase] = { agent: e.phase, output: e.output ?? "", usage: emptyUsage(), ok: true };
+			out[e.phase] = {
+				agent: e.phase, output: e.output ?? "", usage: emptyUsage(), ok: true,
+				...(typeof e.resultRef === "string" ? { resultRef: e.resultRef } : {}),
+				...(e.resultVersion === 1 ? { resultVersion: 1 as const } :
+					e.resultRef !== undefined || e.resultVersion !== undefined
+						? { refUnavailable: "unsupported or missing archived result journal version" } : {}),
+			};
 			// Preserve an approval from either this line or an earlier line for the same phase.
 			if (e.gateApproved || prior?.gateApproved) out[e.phase]!.gateApproved = true;
 		} else delete out[e.phase];

package/src/orchestration/flow-run.ts

@@ -15,11 +15,14 @@ import type { AgentResult, FailureKind } from "./types.ts";
 
 export type PhaseStatus = "running" | "done" | "failed";
 
-/** One phase ready to run: its spec, the built task, and its upstream phases' results. */
+/** One phase ready to run: its spec, the built task, its upstream phases' results, and — in
+ *  reference mode — the DIRECT upstream refs granted to this phase's legs (nothing transitive). */
 export interface FlowPhaseRun {
 	phase: FlowPhase;
 	task: string;
 	upstream: Record<string, AgentResult>;
+	/** Empty in inline mode; the phase's direct needs' archived refs in reference mode. */
+	resultRefs: readonly string[];
 }
 
 export type RunPhaseFn = (run: FlowPhaseRun) => Promise<AgentResult>;
@@ -32,10 +35,23 @@ export interface FlowJournalEntry {
 	output: string;
 	/** A gated phase whose checkpoint was approved — so a resume doesn't re-prompt. */
 	gateApproved?: boolean;
+	/** Reference handoff: the archived `result:<UUID>` this phase's output lives under — the
+ *  body itself is NOT journaled in that mode (resume reads it back via the archive). */
+	resultRef?: string;
+	/** The archive-record schema version the `resultRef` line was written against. */
+	resultVersion?: 1;
 }
 
 /** A resume map value: a phase result plus whether its checkpoint gate was already approved. */
-export type ResumedResult = AgentResult & { gateApproved?: boolean };
+export type ResumedResult = AgentResult & {
+	gateApproved?: boolean;
+	resultVersion?: 1;
+	/** Reference handoff: the archived ref this phase was journaled under (from the journal). */
+	resultRef?: string;
+	/** The archived body for a phase's ref could not be read back (resume, or a live capture
+	 *  that produced no ref) — dependents block on this need; nothing re-runs or falls back. */
+	refUnavailable?: string;
+};
 
 export interface FlowRunDeps {
 	/** Run one phase's strategy → its result (wraps `runPersonaStrategy` in prod). */
@@ -43,6 +59,10 @@ export interface FlowRunDeps {
 	/** The pinned run identity (I3: `flowRunHash` = flow + task + cwd) — recorded in every journal line. */
 	hash: string;
 	signal?: AbortSignal;
+	/** Reference handoff: read a journaled ref's stored body back from the terminal archive —
+	 *  how a RESUME rebuilds a done phase's output without re-running it. Required for a
+	 *  reference-mode resume that has refs to restore; absent ⇒ every ref reads unavailable. */
+	readArchivedResult?: (ref: string) => { ok: true; body: string; status: "done" | "failed" | "stopped"; truncated?: boolean } | { ok: false; error: string };
 	/** Grace an aborted wave gets to unwind cooperatively before its still-running phases are
 	 *  force-settled (defaults to {@link ABORT_GRACE_MS}); shrinkable in tests. */
 	abortGraceMs?: number;
@@ -123,37 +143,94 @@ function within(p: Promise<unknown>, ms: number): Promise<void> {
 	});
 }
 
-/** Build a phase's task: the base task plus each upstream phase's output as context. */
+/** Reference handoff: how much of an upstream body is embedded as a PREVIEW (contract 2).
+ *  The full report stays in the archive; the dependent pages it with `read_result`. */
+export const RESULT_PREVIEW_CHARS = 1200;
+
+/** Build a phase's task. Inline (the default, first-class): the base task plus each upstream
+ *  phase's FULL fenced output. Reference: per upstream phase ONLY a bounded fenced preview +
+ *  the archived ref + its status + how to read more — never the full body. */
 function buildPhaseTask(baseTask: string, spec: FlowSpec, phase: FlowPhase, upstream: Record<string, AgentResult>): string {
 	const parts = [`Flow "${spec.name}" — phase "${phase.id}" (strategy: ${phase.strategy}).`, baseTask];
 	const ups = Object.entries(upstream);
-	if (ups.length > 0) {
-		parts.push("\nUpstream results to build on:");
-		for (const [id, r] of ups) parts.push(`\n--- ${id} ---\n${fenceUntrusted(r.output)}`);
+	if (ups.length === 0) return parts.join("\n");
+	if (spec.handoff === "reference") {
+		parts.push("\nUpstream results (archived references — read more with the read_result tool):");
+		for (const [id, r] of ups) {
+			const ref = r.resultReceipt?.ref;
+			parts.push(`\n--- ${id} ---`);
+			parts.push(`status: ${r.ok ? "done" : "failed"}`);
+			if (ref === undefined) {
+				parts.push(`result reference unavailable: ${r.output.slice(0, 200) || "(no output)"}`);
+				continue;
+			}
+			parts.push(`result ref: ${ref}`);
+			if (r.resultReceipt?.truncated) parts.push("Archive retention truncated the original report; the stored body is partial even after reading every page.");
+			parts.push(`preview (first ${RESULT_PREVIEW_CHARS} of ${r.output.length} chars):\n${fenceUntrusted(r.output.slice(0, RESULT_PREVIEW_CHARS))}${r.output.length > RESULT_PREVIEW_CHARS ? "\n(preview truncated — use read_result for the rest)" : ""}`);
+			parts.push(`Read the full report with the read_result tool, e.g. {"ref":"${ref}","offset":0,"limit":8000}; follow each reply's nextOffset until endOfStoredBody.`);
+		}
+		return parts.join("\n");
 	}
+	parts.push("\nUpstream results to build on:");
+	for (const [id, r] of ups) parts.push(`\n--- ${id} ---\n${fenceUntrusted(r.output)}`);
 	return parts.join("\n");
 }
 
 export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDeps): Promise<FlowOutcome> {
 	const byId = new Map(spec.phases.map((p) => [p.id, p]));
+	const reference = spec.handoff === "reference";
+	/** One journal write, mode-aware: reference lines carry the ref (+version marker) and never
+	 *  the body; inline lines stay byte-identical to the historical format. */
+	const journalSettled = (id: string, r: AgentResult, gateApproved = false): void => {
+		if (!deps.journal) return;
+		const ref = r.resultReceipt?.ref;
+		deps.journal(reference
+			? { phase: id, hash: deps.hash, ok: r.ok, output: "", ...(r.ok && ref !== undefined ? { resultRef: ref, resultVersion: 1 as const } : {}), ...(gateApproved ? { gateApproved: true } : {}) }
+			: { phase: id, hash: deps.hash, ok: r.ok, output: r.output, ...(gateApproved ? { gateApproved: true } : {}) });
+	};
+	/** Reference resume: rebuild a done phase's output from the terminal archive. A ref that
+	 *  cannot be read back marks the phase `refUnavailable` — its dependents BLOCK (no respawn,
+	 *  no inline fallback, no re-run of the done phase); the error says why. */
+	const restoreResumed = (r: ResumedResult): ResumedResult => {
+		if (r.refUnavailable) return { ...r, output: "" };
+		const ref = r.resultRef;
+		if (ref === undefined) {
+			return { ...r, output: "", refUnavailable: "the phase was journaled without an archived result reference" };
+		}
+		if (r.resultVersion !== 1) return { ...r, output: "", refUnavailable: "unsupported or missing archived result journal version" };
+		const read = deps.readArchivedResult?.(ref);
+		if (!read) return { ...r, output: "", refUnavailable: `archived result ${ref} is unreadable (no archive reader is wired for this run)` };
+		if (!read.ok) return { ...r, output: "", refUnavailable: `archived result ${ref} is unreadable (${read.error})` };
+		if (read.status !== "done") return { ...r, output: "", refUnavailable: `archived result ${ref} has status ${read.status}; expected done` };
+		return { ...r, output: read.body, resultReceipt: { ...(r.resultReceipt ?? {}), ref, ...(read.truncated === undefined ? {} : { truncated: read.truncated }) } };
+	};
 	// A gated phase only satisfies its dependents once its checkpoint is "passed" (or it blocks
 	// them once "rejected"). Resume pre-seeds gates the journal already recorded as approved.
 	const gateState = new Map<string, "passed" | "rejected">();
-	const done = new Map<string, AgentResult>();
-	for (const [id, r] of Object.entries(deps.resume ?? {})) {
+	const done = new Map<string, ResumedResult>();
+	for (const [id, r0] of Object.entries(deps.resume ?? {})) {
 		const gated = byId.get(id)?.gate === true;
 		// A gated phase resumed as ok but WITHOUT a recorded approval (the process died between
 		// journaling its completion and its gate decision) must RE-RUN, not be treated as done —
 		// otherwise it sits in `done` with an unresolved gate and its dependents can never run.
-		if (gated && r.ok && !(r as ResumedResult).gateApproved) continue;
+		let r: ResumedResult = r0;
+		if (reference && r0.ok) {
+			const restored = restoreResumed(r0);
+			r = restored.resultReceipt?.ref !== undefined ? restored : { ...restored, refUnavailable: restored.refUnavailable ?? "the phase has no archived result reference" };
+		}
+		// An invalid reference cannot turn this historical checkpoint into newly paid work.
+		if (gated && r.ok && !r.gateApproved && !r.refUnavailable) continue;
 		done.set(id, r);
-		if (gated && (r as ResumedResult).gateApproved) gateState.set(id, "passed");
+		if (gated && r0.gateApproved) gateState.set(id, "passed");
 	}
 	// A FAILED gated phase has no checkpoint to resolve — its gate must not keep dependents
 	// from being considered (needFailed then records them "blocked", exactly like a failed
 	// non-gated need; otherwise they'd never become ready and silently vanish, stuck ⏳).
 	const gateResolved = (id: string): boolean => !byId.get(id)?.gate || gateState.has(id) || done.get(id)?.ok === false;
 	const needFailed = (n: string): boolean => (done.has(n) && !done.get(n)?.ok) || gateState.get(n) === "rejected";
+	/** An OK need whose archived reference cannot serve dependents (unreadable at resume, or a
+	 *  live capture that produced no ref). The need stays DONE — only its dependents block. */
+	const needUnavailable = (n: string): boolean => (done.get(n)?.refUnavailable ?? "") !== "";
 	let remaining = spec.phases.filter((p) => !done.has(p.id));
 	let cancelled = false;
 	// Keep blocked dependents distinct from phases that actually ran and failed. The flow's
@@ -170,12 +247,18 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 		const ready = remaining.filter((p) => (p.needs ?? []).every((n) => done.has(n) && gateResolved(n)));
 		if (ready.length === 0) break; // acyclic + progress guarantees this can't happen
 
-		// A phase whose any need FAILED or whose gate was REJECTED is blocked — record, don't run.
-		const blocked = ready.filter((p) => (p.needs ?? []).some((n) => needFailed(n)));
+		// A phase whose any need FAILED, whose gate was REJECTED, or (reference mode) whose need's
+		// archived ref cannot be read — record, don't run.
+		const blocked = ready.filter((p) => (p.needs ?? []).some((n) => needFailed(n) || needUnavailable(n)));
 		for (const p of blocked) {
 			blockedPhaseIds.add(p.id);
 			const gateReject = (p.needs ?? []).some((n) => gateState.get(n) === "rejected");
-			const error = gateReject ? "blocked: a checkpoint gate was not approved" : "blocked: an upstream phase failed";
+			const unavailableNeed = (p.needs ?? []).find((n) => needUnavailable(n));
+			const error = gateReject
+				? "blocked: a checkpoint gate was not approved"
+				: unavailableNeed !== undefined
+					? `blocked: upstream phase "${unavailableNeed}" result reference is unavailable (${done.get(unavailableNeed)?.refUnavailable})`
+					: "blocked: an upstream phase failed";
 			const r: AgentResult = { agent: p.id, output: "", usage: emptyUsage(), ok: false, error };
 			done.set(p.id, r);
 			deps.onPhase?.(p.id, "failed", r);
@@ -196,28 +279,38 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 					const u = done.get(n);
 					if (u) upstream[n] = u;
 				}
+				// Reference mode: the phase's legs are granted EXACTLY its direct needs' refs —
+				// never a transitive ancestor's (the reader scope mirrors the task's previews).
+				const resultRefs: readonly string[] = reference
+					? (p.needs ?? []).map((n) => done.get(n)?.resultReceipt?.ref).filter((x): x is string => x !== undefined)
+					: [];
 				const task = buildPhaseTask(baseTask, spec, p, upstream);
 				// A throwing phase (e.g. a misconfigured strategy) is a phase FAILURE, not a
 				// crashed DAG — record it failed so its dependents block and the flow finishes.
-				let r: AgentResult;
+				let r: ResumedResult;
 				try {
-					r = await deps.runPhase({ phase: p, task, upstream });
+					r = await deps.runPhase({ phase: p, task, upstream, resultRefs });
 				} catch (err) {
 					const error = err instanceof Error ? err.message : String(err);
 					r = { agent: p.id, output: "", usage: emptyUsage(), ok: false, error };
 				}
+				// Reference mode is a durability contract: a phase that finished without an archived
+				// ref cannot serve its dependents. It stays done — dependents BLOCK on it below.
+				if (reference && r.ok && r.resultReceipt?.ref === undefined) {
+					r = { ...r, refUnavailable: "the phase completed without an archived result reference" };
+				}
 				// The run already gave up on this phase and moved on. Its UI node is torn down and
 				// its outcome is already reported, so re-drive neither — but work that DID complete
 				// is still worth keeping: journal it so a RESUME reuses the output instead of paying
 				// for the same phase a second time. A late FAILURE is not journaled — there is
 				// nothing to reuse, and a resume has to re-run it anyway.
 				if (forced) {
-					if (r.ok) deps.journal?.({ phase: p.id, hash: deps.hash, ok: true, output: r.output });
+					if (r.ok) journalSettled(p.id, r);
 					return;
 				}
 				settled.set(p.id, r);
 				deps.onPhase?.(p.id, r.ok ? "done" : "failed", r);
-				deps.journal?.({ phase: p.id, hash: deps.hash, ok: r.ok, output: r.output });
+				journalSettled(p.id, r);
 			}),
 		);
 
@@ -257,16 +350,26 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 			if (!phase?.gate || !r.ok || gateState.has(id)) continue;
 			const approved = deps.approveGate ? await deps.approveGate(phase, r) : true;
 			gateState.set(id, approved ? "passed" : "rejected");
-			if (approved) deps.journal?.({ phase: id, hash: deps.hash, ok: true, output: r.output, gateApproved: true });
+			if (approved) journalSettled(id, r, true);
 		}
 		remaining = remaining.filter((p) => !done.has(p.id));
 	}
 
+	// Missing reference evidence is a failed resume, even when the saved phase is a sink
+	// with no dependent to expose the problem. Retain it in done to prevent any respawn.
+	for (const [id, result] of done) {
+		if (result.refUnavailable) done.set(id, {
+			...result, ok: false, error: `Archived result reference is unavailable: ${result.refUnavailable}`, failureKind: "contract",
+		});
+	}
 	const results: Record<string, AgentResult> = Object.fromEntries(done);
 	const needed = new Set(spec.phases.flatMap((p) => p.needs ?? []));
 	const terminals = spec.phases.filter((p) => !needed.has(p.id));
 	const terminalOutput = terminals
-		.map((p) => done.get(p.id)?.output ?? "")
+		.map((p) => {
+			const result = done.get(p.id);
+			return `${result?.output ?? ""}${result?.resultReceipt?.truncated ? "\n[pi-persona] Archive retention truncated this report; this is the partial stored body." : ""}`;
+		})
 		.filter((s) => s.trim())
 		.join("\n\n---\n\n");
 	const ok = spec.phases.every((p) => done.get(p.id)?.ok ?? false);

package/src/orchestration/flow.ts

@@ -22,6 +22,11 @@ export interface FlowPhase {
 export interface FlowSpec {
 	name: string;
 	description?: string;
+	/** How a dependent phase receives its upstream phases' output. `inline` (the default,
+	 *  and still first-class) embeds each upstream result's full fenced body in the dependent's
+	 *  task; `reference` embeds only a bounded preview plus the archived result reference — the
+	 *  dependent reads the rest through the scoped `read_result` tool (see flow-run.ts). */
+	handoff?: "inline" | "reference";
 	phases: FlowPhase[];
 }
 
@@ -111,6 +116,12 @@ export function parseFlow(content: string): FlowParse {
 
 	const flow: FlowSpec = { name: raw.name, phases };
 	if (typeof raw.description === "string") flow.description = raw.description;
+	if (raw.handoff !== undefined) {
+		if (raw.handoff !== "inline" && raw.handoff !== "reference") {
+			return { ok: false, error: `flow.handoff must be "inline" or "reference" (got ${JSON.stringify(raw.handoff)})` };
+		}
+		flow.handoff = raw.handoff;
+	}
 	return { ok: true, flow };
 }
 

package/src/orchestration/roster.ts

@@ -3,7 +3,7 @@
  * Referenced by a persona's `orchestration.roster` or `council.roster`.
  *
  * A member is either a bare agent name (`- scout`) OR a map that specialises ONE
- * agent inline — `{ agent, role?, model?, skills? }` — so an ensemble of distinct
+ * agent inline — `{ agent, role?, model?, thinking?, skills? }` — so an ensemble of distinct
  * perspectives can be built from a SINGLE agent (e.g. one `reviewer` run three times
  * with different `role`s and models) instead of one .md file per perspective. That is
  * the "skills + role provide specialisation, not files" principle applied to rosters.
@@ -14,6 +14,9 @@
  */
 
 import { asBoolean, asStringArray, parseYamlSubset } from "../core/frontmatter.ts";
+import { stripTerminalControls } from "../core/fence.ts";
+import { parseLegThinking } from "../core/leg-thinking.ts";
+import { isThinkingLevel, THINKING_LEVELS, type ThinkingLevel } from "../core/types.ts";
 import type { Roster } from "./sdk.ts";
 
 /** A roster member: a bare agent name, or an inline specialisation of one agent. `tools`/
@@ -21,13 +24,14 @@ import type { Roster } from "./sdk.ts";
  *  knobs (see `tools/delegate.ts`'s `DelegateTask`). */
 export type RosterMember =
 	| string
-	| { agent: string; role?: string; model?: string; skills?: string[]; tools?: string[]; isolation?: "none" | "worktree"; mcp?: boolean };
+	| RosterSpec;
 
 /** The normalised run-spec fields a member contributes (agent + any specialisation). */
 export interface RosterSpec {
 	agent: string;
 	role?: string;
 	model?: string;
+	thinking?: ThinkingLevel;
 	skills?: string[];
 	tools?: string[];
 	isolation?: "none" | "worktree";
@@ -43,6 +47,8 @@ export function rosterSpec(member: RosterMember): RosterSpec {
 	const spec: RosterSpec = { agent: member.agent };
 	if (member.role?.trim()) spec.role = member.role.trim();
 	if (member.model?.trim()) spec.model = member.model.trim();
+	const thinking = parseLegThinking(member.thinking);
+	if (thinking !== undefined) spec.thinking = thinking;
 	if (member.skills && member.skills.length > 0) spec.skills = member.skills;
 	if (member.tools !== undefined) spec.tools = member.tools;
 	if (member.isolation !== undefined) spec.isolation = member.isolation;
@@ -57,19 +63,56 @@ const ROLE_STOPWORDS = new Set([
 	"ON", "IN", "OF", "TO", "IS", "IT", "BE", "DO", "AS", "AT", "BY", "AN", "A",
 ]);
 
+const GIT_REF = /^(?:HEAD|ORIG_HEAD|FETCH_HEAD|MERGE_HEAD|CHERRY_PICK_HEAD|REBASE_HEAD)(?:[~^].*)?$/i;
+const HASH = /^(?:0x)?[\da-f]{7,40}$/i;
+
+function technicalRoleToken(token: string): boolean {
+	const trimmed = token.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+	return token.includes("_")
+		|| token.includes("/")
+		|| token.includes("\\")
+		|| token.includes("$")
+		|| token.includes("=")
+		|| (trimmed.includes(":") && !trimmed.endsWith(":"))
+		|| GIT_REF.test(trimmed)
+		|| HASH.test(trimmed)
+		|| /^[\p{L}\p{N}_.-]+\.[\p{L}\p{N}]{1,8}$/u.test(trimmed);
+}
+
+function roleWords(role: string): string[] {
+	// Inline/fenced code is not a role label. An unmatched opening fence also hides the
+	// remainder instead of leaking its contents into the fallback label.
+	const withoutCode = role.replace(/(`{1,3})[\s\S]*?\1/g, " ").replace(/`{1,3}[\s\S]*$/g, " ");
+	return withoutCode.split(/\s+/).flatMap((raw) => {
+		const word = raw.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+		return word && !technicalRoleToken(raw) && !technicalRoleToken(word) ? [word] : [];
+	});
+}
+
+function boundedRoleHint(text: string): string {
+	const points = Array.from(text);
+	return points.length > 20 ? `${points.slice(0, 19).join("")}…` : text;
+}
+
 /** A short emphasis hint from a member's role text — the first salient ALL-CAPS keyword
- *  (e.g. "SECURITY" from "Focus ONLY on the SECURITY lens…"), else the first few words.
- *  Used to disambiguate same-agent roster-role members in the UI tree. Pure. */
+ *  (e.g. "SECURITY" from "Focus ONLY on the SECURITY lens…"), else a short human-readable
+ *  prefix. Technical identifiers, code, paths, hashes and generic Git refs are omitted; a
+ *  role with no readable words gets the neutral "role" hint. Used by presentation and
+ *  run-unique UI keys, with roster seeding and SDK keys sharing this exact function. Pure. */
 export function roleHint(role: string): string {
-	const words = role.split(/\s+/);
+	// Roles become picker/tree chrome. Strip terminal sequences before token parsing so their
+	// numeric parameters cannot be mistaken for visible prose, then remove bidi formatting
+	// controls that could visually reorder or disguise the resulting label.
+	const readable = stripTerminalControls(role).replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u206f]/gu, "");
+	const words = roleWords(readable);
 	for (const w of words) {
-		const clean = w.replace(/[^A-Za-z0-9]/g, "");
-		if (clean.length >= 3 && /[A-Z]/.test(clean) && clean === clean.toUpperCase() && !ROLE_STOPWORDS.has(clean)) {
-			return clean;
+		if (/^\p{L}{3,}$/u.test(w) && w === w.toUpperCase() && !ROLE_STOPWORDS.has(w)) {
+			return boundedRoleHint(w);
 		}
 	}
-	const brief = words.slice(0, 4).join(" ").replace(/[:.,;].*$/, "").trim();
-	return brief.length > 20 ? `${brief.slice(0, 20)}…` : brief || "role";
+	const brief = words.slice(0, 4);
+	while (brief.length && ROLE_STOPWORDS.has(brief[brief.length - 1]!.toUpperCase())) brief.pop();
+	return boundedRoleHint(brief.join(" ")) || "role";
 }
 
 /** The base UI label for a member: `agent`, or `agent · HINT` when it carries a role —
@@ -99,6 +142,7 @@ export function rosterNodeKeys(members: RosterMember[]): string[] {
  *  LENIENT, and deliberately so: this is the STATIC `teams.yaml` path (authored, trusted project
  *  data), where a member with a badly-typed field is normalised, not rejected — a bad `model`
  *  is dropped and a numeric `tools` entry is coerced to its string, so the panel still runs.
+ *  Explicit `thinking` is always strict: a typo must never inherit a different effort.
  *  Anything RUNTIME-supplied (a `council` call's `members`, an aux actor param) must go through
  *  {@link parseRuntimeRosterMember} instead: there, a dropped `tools` silently WIDENS a leg to
  *  the agent's default tool permissions, so a malformed field has to be refused, not normalised.
@@ -108,11 +152,13 @@ export function parseRosterMember(raw: unknown): RosterMember | undefined {
 	if (raw && typeof raw === "object" && !Array.isArray(raw)) {
 		const o = raw as Record<string, unknown>;
 		if (typeof o.agent !== "string" || !o.agent.trim()) return undefined;
-		const m: { agent: string; role?: string; model?: string; skills?: string[]; tools?: string[]; isolation?: "none" | "worktree"; mcp?: boolean } = {
+		const m: RosterSpec = {
 			agent: o.agent.trim(),
 		};
 		if (typeof o.role === "string" && o.role.trim()) m.role = o.role.trim();
 		if (typeof o.model === "string" && o.model.trim()) m.model = o.model.trim();
+		const thinking = parseLegThinking(o.thinking);
+		if (thinking !== undefined) m.thinking = thinking;
 		const skills = asStringArray(o.skills);
 		if (skills) m.skills = skills;
 		const tools = asStringArray(o.tools);
@@ -126,7 +172,7 @@ export function parseRosterMember(raw: unknown): RosterMember | undefined {
 }
 
 /** Every field a member map may carry — anything else is a typo, not a silent no-op. */
-const MEMBER_FIELDS = new Set(["agent", "role", "model", "skills", "tools", "isolation", "mcp"]);
+const MEMBER_FIELDS = new Set(["agent", "role", "model", "thinking", "skills", "tools", "isolation", "mcp"]);
 
 export type RuntimeMember = { ok: true; member: RosterMember } | { ok: false; error: string };
 
@@ -155,17 +201,13 @@ export function parseRuntimeRosterMember(raw: unknown): RuntimeMember {
 	}
 	const unknownKeys = Object.keys(o).filter((k) => !MEMBER_FIELDS.has(k));
 	if (unknownKeys.length > 0) {
-		return { ok: false, error: `unknown member field(s) ${unknownKeys.join(", ")} — expected agent, role, model, skills, tools, isolation, mcp` };
+		return { ok: false, error: `unknown member field(s) ${unknownKeys.join(", ")} — expected agent, role, model, thinking, skills, tools, isolation, mcp` };
+	}
+	const member: RosterSpec = { agent: o.agent.trim() };
+	if (o.thinking !== undefined) {
+		if (!isThinkingLevel(o.thinking)) return { ok: false, error: `"thinking" must be one of: ${THINKING_LEVELS.join(", ")}` };
+		member.thinking = o.thinking;
 	}
-	const member: {
-		agent: string;
-		role?: string;
-		model?: string;
-		skills?: string[];
-		tools?: string[];
-		isolation?: "none" | "worktree";
-		mcp?: boolean;
-	} = { agent: o.agent.trim() };
 	// A blank string is "unset" (the lenient path's own reading); a non-string is a type error.
 	for (const key of ["role", "model"] as const) {
 		const value = o[key];
@@ -199,7 +241,13 @@ export function parseTeams(yaml: string): Record<string, RosterMember[]> {
 	const teams: Record<string, RosterMember[]> = {};
 	for (const [name, value] of Object.entries(raw)) {
 		const items: unknown[] = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
-		const members = items.map(parseRosterMember).filter((m): m is RosterMember => m !== undefined);
+		const members = items.map((item, index) => {
+			try {
+				return parseRosterMember(item);
+			} catch (error) {
+				throw new Error(`team ${name}[${index}]: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}).filter((m): m is RosterMember => m !== undefined);
 		if (members.length > 0) teams[name] = members;
 	}
 	return teams;

package/src/orchestration/sdk.ts

@@ -5,6 +5,7 @@
  * exact same surface as future user-authored strategy files.
  */
 
+import type { ThinkingLevel } from "../core/types.ts";
 import type { RunLimits } from "../core/capabilities.ts";
 import { type ChildUsage, emptyUsage, type ToolEvent } from "../engine/stream.ts";
 import { type JudgePrep, prepareJudge } from "./judge.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,6 +52,22 @@ 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,
@@ -183,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). */
@@ -241,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).
@@ -269,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;
@@ -415,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/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`