@aeondave/pi-persona 1.17.1 → 1.17.3

package/src/core/nudge.ts

@@ -15,7 +15,7 @@
  * (echo/cd/one-line check) is orchestration glue and does not advance the run; a run reaching the
  * threshold is a by-hand sweep. Tool identity is not required (a real sweep mixes read/grep/curl). A
  * high single-command threshold stays as a SECONDARY trigger for a genuinely enormous one-shot dump
- * (a sign it should have been detached/quarantined). A hand-off (delegate/council) resets the run;
+ * (a sign it should have been detached/quarantined). A hand-off (delegate/council/flow) resets the run;
  * nothing else does.
  *
  * Backoff: repeating the identical reminder is noise once the operator has seen it and kept going —
@@ -23,15 +23,19 @@
  * sub-agent can't inherit; from the supervisor side that loop is indistinguishable from a delegable
  * sweep, so no signal can separate them). Each un-actioned nudge WIDENS the next run window (n× the
  * base): the reminder lands early, then de-escalates. Pure — no I/O, fully unit-testable.
+ *
+ * The module also hosts the two call-time wake guards, {@link PollGuard} and {@link longWaitSeconds}.
  */
+import { recommendModels, shortlistModels } from "./model-catalog.ts";
+import { modelCostTiers, type ModelCostMetadata } from "./model-tier.ts";
 
 /** Tools that mean "the operator handed work off" — they end (reset) a by-hand run. */
-export const HANDOFF_TOOL_NAMES: ReadonlySet<string> = new Set(["delegate", "council"]);
-/** Supervision glue: collecting a delegated result (`intercom wait`/`result`) or arming a
- *  `timer` is neither hands-on work nor a hand-off. Their payloads are large by nature, so
+export const HANDOFF_TOOL_NAMES: ReadonlySet<string> = new Set(["delegate", "council", "flow"]);
+/** Supervision glue: collecting a delegated result (`intercom result`) or arming a
+ *  `timer`/`monitor` is neither hands-on work nor a hand-off. Their payloads are large by nature, so
  *  counting them would punish the exact behavior the nudge exists to encourage. They neither
  *  advance nor reset the run, and never nudge. */
-const GLUE_TOOLS = new Set(["intercom", "timer"]);
+const GLUE_TOOLS = new Set(["intercom", "timer", "monitor"]);
 /** Mutation tools often return only a terse acknowledgement. Their output size is not a useful
  * proxy for the amount of direct coding work, so every call counts as substantive. */
 const MUTATING_TOOLS = new Set(["edit", "write", "apply_patch"]);
@@ -58,7 +62,7 @@ export interface NudgeThresholds {
 	 *  check), not a sweep step: it does not advance the run counter. */
 	minStepChars: number;
 	/** Minimum cumulative burn (chars since last hand-off) before a sweep run can fire. Without
-	 *  this, 5 tiny git/grep commands (200 chars each = 1000 total ≈ 0k tokens) trip the nudge
+	 *  this, a few tiny git/grep commands (200 chars each = 600 total ≈ 0k tokens) trip the nudge
 	 *  and renderNudge prints "~0k tokens" — advice to "delegate what burns context" when nothing
 	 *  burned. This floor gates the sweep so it only fires when the burn is substantive.
 	 *  Defaults to `DEFAULT_NUDGE_THRESHOLDS.minSweepBurnChars` when omitted. */
@@ -69,11 +73,12 @@ export interface NudgeThresholds {
 
 export const DEFAULT_NUDGE_THRESHOLDS: NudgeThresholds = {
 	singleHeavyChars: 40_000, // ~10k tokens in one command — a fat one-shot dump
-	runLength: 5, // 5 substantive hands-on commands in a row without a hand-off = a by-hand sweep.
+	runLength: 3, // 3 substantive hands-on commands in a row without a hand-off = a by-hand sweep.
 	// The standing delegation brief (core/brief.ts) carries the default every turn; this is the
-	// reactive backstop for the supervisor who grinds a sweep through it anyway.
+	// reactive backstop for the supervisor who grinds a sweep through it anyway. It lands EARLY on
+	// purpose: by the fifth by-hand step the context is already spent, which is the cost it prevents.
 	minStepChars: 200, // below this a command is glue, not a sweep step
-	minSweepBurnChars: 8_000, // ~2k tokens cumulative — below this the sweep is cheap triage, not a grind
+	minSweepBurnChars: 4_000, // ~1k tokens cumulative — below this the sweep is cheap triage, not a grind
 	failedHandoffBackoff: 1, // suppress one identical immediate repair reminder; the failure remains visible
 };
 
@@ -96,18 +101,115 @@ function renderVisibleCheckpoint(title: string, lines: readonly string[]): strin
  * not all burn is delegable: work bound to one interactive session a sub-agent can't inherit
  * (a live shell, a specific tunnel) stays with you — then the fix is to keep it lean, not to hand off.
  */
-function renderNudge(reason: "dump" | "sweep", run: number, burn: number, size: number): string {
+function renderNudge(reason: "dump" | "sweep", run: number, burn: number, size: number, hints: NudgeHints = {}): string {
 	const signal =
 		reason === "dump"
 			? [`Trigger: one direct tool result · ~${toK(size)}k estimated output tokens.`, `Scope: ~${toK(burn)}k in the current direct-work streak.`]
 			: [`Trigger: ${run} substantive direct tool calls · ~${toK(burn)}k estimated output tokens.`, "Scope: since the last successful hand-off."];
+	// With a roster the action says TO WHOM (and to size the leg's model); without one it stays generic.
+	const action = hints.roster
+		? `Action: hand remaining independent breadth to a leg — ${hints.roster} — choose a known compatible model from your provider or inherit yours, then supervise.`
+		: "Action: delegate independent work; repair weak hand-offs, then re-dispatch.";
 	return renderVisibleCheckpoint("delegation checkpoint", [
 		...signal,
-		"Action: delegate independent work; repair weak hand-offs, then re-dispatch.",
-		"Keep local: session-bound work; keep it lean and grep-first.",
+		action,
+		...(hints.models ? [`Model candidates (your provider; account support may vary): ${hints.models}`] : []),
+		"Keep local: quick checks or coupled/session-bound work; keep it lean and grep-first.",
 	]);
 }
 
+/** Longest roster / model list carried on a checkpoint line — one bounded line, never a paragraph. */
+const HINT_CLIP = 320;
+
+/** Run a caller-supplied thunk into one bounded, single-line string, or undefined. The text comes from
+ *  installed agent descriptions and the model registry, so it is collapsed (no newline can forge a
+ *  card line) and clipped; a throwing or empty thunk is simply no hint — it must never break the hook. */
+function hint(thunk: (() => string | undefined) | undefined): string | undefined {
+	if (!thunk) return undefined;
+	let raw: string | undefined;
+	try {
+		raw = thunk();
+	} catch {
+		return undefined;
+	}
+	const text = raw?.replace(/\s+/g, " ").trim();
+	if (!text) return undefined;
+	return text.length > HINT_CLIP ? `${text.slice(0, HINT_CLIP - 1)}…` : text;
+}
+
+/** Live context the reminder cites. Thunks, not values: both change under a running session (agents on
+ *  `/persona reload`, the session model on a switch), so they are read when the reminder fires. */
+export interface NudgeOptions {
+	/** Who to hand the breadth to, e.g. `scout (reads) · operator (edits, runs)`. */
+	roster?: () => string | undefined;
+	/** Catalog candidates for this provider, not account entitlement (the session's own marked). */
+	models?: () => string | undefined;
+}
+
+interface NudgeHints {
+	roster?: string | undefined;
+	models?: string | undefined;
+}
+
+/** Longest description carried per agent on the roster line. */
+const ROSTER_DESC_CLIP = 40;
+
+/** Order delegate targets by the active persona's own prompt: agents it names come first, in order of
+ *  first mention, then the rest in their given (registry) order. A mention is a whole-word,
+ *  case-insensitive match of the agent's name, so `scouting` is not `scout` and `evidence-verifier` is
+ *  not `verifier`. Generic by construction: the persona text is the data, no name is listed here. A
+ *  prompt that names no agent (or none at all) leaves the order untouched. Pure; returns a new array. */
+export function orderByMention<T extends { name: string }>(agents: readonly T[], personaPrompt: string | undefined): T[] {
+	if (!personaPrompt) return [...agents];
+	const firstMention = (name: string): number => {
+		if (!name) return Number.POSITIVE_INFINITY;
+		const literal = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const at = personaPrompt.search(new RegExp(`(?<![\\w-])${literal}(?![\\w-])`, "i"));
+		return at < 0 ? Number.POSITIVE_INFINITY : at;
+	};
+	return agents
+		.map((agent, index) => ({ agent, index, at: firstMention(agent.name) }))
+		.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.index - b.index))
+		.map((entry) => entry.agent);
+}
+
+/** The reminder's roster: `name (clipped description)` for the first `max` delegate targets, joined
+ *  ` · `. The caller passes the capability-filtered targets, so it never names an agent the persona
+ *  cannot call. Undefined when there are none. */
+export function renderNudgeRoster(agents: ReadonlyArray<{ name: string; description?: string }>, max = 4): string | undefined {
+	const parts = agents.slice(0, max).map((agent) => {
+		const description = (agent.description ?? "").replace(/\s+/g, " ").trim();
+		if (!description) return agent.name;
+		const clipped = description.length > ROSTER_DESC_CLIP ? `${description.slice(0, ROSTER_DESC_CLIP - 1)}…` : description;
+		return `${agent.name} (${clipped})`;
+	});
+	return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+/** Nearby naming/generation candidates: exact active model first, then provider-relative cost
+ *  bands and version-ranked representatives. This does not prove account access or quality.
+ *  Undefined when there is no session model or the provider has no catalog entries. */
+export function renderNudgeModels(
+	models: readonly ModelCostMetadata[],
+	session: { provider: string; id: string } | undefined,
+	max = 10,
+): string | undefined {
+	if (!session?.provider) return undefined;
+	const own = models.filter((m) => m.provider === session.provider);
+	if (own.length === 0) return undefined;
+	const limit = Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 40;
+	if (limit === 0) return undefined;
+	const recommendations = recommendModels(own, session, Number.MAX_SAFE_INTEGER);
+	const selected = recommendations.slice(0, limit);
+	if (selected.length === 0) return undefined;
+	const tiers = modelCostTiers(own, shortlistModels(own, undefined, Number.MAX_SAFE_INTEGER));
+	const shown = selected.map((m) => {
+		const ref = `${m.provider}/${m.id}`;
+		return `${ref} [cost:${tiers.get(ref) ?? "unknown"}]${m.id === session.id ? " (you)" : ""}`;
+	});
+	return `${shown.join(", ")}${recommendations.length > shown.length ? " …" : ""}`;
+}
+
 export class DelegationNudge {
 	private run = 0; // consecutive SUBSTANTIVE hands-on calls since the last hand-off
 	private burn = 0; // cumulative output chars since the last hand-off (for the message only)
@@ -116,9 +218,11 @@ export class DelegationNudge {
 	private failedHandoffKey: string | undefined;
 	private failedHandoffRepeats = 0;
 	private readonly t: NudgeThresholds;
+	private readonly opts: NudgeOptions;
 
-	constructor(thresholds: NudgeThresholds = DEFAULT_NUDGE_THRESHOLDS) {
+	constructor(thresholds: NudgeThresholds = DEFAULT_NUDGE_THRESHOLDS, opts: NudgeOptions = {}) {
 		this.t = thresholds;
+		this.opts = opts;
 	}
 
 	/** Clear the run — call on a new session or persona switch. */
@@ -140,6 +244,7 @@ export class DelegationNudge {
 		if (GLUE_TOOLS.has(toolName)) return undefined;
 		if (HANDOFF_TOOL_NAMES.has(toolName)) {
 			if (!handoffSucceeded) {
+				if (toolName === "flow") return undefined; // self-describing failure (abort, bad name, a failed phase): never a re-dispatch cue (a rejected checkpoint is not an error: it counts as a landed hand-off)
 				const normalizedSize = Math.max(0, Math.floor(size));
 				const identity = failureText === undefined ? `size:${normalizedSize}` : fingerprintFailure(failureText);
 				const key = `${toolName}:${identity}`;
@@ -183,7 +288,10 @@ export class DelegationNudge {
 		if (!single && !sweep) return undefined;
 		this.lastNudgeRun = this.run;
 		this.nudges += 1;
-		return renderNudge(sweep ? "sweep" : "dump", this.run, this.burn, size);
+		return renderNudge(sweep ? "sweep" : "dump", this.run, this.burn, size, {
+			roster: hint(this.opts.roster),
+			models: hint(this.opts.models),
+		});
 	}
 }
 
@@ -193,32 +301,31 @@ export class DelegationNudge {
  * UP: the child's report carries an explicit surrender/blocked marker. It returns a reminder to
  * append to that very result — in RECENT context, on the leg that just landed — that a delegating
  * supervisor must not bank a premature block: confirm it names a genuine missing capability, else
- * steer it back with the recovery pass or re-dispatch. This is the runtime half of the operator
+ * verify it directly or re-dispatch with a sharper brief. This is the runtime half of the operator
  * protocol's "reject premature surrender" rule; the top-of-prompt persona directive has decayed by
  * the time a blocked leg returns.
  *
  * Keyed on the ecosystem's OWN explicit protocol tokens (an operator emits `[BLOCKED: need X]`, a CTF
  * leg emits `FLAG: UNKNOWN`) — never a fuzzy "sounds stuck" guess, so it does not misfire on ordinary
- * prose. It inspects only `delegate`/`council` results (a child's report); the supervisor's own tools
+ * prose. It inspects only `delegate`/`council`/`flow` results (a child's report); the supervisor's own tools
  * are DelegationNudge's job, so the two never fire on the same event. Pure — no I/O, unit-testable.
  */
 
-/** Tools whose result is a delegated child's report (where a surrender can surface). */
-
 /** Explicit surrender/blocked markers the operator + CTF protocols emit (operator.md). */
 const SURRENDER_MARKERS: readonly RegExp[] = [/\[BLOCKED\b/i, /\bFLAG:\s*UNKNOWN\b/i];
 
 const PERSISTENCE_NOTE = renderVisibleCheckpoint("delegated result needs verification", [
 	"Trigger: a delegated leg returned BLOCKED/UNKNOWN.",
 	"Verify: accept only concrete external blockers (access, credentials, or tools).",
-	"Otherwise: run the recovery pass or re-dispatch with a sharper brief.",
+	"Otherwise: verify directly or re-dispatch with a sharper brief.",
 ]);
 
 export class PersistenceNudge {
 	/**
 	 * Feed one supervisor tool result: its tool name and the full text of the result. Returns the
 	 * reminder to append when a delegated leg's report signals premature surrender, else undefined.
-	 * The SYNC path (a `delegate`/`council` tool_result the supervisor sees inline).
+	 * The INLINE path: a `delegate`/`council`/`flow` tool_result the supervisor sees in the launching call,
+	 * which only a headless session produces (an interactive one backgrounds all three).
 	 */
 	observe(toolName: string, text: string): string | undefined {
 		if (!HANDOFF_TOOL_NAMES.has(toolName)) return undefined;
@@ -227,11 +334,57 @@ export class PersistenceNudge {
 
 	/**
 	 * Tool-agnostic surrender check on already-known-to-be-a-leg-report text. The ASYNC path uses
-	 * this: a background run (the interactive default) delivers its report through the completion
-	 * notifier as a fresh follow-up, NOT a `delegate` tool_result, so {@link observe}'s tool gate
-	 * would never see it — the caller has already established the text is a settled leg's output.
+	 * this: a background run (every interactive `delegate`, `council` and `flow`) delivers its report
+	 * through the completion notifier as a fresh follow-up, or `intercom result` collects it explicitly
+	 * — NOT a tool_result, so {@link observe}'s tool gate would never see it. The caller has already
+	 * established the text is a settled leg's output.
 	 */
 	scan(text: string): string | undefined {
 		return SURRENDER_MARKERS.some((re) => re.test(text)) ? PERSISTENCE_NOTE : undefined;
 	}
 }
+
+/**
+ * PollGuard — the call-time half of "end your turn, a finished run or batch wakes you". A peek (or a
+ * `result` on a still-running run) whose signature equals the previous one for the same scope
+ * learned nothing; asking again only holds the turn that the idle-gated completion wake needs to be
+ * idle. Per scope, the first repeat is refused and the second asks Pi to end the turn (`terminate` is
+ * a batch hint Pi honours only when every call in the batch sets it). No clock: a changed signature —
+ * a run settled, started, queued, began waiting or newly crossed the stall threshold — is
+ * new information and always allowed. Pure.
+ */
+export class PollGuard {
+	private readonly seen = new Map<string, { sig: string; strikes: number }>();
+
+	check(scope: string, sig: string): "ok" | "repeat" | "terminate" {
+		const entry = this.seen.get(scope);
+		if (entry?.sig !== sig) {
+			this.seen.set(scope, { sig, strikes: 0 });
+			return "ok";
+		}
+		entry.strikes += 1;
+		return entry.strikes === 1 ? "repeat" : "terminate";
+	}
+
+	reset(): void {
+		this.seen.clear();
+	}
+}
+
+/** A leading sleep at/above this many seconds holds the turn that background-child wakes need idle. */
+const LONG_WAIT_SECONDS = 20;
+
+const SLEEP_UNIT_SECONDS: Readonly<Record<string, number>> = { s: 1, m: 60, h: 3600, d: 86_400 };
+// Only the leading statement: GNU `sleep N[smhd]` and PowerShell `Start-Sleep [-Seconds|-s] N` /
+// `-Milliseconds|-m N`. Loops, `a; sleep 30`, scripts and `timeout`/`ping` forms are deliberately out.
+const LEADING_SLEEP = /^\s*(?:sleep\s+(?<bash>[\d.]+)(?<unit>[smhd])?|start-sleep(?:\s+-(?:seconds|s)(?=[:\s]))?[:\s]\s*(?<ps>[\d.]+)|start-sleep\s+-(?:milliseconds|m)[:\s]\s*(?<ms>[\d.]+))(?=[\s;&|)]|$)/i;
+
+/** Seconds of a leading long sleep in a shell command, else undefined. */
+export function longWaitSeconds(command: string): number | undefined {
+	const g = LEADING_SLEEP.exec(command)?.groups;
+	if (!g) return undefined;
+	const seconds = g.ms !== undefined
+		? Number(g.ms) / 1000
+		: Number(g.bash ?? g.ps) * (SLEEP_UNIT_SECONDS[g.unit?.toLowerCase() ?? "s"] ?? 1);
+	return seconds >= LONG_WAIT_SECONDS ? seconds : undefined;
+}

package/src/core/seed.ts

@@ -93,7 +93,8 @@ export interface SeedResult {
 
 /** Exact bytes from earlier releases whose seeded copies are known to be stale. A user file is
  * eligible only when BOTH size and digest match. Keep this explicit allow-list deliberately
- * small: it is a migration policy, not a fuzzy upgrader. */
+ * small: it is a migration policy, not a fuzzy upgrader. Before tagging a release, add the
+ * previous tag's digest for every changed asset; the guard test in seed.test.ts prints the row. */
 export interface SeededDefaultSpec {
 	size: number;
 	sha256: string;
@@ -105,9 +106,14 @@ export interface SeededDefaultSpec {
 export type SeededDefaultEntry = SeededDefaultSpec | readonly SeededDefaultSpec[];
 
 const ELITE_REQUIRED_ADDITIONS = ["agents/evidence-verifier.md"] as const;
+/** A migrated planner declares the `design` loop, whose generator is the `architect` agent. */
+const PLANNER_REQUIRED_ADDITIONS = ["agents/architect.md"] as const;
 
 export const LEGACY_SEEDED_DEFAULTS: Readonly<Record<string, SeededDefaultEntry>> = {
 	"personas/dev.md": [
+		// v1.17.2 pristine seed (LF and CRLF checkout variants).
+		{ size: 2712, sha256: "2dff44e3c6626d5eb35c5a9d74d77e345c95319bb6d310101ba53f6f330165b4" },
+		{ size: 2757, sha256: "afdafb105c14a4e4ed960969779f4059491d85bf463739cf01079fe9831ace5b" },
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
 		{ size: 5907, sha256: "1d7abbc482a26c452e2588e405bdcb60af536df1f81aa0b709dcff70554915d2" },
 		{ size: 5977, sha256: "a1b46938316636bc90f525d031490eef3ee46363abe3aa199b267449b8bff06a" },
@@ -119,44 +125,113 @@ export const LEGACY_SEEDED_DEFAULTS: Readonly<Record<string, SeededDefaultEntry>
 		{ size: 5194, sha256: "0899ee3b10971c2b324e9e9c868fcab833ea80a80b83d94a1f0a95147475e9b5" },
 		// v1.12.1
 		{ size: 5195, sha256: "54da40a44a777f8a3b36b6c038248116e19be5a6515707747d070dc3f32ead56" },
+		// v1.14.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 3292, sha256: "d058a5cf683fa178ffb6c6fc98172328680d0fb19e21cf46a24d42613b5c48de" },
+		{ size: 3344, sha256: "a11cd85fd22b1c426c5fe148ceab8550f1815aace0702566fea3ad742bc25c13" },
 	],
 	"personas/planner.md": [
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
-		{ size: 3350, sha256: "78a1f1c88d4d779dca46414029a247e8c48db85b3b7266be9366c6dc23714d87" },
-		{ size: 3397, sha256: "8055b7440f2cf1e79378196eda675bdeb5d58b8941d450f8901672cf82a9e876" },
+		{ size: 3350, sha256: "78a1f1c88d4d779dca46414029a247e8c48db85b3b7266be9366c6dc23714d87", requiredAdditions: PLANNER_REQUIRED_ADDITIONS },
+		{ size: 3397, sha256: "8055b7440f2cf1e79378196eda675bdeb5d58b8941d450f8901672cf82a9e876", requiredAdditions: PLANNER_REQUIRED_ADDITIONS },
+		// v1.14.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 2456, sha256: "a238aa8dbe01f42edc707585d1eccee3b63401eb1dbe91b607347a49624d27cb", requiredAdditions: PLANNER_REQUIRED_ADDITIONS },
+		{ size: 2493, sha256: "f8f8a8cdb6110022984556a7102f523411053282f818249c20ec8e0153c810e1", requiredAdditions: PLANNER_REQUIRED_ADDITIONS },
 	],
 	"personas/researcher.md": [
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
 		{ size: 4441, sha256: "a3819ea76afee2a2f14d50c99198a09d4a4bd858e22ea9e4ceb3d868dcbb78c8" },
 		{ size: 4498, sha256: "2bd9dcaf47bd4ef3d139be361d260fbf7c9caa523144548593cdfc7ea4a2246c" },
+		// v1.14.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 2606, sha256: "68a1e62ddde7b0b0ecfd165e699c76cf6d6f3d533b6d1051dc4d5a64e9968807" },
+		{ size: 2643, sha256: "717fcd632de176e339928158516f35a6a4d82588e6ca36083726d1dbcfdc0e18" },
 	],
 	"personas/audit.md": [
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
 		{ size: 2110, sha256: "ea893333fc128a760455bb4eaac3ee2d384163f40950fca2c201b41860bd9d8a" },
 		{ size: 2145, sha256: "04f2167437081d69806a704238411275006df98e6ee902bc0a8cb6eb81b0ef14" },
+		// v1.14.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 1636, sha256: "c35e053ef8578d93b1aa2efa4ecb97138ef84542f9cd7b524b1c7a267c4fdc05" },
+		{ size: 1665, sha256: "0c8dd4e637570aa82b25070a9027a2f46bda25a25f2195d06df0ccb6d98bb211" },
 	],
 	"personas/verify.md": [
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
 		{ size: 1927, sha256: "4c670aba28ce15937d60074ec4ac7d50f6db3cccf137b60d9758627d69e82a0f" },
 		{ size: 1955, sha256: "9696278c243f83c9e8ee5f128faacebb8a89f85464b2c182f1bb77365a6d5643" },
+		// v1.14.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 2127, sha256: "d17d2f73f13388f1c92a13045b7a6d1032aa6b710ab4147dfc2eacd27f07a522" },
+		{ size: 2158, sha256: "7e26e68b77793e7349a2945f7674d5a116e3d1cfc5299e038d7b3a468e977ab2" },
+	],
+	// v1.7.0–v1.17.1 pristine seeds (LF and CRLF checkout variants); these two had no row before.
+	"personas/judge.md": [
+		{ size: 1778, sha256: "2f8c987de59d0f2aac6bdb62f556fc5937605d1036b4a42c8ada7a48461d4710" },
+		{ size: 1810, sha256: "3f0287dd7052f1f0bc65b40dc3af52847c0e5b2295cfcb4001ebe345b9e3fadc" },
+	],
+	"personas/magi.md": [
+		{ size: 2361, sha256: "a608fc26a13070fad79b84f9d1a5f39fd3b760aefb98732f1f95134a89cd0366" },
+		{ size: 2402, sha256: "0b24f01d93517d5fc56a7318d374ee679fa146e919e86e753f422f9f10a37bda" },
 	],
 	// The MAGI cores gained `purpose:` (their verticalization) in v1.10.6. Agents are seeded COPIES,
 	// not a live layer read from the package, so without these an existing install keeps three cores
 	// that render as bare names — the label feature would ship inert for everyone who already has them.
-	"agents/melchior.md": { size: 1503, sha256: "aa7a69296640f1023e00e2f2285b12cfdee158bb89f7b0b3d8c03a6317de9508" },
-	"agents/balthasar.md": { size: 1527, sha256: "27273ed49ea265f528efad4724e6abec6d051fa60d1f4fa678982e7383364981" },
-	"agents/casper.md": { size: 1508, sha256: "5074341b7e1ae7e9a44bc71de0405a17ccb404eacfaeb2fcf40f2ac4c23828ea" },
+	// Each core lists v1.0.0–v1.10.5, then v1.11.0–v1.14.0 (adds the confidence tie-break paragraph).
+	"agents/melchior.md": [
+		{ size: 1503, sha256: "aa7a69296640f1023e00e2f2285b12cfdee158bb89f7b0b3d8c03a6317de9508" },
+		{ size: 1523, sha256: "8a78c1ff201d728187fe19f19ea5f62f2d02f67c5cc5c3a9e5255c8776cbe74d" },
+		// v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 1747, sha256: "43ab5f65ecb89260c09b7e33daef3b68b1bc1c60c81b73b245fdf9984f601044" },
+		{ size: 1779, sha256: "6b4dcc0cc7416ac9a4543b7330edaeefb29b1006cc5e67b86f15ca94c4eaaf24" },
+	],
+	"agents/balthasar.md": [
+		{ size: 1527, sha256: "27273ed49ea265f528efad4724e6abec6d051fa60d1f4fa678982e7383364981" },
+		{ size: 1549, sha256: "9e91de81e76dc6fab13ed5a6d0c26319ca89da8da6fb5c71c8d852fcb86b73f0" },
+		// v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 1773, sha256: "6716f5c68f2eb0bc1e72b33cef3e78b062efa07a01d12edb95e671a482832753" },
+		{ size: 1805, sha256: "baafecc02b01c962bfc933b3f3f768808d541c85b0e01b29f6ff04a710f6d716" },
+	],
+	"agents/casper.md": [
+		{ size: 1508, sha256: "5074341b7e1ae7e9a44bc71de0405a17ccb404eacfaeb2fcf40f2ac4c23828ea" },
+		{ size: 1531, sha256: "97f2fd367b7c13bfaec39d9bd61065023ef501a519d95e516e39842c487f9427" },
+		// v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 1832, sha256: "32effd595231b7bb6ce6af01c87108bb030d489cc8758946206161e148e270e4" },
+		{ size: 1865, sha256: "9d22349de3252074ba7d1482ee942c36e384181939ec71f1fddfd4c527d3d436" },
+	],
 	// Current pristine seed before the compact-digest/reusable-artifact prompt update (LF and CRLF).
 	"agents/research.md": [
 		{ size: 3771, sha256: "6d084d11c84a594ddac0986bcf81aea6e5768b9df18196fedc8715bfd3f1eb16" },
 		{ size: 3825, sha256: "768899c4c9a5f60a8ff18602d7ee5a696414fd35a8d53e6ae2cc9dfa41d7a88f" },
+		// v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 4132, sha256: "bb35ec537ae654bf60e8552721dfd797db34b5dd5f623b23a95adf2cd72c70e0" },
+		{ size: 4190, sha256: "b579b08e6a9035b8ec9e55166f7bbe3dd11d421edca4e0df6146ceff4fe3d459" },
 	],
 	// v1.14.1 pristine seed (LF and CRLF checkout variants).
 	"agents/evidence-verifier.md": [
 		{ size: 1465, sha256: "428be556abbbd530826631ef255cd7effa3484b00b0c7c35877e8b0c9a786aef" },
 		{ size: 1487, sha256: "5e4b2b41700bf7b669769f40dd5e98b41db0d708e1dec75697d06fd6abeaa2a1" },
+		// v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 1560, sha256: "4fa0af121789e4408bde6ae1d8ced73c7b42adf31e4bf48121621e1047b09861" },
+		{ size: 1583, sha256: "3156e4748dc32bfd0d4699054a0a8407f7110270ce717af774d54d34d0e98d13" },
+	],
+	// v1.17.1 pristine seeds (LF and CRLF checkout variants); these four had no row before.
+	"agents/operator.md": [
+		{ size: 4598, sha256: "be7a18654c6106c8fa3be9694c75ef375d17bf13789bfce9ed1f76012d646d59" },
+		{ size: 4661, sha256: "9031054af66bca2b726536e5348f6d0223f66bb7b544cc256457b015d55c850f" },
+	],
+	"agents/reviewer.md": [
+		{ size: 3427, sha256: "8570b80e48a2b44dc364f7a41b3cd06741507329d91b0b9d7e1b716e7eaf7ee2" },
+		{ size: 3476, sha256: "73f404259730719051f8e9aedb17ddd398304ed40068128cd97eae3a884b0912" },
+	],
+	"agents/scout.md": [
+		{ size: 1341, sha256: "ffea9fe3643dbc0e5dea8ffc0722f41050374daed33e7f3a46378de36a630a62" },
+		{ size: 1364, sha256: "425b8ef2c1141b602b2f67e47224f855a8a11f936affd4429272347678de8b58" },
+	],
+	"agents/verifier.md": [
+		{ size: 1037, sha256: "ce8f161b1879084b336e2f24495a82aba7279f099b450852ba02db8b4850def5" },
+		{ size: 1058, sha256: "78d7c9e7e6d961b0005d216968196dea28b8ef09a8ccd52b0f7a4de97754a800" },
 	],
 	"personas/elite.md": [
+		// v1.17.2 pristine seed (LF and CRLF checkout variants).
+		{ size: 17580, sha256: "5a45759f0c94ea090c8a537c59a6549449ed089d0f02fac9a09ba14b01a09ff2", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
+		{ size: 17835, sha256: "425e0f4fbeb855a788706eb278db4ed4c1026c59bedcca9768c258966ede1654", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
 		{
 			// v1.0.0
 			size: 10489,
@@ -217,6 +292,12 @@ export const LEGACY_SEEDED_DEFAULTS: Readonly<Record<string, SeededDefaultEntry>
 			sha256: "dbe4a4da34338e4210b5abf9a902b4c56bba31eced1f00eb775e30b25ee37b90",
 			requiredAdditions: ELITE_REQUIRED_ADDITIONS,
 		},
+		{
+			// v1.12.2–v1.14.0
+			size: 19312,
+			sha256: "a817f6e76164a142a15ec843978942e31ab765ae463bdded3966c0863d010894",
+			requiredAdditions: ELITE_REQUIRED_ADDITIONS,
+		},
 		{
 			// v1.14.1 pristine seed (LF and CRLF checkout variants).
 			size: 19417,
@@ -228,10 +309,18 @@ export const LEGACY_SEEDED_DEFAULTS: Readonly<Record<string, SeededDefaultEntry>
 			sha256: "69be3a81b6b20ff51e21f8a6730049a5f740dd00c069f21d1a5a2184fda97f24",
 			requiredAdditions: ELITE_REQUIRED_ADDITIONS,
 		},
+		// v1.14.2–v1.16.1 and v1.16.2–v1.17.1 pristine seeds (LF and CRLF checkout variants each).
+		{ size: 19575, sha256: "7a349e63abc07c60c3937eb01005c0567e27327ec13a79550fcfe7deb5f87630", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
+		{ size: 19831, sha256: "7b078a2b2c2339df1169351fd58c97d5e99e4b33bff00c43229e566f0a737701", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
+		{ size: 19585, sha256: "23146654476bc477c48ce972b13566a31198c41c1aa051540d25cfb45394ab9d", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
+		{ size: 19841, sha256: "2751df2d27066c1d7398be3cc4d72abc4ecba01fb757c34b949bf74d64154dcb", requiredAdditions: ELITE_REQUIRED_ADDITIONS },
 	],
 	// Live-peer collaboration landed in v1.12.2. Without these, a seeded copy from 1.7–1.12.1
 	// (and the two earlier untouched hashes) keeps the pre-collaboration prompt forever.
 	"personas/swarm.md": [
+		// v1.17.2 pristine seed (LF and CRLF checkout variants).
+		{ size: 2694, sha256: "72d17416941edb6f31ca86cff1de6fa6d85c5ba7ae0cd269d104c770c9e42bf2" },
+		{ size: 2737, sha256: "303ddc6bd44f2f909765d99d8f753136dae9d8a635616d6e65523814e06131a1" },
 		// v1.13.4 pristine seed (LF and CRLF checkout variants)
 		{ size: 2729, sha256: "3d5060277ecaec717e87beb8d95b0fe9f3dc70fe5f0192823aa79b55f9e49507" },
 		{ size: 2768, sha256: "b81910521e05d62e06abaf0f2a89bd18ad252ba968bb296cc85dea973028e7a5" },
@@ -241,6 +330,10 @@ export const LEGACY_SEEDED_DEFAULTS: Readonly<Record<string, SeededDefaultEntry>
 		{ size: 1857, sha256: "77de7f590fdede6ede4848be11b39fb16bfb4733687ac1b1244cc59e626874c6" }, // v1.1.0–v1.4.0
 		{ size: 1955, sha256: "b7a7caa38c4d31c8cc27b85eb7facbf2339a024ad8d4cd2ba681a2a885de7646" }, // v1.5.1–v1.6.3
 		{ size: 2285, sha256: "985a1c5455b2c81537a55b31daed216d7f67a897b3b2d5bde35d64f3779d6fe4" }, // v1.7.0–v1.12.1
+		{ size: 2360, sha256: "ae0cfe758d9e1b9a4d2d4bad151999418e10e8291226764e7d155b44ce8ff5ea" }, // v1.14.0–v1.14.2
+		// v1.15.0–v1.17.1 pristine seed (LF and CRLF checkout variants).
+		{ size: 2570, sha256: "3e6537f555d35b396041166d38da5cb397e076d00c258e25992d2e6abb8a37ef" },
+		{ size: 2608, sha256: "c54acac4f88a1dfbe7b21eb3c4bcea658896f953ea8de5d592bc06d2ad0f312a" },
 	],
 };
 

package/src/core/session-runs.ts

@@ -0,0 +1,87 @@
+/**
+ * What a session restore cannot carry over.
+ *
+ * Background runs, armed timers and monitors live only in the memory of one extension instance. A
+ * `/reload`, an in-session `/resume` or `pi -c` tears that instance down, so the restored supervisor
+ * would otherwise keep waiting for wakes that can no longer come, and run ids would restart at
+ * `run-1` and collide with the ids already in its history. The shutdown hook records the loss and
+ * the id counter in a session entry; the next start reads it back (the session-identity pattern)
+ * and tells the supervisor once.
+ *
+ * Everything read back is untrusted session data, so nothing but run ids matching a strict shape and
+ * small counts is ever kept: no free text can reach the model through this entry. Pure — no I/O.
+ */
+
+/** Custom session-entry type for {@link RunsEntry}; deliberately unrendered. */
+export const RUNS_ENTRY_CUSTOM_TYPE = "pi-persona:runs";
+
+const RUN_ID = /^run-[0-9a-z]{1,8}$/;
+/** One cap for every count and the id list (a full 64-leg fan-out fits whole); the entry stays small. */
+const MAX_COUNT = 99;
+const MAX_ISSUED = 1_000_000_000;
+/** Ids named in the notice itself; the rest are counted. */
+const MAX_NAMED_IDS = 8;
+
+export interface LostWork {
+	runs: string[];
+	timers: number;
+	monitors: number;
+}
+
+export interface RunsEntry {
+	version: 1;
+	sessionId: string;
+	/** Run ids issued so far in this session lineage: the next instance continues from here. */
+	issued: number;
+	lost: LostWork;
+}
+
+const count = (value: unknown): number => (Number.isInteger(value) && (value as number) > 0 ? Math.min(value as number, MAX_COUNT) : 0);
+
+function cleanLost(value: { runs?: unknown; timers?: unknown; monitors?: unknown }): LostWork {
+	const runs = (Array.isArray(value.runs) ? value.runs : []).filter((id): id is string => typeof id === "string" && RUN_ID.test(id));
+	return { runs: [...new Set(runs)].slice(0, MAX_COUNT), timers: count(value.timers), monitors: count(value.monitors) };
+}
+
+export function makeRunsEntry(sessionId: string, issued: number, lost: LostWork): RunsEntry {
+	return { version: 1, sessionId, issued, lost: cleanLost(lost) };
+}
+
+/**
+ * The newest runs entry written for THIS session id, or undefined. The newest one wins even when it
+ * is malformed (fail closed): skipping it would let an older loss replay after it was acknowledged.
+ */
+export function findStoredRuns(entries: readonly unknown[], sessionId: string): RunsEntry | undefined {
+	if (!sessionId) return undefined;
+	let data: Partial<RunsEntry> | undefined;
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const item = entry as { type?: unknown; customType?: unknown; data?: unknown };
+		if (item.type !== "custom" || item.customType !== RUNS_ENTRY_CUSTOM_TYPE) continue;
+		if (!item.data || typeof item.data !== "object") continue;
+		const candidate = item.data as Partial<RunsEntry>;
+		if (candidate.version === 1 && candidate.sessionId === sessionId) data = candidate;
+	}
+	if (!data) return undefined;
+	const { issued, lost } = data;
+	if (typeof issued !== "number" || !Number.isInteger(issued) || issued < 0 || issued > MAX_ISSUED) return undefined;
+	if (!lost || typeof lost !== "object") return undefined;
+	return makeRunsEntry(sessionId, issued, lost);
+}
+
+const plural = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
+/** The one line the restored supervisor is told, or undefined when nothing was lost. */
+export function restoreNotice(lost: LostWork): string | undefined {
+	const parts: string[] = [];
+	if (lost.runs.length > 0) {
+		const named = lost.runs.slice(0, MAX_NAMED_IDS).join(", ");
+		const more = lost.runs.length - MAX_NAMED_IDS;
+		parts.push(`run${lost.runs.length === 1 ? "" : "s"} ${named}${more > 0 ? ` +${more} more` : ""} (stopped or never reported)`);
+	}
+	if (lost.timers > 0) parts.push(plural(lost.timers, "timer"));
+	if (lost.monitors > 0) parts.push(plural(lost.monitors, "monitor"));
+	if (parts.length === 0) return undefined;
+	return `Session restored. Background work from before the restore did not survive (it lives only in memory): ${parts.join("; ")}. `
+		+ "Earlier run results can no longer be fetched. Do not wait for them; relaunch or re-arm only what you still need.";
+}

package/src/core/settings.ts

@@ -50,7 +50,7 @@ export const PERSONA_SETTINGS: readonly PersonaSetting[] = [
 	{ id: "checkInEveryMs", group: "Delegation", label: "Progress check-in interval", description: "Milliseconds between operator-only progress entries; zero disables check-ins.", kind: "number", env: "PI_PERSONA_CHECKIN_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
 	{ id: "agentHardTimeoutMs", group: "Delegation", label: "Agent hard timeout", description: "Opt-in wall-clock limit in milliseconds for one agent run; zero means unlimited.", kind: "number", env: "PI_PERSONA_AGENT_MAX_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
 	{ id: "agentStartupTimeoutMs", group: "Delegation", label: "Agent startup deadline", description: "Milliseconds allowed without first progress while an agent starts; zero disables the deadline.", kind: "number", env: "PI_PERSONA_AGENT_STARTUP_MS", applyWhen: APPLY_WHEN, min: 0, max: MAX_TIMER_DELAY_MS },
-	{ id: "nudge", group: "Delegation", label: "Delegation nudges", description: "Delegation and persistence checkpoints; disabling silences both.", kind: "boolean", env: "PI_PERSONA_NUDGE", applyWhen: APPLY_WHEN },
+	{ id: "nudge", group: "Delegation", label: "Delegation nudges", description: "Delegation and persistence checkpoints, plus the repeated peek/result and long-sleep guards; disabling turns all of them off.", kind: "boolean", env: "PI_PERSONA_NUDGE", applyWhen: APPLY_WHEN },
 	{ id: "broker", group: "Collaboration", label: "Cross-process communication broker", description: "Connect child-engine agents to supervisor messaging and steering.", kind: "boolean", env: "PI_PERSONA_BROKER", applyWhen: APPLY_WHEN },
 	{ id: "exocom", group: "Collaboration", label: "External agent communication", description: "Enable communication between independent top-level Pi instances.", kind: "boolean", env: "PI_PERSONA_EXOCOM", applyWhen: APPLY_WHEN },
 	{ id: "asyncRetain", group: "Delegation", label: "Retained async results", description: "Number of settled async runs retained for later collection.", kind: "number", env: "PI_PERSONA_ASYNC_RETAIN", applyWhen: APPLY_WHEN, min: 1, max: MAX_SAFE_INTEGER },