@hank-warren/pi-loop 0.7.0 → 0.8.0

package/src/loop.ts

@@ -34,7 +34,13 @@ import {
 	type TickDecision,
 	type TickEnvironment,
 } from "./decide.js";
-import { formatClock, formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import {
+	formatClock,
+	formatDuration,
+	formatElapsed,
+	MAX_INTERVAL_MS,
+	parseDuration,
+} from "./interval.js";
 import {
 	createLedger,
 	criteriaFromDescriptions,
@@ -77,7 +83,17 @@ import {
 	type ResolvedWaitDelay,
 } from "./wait.js";
 import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
-import { clearLoopWidget, updateLoopWidget } from "./widget.js";
+import {
+	buildProposal,
+	type LoopPlanningState,
+	type LoopProposal,
+} from "./planning.js";
+import {
+	clearLoopWidget,
+	loopWidgetLine,
+	type LoopWidgetView,
+	updateLoopWidget,
+} from "./widget.js";
 
 export const LOOP_STATUS_KEY = "loop";
 
@@ -91,6 +107,17 @@ export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
  */
 export const MAX_FALLBACK_BACKOFF = 4;
 
+/**
+ * How long a single run may stay open before the widget calls it blocked.
+ *
+ * Deliberately generous: a long build, a big test suite, or a deep subagent
+ * fan-out are all legitimately busy for a while, and crying blocked on honest
+ * work would train the signal to be ignored. Fifteen minutes with no completed
+ * turn is well past ordinary work and well short of the seven-day expiry that
+ * would otherwise be the first sign anything was wrong.
+ */
+export const STALL_ATTENTION_MS = 900_000;
+
 /** Consecutive loop deliveries that produce no run before the loop pauses. */
 export const MAX_DEAD_DELIVERIES = 3;
 
@@ -154,6 +181,30 @@ export class LoopController {
 	private awaitingRun = false;
 	/** Set when an interrupted turn needs a compaction before the loop continues. */
 	private compactionRequested = false;
+	/**
+	 * When the in-flight run started, or undefined between runs.
+	 *
+	 * A session blocked on a modal prompt — a permission approval, a question,
+	 * anything that waits for a human — is `busy`, and `busy` makes every
+	 * continuation and every fallback tick skip. No turn completes, so the cap
+	 * never trips and the no-progress breaker (which counts turns) never fires.
+	 * Expiry is the only thing left, up to seven days later. The engine cannot
+	 * see the prompt, but it can see that a run has been open far longer than
+	 * work usually takes, which is enough to put an attention state on the
+	 * widget instead of a cheerful next-wake time.
+	 */
+	private busySince: number | undefined;
+	/** How long the current run has been open, once past the stall threshold. */
+	private blockedForMs: number | undefined;
+	/**
+	 * Loop planning: the drafting conversation that precedes a loop.
+	 *
+	 * In-memory on purpose. A draft is a short interactive flow, and persisting
+	 * it would mean a half-written objective could outlive the conversation that
+	 * produced it and be approved later out of context. The loop it becomes is
+	 * persisted; the draft is not.
+	 */
+	planning: LoopPlanningState = { active: false };
 
 	constructor(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 		this.pi = pi;
@@ -175,6 +226,9 @@ export class LoopController {
 		this.noOpStreak = 0;
 		this.deadDeliveries = 0;
 		this.awaitingRun = false;
+		this.busySince = undefined;
+		this.blockedForMs = undefined;
+		this.planning = { active: false };
 		this.sessionCtx = ctx;
 
 		const loaded = readLoopSettings(this.settingsPath);
@@ -224,11 +278,16 @@ export class LoopController {
 		this.sessionCtx = ctx;
 		this.awaitingRun = false;
 		this.deadDeliveries = 0;
+		this.busySince = this.now();
+		this.blockedForMs = undefined;
 	}
 
 	onAgentEnd(ctx: ExtensionContext, messages: readonly unknown[] = []): void {
 		this.sessionCtx = ctx;
 		this.awaitingRun = false;
+		// A completed turn is proof the session was not blocked on a human.
+		this.busySince = undefined;
+		this.blockedForMs = undefined;
 		const origin = this.runOrigin;
 		this.runOrigin = undefined;
 		const loop = this.state;
@@ -744,6 +803,13 @@ export class LoopController {
 					// Busy or compacting: coalesce into one pending wake that
 					// the next agent_settled (or compaction onComplete) delivers.
 					this.wakePending = true;
+					if (decision.reason === "agent-busy") this.noteBusyTick(env.now);
+					// Keep the heartbeat armed while busy. Coalescing is about
+					// deliveries, not about the timer: wakePending is a boolean, so a
+					// further tick cannot produce a second wake. Without re-arming,
+					// the first busy tick would be the last one ever taken, and a
+					// session blocked on a prompt would never be noticed at all.
+					this.armFallback();
 				}
 				this.updateWidget();
 				return;
@@ -937,44 +1003,63 @@ export class LoopController {
 		this.pi.appendEntry(LOOP_STATE_ENTRY_TYPE, { loop: this.state });
 	}
 
-	updateWidget(): void {
-		const ui = this.sessionCtx?.ui;
-		if (!ui) return;
+	/**
+	 * A run has been open past the stall threshold, so the most likely
+	 * explanation is a prompt waiting for a human. Reported, never acted on:
+	 * approving on the user's behalf is exactly the boundary pi-auto-permissions
+	 * exists to hold.
+	 */
+	private noteBusyTick(now: number): void {
+		const since = this.busySince;
+		if (since === undefined) return;
+		const openFor = now - since;
+		this.blockedForMs = openFor >= STALL_ATTENTION_MS ? openFor : undefined;
+	}
+
+	/**
+	 * The view both surfaces render, or undefined when there is nothing to show.
+	 *
+	 * One function feeds the widget and the footer because two hand-rolled
+	 * formatters drifted: the footer handled `loop.waiting` and the widget did
+	 * not, so a loop blocked on CI read as an ordinary scheduled loop above the
+	 * editor while the footer said it was waiting.
+	 */
+	widgetView(): LoopWidgetView | undefined {
 		const loop = this.state;
-		updateLoopWidget(
-			ui,
-			loop ? { loop, wakePending: this.wakePending, nextWakeAt: this.nextWakeAt } : undefined,
-		);
 		if (!loop || loop.status === "stopped") {
-			ui.setStatus(LOOP_STATUS_KEY, undefined);
-			return;
-		}
-		if (loop.status === "paused") {
-			ui.setStatus(
-				LOOP_STATUS_KEY,
-				loop.pauseCause ? `loop paused · ${loop.pauseCause}` : "loop paused",
-			);
-			return;
+			if (!this.planning.active) return undefined;
+			const proposed = this.planning.proposal?.criteria.length;
+			return { kind: "planning", ...(proposed === undefined ? {} : { proposedCriteria: proposed }) };
 		}
-		if (loop.waiting) {
-			ui.setStatus(
-				LOOP_STATUS_KEY,
-				`loop waiting · ${loop.waiting.reason}${
-					loop.waiting.resumeAt ? ` · until ${formatClock(loop.waiting.resumeAt)}` : ""
-				}`,
-			);
-			return;
-		}
-		const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
-		const next = this.wakePending
-			? "next on idle"
-			: this.nextWakeAt
-				? `next ${formatClock(this.nextWakeAt)}`
-				: "next unscheduled";
-		ui.setStatus(
-			LOOP_STATUS_KEY,
-			`loop ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`,
-		);
+		const criteria = this.criteriaProgress();
+		return {
+			kind: "loop",
+			loop,
+			wakePending: this.wakePending,
+			nextWakeAt: this.nextWakeAt,
+			...(criteria ? { criteria } : {}),
+			...(this.blockedForMs === undefined ? {} : { blockedForMs: this.blockedForMs }),
+			now: this.now(),
+		};
+	}
+
+	/**
+	 * Criteria progress for the widget. Re-read rather than cached: this runs on
+	 * discrete state transitions, not per frame, and a stale count right after a
+	 * criterion is marked would undercut the one number the line exists to show.
+	 */
+	private criteriaProgress(): { met: number; total: number } | undefined {
+		const criteria = this.criteria();
+		if (!criteria || criteria.length === 0) return undefined;
+		return { met: criteria.filter((criterion) => criterion.passes).length, total: criteria.length };
+	}
+
+	updateWidget(): void {
+		const ui = this.sessionCtx?.ui;
+		if (!ui) return;
+		const view = this.widgetView();
+		updateLoopWidget(ui, view);
+		ui.setStatus(LOOP_STATUS_KEY, view ? loopWidgetLine(view) : undefined);
 	}
 
 	statusLines(ctx: ExtensionContext): string[] {
@@ -1023,7 +1108,11 @@ export class LoopController {
 			}
 		}
 		if (loop.prompt) lines.push(`Focus: ${loop.prompt}`);
-		if (this.nextWakeAt && loop.status === "active") {
+		// A pending wake is delivered at the next settle, whatever the timer says.
+		// The heartbeat stays armed while the agent is busy so a stalled session is
+		// still noticed, which means nextWakeAt can be set here even though no wake
+		// will fire at that time — claiming it would be a stale clock time.
+		if (this.nextWakeAt && !this.wakePending && loop.status === "active") {
 			lines.push(
 				`Next fallback wake: ${formatClock(this.nextWakeAt)}${
 					this.noOpStreak > 0
@@ -1043,6 +1132,42 @@ export class LoopController {
 		return lines;
 	}
 
+	// --- planning ---
+
+	/**
+	 * Open the drafting conversation. Idempotent: running /loop again while
+	 * planning shows the current draft rather than restarting the flow.
+	 */
+	beginPlanning(): void {
+		this.planning = { active: true };
+		this.updateWidget();
+	}
+
+	/** Record a drafted loop for approval, replacing any previous draft. */
+	propose(
+		objective: string,
+		overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
+	): LoopProposal {
+		const proposal = buildProposal(
+			objective,
+			{
+				intervalMs: parseDuration(this.settings.defaultInterval) ?? 600_000,
+				maxTurns: this.settings.maxTurns,
+				expiresInMs: parseDuration(this.settings.maxLoopDuration) ?? 604_800_000,
+			},
+			this.now(),
+			overrides,
+		);
+		this.planning = { active: true, proposal };
+		this.updateWidget();
+		return proposal;
+	}
+
+	endPlanning(): void {
+		this.planning = { active: false };
+		this.updateWidget();
+	}
+
 	// --- command actions ---
 
 	/**

package/src/manager.ts

@@ -14,6 +14,7 @@ import {
 	saveLoopSettings,
 } from "./settings.js";
 import { parseDuration } from "./interval.js";
+import { renderProposalCard } from "./planning.js";
 
 export async function showLoopManager(
 	controller: LoopController,
@@ -266,3 +267,76 @@ function applySettings(
 	controller.settings = next;
 	return true;
 }
+
+/**
+ * The approval card and its actions.
+ *
+ * This is where a planned loop starts, and the approval is what authorises it.
+ * `loop_start`'s gate exists because a loop is self-continuing and must never
+ * begin on model initiative; an explicit choice here, on a card showing the
+ * objective, the derived criteria, the cadence and the caps, is stronger
+ * evidence of intent than a typed token, so it starts the loop directly rather
+ * than routing back through a tool the model could reach on its own.
+ */
+export async function showLoopApproval(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const proposal = controller.planning.proposal;
+	if (!proposal) return;
+	ctx.ui.notify(renderProposalCard(proposal).join("\n"), "info");
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			"Approve it from a TUI session, or start it directly with /loop <interval> <objective>.",
+			"info",
+		);
+		return;
+	}
+	const choice = await ctx.ui.select("Start this loop?", [
+		"Start loop",
+		"Change cadence",
+		"Keep editing",
+		"Cancel",
+	]);
+	switch (choice) {
+		case "Start loop": {
+			const result = controller.startLoop(ctx, {
+				kind: "start",
+				requestedMs: proposal.intervalMs,
+				intervalMs: proposal.intervalMs,
+				clamped: false,
+				maxTurns: proposal.maxTurns,
+				expiresInMs: proposal.expiresInMs,
+				prompt: proposal.objective,
+			});
+			if (result.ok) controller.endPlanning();
+			else ctx.ui.notify(result.message, "error");
+			return;
+		}
+		case "Change cadence": {
+			const text = await ctx.ui.input(
+				"Fallback heartbeat (e.g. 30m). The loop advances whenever the session settles.",
+				formatDuration(proposal.intervalMs),
+			);
+			if (text === undefined) return;
+			const interval = parseInterval(text.trim());
+			if (!interval) {
+				ctx.ui.notify(`Invalid interval: ${text}. Use <number><unit>, e.g. 30m.`, "error");
+				return;
+			}
+			controller.propose(proposal.objective, {
+				intervalMs: interval.effectiveMs,
+				maxTurns: proposal.maxTurns,
+				expiresInMs: proposal.expiresInMs,
+			});
+			await showLoopApproval(controller, ctx);
+			return;
+		}
+		case "Keep editing":
+			ctx.ui.notify("Still planning. Tell the agent what to change.", "info");
+			return;
+		default:
+			controller.endPlanning();
+			ctx.ui.notify("Loop planning cancelled. Nothing was started.", "info");
+	}
+}

package/src/objective.ts

@@ -44,6 +44,16 @@ export function buildLoopObjectivePrompt(
 		"- Effort exhaustion is not completion. Running long, running out of ideas, or approaching a cap is never a reason to call loop_complete.",
 		"- Call loop_complete with this exact loop_id only when every completion criterion is proven, passing one cited piece of evidence per criterion id. It stops the wakeups; it does not assert that unrelated work is finished.",
 		"- If the criteria are not met, keep working and expect another wake.",
+		// Autonomy. Stated as mechanics rather than as a rule to obey, because the
+		// mechanics are the reason: a blocked session is `busy`, and `busy` makes
+		// every continuation and every fallback tick skip. Nothing enumerates
+		// tools here on purpose — the user's other extensions are unknowable, and
+		// a blacklist would go stale the moment one of them ships a new prompt.
+		"- You are running unattended. A prompt that blocks on a human — a permission approval, a clarifying question, any tool that waits for an answer — does not pause this loop, it deadlocks it: the session stays busy, so no continuation fires, no wake lands, and no cap trips. Nothing ends the loop until it expires. Plan to work without prompting.",
+		"- Decide rather than ask. Take the reversible option, record the decision and the reasoning behind it in the ledger, and keep going. A decision written down is worth more than a question nobody is there to answer.",
+		"- When you genuinely need a human, call loop_wait: it is the only way to ask that does not deadlock the session. Put the options in the ledger first, so the answer can be one word.",
+		"- Never reshape a command to get past a permission prompt. A blocked command means stop and ask through loop_wait, never find another way around it.",
+		"- Prefer the undoable. Nobody is watching to catch a bad call, so when two paths are close, take the one that is cheap to reverse.",
 		...(ledger ? ledgerRules(ledger) : []),
 		`${focus}`,
 	]
@@ -63,8 +73,9 @@ function ledgerRules(ledger: LedgerPaths): string[] {
 	return [
 		"",
 		`Loop ledger (durable state for this loop, at ${ledger.dir}):`,
-		`- ${PROGRESS_FILE} is yours to maintain. Update it as you work, keeping its four sections: current status, completed, failed approaches and why, next actions. Record failures and their reasons — nothing else remembers them once the conversation is compacted.`,
-		`- ${CRITERIA_FILE} holds this loop's completion criteria. You may change only the \`passes\` field of an entry, and only when authoritative evidence proves that criterion, citing the evidence in ${PROGRESS_FILE}. Never edit an id, description, or check, and never add or remove entries.`,
+		`- ${PROGRESS_FILE} is yours to maintain, keeping its four sections: current status, completed, failed approaches and why, next actions. Record failures and their reasons as you go — nothing else remembers them once the conversation is compacted.`,
+		`- Write it with the loop_progress tool and never with the file or shell tools: loop_progress edits one section and leaves every other byte alone, where a whole-file write destroys the objective line and the other three sections along with the one you meant to update.`,
+		`- ${CRITERIA_FILE} holds this loop's completion criteria. Mark one met with loop_progress, which stores the citation next to it; only the \`passes\` field ever changes. Never edit an id, description, or check, never add or remove entries, and never write this file by hand.`,
 		"- After a compaction, re-read both files before acting. They are the record; a summary is not.",
 	];
 }

package/src/planning.ts

@@ -0,0 +1,98 @@
+/**
+ * Loop planning: authoring an objective with the user before any loop exists.
+ *
+ * The criteria are frozen the moment a loop starts, and until now the first
+ * time anyone saw them was after that point. That is the wrong order. The
+ * objective's wording is the single leverage point on a loop's whole life —
+ * it becomes the acceptance gate — and the moment it is decided is a
+ * conversation, not a typed command.
+ *
+ * So `/loop` with nothing running opens a drafting conversation instead of an
+ * error about a missing interval, and the loop starts from an approval card
+ * that shows the exact criteria the split will produce. The card is the design
+ * language: because the cadence and the caps are on it and editable there, the
+ * command grammar does not have to be natural, and none of the
+ * optional-interval, `every`-prefix, adverb or dry-run machinery needs to
+ * exist. A concept removed rather than a knob added.
+ *
+ * The typed form (`/loop 30m <objective>`) is untouched, as is inline `loop:`
+ * invocation. Planning is the front door, not the only door.
+ */
+
+import { deriveCriteria, type LoopCriterion } from "./ledger.js";
+import { formatDuration } from "./interval.js";
+
+/** A drafted loop, put up for approval and not yet started. */
+export interface LoopProposal {
+	objective: string;
+	/** Exactly what `deriveCriteria` will produce, computed here so the card cannot lie. */
+	criteria: LoopCriterion[];
+	intervalMs: number;
+	maxTurns: number | null;
+	expiresInMs: number;
+	proposedAt: number;
+}
+
+export interface LoopPlanningState {
+	/** The user opened planning and no loop has started yet. */
+	active: boolean;
+	/** The current draft awaiting approval, when one has been proposed. */
+	proposal?: LoopProposal;
+}
+
+export function buildProposal(
+	objective: string,
+	defaults: { intervalMs: number; maxTurns: number | null; expiresInMs: number },
+	now: number,
+	overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
+): LoopProposal {
+	return {
+		objective: objective.trim(),
+		// Derived, never authored: the card has to show the criteria the engine
+		// will actually freeze, or approving it means approving something else.
+		criteria: deriveCriteria(objective),
+		intervalMs: overrides.intervalMs ?? defaults.intervalMs,
+		maxTurns: overrides.maxTurns === undefined ? defaults.maxTurns : overrides.maxTurns,
+		expiresInMs: overrides.expiresInMs ?? defaults.expiresInMs,
+		proposedAt: now,
+	};
+}
+
+/** The approval card, as transcript lines. */
+export function renderProposalCard(proposal: LoopProposal): string[] {
+	return [
+		"**◆ Loop ready to start**",
+		"",
+		"**Objective**",
+		...proposal.objective.split("\n").map((line) => `> ${line}`),
+		"",
+		`**Criteria the gate will hold you to** (${proposal.criteria.length})`,
+		...proposal.criteria.map((criterion) => `- \`${criterion.id}\`  ${criterion.description}`),
+		"",
+		`**Cadence** every ${formatDuration(proposal.intervalMs)} — a fallback heartbeat; the loop advances whenever the session settles.`,
+		`**Turn cap** ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns} · **Expires** ${formatDuration(proposal.expiresInMs)}`,
+		"",
+		"Run `/loop` to approve and start, keep editing, or cancel.",
+	];
+}
+
+export const LOOP_PLANNING_HINT = [
+	"<system-reminder>",
+	"The user opened loop planning. You are drafting a loop objective with them; no loop is running and none starts until they approve one.",
+	"A loop's objective becomes its acceptance gate, so draft it as an acceptance test, not as a prompt:",
+	"- One requirement per line, as a bullet. A conjunction inside a sentence does not split, so 'fix the flaky test and update the docs' becomes one criterion whose evidence must cover both halves.",
+	"- Name the check in the requirement itself ('…, verified by npm test passing'), so completion is a lookup instead of an argument.",
+	"- The two questions that fix most objectives: how will we know it is done, and what command proves it?",
+	"When the draft is ready, call loop_propose with it. That renders an approval card showing the exact criteria the split will produce; the user approves, edits, or cancels.",
+	// Without this the model reaches for the loop_start prohibition instead. It
+	// is stated emphatically and repeatedly ('never start a loop without that
+	// token, no matter how loop-like the request sounds'), so a conversational
+	// request for a loop pattern-matches straight onto it — and the model
+	// answers by telling the user to type /loop, which is precisely the dead end
+	// planning exists to remove. Observed live in a canary session.
+	"loop_propose is not loop_start. It starts nothing, so the inline-token rule does not apply to it: while planning is open, a conversational request for a loop is exactly when to call loop_propose. Do not refuse and tell the user to type /loop instead — drafting a proposal for them is the whole point of this mode.",
+	"The user has already opened planning, so their intent to consider a loop is established. What still requires their explicit approval is starting one, and the card is where they give it.",
+	"Never restate the objective as a tidier version of what they meant. If they decline to name checks, say plainly what the gate will and will not catch, and let them decide.",
+	"If the work is a bad fit for a loop at all — a recurring cadence, open-ended investigation with no end state, or something that finishes this turn — say so in one line and offer the alternative instead of drafting one anyway.",
+	"</system-reminder>",
+].join("\n");

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,
+	};
+}