@hank-warren/pi-loop 0.5.0 → 0.7.0

package/src/decide.ts

@@ -9,17 +9,13 @@
  *   handler for a lost continuation or an external wait, not the pacemaker.
  *
  * Both share one precedence prefix: loop liveness → expiry → plan mode →
- * compaction → busy → mode-specific stop criteria → caps → act.
+ * compaction → busy → wait → the turn cap → act.
  *
- * The mode-specific step is the whole difference between the two kinds of
- * loop. A goal-bound loop delegates "is the work done" to pi-goal and reads
- * its `goal-state`, so a missing goal pauses it and a safety state holds it;
- * pi-goal also owns its settle continuations, so `decideContinuation` never
- * acts for one. A standalone loop owns its own objective, reads no goal state
- * at all, and ends only through `loop_complete`, a cap, or the user.
+ * A loop owns its own objective and reads no other extension's state: it ends
+ * only through `loop_complete`, a cap, an expiry, or the user.
  */
 
-import { GOAL_SAFETY_STATUSES, type GoalSnapshot, isStandaloneLoop, type LoopState } from "./state.js";
+import type { LoopState } from "./state.js";
 
 export interface TickEnvironment {
 	now: number;
@@ -28,7 +24,6 @@ export interface TickEnvironment {
 	/** A loop-owned proactive compaction is in flight; hold pokes. */
 	compacting: boolean;
 	planModeEnabled: boolean;
-	goal: GoalSnapshot | undefined;
 }
 
 /** A `loop_wait` whose deadline has passed is due, not waiting. */
@@ -39,8 +34,8 @@ function isWaiting(loop: LoopState, now: number): boolean {
 }
 
 /**
- * An expiring standalone loop gets one last turn to write its state into the
- * ledger before it stops; every other expiry stops immediately.
+ * An expiring loop gets one last turn to write its state into the ledger
+ * before it stops; a loop already spending that turn stops immediately.
  */
 export type ExpiryReason = "loop-expired" | "expiry-final-wake";
 
@@ -54,36 +49,26 @@ export type TickDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "goal-complete" | "max-iterations" | "max-automatic-turns" }
-	| { action: "pause"; reason: "goal-safety"; cause: string }
-	| { action: "pause"; reason: "goal-missing" }
-	| {
-			action: "poke";
-			reason: "goal-stalled" | "goal-waiting" | "objective-stalled" | "wait-elapsed";
-	  };
+	| { action: "stop"; reason: "max-turns" }
+	| { action: "poke"; reason: "objective-stalled" | "wait-elapsed" };
 
 export type ContinuationDecision =
-	| { action: "none"; reason: "loop-not-active" | "goal-bound" }
+	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "stop"; reason: "max-turns" }
 	| { action: "continue"; reason: "settled-idle" };
 
-/** Shared prefix: everything that holds or ends a loop before mode matters. */
+/** Shared prefix: everything that holds or ends a loop before caps matter. */
 function decideCommonPrefix(
 	loop: LoopState,
 	env: TickEnvironment,
 ): Extract<TickDecision, { action: "none" | "expire" | "skip" }> | undefined {
 	if (loop.status !== "active") return { action: "none", reason: "loop-not-active" };
 	if (env.now >= loop.expiresAt) {
-		// The final wake is a standalone loop's own summarise-and-stop turn; a
-		// goal-bound loop has no ledger of its own to write, and pi-goal owns
-		// that conversation.
-		return {
-			action: "expire",
-			reason:
-				isStandaloneLoop(loop) && !loop.expiring ? "expiry-final-wake" : "loop-expired",
-		};
+		// The final wake is the loop's own summarise-and-stop turn; a loop already
+		// spending it has nothing left to buy.
+		return { action: "expire", reason: loop.expiring ? "loop-expired" : "expiry-final-wake" };
 	}
 	if (env.planModeEnabled) return { action: "skip", reason: "plan-mode-active" };
 	if (env.compacting) return { action: "skip", reason: "compaction-in-flight" };
@@ -95,33 +80,27 @@ function decideCommonPrefix(
 }
 
 /**
- * Caps are checked in a fixed order so a loop that trips both reports the
- * wake cap first — it is the one the user configured with `--max`.
+ * The one cap, counting every turn the loop caused: continuations and pokes
+ * alike. A delivered-wake cap sat next to it until it was collapsed into
+ * this one — in a settle-paced loop the wake counter can stay at zero for the
+ * loop's whole life, so it was never the ceiling that held.
  */
-function decideCaps(
-	loop: LoopState,
-): { action: "stop"; reason: "max-iterations" | "max-automatic-turns" } | undefined {
-	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
-		return { action: "stop", reason: "max-iterations" };
-	}
-	if (loop.maxAutomaticTurns !== null && loop.automaticTurns >= loop.maxAutomaticTurns) {
-		return { action: "stop", reason: "max-automatic-turns" };
+function decideCap(loop: LoopState): { action: "stop"; reason: "max-turns" } | undefined {
+	if (loop.maxTurns !== null && loop.automaticTurns >= loop.maxTurns) {
+		return { action: "stop", reason: "max-turns" };
 	}
 	return undefined;
 }
 
 /**
- * The settled-idle boundary of a standalone loop: the session finished a turn
- * with the objective unfinished, so the loop continues immediately instead of
- * waiting out an interval of idle wall time.
+ * The settled-idle boundary: the session finished a turn with the objective
+ * unfinished, so the loop continues immediately instead of waiting out an
+ * interval of idle wall time.
  */
 export function decideContinuation(loop: LoopState, env: TickEnvironment): ContinuationDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	// pi-goal drives its own settle continuations for a goal-bound loop; two
-	// extensions continuing the same session would double every turn.
-	if (!isStandaloneLoop(loop)) return { action: "none", reason: "goal-bound" };
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
 	return { action: "continue", reason: "settled-idle" };
 }
@@ -129,40 +108,10 @@ export function decideContinuation(loop: LoopState, env: TickEnvironment): Conti
 export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-
-	// A standalone loop carries its own objective, so it never consults
-	// pi-goal: it runs until loop_complete stops it, a cap is reached, or the
-	// user intervenes.
-	if (isStandaloneLoop(loop)) {
-		const capped = decideCaps(loop);
-		if (capped) return capped;
-		// The prefix already let a still-waiting loop skip, so a wait surviving
-		// to here is one whose deadline has come due: this wake is the wake it
-		// asked for, and it counts against the wake cap like any other.
-		return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
-	}
-
-	const goal = env.goal;
-	// Goal-bound loops require a goal to operate: the goal evaluator owns the
-	// stop criterion, so such a loop with no goal has nothing to decide when it
-	// is done.
-	if (!goal) return { action: "pause", reason: "goal-missing" };
-	if (goal.status === "complete") return { action: "stop", reason: "goal-complete" };
-	if ((GOAL_SAFETY_STATUSES as readonly string[]).includes(goal.status)) {
-		return { action: "pause", reason: "goal-safety", cause: goal.status };
-	}
-	if (goal.status !== "active") {
-		// Unknown status from a newer pi-goal: treat like a safety state
-		// rather than poking past a guard we do not understand.
-		return { action: "pause", reason: "goal-safety", cause: goal.status };
-	}
-
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
-
-	// An idle session with an active goal is exactly the stall/wait case:
-	// pi-goal continues on its own at every idle boundary, so idleness at
-	// tick time means its continuation was lost, or the goal is waiting on
-	// an external event — which this wakeup is.
-	return { action: "poke", reason: goal.waiting ? "goal-waiting" : "goal-stalled" };
+	// The prefix already let a still-waiting loop skip, so a wait surviving to
+	// here is one whose deadline has come due: this wake is the wake it asked
+	// for, and the turn it starts counts against the cap like any other.
+	return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
 }

package/src/index.ts

@@ -1,15 +1,17 @@
 /**
- * pi-loop: Claude-Code-/loop-inspired pacemaker for Pi. A loop wakes the
- * session on an interval to keep an active pi-goal goal moving (stall rescue
- * and goal_wait wakes) with loop-aware compaction. Loops require an active
- * goal: the loop owns *when* the session wakes; @narumitw/pi-goal (or the
- * @hank-warren/pi-goal fork) owns *whether the work is done*, read through
- * its `goal-state` session entries only.
+ * pi-loop: Claude-Code-/loop-inspired long-running work for Pi. A loop
+ * carries its own objective and completion criteria, is paced by the session
+ * settling, keeps a durable ledger, compacts itself, and ends through
+ * `loop_complete`, a cap, its expiry, or the user. It depends on no other
+ * extension; the only sibling state it reads is pi-plan-mode's, fail-open, so
+ * a loop never injects into a planning conversation.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
+import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.js";
+import { registerLoopStartTool } from "./start-tool.js";
 import { registerLoopWaitTool } from "./wait-tool.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
 import { showLoopManager, showLoopSettings } from "./manager.js";
@@ -28,12 +30,19 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 	// Registered unconditionally and never toggled with loop state: tools are
 	// part of the cached request prefix, so mutating the tool set mid-session
-	// would invalidate the whole conversation cache. It refuses when no
-	// standalone loop is active.
+	// would invalidate the whole conversation cache. It refuses when no loop is
+	// active.
 	registerLoopCompleteTool(pi, controller);
 	// Registered on the same terms and for the same reason: the tool set is
 	// part of the cached prefix, so it never changes with loop state.
 	registerLoopWaitTool(pi, controller);
+	// Inline invocation: an `input` handler arms a one-turn system-prompt hint
+	// for a mid-prompt `/loop` token, `before_agent_start` appends it, and
+	// loop_start is the model-invoked start it points at — refused on any turn
+	// the hint did not arm. The user's message is never transformed.
+	const invocation = new InlineInvocationState();
+	registerInlineInvocation(pi, controller, invocation);
+	registerLoopStartTool(pi, controller, invocation);
 	// Collapse loop pokes into one-line transcript chips (display-only; the
 	// stored message and model context are untouched).
 	registerLoopMessageRendering(pi);
@@ -84,7 +93,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 							return;
 						}
 					}
-					controller.startLoop(ctx, command);
+					const result = controller.startLoop(ctx, command);
+					if (!result.ok) ctx.ui.notify(result.message, "error");
 					return;
 				}
 			}
@@ -169,8 +179,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		controller.onSessionShutdown();
 		scheduler.onSessionShutdown();
 	});
-	// The pacemaker of a standalone loop: agent_end records the intent to
-	// continue, agent_settled delivers it once Pi will accept a message.
+	// The pacemaker: agent_end records the intent to continue, agent_settled
+	// delivers it once Pi will accept a message.
 	pi.on("agent_start", async (_event, ctx) => {
 		controller.onAgentStart(ctx);
 	});
@@ -181,10 +191,9 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		controller.onAgentSettled(ctx);
 		scheduler.onAgentSettled(ctx);
 	});
-	// A standalone loop carries its own objective, so it injects it the way
-	// pi-goal does for a goal-bound one: a byte-stable system append, which is
-	// what lets the poke messages stay pointer-sized. A goal-bound loop adds
-	// nothing here — pi-goal already owns that turn's append.
+	// A loop carries its own objective and injects it as a byte-stable system
+	// append, which is what lets the poke and continuation messages stay
+	// pointer-sized.
 	pi.on("before_agent_start", (event) => {
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;

package/src/inline-command.ts

@@ -0,0 +1,159 @@
+/**
+ * Inline slash-command detection.
+ *
+ * Pi dispatches extension commands only when a message *starts* with the
+ * command token; a command mentioned mid-prompt arrives as plain text. This
+ * helper finds inline occurrences of a `/cmd` token (and `cmd:` prefix lines)
+ * so the caller can react — here, by appending a reminder that tells the model
+ * to invoke the corresponding tool. It never rewrites or re-sends the user's
+ * message.
+ *
+ * Ported from @hank-warren/pi-goal, which proved the mechanism before pi-loop
+ * absorbed it; the helper was always generic over the command name.
+ */
+
+export interface InlineCommandSplit {
+	/** Text before the command token, trailing whitespace removed. */
+	prose: string;
+	/** Everything after the command token to end of message, trimmed. */
+	commandArgs: string;
+}
+
+/**
+ * Find the first inline `/<commandName>` occurrence in `text`.
+ *
+ * Detection rules:
+ * - The token must be preceded by start-of-line or whitespace and followed by
+ *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
+ *   path-like `foo/cmd` never matches.
+ * - A token at position 0 is ignored: that is Pi's native dispatch position.
+ * - Occurrences inside backtick code (inline spans and fenced blocks) or
+ *   inside a single/double-quoted span are ignored. Code regions are
+ *   approximated by the CommonMark backtick-run rule: a run of N backticks
+ *   opens a region closed by the next run of exactly N backticks.
+ *
+ * Returns undefined when no qualifying occurrence exists.
+ */
+export function extractInlineCommand(
+	text: string,
+	commandName: string,
+): InlineCommandSplit | undefined {
+	const token = `/${commandName}`;
+	const ignored = ignoredRegions(text);
+	let searchFrom = 0;
+	while (searchFrom < text.length) {
+		const index = text.indexOf(token, searchFrom);
+		if (index === -1) return undefined;
+		searchFrom = index + 1;
+		if (index === 0) continue;
+		const before = text[index - 1];
+		if (before !== undefined && !/\s/.test(before)) continue;
+		const afterToken = text[index + token.length];
+		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
+		if (insideRegion(ignored, index)) continue;
+		const commandArgs = text.slice(index + token.length).trim();
+		if (!commandArgs) continue;
+		return {
+			prose: text.slice(0, index).trimEnd(),
+			commandArgs,
+		};
+	}
+	return undefined;
+}
+
+/**
+ * True when the message inline-invokes the command: a mid-message `/cmd`
+ * token with a remainder, or a `cmd:` prefix at the start of any line — both
+ * outside backtick code and quoted spans.
+ */
+export function detectsInlineInvocation(text: string, commandName: string): boolean {
+	if (extractInlineCommand(text, commandName) !== undefined) return true;
+	const ignored = ignoredRegions(text);
+	const prefixPattern = new RegExp(`^[ \\t]*${escapeRegExpText(commandName)}:[ \\t]+\\S`, "gim");
+	for (
+		let match = prefixPattern.exec(text);
+		match;
+		match = prefixPattern.exec(text)
+	) {
+		if (!insideRegion(ignored, match.index)) return true;
+	}
+	return false;
+}
+
+type Region = readonly [start: number, end: number];
+
+/**
+ * Backtick code regions plus single/double-quoted spans. Quoting a command is
+ * how people discuss one (`use "/loop 10m ship it" to start`), so a quoted
+ * token is a mention, not an invocation.
+ */
+function ignoredRegions(text: string): Region[] {
+	return [...codeRegions(text), ...quoteRegions(text)];
+}
+
+function codeRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	const runs: Array<{ index: number; length: number }> = [];
+	const runPattern = /`+/g;
+	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
+		runs.push({ index: match.index, length: match[0].length });
+	}
+	for (let open = 0; open < runs.length; open += 1) {
+		const opener = runs[open];
+		if (opener === undefined) continue;
+		for (let close = open + 1; close < runs.length; close += 1) {
+			const closer = runs[close];
+			if (closer === undefined || closer.length !== opener.length) continue;
+			regions.push([opener.index, closer.index + closer.length]);
+			open = close;
+			break;
+		}
+	}
+	return regions;
+}
+
+/**
+ * Single- and double-quoted spans, matched conservatively so an apostrophe
+ * inside a word (`don't`) never opens one: an opening quote follows nothing,
+ * whitespace, or an opening bracket and precedes a non-space; its closing
+ * quote is on the same line, follows a non-space, and precedes end-of-line,
+ * whitespace, or closing punctuation.
+ */
+function quoteRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	for (let index = 0; index < text.length; index += 1) {
+		const quote = text[index];
+		if (quote !== '"' && quote !== "'") continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before !== undefined && !/[\s([{<]/.test(before)) continue;
+		if (after === undefined || /\s/.test(after)) continue;
+		const close = closingQuoteIndex(text, index, quote);
+		if (close === undefined) continue;
+		regions.push([index, close + 1]);
+		index = close;
+	}
+	return regions;
+}
+
+function closingQuoteIndex(text: string, openIndex: number, quote: string): number | undefined {
+	for (let index = openIndex + 1; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === "\n") return undefined;
+		if (char !== quote) continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before === undefined || /\s/.test(before)) continue;
+		if (after !== undefined && !/[\s.,;:!?)\]}>]/.test(after)) continue;
+		return index;
+	}
+	return undefined;
+}
+
+function insideRegion(regions: readonly Region[], index: number): boolean {
+	return regions.some(([start, end]) => index >= start && index < end);
+}
+
+function escapeRegExpText(value: string) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/inline-invocation.ts

@@ -0,0 +1,109 @@
+/**
+ * Inline `/loop` invocation, tool-mediated.
+ *
+ * Pi only dispatches `/loop` when it starts the message. When the user writes
+ * `quick check /loop 10m get CI green` or a `loop:` prefixed line mid-prompt,
+ * this module appends a one-turn reminder to the system prompt so the model
+ * reliably calls the `loop_start` tool with the objective. The user's message
+ * itself is never touched — no cutting, splitting, re-sending, or visible
+ * annotation — so there are no delivery races, no message loss, and no
+ * transcript noise: guidance is injected at agent-start time, not by
+ * rewriting input.
+ *
+ * Two hooks cooperate because neither alone is safe:
+ * - `input` carries a `source` and so can tell user-typed text from
+ *   extension-sent prompts, but any transform it returns rewrites the stored,
+ *   visible user message. It only records the armed text here.
+ * - `before_agent_start` can extend the system prompt, but fires for
+ *   extension-sent prompts too, and pi-loop's own kickoff and continuation
+ *   prompts contain phrases like "the active /loop objective" that the
+ *   detector would match. It injects only when the starting prompt *is* the
+ *   armed user message, and disarms on every start, matched or not.
+ *
+ * Two deliberate limits keep the armed window one turn wide:
+ * - Streaming-typed input (`streamingBehavior` set, i.e. steered or queued)
+ *   never arms. Pi returns from `prompt()` before `before_agent_start` for
+ *   those, so an armed flag would survive to a later, unrelated turn — the
+ *   window through which pi-loop's own continuation prompts could be matched.
+ * - The hint is a per-turn `systemPrompt` append, not a stored message, so
+ *   "call loop_start now" cannot linger in the conversation and fire on a
+ *   later turn.
+ *
+ * The armed flag is also the `loop_start` tool's gate: unlike pi-goal, which
+ * relied on prompt guidelines alone, a loop is self-continuing, so this
+ * extension *enforces* that the tool only runs on a turn the user explicitly
+ * invoked. See `InlineInvocationState.invokedThisTurn`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { detectsInlineInvocation } from "./inline-command.js";
+import type { LoopController } from "./loop.js";
+
+export const INLINE_LOOP_COMMAND = "loop";
+
+export const INLINE_LOOP_HINT =
+	"<system-reminder>The user's message this turn inline-invoked a loop (/loop or loop:). Call the loop_start tool now with the objective text that follows the token in that message, then begin working toward it. Do not answer the objective as prose without starting the loop. If the message is discussing, quoting, or documenting the /loop command rather than invoking it, do not call loop_start. This reminder applies only to the user's message this turn.</system-reminder>";
+
+/**
+ * The armed state, shared between the hooks and the `loop_start` tool.
+ *
+ * `invokedThisTurn` is the hard gate: set when `before_agent_start` matched
+ * the armed user message, cleared at `agent_end` and at every session
+ * boundary. `loop_start` refuses whenever it is false, so no amount of prompt
+ * drift, transcript replay, or model initiative can start a self-continuing
+ * loop the user did not ask for.
+ */
+export class InlineInvocationState {
+	invokedThisTurn = false;
+}
+
+export function registerInlineInvocation(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	state: InlineInvocationState,
+) {
+	let armedText: string | undefined;
+
+	pi.on("input", (event) => {
+		// Extension-sourced messages (loop kickoffs, continuations, pokes, other
+		// extensions' injections) never arm the hint.
+		if (event.source === "extension") return;
+		// Steered or queued input returns from prompt() without ever reaching
+		// before_agent_start, so arming it would leave stale text armed.
+		if (event.streamingBehavior !== undefined) return;
+		if (!controller.settings.inlineInvocation) return;
+		if (!detectsInlineInvocation(event.text, INLINE_LOOP_COMMAND)) return;
+		armedText = event.text;
+	});
+
+	pi.on("before_agent_start", (event) => {
+		const armed = armedText;
+		armedText = undefined;
+		// Every start closes the previous turn's window, so a turn that ends
+		// without an agent_end still cannot leave the tool unlocked.
+		state.invokedThisTurn = false;
+		if (armed === undefined) return;
+		if (!controller.settings.inlineInvocation) return;
+		if (!promptCarriesArmedMessage(event.prompt, armed)) return;
+		state.invokedThisTurn = true;
+		return { systemPrompt: `${event.systemPrompt}\n\n${INLINE_LOOP_HINT}` };
+	});
+
+	const disarm = () => {
+		armedText = undefined;
+		state.invokedThisTurn = false;
+	};
+	pi.on("agent_end", disarm);
+	pi.on("session_start", disarm);
+	pi.on("session_shutdown", disarm);
+}
+
+/**
+ * True when the starting prompt is the armed user message. Pi may wrap the
+ * text with expanded prefixes or suffixes, so the armed text has to be the
+ * whole prompt or one of its ends — mirroring how upstream recognises its own
+ * owned prompts at a terminal boundary.
+ */
+function promptCarriesArmedMessage(prompt: string, armed: string) {
+	return prompt === armed || prompt.startsWith(armed) || prompt.endsWith(armed);
+}

package/src/ledger.ts

@@ -30,9 +30,9 @@ export const LEDGER_DIR_NAME = "loop";
 export const CRITERIA_FILE = "criteria.json";
 export const PROGRESS_FILE = "PROGRESS.md";
 
-/** Cap on derived criteria: an objective is a paragraph, not a backlog. */
-const MAX_CRITERIA = 12;
-const MAX_DESCRIPTION_LENGTH = 500;
+/** Cap on a loop's criteria: an objective is a paragraph, not a backlog. */
+export const MAX_CRITERIA = 12;
+export const MAX_DESCRIPTION_LENGTH = 500;
 
 export interface LoopCriterion {
 	id: string;
@@ -69,7 +69,20 @@ export function deriveCriteria(objective: string): LoopCriterion[] {
 		.filter(Boolean);
 	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
 	if (parts.length < 2) return [implicitCriterion(trimmed)];
-	return parts.slice(0, MAX_CRITERIA).map((description, index) => ({
+	return criteriaFromDescriptions(parts);
+}
+
+/**
+ * Number a list of descriptions into criteria.
+ *
+ * Shared by the deterministic split and by the criteria a model may propose
+ * at `loop_start`, so nothing downstream — the echo at start, the evidence
+ * gate, the immutability rule — can tell the two apart. The extension still
+ * writes every field but the description: ids are positional, `check` is
+ * empty (audit against authoritative state), and a criterion starts unmet.
+ */
+export function criteriaFromDescriptions(descriptions: readonly string[]): LoopCriterion[] {
+	return descriptions.slice(0, MAX_CRITERIA).map((description, index) => ({
 		id: `c${index + 1}`,
 		description: truncate(description),
 		check: "",