@aeondave/pi-persona 1.15.2

package/src/orchestration/strategies/pipeline.ts

@@ -0,0 +1,91 @@
+/**
+ * pipeline — run the roster agents in SEQUENCE, each building on the previous one's
+ * output (a chain / refinement / debate shape, vs `fanout`'s parallel and `magi`'s vote).
+ * The built-in behind L1 `mode: pipeline`. The pipeline's answer is the LAST step's output
+ * (the culmination); usage is summed across the chain and a failed step stops it.
+ */
+
+import { emptyUsage } from "../../engine/stream.ts";
+import { fenceUntrusted } from "../../core/fence.ts";
+import { sumUsage } from "../reducers.ts";
+import { rosterSpec } from "../roster.ts";
+import type { Strategy } from "../sdk.ts";
+import type { AgentResult } from "../types.ts";
+
+/** A chain the run cancelled — distinct from one a step failed, so a journal or supervisor
+ *  records it as cancelled rather than as a broken step. The work already produced rides
+ *  along: it cost real tokens and is still the best thing to show. */
+function cancelled(results: AgentResult[], upstream: string): AgentResult {
+	return {
+		agent: "pipeline",
+		output: upstream || "(no output)",
+		structured: { steps: results.length, cancelled: true },
+		usage: results.length > 0 ? sumUsage(results.map((r) => r.usage)) : emptyUsage(),
+		ok: false,
+		error: "the run was aborted",
+		failureKind: "abort",
+	};
+}
+
+function failed(results: AgentResult[], upstream: string, step: AgentResult): AgentResult {
+	const cause = step.error ?? step.output ?? "failed";
+	const failedStep = `--- failed step (${step.agent}): ${cause} ---`;
+	const result: AgentResult = {
+		agent: "pipeline",
+		output: upstream ? `${upstream}\n\n${failedStep}` : (step.output || failedStep),
+		usage: results.length > 0 ? sumUsage(results.map((r) => r.usage)) : emptyUsage(),
+		ok: false,
+	};
+	if (step.error) result.error = step.error;
+	if (step.failureKind) result.failureKind = step.failureKind;
+	if (step.structured) result.structured = step.structured;
+	return result;
+}
+
+export const pipeline: Strategy = {
+	name: "pipeline",
+	async run(input, sdk) {
+		const team = input.roster ? sdk.roster.team(input.roster) : [];
+		if (team.length === 0) throw new Error("pipeline: a non-empty roster is required");
+		sdk.log(`pipeline: ${team.length} agents in sequence`);
+
+		const results: AgentResult[] = [];
+		let upstream = "";
+		for (const member of team) {
+			// An abort settles a step as ok:false/'abort' instead of throwing, and one that lands
+			// between steps marks nothing at all — either way the chain must stop here rather than
+			// walk the rest of the roster.
+			if (sdk.signal?.aborted) return cancelled(results, upstream);
+			const task = upstream
+				? `${input.task}\n\n--- previous step's output (build on it) ---\n${fenceUntrusted(upstream)}`
+				: input.task;
+			const r = await sdk.agent({ ...rosterSpec(member), task });
+			results.push(r);
+			if (!r.ok) {
+				// A stop that lands WHILE this step runs settles it here, never at the loop guard
+				// above (the chain already broke): that guard reads `sdk.signal`, which is wired but
+				// only consulted BETWEEN steps. Report it as a cancelled chain that keeps the
+				// upstream work, not as a failed step whose empty output replaces it.
+				if (r.failureKind === "abort") return cancelled(results, upstream);
+				return failed(results, upstream, r);
+			}
+			if (r.output) upstream = r.output;
+		}
+
+		const last = results[results.length - 1];
+		const result: AgentResult = {
+			agent: "pipeline",
+			output: last?.output ?? "(no output)",
+			usage: results.length > 0 ? sumUsage(results.map((r) => r.usage)) : emptyUsage(),
+			ok: results.length === team.length && results.every((r) => r.ok),
+		};
+		if (last?.structured) result.structured = last.structured;
+		// The chain breaks AT the failing step, so `last` carries the cause — without it the phase
+		// renders as failed with an empty output and nothing to act on.
+		if (!result.ok && last && !last.ok) {
+			if (last.error) result.error = last.error;
+			if (last.failureKind) result.failureKind = last.failureKind;
+		}
+		return result;
+	},
+};

package/src/orchestration/strategies/synthesize.ts

@@ -0,0 +1,99 @@
+/**
+ * synthesize — fan the roster out on the task in parallel, then ONE synthesiser agent
+ * merges the labeled findings into a single coherent answer. This is the "reduce" that
+ * `fanout` lacks (its aggregate is only concatenated sections): use it whenever the
+ * ensemble's value is a unified deliverable — research sweeps, multi-angle reviews,
+ * gather-then-write — rather than a vote (`magi`) or a pick (`judge`).
+ *
+ * roster = the gatherers · params = { synthesizer?: "<agent>" (default: the first roster agent),
+ *          peers?: boolean (gatherers share contradictions/corroborations live — default off) }
+ */
+
+import { rosterSpec } from "../roster.ts";
+import { fenceUntrusted } from "../../core/fence.ts";
+import { sumUsage, summarizeFailedResults } from "../reducers.ts";
+import type { Strategy } from "../sdk.ts";
+import type { AgentResult } from "../types.ts";
+
+// Cooperative cross-talk (params.peers): gatherers surface contradictions early instead of
+// leaving them all to the synthesizer. Task-text injection keeps UI tree keys stable.
+const CROSS_TALK = [
+	"You have sibling gatherers working OTHER angles of this same task. If you find something that",
+	"contradicts or strongly corroborates what another angle would see, share it once via",
+	"`contact_peer` (action `list`, then `send`) — short and factual. Incorporate any",
+	'"[message from peer …]" notes you receive. No chatter: only load-bearing findings.',
+].join(" ");
+
+export const synthesize: Strategy = {
+	name: "synthesize",
+	params: {
+		synthesizer: { type: "string", doc: "default: the first roster agent" },
+		peers: { type: "boolean", default: false, doc: "gatherers share contradictions/corroborations live" },
+	},
+	async run(input, sdk) {
+		const team = input.roster ? sdk.roster.team(input.roster) : [];
+		if (team.length === 0) throw new Error("synthesize: a non-empty roster (the gatherers) is required");
+		const synthesizer =
+			typeof input.params.synthesizer === "string" && input.params.synthesizer.trim()
+				? input.params.synthesizer.trim()
+				: rosterSpec(team[0]!).agent;
+		const peers = input.params.peers === true;
+		sdk.log(`synthesize: ${team.length} gatherers → ${synthesizer}${peers ? " (cross-talk on)" : ""}`);
+		if (peers && team.length > sdk.limits.maxConcurrency) {
+			sdk.log(
+				`synthesize: ${team.length} gatherers exceeds maxConcurrency (${sdk.limits.maxConcurrency}) — the live exchange will be batched (gatherers beyond the concurrency window join late)`,
+			);
+		}
+
+		const results = await sdk.parallel(
+			team.map((m) => () =>
+				sdk.agent({
+					...rosterSpec(m),
+					task: peers ? `${input.task}\n\n--- gatherer cross-talk ---\n${CROSS_TALK}` : input.task,
+					...(peers ? { peers: true } : {}),
+				}),
+			),
+		);
+		const usable = results.filter((r) => r.ok && r.output.trim());
+		if (usable.length === 0) {
+			const cause = summarizeFailedResults(results, "no gatherer produced output");
+			const reasons = results.map((r) => `[${r.agent}] ${r.error ?? "(no output)"}`).join("; ");
+			return {
+				agent: "synthesize",
+				output: `(no gatherer produced output: ${reasons})`,
+				usage: sumUsage(results.map((r) => r.usage)),
+				ok: false,
+				error: cause.error,
+				failureKind: cause.failureKind,
+			};
+		}
+
+		const sections = usable.map((r) => `--- [${r.agent}] ---\n${fenceUntrusted(r.output.trim())}`).join("\n\n");
+		const final = await sdk.agent({
+			agent: synthesizer,
+			task:
+				`Synthesise the findings below into ONE coherent, de-duplicated answer to the task. ` +
+				`Resolve contradictions explicitly (say which finding you trusted and why) and keep every load-bearing detail.\n\n` +
+				`Task: ${input.task}\n\nFindings:\n${sections}`,
+		});
+
+		// A one-line headline for the collapsed council card (the tool reads `headline`):
+		// the synthesiser's `result` field if it emitted one, else the first non-empty line.
+		const firstLine = final.output.split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+		const structuredResult = final.structured?.result;
+		const headline = (typeof structuredResult === "string" && structuredResult.trim() ? structuredResult : firstLine).slice(0, 120);
+
+		const result: AgentResult = {
+			agent: "synthesize",
+			output: final.output,
+			structured: { ...(final.structured ?? {}), gatherers: usable.length, headline },
+			usage: sumUsage([...results, final].map((r) => r.usage)),
+			ok: final.ok,
+		};
+		if (!final.ok) {
+			result.error = final.error ?? "the synthesizer failed";
+			result.failureKind = final.failureKind ?? "agent";
+		}
+		return result;
+	},
+};

package/src/orchestration/strategy.ts

@@ -0,0 +1,49 @@
+/**
+ * Built-in strategy registry — TS modules conforming to the `Strategy` interface.
+ * A future loader for user-authored `strategies/*.js` (same SDK, trusted/project-
+ * gated code) would register through the same map.
+ */
+
+import type { Strategy, StrategyParam } from "./sdk.ts";
+import { compete } from "./strategies/compete.ts";
+import { councilRounds } from "./strategies/council-rounds.ts";
+import { criticLoop } from "./strategies/critic-loop.ts";
+import { debate } from "./strategies/debate.ts";
+import { fanout } from "./strategies/fanout.ts";
+import { judge } from "./strategies/judge.ts";
+import { magi } from "./strategies/magi.ts";
+import { map } from "./strategies/map.ts";
+import { pair } from "./strategies/pair.ts";
+import { pipeline } from "./strategies/pipeline.ts";
+import { synthesize } from "./strategies/synthesize.ts";
+
+const BUILTINS: Record<string, Strategy> = {
+	fanout,
+	pipeline,
+	map,
+	"critic-loop": criticLoop,
+	"council-rounds": councilRounds,
+	debate,
+	magi,
+	judge,
+	pair,
+	synthesize,
+	compete,
+};
+
+export function getStrategy(name: string): Strategy | undefined {
+	return BUILTINS[name];
+}
+
+/** The registered built-in strategy names, sorted — for error messages and discovery. */
+export function strategyNames(): string[] {
+	return Object.keys(BUILTINS).sort();
+}
+
+/** A strategy's declared param schema, for discovery (`/doctor`) and the council tool's
+ *  lenient unknown-key warning. Known param-less strategies return an empty schema;
+ *  `undefined` is reserved for an unknown strategy. */
+export function knownParams(name: string): Record<string, StrategyParam> | undefined {
+	const strategy = BUILTINS[name];
+	return strategy ? (strategy.params ?? {}) : undefined;
+}

package/src/orchestration/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Orchestration-layer types shared by the SDK, strategies, and reducers.
+ */
+
+import type { ChildUsage } from "../engine/stream.ts";
+
+export type { ChildUsage };
+
+/** Machine-readable cause of an `ok:false` run — so callers can react by CAUSE, not by
+ *  string-matching the error. Only `"provider"` (the model's provider rejected/broke:
+ *  auth, outage, 5xx, model-not-supported) is retryable by switching provider; the rest
+ *  are terminal for that model. `"verification"` is the one value that never appears on an
+ *  `AgentResult` itself — it appears only on `map`'s per-item ledger entry (`ItemLedgerEntry`,
+ *  `orchestration/reducers.ts`), where it means the worker LEG succeeded but a separate
+ *  `params.verify` reviewer rejected that item's work after the fact. */
+export type FailureKind = "provider" | "abort" | "timeout" | "contract" | "unknown-agent" | "unknown-model" | "agent" | "verification";
+
+/** The result of running one agent through the engine, as strategies see it. */
+export interface AgentResult {
+	agent: string;
+	output: string;
+	/** Validated structured fields (when the agent ran against a contract). */
+	structured?: Record<string, unknown>;
+	usage: ChildUsage;
+	ok: boolean;
+	error?: string;
+	/** The canonical `provider/id` the run actually used (drives provider fallback + UI). */
+	modelUsed?: string;
+	/** Why it failed (set only when `ok` is false) — drives the model-fallback decision. */
+	failureKind?: FailureKind;
+}

package/src/orchestration/voting.ts

@@ -0,0 +1,126 @@
+/**
+ * Voting reducers (v0.2). Fold candidate results into a decision with an honest
+ * status union — never just a `winner`. Built-in bias guards: invalid outputs
+ * are quarantined, dissent is always preserved, and ties/no-consensus are
+ * surfaced (with an optional keep-best-by-confidence fallback). Anonymisation /
+ * order-shuffling apply to judge-based aggregation (added with the judge reducer).
+ */
+
+import type { AgentResult } from "./types.ts";
+
+export type ReducerStatus = "winner" | "tie" | "no_consensus" | "invalid_outputs";
+
+export interface ReducerResult {
+	status: ReducerStatus;
+	winner?: AgentResult;
+	dissent?: AgentResult[];
+	invalid?: AgentResult[];
+	tally: Record<string, number>;
+	usedFallback: boolean;
+}
+
+export interface VoteOpts {
+	aggregate: "majority" | "unanimity";
+	keepBestFallback?: boolean;
+	/** Best-of-X: a plurality winner must reach at least this many votes, else no_consensus. */
+	threshold?: number;
+}
+
+/** Normalise a vote so case/separator variants tally together
+ *  (`json-first`, `JSON_First`, `json first` → `json-first`). */
+function normalizeVote(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[\s_-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+/** The canonical (normalised) vote key for a candidate, or undefined if it cannot vote. */
+function voteKey(r: AgentResult): string | undefined {
+	if (!r.ok) return undefined;
+	const s = r.structured;
+	if (s && typeof s.vote === "string" && s.vote.trim()) return normalizeVote(s.vote);
+	if (s && typeof s.result === "string" && s.result.trim()) return normalizeVote(s.result);
+	return undefined;
+}
+
+function confidence(r: AgentResult): number {
+	const c = r.structured?.confidence;
+	return typeof c === "number" ? c : 0;
+}
+
+export function voteReduce(candidates: AgentResult[], opts: VoteOpts): ReducerResult {
+	const valid: Array<{ result: AgentResult; key: string }> = [];
+	const invalid: AgentResult[] = [];
+	for (const candidate of candidates) {
+		const key = voteKey(candidate);
+		if (key === undefined) invalid.push(candidate);
+		else valid.push({ result: candidate, key });
+	}
+
+	const tally: Record<string, number> = {};
+	for (const v of valid) tally[v.key] = (tally[v.key] ?? 0) + 1;
+
+	if (valid.length === 0) {
+		// Nobody emitted a parseable vote. With keepBestFallback, don't strand the caller with an
+		// empty ruling (small models often drop the vote JSON) — surface the strongest single PROSE
+		// answer among the candidates that actually ANSWERED. That means ok candidates AND
+		// contract-only failures: an engine marks a member that answered in prose instead of the
+		// vote JSON as `ok:false, failureKind:"contract"`, which is precisely the case this rescue
+		// exists for (requiring `ok` here would make it unreachable — live-drive verified: a debate
+		// over generic agents returned an empty ruling). Hard failures (timeout/abort/provider/
+		// agent) stay excluded. No usable prose ⇒ genuinely nothing to show.
+		const res: ReducerResult = { status: "invalid_outputs", invalid, tally, usedFallback: false };
+		if (opts.keepBestFallback) {
+			const prose = candidates.filter((c) => c.output.trim() && (c.ok || c.failureKind === "contract"));
+			const winner = [...prose].sort((a, b) => confidence(b) - confidence(a))[0];
+			if (winner) {
+				res.winner = winner;
+				res.dissent = prose.filter((c) => c !== winner);
+				res.usedFallback = true;
+				// The rescued prose (winner + dissent) is SURFACED, not excluded — keep only the
+				// candidates that produced nothing usable in `invalid`, so an "N invalid excluded"
+				// footer counts what was actually dropped, not the ruling it sits above.
+				res.invalid = invalid.filter((c) => c !== winner && !res.dissent!.includes(c));
+			}
+		}
+		return res;
+	}
+
+	const bestByConfidence = (): AgentResult =>
+		[...valid].sort((a, b) => confidence(b.result) - confidence(a.result))[0]!.result;
+
+	const withFallback = (status: ReducerStatus): ReducerResult => {
+		const res: ReducerResult = { status, invalid, tally, usedFallback: false };
+		if (opts.keepBestFallback) {
+			const winner = bestByConfidence();
+			res.winner = winner;
+			// Preserve the minority report even when we fall back — this is exactly the
+			// case (tie / no_consensus) where the dissent matters most.
+			res.dissent = valid.filter((v) => v.result !== winner).map((v) => v.result);
+			res.usedFallback = true;
+		}
+		return res;
+	};
+
+	if (opts.aggregate === "unanimity") {
+		if (Object.keys(tally).length === 1) {
+			return { status: "winner", winner: valid[0]!.result, dissent: [], invalid, tally, usedFallback: false };
+		}
+		return withFallback("no_consensus");
+	}
+
+	// majority
+	const max = Math.max(...Object.values(tally));
+	const top = Object.keys(tally).filter((k) => tally[k] === max);
+	if (top.length === 1) {
+		// Best-of-X: a clear plurality still needs `threshold` votes to win outright.
+		if (opts.threshold !== undefined && max < opts.threshold) return withFallback("no_consensus");
+		const winnerKey = top[0];
+		const winner = valid.find((v) => v.key === winnerKey)!.result;
+		const dissent = valid.filter((v) => v.key !== winnerKey).map((v) => v.result);
+		return { status: "winner", winner, dissent, invalid, tally, usedFallback: false };
+	}
+	return withFallback("tie");
+}

package/src/persona/config-store.ts

@@ -0,0 +1,215 @@
+/**
+ * Per-persona configuration, indexed by persona name and persisted as one JSON
+ * file in the global persona folder. Intentionally open-ended: a persona that
+ * needs settings gets an entry, others don't. Two personas that share a strategy
+ * keep independent configs. Today it carries per-agent model assignments (so an
+ * ensemble like magi can run its cores on *different* models); more keys later.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface PersonaConfig {
+	/** Roster agent name → provider-qualified model id (e.g. "claude-pro-max-native/claude-opus-4-8"). */
+	models?: Record<string, string>;
+}
+
+export type PersonaConfigStore = Record<string, PersonaConfig>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read the store. NOTE: this reader WRITES on one path — an unusable file is copied to
+ * `${file}.bak` before the next save replaces it (once; an existing backup is never touched).
+ */
+export function readPersonaConfigs(file: string): PersonaConfigStore {
+	let text: string;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return {}; // no config yet (the common case) or unreadable → start empty
+	}
+	try {
+		const parsed: unknown = JSON.parse(text);
+		// Valid JSON that isn't a config object is as unusable as unparseable text — and the next
+		// save replaces it just the same, so it gets the same backup treatment.
+		if (!isPlainObject(parsed)) throw new Error("not a config object");
+		const store: PersonaConfigStore = {};
+		for (const [name, cfg] of Object.entries(parsed)) {
+			if (!isPlainObject(cfg)) continue;
+			const entry: PersonaConfig = {};
+			if (isPlainObject(cfg.models)) {
+				const models: Record<string, string> = {};
+				for (const [agent, model] of Object.entries(cfg.models)) {
+					if (typeof model === "string") models[agent] = model;
+				}
+				entry.models = models;
+			}
+			store[name] = entry;
+		}
+		return store;
+	} catch {
+		// An unusable file is about to be overwritten by the next save; keep it beside the
+		// config so the assignments stay recoverable instead of vanishing silently. `wx` makes
+		// this the FIRST copy only: the underlying fault (a sync client, a failing disk) tends to
+		// recur, and a second bad parse would otherwise overwrite the one copy that still had the
+		// user's assignments in it.
+		try {
+			writeFileSync(`${file}.bak`, text, { encoding: "utf8", flag: "wx" });
+		} catch {
+			/* best effort — an existing backup, or an unwritable dir, must not stop the session */
+		}
+		return {};
+	}
+}
+
+/** Injection seams for the rename retry below (tests drive it on any OS). */
+export interface ConfigWriteIO {
+	rename?: (from: string, to: string) => void;
+	sleep?: (ms: number) => void;
+	/** Test seam for the cross-process lock around the read/merge/write transaction. */
+	acquireLock?: (file: string, sleep: (ms: number) => void) => () => void;
+}
+
+// A handle held by a virus scanner, a sync client or another pi instance mid-read is transient,
+// so a few short waits usually win the race — 25+50+75 ms of backoff at worst, on a save.
+const RENAME_ATTEMPTS = 4;
+const RENAME_BACKOFF_MS = 25;
+const LOCK_ATTEMPTS = 80;
+const LOCK_BACKOFF_MS = 25;
+const STALE_LOCK_MS = 5 * 60 * 1000;
+
+function sleepSync(ms: number): void {
+	// The whole store API is synchronous (this runs on a model assignment, not on a hot path),
+	// so the backoff has to block; Atomics.wait is the standard synchronous sleep.
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** Acquire a small sidecar lock so two independent Pi processes cannot both read the same old
+ * config and race their read-modify-write transactions. `wx` is the portable atomic primitive on
+ * POSIX and Windows. A very old lock is treated as abandoned after a crashed process; active
+ * writers renew no state because the critical section is synchronous and short. */
+function acquireFileLock(file: string, sleep: (ms: number) => void): () => void {
+	const lock = `${file}.lock`;
+	for (let attempt = 1; attempt <= LOCK_ATTEMPTS; attempt++) {
+		try {
+			const fd = openSync(lock, "wx");
+			try {
+				writeSync(fd, `${process.pid}\n`, null, "utf8");
+			} catch (error) {
+				try {
+					closeSync(fd);
+				} finally {
+					try {
+						unlinkSync(lock);
+					} catch {
+						/* best effort; retain the original write error */
+					}
+				}
+				throw error;
+			}
+			return () => {
+				try {
+					closeSync(fd);
+				} finally {
+					try {
+						unlinkSync(lock);
+					} catch {
+						/* another cleanup path or an external remover already won */
+					}
+				}
+			};
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") throw error;
+			try {
+				if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) unlinkSync(lock);
+			} catch {
+				/* It disappeared between stat/unlink; retry normally. */
+			}
+			if (attempt < LOCK_ATTEMPTS) {
+				sleep(LOCK_BACKOFF_MS);
+				continue;
+			}
+			throw new Error(`timed out acquiring persona config lock: ${lock}`);
+		}
+	}
+	throw new Error(`timed out acquiring persona config lock: ${lock}`);
+}
+
+/**
+ * MERGE `store` into the file (read-modify-write), then save it.
+ *
+ * A removal is NOT expressible: an assignment missing from `store` is preserved, not deleted.
+ * The merge exists so a concurrent pi instance's save survives ours, and it cannot tell "the
+ * user cleared this" from "this store was read before that was written" — a clearing gesture
+ * would need its own delete-aware call.
+ */
+export function writePersonaConfigs(file: string, store: PersonaConfigStore, io: ConfigWriteIO = {}): void {
+	mkdirSync(dirname(file), { recursive: true });
+	const sleep = io.sleep ?? sleepSync;
+	const release = (io.acquireLock ?? acquireFileLock)(file, sleep);
+	try {
+		// The caller holds a store read at session start; another pi instance in the same workspace
+		// may have saved since. Re-read and merge so its work survives our whole-store write — down
+		// to the agent, since two instances of the *same* persona assign different roster members.
+		const merged: PersonaConfigStore = { ...readPersonaConfigs(file) };
+		for (const [persona, cfg] of Object.entries(store)) {
+			const prev = merged[persona];
+			merged[persona] = prev ? { ...prev, ...cfg, models: { ...prev.models, ...cfg.models } } : cfg;
+		}
+		const payload = `${JSON.stringify(merged, null, 2)}\n`;
+		// Temp file + same-volume rename, so a crash mid-write can never leave a truncated
+		// config.json behind. That is atomic on POSIX; Windows is NOT the same — rename fails with
+		// EPERM/EBUSY while ANY other handle holds the target open (Defender, a sync client, a second
+		// pi instance mid-read), and the persona folder is an ordinary user directory where that is
+		// routine. So a contended rename is retried, and then written in place: a non-atomic save
+		// that lands beats an atomic one that loses the user's assignments every session.
+		const tmp = `${file}.${process.pid}.tmp`;
+		const rename = io.rename ?? renameSync;
+		writeFileSync(tmp, payload, "utf8");
+		for (let attempt = 1; ; attempt++) {
+			try {
+				rename(tmp, file);
+				return;
+			} catch (err) {
+				const code = (err as NodeJS.ErrnoException).code;
+				if (attempt < RENAME_ATTEMPTS && (code === "EPERM" || code === "EBUSY" || code === "EACCES")) {
+					sleep(RENAME_BACKOFF_MS * attempt);
+					continue;
+				}
+				try {
+					// The scratch file must not be left behind for every pid that ever tried, whether
+					// the in-place write succeeds or throws (the caller still sees a real failure).
+					writeFileSync(file, payload, "utf8");
+				} finally {
+					try {
+						rmSync(tmp, { force: true });
+					} catch {
+						/* best effort */
+					}
+				}
+				return;
+			}
+		}
+	} finally {
+		release();
+	}
+}
+
+/** The model assignments for a persona (empty object when none configured). */
+export function personaModels(store: PersonaConfigStore, persona: string): Record<string, string> {
+	return store[persona]?.models ?? {};
+}
+
+/** Merge model assignments into a persona's config, returning a new store. */
+export function withPersonaModels(
+	store: PersonaConfigStore,
+	persona: string,
+	models: Record<string, string>,
+): PersonaConfigStore {
+	const prev = store[persona] ?? {};
+	return { ...store, [persona]: { ...prev, models: { ...prev.models, ...models } } };
+}