@hank-warren/pi-loop 0.6.0 → 0.8.0

package/src/progress-tool.ts

@@ -0,0 +1,162 @@
+/**
+ * `loop_progress`: the only supported write path into the loop ledger.
+ *
+ * The ledger is the one thing that survives compaction, and until this tool
+ * existed the model was told to maintain it with no way to do so — so it
+ * reached for `write` or a shell heredoc, and a single `cat > PROGRESS.md`
+ * replaced the objective line, the other three sections, and days of
+ * failed-approach notes. `createLedger` opens that file with `flag: "wx"`
+ * precisely so the *engine* can never do that; leaving the *agent* a path that
+ * can made the protection decorative.
+ *
+ * Two operations, deliberately in one tool: record a note in a named section,
+ * and flip a criterion with the citation that justified it. They travel
+ * together — "here is what I did, and here is the criterion it proves" is one
+ * thought, and one tool call per turn keeps the ledger current without a
+ * second round trip.
+ *
+ * Registered unconditionally like `loop_complete` and `loop_wait`: tools are
+ * part of the cached request prefix, so adding one mid-session would
+ * invalidate the whole conversation cache. It refuses when no loop is active.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import {
+	MAX_EVIDENCE_LENGTH,
+	MAX_PROGRESS_TEXT_LENGTH,
+	markCriterion,
+	PROGRESS_SECTIONS,
+	type ProgressSection,
+	writeProgressSection,
+} from "./ledger.js";
+import type { LoopController } from "./loop.js";
+
+export const LOOP_PROGRESS_TOOL = "loop_progress";
+
+export function registerLoopProgressTool(pi: ExtensionAPI, controller: LoopController) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_PROGRESS_TOOL,
+			label: "Loop Progress",
+			description:
+				"Record progress in the active /loop's durable ledger: append a note to one PROGRESS.md section, and/or mark a completion criterion met with the evidence that proves it. The only supported way to write to the ledger — never edit PROGRESS.md or criteria.json with file or shell tools.",
+			promptSnippet: "Record loop progress and mark criteria met with evidence",
+			promptGuidelines: [
+				"Use loop_progress to update the loop ledger. Never write PROGRESS.md or criteria.json with the file or shell tools: a whole-file write destroys the objective line and the other sections, and hand-editing criteria.json bypasses the rule that only `passes` may change.",
+				"Record a note the same turn you learn something, not at the end. The failed-approaches section carries the most value, because it is the only thing that stops the next continuation from re-running an experiment that already failed.",
+				"'current status' replaces what is there (it is one current value); the other three sections append.",
+				"Mark a criterion met only with authoritative evidence: the command and what it printed, the file and what it now contains, the URL and its state. The citation is stored next to the criterion and is what loop_complete answers for later.",
+			],
+			parameters: Type.Object({
+				section: Type.Optional(
+					StringEnum([...PROGRESS_SECTIONS], {
+						description:
+							"Which PROGRESS.md section to write. 'current status' replaces its contents; the others append.",
+					}),
+				),
+				note: Type.Optional(
+					Type.String({
+						maxLength: MAX_PROGRESS_TEXT_LENGTH,
+						description:
+							"Markdown to record in that section. Write list sections as '- ' bullets to match the file.",
+					}),
+				),
+				criterion: Type.Optional(
+					Type.String({
+						maxLength: 40,
+						description: "Criterion id to mark, e.g. 'c2'. Ids come from the loop's criteria.json.",
+					}),
+				),
+				evidence: Type.Optional(
+					Type.String({
+						maxLength: MAX_EVIDENCE_LENGTH,
+						description:
+							"The citation proving that criterion: the command and its output, the file and its contents, the URL and its state. Required when marking one met.",
+					}),
+				),
+				met: Type.Optional(
+					Type.Boolean({
+						description:
+							"Whether the criterion is met. Defaults to true; pass false to retract a criterion marked met in error.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+				const loop = controller.state;
+				if (!loop || loop.objective === undefined) {
+					return failure(
+						"No /loop with an objective is active, so there is no ledger to write. Start one with /loop <interval> <objective>.",
+					);
+				}
+				const paths = controller.ledger;
+				if (!paths) {
+					return failure(
+						"This loop has no ledger (it could not be created), so progress cannot be recorded. Keep the state in your reply instead.",
+					);
+				}
+
+				const section = params.section as ProgressSection | undefined;
+				const note = params.note?.trim();
+				const criterion = params.criterion?.trim();
+				// A tool call that writes nothing is a mistake worth naming: the
+				// model believed it recorded something and it did not.
+				if (!note && !criterion) {
+					return failure(
+						"Nothing to record. Pass section + note to write a ledger entry, criterion + evidence to mark a criterion, or both.",
+					);
+				}
+				if (note && !section) return failure("A note needs a section to write it to.");
+				if (section && !note) return failure("A section needs a note to write into it.");
+
+				const done: string[] = [];
+				if (section && note) {
+					const failed = writeProgressSection(paths, section, note);
+					if (failed) return failure(`Could not write the ledger: ${failed}`);
+					done.push(`Recorded under "${section}".`);
+				}
+
+				let remaining: string | undefined;
+				if (criterion) {
+					const met = params.met ?? true;
+					const result = markCriterion(paths, criterion, params.evidence ?? "", met, Date.now());
+					if (!result.ok) {
+						// A half-applied call still reports the half that landed, so the
+						// model does not record the note twice on the retry.
+						return failure(
+							[...done, `Could not mark ${criterion}: ${result.message}`].join(" "),
+							done.length > 0,
+						);
+					}
+					done.push(result.message);
+					const unmet = (result.criteria ?? []).filter((entry) => !entry.passes);
+					remaining =
+						unmet.length > 0
+							? `Still unmet: ${unmet.map((entry) => entry.id).join(", ")}.`
+							: "Every criterion is now marked met; audit them against authoritative current state before calling loop_complete.";
+					controller.updateWidget();
+				}
+
+				return {
+					content: [
+						{ type: "text" as const, text: [...done, remaining].filter(Boolean).join(" ") },
+					],
+					details: {
+						loopId: loop.id,
+						...(section && note ? { section } : {}),
+						...(criterion ? { criterion, met: params.met ?? true } : {}),
+					},
+				};
+			},
+		}),
+	);
+}
+
+function failure(text: string, partial = false) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details: { partial },
+		isError: true,
+	};
+}

package/src/propose-tool.ts

@@ -0,0 +1,119 @@
+/**
+ * `loop_propose`: put a drafted loop up for the user's approval.
+ *
+ * It starts nothing. That separation is the point — the model drafts, the user
+ * approves, and the approval is what arms the start. `loop_start`'s gate
+ * exists because a loop is self-continuing and must never begin on model
+ * initiative; an explicit approval on a card showing the objective, the
+ * criteria, the cadence and the caps is stronger evidence of intent than a
+ * typed token, not weaker, so it arms the same gate rather than bypassing it.
+ *
+ * Registered unconditionally, like the other loop tools: the tool set is part
+ * of the cached request prefix, so it never changes with loop state.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import type { LoopController } from "./loop.js";
+import { renderProposalCard } from "./planning.js";
+
+export const LOOP_PROPOSE_TOOL = "loop_propose";
+
+export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopController) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_PROPOSE_TOOL,
+			label: "Loop Propose",
+			description:
+				"Put a drafted loop objective up for the user's approval during loop planning. Renders an approval card showing the exact completion criteria the objective will produce. Starts nothing: the user approves, edits, or cancels.",
+			promptSnippet: "Propose a drafted loop objective for approval",
+			promptGuidelines: [
+				"Call loop_propose only while loop planning is open, and only once the objective reads as an acceptance test: one requirement per bullet, each naming the check that proves it.",
+				"Pass the objective you and the user agreed on, not a tidier version of it. The criteria are derived from this text and frozen when the loop starts.",
+				"Do not call loop_start for a planned loop; approving the card is what starts it.",
+				"loop_propose starts nothing, so the rule that a loop needs an inline /loop token in the user's message does not apply to it. While planning is open, a conversational request for a loop is the signal to draft one and propose it — never to refuse and ask the user to type /loop instead.",
+			],
+			parameters: Type.Object({
+				objective: Type.String({
+					minLength: 1,
+					maxLength: 100_000,
+					description:
+						"The drafted objective, one requirement per bullet, each naming how it is verified.",
+				}),
+				interval: Type.Optional(
+					Type.String({
+						description:
+							"Fallback heartbeat as <number><unit> (s, m, h, d), e.g. 30m. Omit to use the configured default.",
+					}),
+				),
+				max_turns: Type.Optional(
+					Type.Number({
+						description:
+							"Cap on loop-caused turns. Omit for the configured default; the user can change it on the card.",
+					}),
+				),
+				expires: Type.Optional(
+					Type.String({
+						description: "Loop lifetime as <number><unit>, e.g. 3d. Omit for the default.",
+					}),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+				if (!controller.planning.active) {
+					return failure(
+						"Loop planning is not open, so there is nothing to propose. The user opens it by running /loop with no loop running.",
+					);
+				}
+				if (controller.state && controller.state.status !== "stopped") {
+					return failure(
+						"A loop is already running in this session. Stop it with /loop stop before planning another.",
+					);
+				}
+				const objective = params.objective.trim();
+				if (!objective) return failure("A proposal needs an objective.");
+
+				const overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } =
+					{};
+				if (params.interval !== undefined) {
+					const parsed = parseDuration(params.interval);
+					if (parsed === undefined) {
+						return failure(
+							`Invalid interval: ${params.interval}. Use <number><unit> with unit s, m, h, or d, e.g. 30m.`,
+						);
+					}
+					overrides.intervalMs = Math.min(parsed, MAX_INTERVAL_MS);
+				}
+				if (params.expires !== undefined) {
+					const parsed = parseDuration(params.expires);
+					if (parsed === undefined) {
+						return failure(
+							`Invalid expires: ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
+						);
+					}
+					overrides.expiresInMs = parsed;
+				}
+				if (params.max_turns !== undefined) {
+					if (!Number.isSafeInteger(params.max_turns) || params.max_turns <= 0) {
+						return failure("max_turns must be a positive whole number.");
+					}
+					overrides.maxTurns = params.max_turns;
+				}
+
+				const proposal = controller.propose(objective, overrides);
+				return {
+					content: [{ type: "text" as const, text: renderProposalCard(proposal).join("\n") }],
+					details: {
+						criteria: proposal.criteria.length,
+						intervalMs: proposal.intervalMs,
+						maxTurns: proposal.maxTurns,
+					},
+				};
+			},
+		}),
+	);
+}
+
+function failure(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {}, isError: true };
+}

package/src/settings.ts

@@ -21,15 +21,22 @@ export interface LoopCompactionSettings {
 	instructions: string | null;
 }
 
+/**
+ * The cap fields this one replaced: a delivered-wake cap (`maxIterations`,
+ * `--max`) and a loop-caused-turn cap (`automaticTurns`). A settle-paced loop
+ * can run its whole life without delivering a single fallback wake, so the
+ * wake cap bounded nothing the turn cap did not already bound.
+ */
+const LEGACY_CAP_KEYS = ["maxIterations", "automaticTurns"] as const;
+
 export interface LoopSettings {
-	/** Delivered-wake cap; null means unlimited (explicit opt-in). */
-	maxIterations: number | null;
 	/**
-	 * Cap on turns the loop itself causes (settle continuations plus fallback
-	 * pokes); null means unlimited. A settle-paced loop can run many turns per
-	 * wake, so this is the bound that actually holds it.
+	 * Cap on the turns the loop itself causes (settle continuations plus
+	 * fallback pokes); null means unlimited (explicit opt-in). The only cap
+	 * there is: one wake can yield many turns, so counting turns is what
+	 * actually bounds a loop.
 	 */
-	automaticTurns: number | null;
+	maxTurns: number | null;
 	/**
 	 * Consecutive tool-free loop turns with identical output that pause the
 	 * loop; null disables the breaker.
@@ -54,8 +61,7 @@ export interface LoopSettings {
 }
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
-	maxIterations: 25,
-	automaticTurns: 25,
+	maxTurns: 25,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
 	inlineInvocation: true,
@@ -76,11 +82,8 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	const record = ownRecord(value);
 	if (!record) return undefined;
 
-	const maxIterations = normalizeCap(record.maxIterations, DEFAULT_LOOP_SETTINGS.maxIterations);
-	if (maxIterations === false) return undefined;
-
-	const automaticTurns = normalizeCap(record.automaticTurns, DEFAULT_LOOP_SETTINGS.automaticTurns);
-	if (automaticTurns === false) return undefined;
+	const maxTurns = normalizeTurnCap(record);
+	if (maxTurns === false) return undefined;
 
 	const noProgressTurns = normalizeCap(
 		record.noProgressTurns,
@@ -134,8 +137,7 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	}
 
 	return {
-		maxIterations,
-		automaticTurns,
+		maxTurns,
 		noProgressTurns,
 		maxLoopDuration,
 		inlineInvocation,
@@ -151,6 +153,32 @@ function normalizeCap(value: unknown, fallback: number | null): number | null |
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : false;
 }
 
+/**
+ * The turn cap, accepting the two caps it replaced.
+ *
+ * A settings file written by an older version names no `maxTurns`, and asking
+ * users to rewrite their settings to keep a cap they already chose is not a
+ * trade worth making. So a file carrying only the legacy keys keeps the
+ * tighter of the two: that is the bound their loops were already running
+ * under. An invalid value in either key still fails the whole file closed,
+ * exactly as it did when the key was current.
+ */
+function normalizeTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		return normalizeCap(record.maxTurns, DEFAULT_LOOP_SETTINGS.maxTurns);
+	}
+	let adopted: number | null | undefined;
+	for (const key of LEGACY_CAP_KEYS) {
+		if (!Object.hasOwn(record, key)) continue;
+		const cap = normalizeCap(record[key], DEFAULT_LOOP_SETTINGS.maxTurns);
+		if (cap === false) return false;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? DEFAULT_LOOP_SETTINGS.maxTurns : adopted;
+}
+
 function readBoolean(record: Record<string, unknown>, key: string, fallback: boolean): unknown {
 	return Object.hasOwn(record, key) ? record[key] : fallback;
 }
@@ -221,11 +249,14 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 	}
 
 	const compaction = ownRecord(raw.compaction) ?? {};
+	// Unknown fields are preserved, but the two caps `maxTurns` replaced are not
+	// unknown: leaving them next to a cap that supersedes them would show the
+	// user two numbers where only one applies.
+	for (const key of LEGACY_CAP_KEYS) delete raw[key];
 	const document = `${JSON.stringify(
 		{
 			...raw,
-			maxIterations: normalized.maxIterations,
-			automaticTurns: normalized.automaticTurns,
+			maxTurns: normalized.maxTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
 			inlineInvocation: normalized.inlineInvocation,

package/src/start-tool.ts

@@ -15,6 +15,14 @@
  * until a cap. So the tool refuses outright unless the inline hint armed for
  * the turn that is calling it.
  *
+ * The one thing this path may decide that the `/loop` command cannot is the
+ * loop's completion criteria. They are otherwise a deterministic split of the
+ * objective's grammar, which turns a context sentence into a gate criterion;
+ * a model that read the objective can do better. It is accepted only *here*,
+ * at start, before any work exists to grade and with the user seeing the
+ * criteria echoed back — the point where the incentive to write an easy gate
+ * is weakest. After start they are immutable, exactly as a derived set is.
+ *
  * Registered unconditionally, like the other loop tools: the tool set is part
  * of the cached request prefix, so it never changes with loop state.
  */
@@ -23,6 +31,7 @@ import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
 import { formatDuration, parseDuration, parseInterval } from "./interval.js";
+import { MAX_CRITERIA, MAX_DESCRIPTION_LENGTH } from "./ledger.js";
 import type { InlineInvocationState } from "./inline-invocation.js";
 import type { LoopController } from "./loop.js";
 
@@ -49,7 +58,11 @@ export function registerLoopStartTool(
 				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
 				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
 				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
+				"Leave the criteria parameter out by default: the extension splits the objective into completion criteria on its own (bullets, else sentences, else the whole objective). Propose criteria only when that split would misfire — when the objective mixes requirements with context sentences (`fix CI. it has been red since Tuesday.`), or packs several requirements into one sentence.",
+				"Every criterion you propose must be a faithful restatement of something the user asked for: never fewer, weaker, or easier than the objective as typed, and never a requirement they did not state. They are echoed back to the user at start and frozen afterwards — you may only ever flip a criterion's passes field.",
+				"When in doubt, omit criteria and let the deterministic split stand.",
 				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
+				"Before your first loop_start this session, read the pi-loop skill: the objective is split into the completion criteria this loop will be gated on, so its wording is the leverage point.",
 			],
 			parameters: Type.Object({
 				objective: Type.String({
@@ -67,7 +80,8 @@ export function registerLoopStartTool(
 				max: Type.Optional(
 					Type.Integer({
 						minimum: 1,
-						description: "Wake cap from a --max flag in the invocation.",
+						description:
+							"Cap on the turns the loop causes (continuations and pokes), from a --max flag in the invocation.",
 					}),
 				),
 				expires: Type.Optional(
@@ -75,6 +89,17 @@ export function registerLoopStartTool(
 						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
 					}),
 				),
+				criteria: Type.Optional(
+					Type.Array(
+						Type.String({ minLength: 1, maxLength: MAX_DESCRIPTION_LENGTH }),
+						{
+							minItems: 1,
+							maxItems: MAX_CRITERIA,
+							description:
+								"Optional completion criteria for this loop, each one checkable requirement restated faithfully from the user's objective. Replaces the deterministic split of the objective, so omit it unless that split would misfire.",
+						},
+					),
+				),
 			}),
 			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				// The gate. Everything below is ordinary validation; this is the
@@ -89,6 +114,14 @@ export function registerLoopStartTool(
 				if (!objective) {
 					return refusal("Loop not started: the objective is empty.", {});
 				}
+				const criteria = params.criteria?.map((description) => description.trim());
+				const badCriteria = criteria && describeBadCriteria(criteria);
+				if (badCriteria) {
+					return refusal(
+						`Loop not started: ${badCriteria}. Pass one short checkable requirement per entry, or omit criteria to split the objective deterministically.`,
+						{ objective },
+					);
+				}
 				const existing = controller.state;
 				if (existing && existing.status !== "stopped") {
 					return refusal(
@@ -119,8 +152,9 @@ export function registerLoopStartTool(
 					requestedMs: interval.requestedMs,
 					intervalMs: interval.effectiveMs,
 					clamped: interval.clamped,
-					...(params.max === undefined ? {} : { maxIterations: params.max }),
+					...(params.max === undefined ? {} : { maxTurns: params.max }),
 					...(expiresInMs === undefined ? {} : { expiresInMs }),
+					...(criteria === undefined ? {} : { criteria }),
 					prompt: objective,
 				});
 				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
@@ -136,6 +170,26 @@ export function registerLoopStartTool(
 	);
 }
 
+/**
+ * Why a proposed criteria list cannot be used, or undefined when it can.
+ *
+ * A list that says nothing is worse than no list: it would replace the
+ * deterministic split with a gate the model wrote and can pass by saying
+ * anything. So a malformed list refuses the start rather than falling back
+ * silently, which would leave the model believing its criteria were accepted.
+ */
+function describeBadCriteria(criteria: readonly string[]): string | undefined {
+	if (criteria.length === 0) return "the criteria list is empty";
+	if (criteria.length > MAX_CRITERIA) {
+		return `a loop takes at most ${MAX_CRITERIA} criteria and ${criteria.length} were given`;
+	}
+	if (criteria.some((description) => !description)) return "one of the criteria is blank";
+	if (criteria.some((description) => description.length > MAX_DESCRIPTION_LENGTH)) {
+		return `a criterion may be at most ${MAX_DESCRIPTION_LENGTH} characters`;
+	}
+	return undefined;
+}
+
 function refusal(text: string, details: Record<string, unknown>) {
 	return { content: toolContent(text), details, isError: true };
 }

package/src/state.ts

@@ -30,19 +30,17 @@ export interface LoopState {
 	 */
 	objective?: string;
 	intervalMs: number;
-	/** Delivered-poke cap; null means unlimited. */
-	maxIterations: number | null;
-	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
-	compactAt: number | null;
 	/**
-	 * Turns this loop caused; null means unlimited. Counted separately from
-	 * `maxIterations` because one wake now yields many turns: a settle-driven
-	 * continuation chain runs without any wake at all.
+	 * Cap on the turns this loop causes (continuations plus pokes); null means
+	 * unlimited. The only cap: a settle-driven continuation chain runs without
+	 * any wake at all, so a wake cap bounded nothing this one does not.
 	 */
-	maxAutomaticTurns: number | null;
-	/** Delivered wakes so far (fallback pokes only). */
+	maxTurns: number | null;
+	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
+	compactAt: number | null;
+	/** Delivered wakes so far (fallback pokes only); uncapped, and displayed. */
 	iteration: number;
-	/** Loop-caused turns so far (continuations + pokes). */
+	/** Loop-caused turns so far (continuations + pokes): what `maxTurns` caps. */
 	automaticTurns: number;
 	startedAt: number;
 	expiresAt: number;
@@ -91,8 +89,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	}
 	const intervalMs = record.intervalMs;
 	if (!isPositiveSafeInteger(intervalMs)) return undefined;
-	const maxIterations = record.maxIterations;
-	if (maxIterations !== null && !isPositiveSafeInteger(maxIterations)) return undefined;
+	const maxTurns = readTurnCap(record);
+	if (maxTurns === false) return undefined;
 	const compactAt = record.compactAt;
 	if (
 		compactAt !== null &&
@@ -100,16 +98,12 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	) {
 		return undefined;
 	}
-	const maxAutomaticTurns = Object.hasOwn(record, "maxAutomaticTurns")
-		? record.maxAutomaticTurns
-		: null;
-	if (maxAutomaticTurns !== null && !isPositiveSafeInteger(maxAutomaticTurns)) return undefined;
 	const iteration = record.iteration;
 	if (typeof iteration !== "number" || !Number.isSafeInteger(iteration) || iteration < 0) {
 		return undefined;
 	}
-	// Loops persisted before the two-counter split carry no automaticTurns; an
-	// absent counter restores as zero rather than rejecting the whole state.
+	// A loop persisted before the turn counter existed carries no automaticTurns;
+	// an absent counter restores as zero rather than rejecting the whole state.
 	const automaticTurns = Object.hasOwn(record, "automaticTurns") ? record.automaticTurns : 0;
 	if (
 		typeof automaticTurns !== "number" ||
@@ -147,8 +141,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(prompt === undefined ? {} : { prompt }),
 		...(objective === undefined ? {} : { objective }),
 		intervalMs,
-		maxIterations: maxIterations as number | null,
-		maxAutomaticTurns: maxAutomaticTurns as number | null,
+		maxTurns,
 		compactAt: compactAt as number | null,
 		iteration,
 		automaticTurns,
@@ -164,6 +157,33 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	};
 }
 
+/**
+ * The turn cap, adopting the caps a loop persisted by an older version
+ * carries: `maxAutomaticTurns` (turns) and `maxIterations` (wakes). An
+ * in-flight loop restored mid-upgrade keeps the tighter of them rather than
+ * having its bound widened or being dropped as unparsable; its wake *counter*
+ * is kept for display but no longer caps anything. Returns the cap, or false
+ * when a present value is invalid.
+ */
+function readTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		const value = record.maxTurns;
+		if (value === null) return null;
+		return isPositiveSafeInteger(value) ? value : false;
+	}
+	let adopted: number | null | undefined;
+	for (const key of ["maxAutomaticTurns", "maxIterations"]) {
+		if (!Object.hasOwn(record, key)) continue;
+		const value = record[key];
+		if (value !== null && !isPositiveSafeInteger(value)) return false;
+		const cap = value as number | null;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? null : adopted;
+}
+
 // --- session-branch entry readers ---
 
 interface SessionEntryLike {