@aeondave/pi-persona 1.17.1 → 1.17.4

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,17 +35,34 @@ 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). */
 	runPhase: RunPhaseFn;
-	/** The pinned `flow@hash` for this run (I3) — recorded in every journal line. */
+	/** 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;
@@ -71,6 +91,17 @@ export interface FlowOutcome {
 	/** The run signal fired before every phase settled ok. A cancelled flow is NOT the same as one
 	 *  that merely finished without an answer, and callers report it differently. */
 	cancelled?: boolean;
+	/** The first checkpoint (in spec order) that was not approved, when that is the ONLY reason the
+	 *  flow did not finish: a stop the operator chose, not a failure. `ok` stays false and `error`
+	 *  stays "blocked: …" (a mandatory flow must keep failing closed); `output` is the gated
+	 *  phase's own answer plus a stop note. */
+	stoppedAtGate?: string;
+}
+
+/** What a finished flow IS to a reader. A checkpoint the operator declined is a STOP, their choice, never a
+ *  failure: the one predicate the tool result, the tree row and the cards share. */
+export function flowDisposition(outcome: { ok: boolean; stoppedAtGate?: string | undefined }): "done" | "stopped" | "failed" {
+	return outcome.ok ? "done" : outcome.stoppedAtGate !== undefined ? "stopped" : "failed";
 }
 
 /** How long an aborted wave is given to unwind COOPERATIVELY before its still-running phases are
@@ -112,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
@@ -159,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);
@@ -185,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);
 			}),
 		);
 
@@ -246,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);
@@ -270,6 +384,12 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 	const failure = cancellation
 		? failures.find((entry) => entry.result.failureKind === "abort")
 		: rootFailures[0] ?? failures[0];
+	// A rejected checkpoint is a STOP, not a failure, only when nothing else went wrong: a real phase
+	// failure or a cancellation is the more important fact and keeps its ordinary report. A rejected
+	// gate with no dependents blocks nothing, so the flow is still `ok` and was not stopped.
+	const stoppedAtGate = !cancellation && !ok && rootFailures.length === 0
+		? spec.phases.find((p) => gateState.get(p.id) === "rejected")?.id
+		: undefined;
 	const failedPhase = failure?.phase.id;
 	const error = cancellation ? (failure?.result.error ?? CANCELLED_ERROR) : failure?.result.error;
 	const failureKind = cancellation ? "abort" as const : failure?.result.failureKind;
@@ -278,24 +398,32 @@ export async function runFlow(spec: FlowSpec, baseTask: string, deps: FlowRunDep
 		: `Flow failed: ${error ?? "the flow did not complete successfully"}`;
 	const cancellationText = `Flow cancelled${failedPhase ? ` at phase "${failedPhase}"` : ""}: ${error ?? CANCELLED_ERROR}`;
 	const outputAlreadySignalsCancellation = /\b(?:cancel(?:led|lation)?|abort(?:ed)?|stopp?ed)\b/i.test(terminalOutput);
-	const output = cancellation
-		? terminalOutput.trim()
-			? outputAlreadySignalsCancellation
-				? terminalOutput
-				: `${terminalOutput}\n\n${cancellationText}`
-			: cancellationText
-		: terminalOutput.trim()
-			? terminalOutput
-			: failure
-				? failureText
-				: terminalOutput;
+	const terminalReport = (): string => {
+		// A rejected checkpoint answers with the gated phase's own output: that is what the operator was
+		// asked to approve, and dropping it on a "no" would throw away work already paid for. Another
+		// branch that finished keeps its answer beside it.
+		if (stoppedAtGate !== undefined) {
+			return [
+				done.get(stoppedAtGate)?.output ?? "",
+				terminalOutput,
+				`- flow stopped at checkpoint "${stoppedAtGate}": not approved (declined, dismissed, or no interactive session). Later phases did not run.`,
+			].filter((part) => part.trim()).join("\n\n");
+		}
+		if (cancellation) {
+			if (!terminalOutput.trim()) return cancellationText;
+			return outputAlreadySignalsCancellation ? terminalOutput : `${terminalOutput}\n\n${cancellationText}`;
+		}
+		if (terminalOutput.trim()) return terminalOutput;
+		return failure ? failureText : terminalOutput;
+	};
 	return {
 		ok,
 		results,
-		output,
+		output: terminalReport(),
 		...(failedPhase ? { failedPhase } : {}),
 		...(error ? { error } : {}),
 		...(failureKind ? { failureKind } : {}),
 		...(cancelled ? { cancelled: true } : {}),
+		...(stoppedAtGate !== undefined ? { stoppedAtGate } : {}),
 	};
 }

package/src/orchestration/flow.ts

@@ -22,18 +22,30 @@ 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[];
 }
 
 export type FlowParse = { ok: true; flow: FlowSpec } | { ok: false; error: string };
 export type TopoResult = { ok: true; order: string[] } | { ok: false; error: string };
 
-/** The pinned `flow@hash` for a run (I3): a stable sha256 over the spec, so a hot reload
- *  of the file can't change an in-flight run and a resume only matches the same flow. */
+/** A stable sha256 over the spec — the flow half of a run's identity, and the journal file name's
+ *  hash (`journalFileName`): a hot reload of the file can't change an in-flight run. */
 export function flowHash(spec: FlowSpec): string {
 	return stableHash(spec);
 }
 
+/** The pinned run identity (I3) recorded in every journal line: flow + task + cwd. A resume
+ *  skips finished phases only for the SAME flow on the SAME task in the SAME project; a failed
+ *  `flow X` on task A must never feed its phases' output to `flow X` on task B. */
+export function flowRunHash(spec: FlowSpec, task: string, cwd: string): string {
+	return stableHash({ flow: flowHash(spec), task: task.trim(), cwd });
+}
+
 function isObject(x: unknown): x is Record<string, unknown> {
 	return typeof x === "object" && x !== null && !Array.isArray(x);
 }
@@ -104,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/reducers.ts

@@ -89,21 +89,25 @@ export function itemLedger(
 	});
 }
 
-/** Combine fan-out results into one labeled-section result; ok iff all ok. */
-export function aggregateResults(results: AgentResult[]): AgentResult {
-	const sections = results.map((r) => {
+/** Combine fan-out results into one labeled-section result; ok iff all ok. `labels` (aligned to
+ *  `results`) name each section by lens or item instead of the bare agent; the label is kept as
+ *  `member` only when it adds something, so a label-free call is byte-identical to before. */
+export function aggregateResults(results: AgentResult[], labels?: readonly string[]): AgentResult {
+	const labelOf = (r: AgentResult, i: number): string => labels?.[i] ?? r.agent;
+	const sections = results.map((r, i) => {
 		const status = r.ok ? "ok" : `failed${r.failureKind ? ` (${r.failureKind})` : ""}`;
 		const body = r.output || r.error || "(no output)";
 		const cause = !r.ok && r.error && r.output && r.error !== r.output ? `\n\nError: ${r.error}` : "";
-		return `### [${r.agent}] ${status}\n\n${body}${cause}`;
+		return `### [${labelOf(r, i)}] ${status}\n\n${body}${cause}`;
 	});
 	const aggregate: AgentResult = {
 		agent: "aggregate",
 		output: sections.join("\n\n---\n\n"),
 		structured: {
 			count: results.length,
-			results: results.map((r) => ({
+			results: results.map((r, i) => ({
 				agent: r.agent,
+				...(labelOf(r, i) !== r.agent ? { member: labelOf(r, i) } : {}),
 				ok: r.ok,
 				output: r.output,
 				error: r.error ?? null,

package/src/orchestration/render.ts

@@ -72,7 +72,7 @@ export function humanizeAggregateResult(r: AgentResult): string | undefined {
 	for (const value of members) {
 		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
 		const member = value as Record<string, unknown>;
-		const agent = typeof member.agent === "string" && member.agent.trim() ? member.agent.trim() : "member";
+		const agent = field(member, "member") ?? field(member, "agent") ?? "member";
 		const ok = member.ok === true;
 		const output = typeof member.output === "string" ? member.output : "";
 		const structured = member.structured && typeof member.structured === "object" && !Array.isArray(member.structured)

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;