@aeondave/pi-persona 1.15.2

package/src/core/config.ts

@@ -0,0 +1,228 @@
+/**
+ * pi-persona configuration resolved from environment variables.
+ *
+ * Pure module — takes an injected env record so it is fully testable. The
+ * canonical PI_PERSONA_* names are defined here once.
+ */
+
+import { isThinkingLevel } from "./types.ts";
+
+export interface PiPersonaConfig {
+	disabled: boolean;
+	extraDirs: string[];
+	defaultPersona?: string;
+	keybinding: string;
+	persist: boolean;
+	delegateDefaultAllow: boolean;
+	seed: boolean;
+	/** Explicit override for the persisted-state file (else a global default). */
+	stateFile?: string;
+	/** Thinking level forced on delegated children (else the supervisor's level).
+	 *  Spawned children must carry an *explicit* level or they fall into the model's
+	 *  default mode ("adaptive"), which some models reject. */
+	childThinking?: string;
+	/** Engine backend for sub-agents: "inproc" (run in-process via `createAgentSession`,
+	 *  the default) or "child" (spawn `pi -p`, the baseline). */
+	engine?: "child" | "inproc";
+	/** Fast stall/message wakeup interval (ms): while async children run, a tick checks progress but
+	 *  stays SILENT unless a leg NEWLY looks stalled or a sub-agent messaged the supervisor — so a
+	 *  healthy run never interrupts. On by default (30000); PI_PERSONA_PEEK_MS=0 opts out (the routine
+	 *  check-in below is independent). */
+	peekEveryMs: number;
+	/** Routine check-in interval (ms): how often, while async children run, the idle supervisor gets
+	 *  a compact progress digest so it can catch a leg going off-track (not stalled — just wrong) and
+	 *  step in early. Deliberately slow so it is an occasional glance, not a poll, and independent of
+	 *  the fast stall/message wakeup. 300000 (5 min) by default; PI_PERSONA_CHECKIN_MS=0 opts out. */
+	checkInEveryMs: number;
+	/** Per-agent hard wall-clock cap (ms): an OPT-IN lifetime ceiling. When set (>0) it settles even
+	 *  a busy-but-non-converging child the idle watchdog (reset on every event) never catches.
+	 *  DISABLED by default (0 = no cap / unlimited) so a healthy, progressing child runs to completion
+	 *  instead of being killed mid-work; the idle watchdog + startup deadline + token budget remain the
+	 *  always-on backstops. Set PI_PERSONA_AGENT_MAX_MS=<ms> to arm a hard cap. */
+	agentHardTimeoutMs: number;
+	/** Per-agent STARTUP deadline (ms): a child that produces no progress of its own (no completed
+	 *  turn / tokens / streamed assistant output) within this window is killed as a stalled start.
+	 *  It exists because the idle watchdog cannot catch a hung start — that watchdog is re-armed by
+	 *  ANY stdout, and a child emits header/noise before it does any work.
+	 *
+	 *  The window must cover the WHOLE cold start, not just init: spawn, pi init, MCP init, and the
+	 *  first provider response. A queued or rate-limited provider (a 429 carrying a 60s
+	 *  retry-after, then retried), a cold serverless endpoint, or a local model doing a long prompt
+	 *  eval on CPU can all exceed a tight window while perfectly healthy — and this deadline KILLS,
+	 *  where the idle watchdog would have let the leg live. Killing healthy work costs the user
+	 *  more than a dead leg settling slowly, so the default is deliberately generous.
+	 *  300000 (5 min) by default; PI_PERSONA_AGENT_STARTUP_MS=0 disables it. */
+	agentStartupTimeoutMs: number;
+	/** Delegation nudge: when a delegating supervisor grinds a RUN of hands-on commands by hand (a
+	 *  by-hand sweep) without a hand-off, append a reminder to the offending tool's result. On by
+	 *  default; PI_PERSONA_NUDGE=off opts out. */
+	nudge: boolean;
+	/** Cross-process broker (spec B1-B7): on by default so child-engine legs (MCP, worktree,
+	 *  `PI_PERSONA_ENGINE=child`) expose the same steer/contact_supervisor plane in-process
+	 *  runs already have. The host still starts lazily on the first child-engine build.
+	 *  PI_PERSONA_BROKER=off restores pre-broker spawn env (no host, no extra env vars). */
+	broker: boolean;
+	/** External agent-to-agent plane (exocom): independent top-level instances in one workspace
+	 *  discover + message each other. Opt-in, OFF by default (PI_PERSONA_EXOCOM=1 / --exocom),
+	 *  additionally gated by the persona's canUseBus. */
+	exocom: boolean;
+	/** How many settled-but-uncollected async runs {@link AsyncRunTracker} retains before
+	 *  FIFO-evicting the oldest completed ones. 25 by default (today's hardcoded bound); set
+	 *  PI_PERSONA_ASYNC_RETAIN=<n> (a finite value >= 1) to raise it under heavy fan-out. A
+	 *  value < 1 (junk, negative, or 0 — not a meaningful retention bound) keeps the default. */
+	asyncRetain: number;
+	/** Opt-in wider {@link DelegationLedger} veto key: OFF (default) keys purely on
+	 *  `agent+model+task` (today's veto *behavior* — unchanged; the key bytes themselves have
+	 *  moved on, NUL → space → `\x1f`, but record/vet always share the same key() so it
+	 *  cancels out). ON additionally folds in `role`/`tools`/`isolation`, so a genuine retry
+	 *  that only changes those isn't falsely vetoed as "identical" by the 2-strike anti-loop
+	 *  guard. Truthy convention mirrors exocom — see {@link OFF_WORDS}. */
+	ledgerV2: boolean;
+	/** Source selector for the spine — the shared behavioral layer injected between Pi's base
+	 *  prompt and the persona body (docs/SPINE.md). `""` ⇒ off (the default; composition stays
+	 *  byte-identical to pre-spine), `"on"` ⇒ the user-dir `spine.md` if present else the
+	 *  bundled one, anything else ⇒ that path. Off convention mirrors exocom (see
+	 *  {@link OFF_WORDS}); the value is otherwise kept VERBATIM because it is a path. */
+	spine: string;
+	/** Source selector for the spine DELEGATED LEGS get — the worker variant, a different prompt
+	 *  doing a different job. Same grammar as {@link PiPersonaConfig.spine}, and it FOLLOWS that
+	 *  value unless PI_PERSONA_SPINE_LEGS is set: one switch still lifts both roles, while the two
+	 *  together express the four measurement arms of docs/SPINE.md (off / supervisor-only /
+	 *  legs-only / both), which one selector cannot. */
+	spineLegs: string;
+	/** Files-changed report for a non-worktree leg (`engine/change-report.ts`): on by default,
+	 *  matching the existing behavior. Costs up to two `git status` spawns per leg (one at launch,
+	 *  one at settle) with no per-leg way to skip it otherwise — a large monorepo running many
+	 *  parallel legs may want to opt out. Off-word convention mirrors `broker`/`exocom`
+	 *  ({@link OFF_WORDS}); PI_PERSONA_LEG_CHANGE_REPORT=off/0/false disables it. */
+	changeReport: boolean;
+}
+
+type Env = Record<string, string | undefined>;
+
+/** The words that mean "off" for an opt-in switch. `false`/`no` are in here because they are
+ *  what a user actually types: without them `PI_PERSONA_EXOCOM=false` reads as truthy and
+ *  `PI_PERSONA_SPINE=false` is reinterpreted as a relative file PATH. Exported (read-only) so
+ *  the `{@link OFF_WORDS}` references on the switches above resolve for a reader holding only
+ *  the emitted types — a link into a module-private const documents nothing outside this file. */
+export const OFF_WORDS: ReadonlySet<string> = new Set(["", "off", "0", "false", "no"]);
+
+/** The words that mean "on". Symmetric with {@link OFF_WORDS} and needed for the same reason: a
+ *  switch whose value can also be a PATH cannot treat "not off" as "on", so `1`/`true`/`yes` —
+ *  which the broker's own docs teach users to type — would otherwise be resolved as relative
+ *  filenames. */
+export const ON_WORDS: ReadonlySet<string> = new Set(["on", "1", "true", "yes"]);
+
+/** One definition of "off", shared by the switches whose value is a plain flag or a path. The
+ *  older boolean switches (`persist`, `nudge`, `seed`, `disabled`, `delegateDefaultAllow`)
+ *  predate it and keep their own published conventions — changing those would alter what an
+ *  existing user's environment means. Unset counts as off. `broker` uses this helper with a
+ *  default-on pin (`PI_PERSONA_BROKER ?? "on"`). */
+function isOff(value: string | undefined): boolean {
+	return OFF_WORDS.has((value ?? "").trim().toLowerCase());
+}
+
+/** The spine selectors' shared value grammar: an off word ⇒ `""`, an on word ⇒ `"on"`, anything
+ *  else is a PATH. Only the SELECTOR words are matched case-insensitively; a path survives
+ *  verbatim, case included, because filesystems are case-sensitive. */
+function spineSelector(raw: string): string {
+	if (isOff(raw)) return "";
+	return ON_WORDS.has(raw.trim().toLowerCase()) ? "on" : raw;
+}
+
+function splitDirs(value: string | undefined): string[] {
+	if (!value) return [];
+	return value
+		.split(/[;,]/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+}
+
+export function resolveConfig(env: Env): PiPersonaConfig {
+	const disableFlag = env.PI_PERSONA_DISABLE;
+	const def = env.PI_PERSONA_DEFAULT?.trim();
+
+	const config: PiPersonaConfig = {
+		disabled: disableFlag !== undefined && disableFlag.length > 0,
+		extraDirs: splitDirs(env.PI_PERSONA_DIRS),
+		keybinding: env.PI_PERSONA_KEY?.trim() || "f8",
+		persist: env.PI_PERSONA_PERSIST?.trim().toLowerCase() !== "off",
+		// "deny" locks the delegate roster down; the shared OFF_WORDS are accepted as the same
+		// request (additive — "off" previously meant default-ALLOW, a security default a user
+		// could believe they had tightened while changing nothing).
+		delegateDefaultAllow: (() => {
+			const v = env.PI_PERSONA_DELEGATE_DEFAULT?.trim().toLowerCase();
+			if (v === undefined || v === "") return true; // unset stays default-allow
+			return v !== "deny" && !OFF_WORDS.has(v);
+		})(),
+		// Opt-in: auto-install the bundled defaults on first run ONLY when explicitly enabled with
+		// `PI_PERSONA_SEED=on`. Default off — personas are installed via `/persona seed|restore`.
+		seed: env.PI_PERSONA_SEED?.trim().toLowerCase() === "on",
+		peekEveryMs: 30_000,
+		checkInEveryMs: 300_000,
+		// Opt-in: 0 = no hard cap (a healthy child runs to completion). The idle watchdog
+		// (RUN_LIMITS.timeoutMs, reset on progress) + startup deadline + token budget are the
+		// always-on backstops; set PI_PERSONA_AGENT_MAX_MS=<ms> to arm a wall-clock ceiling.
+		agentHardTimeoutMs: 0,
+		agentStartupTimeoutMs: 300_000,
+		// On unless explicitly turned off (mirrors PI_PERSONA_PERSIST's `!== "off"` convention).
+		nudge: env.PI_PERSONA_NUDGE?.trim().toLowerCase() !== "off",
+		// On unless explicitly turned off, so an MCP/worktree/child-engine async leg is
+		// steerable without a hidden env pin. Off-words restore pre-broker spawn env.
+		broker: !isOff(env.PI_PERSONA_BROKER ?? "on"),
+		exocom: false,
+		asyncRetain: 25,
+		ledgerV2: false,
+		spine: "",
+		spineLegs: "",
+		changeReport: !isOff(env.PI_PERSONA_LEG_CHANGE_REPORT ?? "on"),
+	};
+	// A valid finite value >= 0 sets the interval (0 opts out); junk/negative keeps the default.
+	const peekRaw = env.PI_PERSONA_PEEK_MS?.trim();
+	if (peekRaw !== undefined && peekRaw !== "") {
+		const peek = Number(peekRaw);
+		if (Number.isFinite(peek) && peek >= 0) config.peekEveryMs = peek;
+	}
+	const checkInRaw = env.PI_PERSONA_CHECKIN_MS?.trim();
+	if (checkInRaw !== undefined && checkInRaw !== "") {
+		const checkIn = Number(checkInRaw);
+		if (Number.isFinite(checkIn) && checkIn >= 0) config.checkInEveryMs = checkIn;
+	}
+	const hardRaw = env.PI_PERSONA_AGENT_MAX_MS?.trim();
+	if (hardRaw !== undefined && hardRaw !== "") {
+		const hard = Number(hardRaw);
+		if (Number.isFinite(hard) && hard >= 0) config.agentHardTimeoutMs = hard;
+	}
+	const startupRaw = env.PI_PERSONA_AGENT_STARTUP_MS?.trim();
+	if (startupRaw !== undefined && startupRaw !== "") {
+		const startup = Number(startupRaw);
+		if (Number.isFinite(startup) && startup >= 0) config.agentStartupTimeoutMs = startup;
+	}
+	// A finite value >= 1 sets the retention bound; 0 isn't meaningful here (unlike the interval
+	// knobs above, where 0 opts out) so it — like junk/negative — falls back to the default 25.
+	const asyncRetainRaw = env.PI_PERSONA_ASYNC_RETAIN?.trim();
+	if (asyncRetainRaw !== undefined && asyncRetainRaw !== "") {
+		const retain = Number(asyncRetainRaw);
+		if (Number.isFinite(retain) && retain >= 1) config.asyncRetain = retain;
+	}
+	if (def) config.defaultPersona = def;
+	const stateFile = env.PI_PERSONA_STATE_FILE?.trim();
+	if (stateFile) config.stateFile = stateFile;
+	const childThinking = env.PI_PERSONA_CHILD_THINKING?.trim().toLowerCase();
+	if (childThinking && isThinkingLevel(childThinking)) config.childThinking = childThinking;
+	// In-process is the default backend; opt back to the spawn-based child engine with
+	// PI_PERSONA_ENGINE=child.
+	const engine = env.PI_PERSONA_ENGINE?.trim().toLowerCase();
+	config.engine = engine === "child" ? "child" : "inproc";
+	config.exocom = !isOff(env.PI_PERSONA_EXOCOM);
+	config.ledgerV2 = !isOff(env.PI_PERSONA_LEDGER_V2);
+	config.spine = spineSelector(env.PI_PERSONA_SPINE?.trim() ?? "");
+	// The legs' selector FOLLOWS the supervisor's unless it is set, so one switch still lifts both
+	// roles while the pair expresses all four measurement arms (docs/SPINE.md). Present-but-empty
+	// counts as UNSET here rather than as the off word it is elsewhere: `PI_PERSONA_SPINE_LEGS=` is
+	// how a shell clears a variable, and an inherited empty splitting the legs off from the
+	// supervisor would be a silent, invisible arm nobody chose.
+	const legsRaw = env.PI_PERSONA_SPINE_LEGS?.trim();
+	config.spineLegs = legsRaw ? spineSelector(legsRaw) : config.spine;
+	return config;
+}

package/src/core/contract.ts

@@ -0,0 +1,391 @@
+/**
+ * Structured return contracts — the substrate that makes voting/judging
+ * mechanical (reducers read fields generically) and that is PINNED per run.
+ *
+ * Pure module (Node stdlib only, no Pi imports). A contract is a small typed
+ * schema; `pinContract` freezes a `name@hash` for a run so hot-reloading a
+ * contract file never changes an in-flight run (guardrails I3).
+ */
+
+import { createHash } from "node:crypto";
+
+export type FieldType = "string" | "number" | "boolean" | "enum";
+
+export interface FieldSpec {
+	type: FieldType;
+	required?: boolean;
+	/** Allowed values for `type: "enum"`. */
+	values?: string[];
+	/** Inclusive bounds for `type: "number"`. */
+	min?: number;
+	max?: number;
+	/** Minimum string length for `type: "string"` — a non-empty / substantive gate (e.g. a proof
+	 *  line that must carry a real command + live output, not an empty placeholder). */
+	minLength?: number;
+}
+
+export interface ContractDef {
+	name: string;
+	fields: Record<string, FieldSpec>;
+}
+
+export interface PinnedContract {
+	name: string;
+	hash: string;
+	def: ContractDef;
+}
+
+export interface ValidationResult {
+	ok: boolean;
+	errors: string[];
+	/** The validated object (present only when `ok`). */
+	value?: Record<string, unknown>;
+}
+
+/** The built-in default contract: pi-fork's four sections + voting substrate. */
+export const DEFAULT_CONTRACT: ContractDef = {
+	name: "default",
+	fields: {
+		result: { type: "string", required: true },
+		output: { type: "string" },
+		evidence: { type: "string" },
+		learnings: { type: "string" },
+		vote: { type: "string" },
+		confidence: { type: "number", min: 0, max: 1 },
+		stance: { type: "enum", values: ["approve", "reject", "revise"] },
+		dissent: { type: "string" },
+	},
+};
+
+const FIELD_TYPES: readonly FieldType[] = ["string", "number", "boolean", "enum"];
+
+export type ContractParse = { ok: true; def: ContractDef } | { ok: false; error: string };
+
+/** Parse a `contracts/<name>.contract.json` file into a validated {@link ContractDef}.
+ *  Data-driven authoring surface (spec §4.6): drop a JSON file, reference it by name via a
+ *  persona/strategy `outputContract`. Reducers then read its fields generically. */
+export function parseContract(content: string): ContractParse {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		return { ok: false, error: "contract is not valid JSON" };
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { ok: false, error: "contract must be a JSON object" };
+	const o = raw as Record<string, unknown>;
+	if (typeof o.name !== "string" || !o.name.trim()) return { ok: false, error: "contract.name is required" };
+	if (typeof o.fields !== "object" || o.fields === null || Array.isArray(o.fields)) return { ok: false, error: "contract.fields must be an object" };
+
+	const fields: Record<string, FieldSpec> = {};
+	for (const [fname, rawSpec] of Object.entries(o.fields as Record<string, unknown>)) {
+		if (typeof rawSpec !== "object" || rawSpec === null || Array.isArray(rawSpec)) return { ok: false, error: `field "${fname}" must be an object` };
+		const s = rawSpec as Record<string, unknown>;
+		if (typeof s.type !== "string" || !(FIELD_TYPES as readonly string[]).includes(s.type)) {
+			return { ok: false, error: `field "${fname}" has an invalid type (string|number|boolean|enum)` };
+		}
+		const spec: FieldSpec = { type: s.type as FieldType };
+		if (s.required === true) spec.required = true;
+		if (spec.type === "enum") {
+			if (!Array.isArray(s.values) || !s.values.every((v): v is string => typeof v === "string") || s.values.length === 0) {
+				return { ok: false, error: `enum field "${fname}" needs a non-empty string "values" list` };
+			}
+			spec.values = s.values;
+		}
+		if (typeof s.min === "number") spec.min = s.min;
+		if (typeof s.max === "number") spec.max = s.max;
+		if (typeof s.minLength === "number") spec.minLength = s.minLength;
+		fields[fname] = spec;
+	}
+	return { ok: true, def: { name: o.name, fields } };
+}
+
+/** Does this text parse as JSON? The only honest test of a candidate. */
+function parses(candidate: string): boolean {
+	if (candidate.length === 0) return false;
+	try {
+		JSON.parse(candidate);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Every fenced code block in the text, last one first. The contract asks for the JSON at
+ * the END ("prose before it is fine, nothing after it"), so the last fence is the answer
+ * and any earlier fence is quoted evidence in the report.
+ */
+function fencedBlocks(s: string): string[] {
+	const out: string[] = [];
+	const re = /```[^\n`]*\n([\s\S]*?)```/g;
+	let m = re.exec(s);
+	while (m !== null) {
+		if (m[1] !== undefined) out.push(m[1].trim());
+		m = re.exec(s);
+	}
+	return out.reverse();
+}
+
+/**
+ * Scan backwards from one closer for a BALANCED object/array: walk from `close` to its
+ * matching opener, tracking string state so a brace inside a string value never miscounts.
+ * This is what survives prose that itself contains braces (a report quoting code or a
+ * `${…}`), where a naive first-`{` scan slices from the prose and yields garbage.
+ */
+function balancedFrom(s: string, close: number): string | undefined {
+	const open = s[close] === "}" ? "{" : "[";
+	const shut = s[close];
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	// Walk backwards. `escaped` needs a forward look: a quote is literal when preceded by an
+	// ODD number of backslashes, so count them rather than tracking a single flag.
+	for (let i = close; i >= 0; i--) {
+		const ch = s[i];
+		if (ch === '"') {
+			let backslashes = 0;
+			for (let j = i - 1; j >= 0 && s[j] === "\\"; j--) backslashes++;
+			escaped = backslashes % 2 === 1;
+			if (!escaped) inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === shut) depth++;
+		else if (ch === open) {
+			depth--;
+			if (depth === 0) return s.slice(i, close + 1);
+		}
+	}
+	return undefined;
+}
+
+/** Candidates are cheap; the cap only bounds pathological prose dense with closers. */
+const MAX_JSON_CANDIDATES = 64;
+
+/**
+ * Every balanced object/array in the text, walking closers RIGHT-TO-LEFT (the contract
+ * asks for the answer at the end). One candidate per closer is not enough: trailing prose
+ * like "option [2]" or "Done {thanks}." yields a slice that parses (or mis-slices into
+ * prose) and must not shadow the real answer object sitting behind it.
+ */
+function* balancedFromEnd(s: string): Generator<string> {
+	const seen = new Set<string>();
+	let yielded = 0;
+	for (let close = s.length - 1; close >= 0 && yielded < MAX_JSON_CANDIDATES; close--) {
+		const ch = s[close];
+		if (ch !== "}" && ch !== "]") continue;
+		const slice = balancedFrom(s, close);
+		if (slice !== undefined && !seen.has(slice)) {
+			seen.add(slice);
+			yielded++;
+			yield slice;
+		}
+	}
+}
+
+/**
+ * All JSON candidates of a reply, most-specific first, deduped: the whole text, each
+ * fenced block last-first (plus the balanced objects inside a fence that holds prose
+ * around the JSON), then every balanced object/array of the whole text right-to-left,
+ * and finally the legacy outermost slice (error shaping only — it may not parse).
+ */
+function* jsonCandidates(text: string): Generator<string> {
+	const seen = new Set<string>();
+	const emit = function* (c: string | undefined): Generator<string> {
+		if (c !== undefined && c.length > 0 && !seen.has(c)) {
+			seen.add(c);
+			yield c;
+		}
+	};
+	const s = text.trim();
+	yield* emit(s);
+	for (const block of fencedBlocks(s)) {
+		yield* emit(block);
+		yield* balancedFromEnd(block);
+	}
+	yield* balancedFromEnd(s);
+	// Legacy fallback: outermost slice. If nothing parsed, this only shapes the error.
+	const starts = [s.indexOf("{"), s.indexOf("[")].filter((i) => i >= 0);
+	if (starts.length > 0) {
+		const start = Math.min(...starts);
+		const end = Math.max(s.lastIndexOf("}"), s.lastIndexOf("]"));
+		if (end > start) yield* emit(s.slice(start, end + 1));
+	}
+}
+
+/**
+ * Pull a JSON candidate out of an LLM reply before parsing. Models very often wrap
+ * structured output in a ```json fence or surround it with prose ("Here you go: {…}"),
+ * which makes a raw `JSON.parse` throw and silently fails the whole contract (the magi
+ * bug: every member's vote excluded as "invalid output").
+ *
+ * Candidates are tried most-specific first and the FIRST ONE THAT ACTUALLY PARSES wins,
+ * so a heuristic can never win by producing confident garbage — with one refinement:
+ * contracts always want a JSON OBJECT, so among parseable candidates an object beats an
+ * array/scalar (trailing prose like "option [2]" parses as JSON but can never be the
+ * answer; the real object behind it is).
+ *   1. the whole text (already-clean JSON);
+ *   2. each fenced block, last fence first (the contract puts the answer last, so an
+ *      earlier fence is quoted evidence);
+ *   3. every balanced object/array scanned backwards, string-aware, right-to-left.
+ * Falls back to the legacy outermost-slice so genuinely-malformed output still fails
+ * parsing naturally with the same shape of error as before.
+ *
+ * Regressions this closes: a report whose PROSE contains a brace (quoted code, a `${…}`)
+ * followed by the fenced answer; and a correct answer followed by prose carrying its own
+ * bracketed token ("I picked option [2]"), which used to shadow the real object and fail
+ * a leg whose work was correct ("contract <name> failed: output was not valid JSON").
+ */
+export function extractJsonCandidate(text: string): string {
+	let firstParseable: string | undefined;
+	for (const candidate of jsonCandidates(text)) {
+		if (!parses(candidate)) continue;
+		if (candidate.startsWith("{")) return candidate;
+		firstParseable ??= candidate;
+	}
+	if (firstParseable !== undefined) return firstParseable;
+	// Nothing parsed: return the last (legacy outermost-slice) candidate if it exists,
+	// else the trimmed text — both only shape the downstream parse error.
+	let last: string | undefined;
+	for (const candidate of jsonCandidates(text)) last = candidate;
+	return last ?? text.trim();
+}
+
+/** One human-readable ballot line for a field: `- vote (string, required, one of: a | b)`. */
+function fieldLine(name: string, spec: FieldSpec): string {
+	const parts: string[] = [spec.type];
+	if (spec.required) parts.push("required");
+	if (spec.type === "enum" && spec.values) parts.push(`one of: ${spec.values.join(" | ")}`);
+	if (spec.min !== undefined && spec.max !== undefined) parts.push(`${spec.min}..${spec.max}`);
+	else if (spec.min !== undefined) parts.push(`>= ${spec.min}`);
+	else if (spec.max !== undefined) parts.push(`<= ${spec.max}`);
+	if (spec.minLength !== undefined) parts.push(`min ${spec.minLength} chars`);
+	return `- ${name} (${parts.join(", ")})`;
+}
+
+/**
+ * The task preamble that tells a member HOW to satisfy `outputContract` — derived
+ * mechanically from the (pinned) def and appended by BOTH engine backends whenever a
+ * spec carries a contract. Without this, only agents whose own .md hand-writes the JSON
+ * format (e.g. the MAGI cores) could be convened by a voting strategy; a generic
+ * executor would answer in prose and be quarantined as an invalid output. Live-drive
+ * verified: debate over two bare `operator`s fails exactly that way without it.
+ */
+export function contractInstructions(def: ContractDef): string {
+	const lines = [
+		`--- output contract (${def.name}) ---`,
+		"End your FINAL answer with a single JSON object (prose before it is fine, nothing after it) with these fields:",
+		...Object.entries(def.fields).map(([n, s]) => fieldLine(n, s)),
+		"The object is parsed mechanically. Include every required field; omit fields you have nothing for.",
+	];
+	if (def.fields.vote) {
+		// Vote hygiene (the MAGI cores hand-write this in their .md; a generic agent needs it
+		// here): qualifiers make equivalent votes tally apart ("esm" vs "esm (but only if…)").
+		lines.push(
+			'For "vote": the BARE option token only — for "X or Y?" vote "x" or "y", no qualifiers or conditions (put nuance in result/output) so equivalent votes tally together.',
+		);
+	}
+	return lines.join("\n");
+}
+
+export interface ParseResult {
+	ok: boolean;
+	/** The validated object (present only when `ok`). */
+	value?: Record<string, unknown>;
+	error?: string;
+}
+
+/** Unwrap (fences/prose), JSON-parse, and validate an agent's raw output against a
+ *  contract in one step — the shared path for every engine backend. Every candidate is
+ *  tried until one BOTH parses and validates: a candidate that parses but is not the
+ *  answer object (trailing "option [2]", quoted code) must not quarantine a correct,
+ *  already-billed leg as an invalid output. */
+export function parseAndValidate(output: string, def: ContractDef): ParseResult {
+	let firstErrors: string[] | undefined;
+	for (const candidate of jsonCandidates(output)) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(candidate);
+		} catch {
+			continue;
+		}
+		const v = validateAgainst(def, parsed);
+		if (v.ok && v.value) return { ok: true, value: v.value };
+		firstErrors ??= v.errors;
+	}
+	const errors = firstErrors ?? ["output was not valid JSON"];
+	return { ok: false, error: `contract ${def.name} failed: ${errors.join("; ")}` };
+}
+
+/** Deterministic, key-order-independent serialisation for hashing. */
+function stableStringify(v: unknown): string {
+	if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+	if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+	const obj = v as Record<string, unknown>;
+	const keys = Object.keys(obj).sort();
+	return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+
+/** A stable sha256 over any JSON-ish value (key-order-independent) — the pinning hash. */
+export function stableHash(value: unknown): string {
+	return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+
+/** Freeze a contract for a run: `name` + a stable sha256 over its definition. */
+export function pinContract(def: ContractDef): PinnedContract {
+	return { name: def.name, hash: stableHash(def), def };
+}
+
+/** Every contract name a spec may reference: the built-in `default` plus the installed files. */
+export function installedContractNames(defs: Record<string, ContractDef>): string[] {
+	return [...new Set(["default", ...Object.keys(defs)])];
+}
+
+/** Validate a structured value against a contract. Unknown extra fields are kept. */
+export function validateAgainst(def: ContractDef, value: unknown): ValidationResult {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return { ok: false, errors: ["expected a JSON object"] };
+	}
+	const obj = value as Record<string, unknown>;
+	const errors: string[] = [];
+
+	for (const [name, spec] of Object.entries(def.fields)) {
+		const fv = obj[name];
+		const present = fv !== undefined && fv !== null;
+		if (!present) {
+			if (spec.required) errors.push(`missing required field: ${name}`);
+			continue;
+		}
+		switch (spec.type) {
+			case "string":
+				if (typeof fv !== "string") {
+					errors.push(`field ${name} must be a string`);
+					break;
+				}
+				if (spec.minLength !== undefined && fv.length < spec.minLength) {
+					errors.push(`field ${name} must be at least ${spec.minLength} characters`);
+				}
+				break;
+			case "number":
+				if (typeof fv !== "number" || Number.isNaN(fv)) {
+					errors.push(`field ${name} must be a number`);
+					break;
+				}
+				if (spec.min !== undefined && fv < spec.min) errors.push(`field ${name} must be >= ${spec.min}`);
+				if (spec.max !== undefined && fv > spec.max) errors.push(`field ${name} must be <= ${spec.max}`);
+				break;
+			case "boolean":
+				if (typeof fv !== "boolean") errors.push(`field ${name} must be a boolean`);
+				break;
+			case "enum": {
+				const values = spec.values ?? [];
+				if (typeof fv !== "string" || !values.includes(fv)) {
+					errors.push(`field ${name} must be one of: ${values.join(", ")}`);
+				}
+				break;
+			}
+		}
+	}
+
+	return errors.length === 0 ? { ok: true, errors, value: obj } : { ok: false, errors };
+}