@hank-warren/pi-loop 0.7.0 → 0.9.0

package/src/planning.ts

@@ -0,0 +1,108 @@
+/**
+ * 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;
+	/**
+	 * `proposedAt` of the draft whose card has already been rendered.
+	 *
+	 * The card is an artifact in the transcript, not a status line, so re-running
+	 * `/loop` to reopen the menu must not emit a second copy of the same card.
+	 * A new draft — a reworded objective, a changed cadence — has a new
+	 * `proposedAt` and does get its own card, because it is a different thing to
+	 * approve.
+	 */
+	cardShownAt?: number;
+}
+
+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` for the actions: start here, start in a fresh session, change the cadence, 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/presentation.ts

@@ -0,0 +1,50 @@
+/**
+ * The approval card, as a framed transcript block.
+ *
+ * It used to go out twice and neither copy was a card: `loop_propose`
+ * returned it as tool-result text, and `/loop` re-printed it through
+ * `ctx.ui.notify`. Tool text is rendered as a wall of markdown inside a tool
+ * result, and a toast is a transient line that scrolls away — so the one
+ * artifact the whole planning flow exists to produce was the least legible
+ * thing on the screen, and duplicated.
+ *
+ * A custom-type message with `display: true` is what Pi frames, and
+ * `triggerTurn: false` is what keeps it an artifact rather than a prompt: the
+ * card appears, the model is not asked to respond to it, and the user's
+ * approval remains the only thing that starts a loop. This is exactly how
+ * pi-plan-mode renders a proposed plan (`packages/pi-plan-mode/src/
+ * presentation.ts`), for the same reason.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type LoopProposal, renderProposalCard } from "./planning.js";
+
+export const LOOP_PROPOSAL_MESSAGE_TYPE = "loop-proposal";
+
+/**
+ * Emit the card. Returns false when Pi refused it, in which case the caller
+ * still has a working flow — the menu carries the actions, and the criteria
+ * are on disk the moment the loop starts.
+ */
+export function showLoopProposalCard(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	proposal: LoopProposal,
+): boolean {
+	try {
+		pi.sendMessage(
+			{
+				customType: LOOP_PROPOSAL_MESSAGE_TYPE,
+				content: renderProposalCard(proposal).join("\n"),
+				display: true,
+				details: { criteria: proposal.criteria.length, proposedAt: proposal.proposedAt },
+			},
+			{ triggerTurn: false },
+		);
+		return true;
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Unable to show the loop proposal: ${detail}`, "error");
+		return false;
+	}
+}

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,130 @@
+/**
+ * `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 { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import type { LoopController } from "./loop.js";
+import { showLoopProposalCard } from "./presentation.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);
+				// The card goes to the transcript as a framed block, not back through
+				// this tool result. Returning it here too would render the same
+				// artifact twice, once framed and once as a wall of markdown, and
+				// spend the objective's tokens a second time in the model's own
+				// context for no reader that does not already have it.
+				controller.showProposalCard(ctx);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Approval card rendered: ${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}, waking every ${formatDuration(proposal.intervalMs)}, cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns}, expires in ${formatDuration(proposal.expiresInMs)}. The user starts it from /loop; nothing is running yet.`,
+						},
+					],
+					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/state.ts

@@ -63,6 +63,19 @@ export interface LoopState {
 	 * while it writes its state down; the next settle stops it.
 	 */
 	expiring?: true;
+	/**
+	 * Set on a loop handed to a fresh session and cleared the moment that
+	 * session restores it.
+	 *
+	 * The launching session cannot kick the loop off itself: Pi builds a new
+	 * extension instance for the new session, so the controller that ran the
+	 * approval menu is not the controller that ends up holding the loop —
+	 * observed live, where the loop crossed correctly and then sat idle waiting
+	 * for its first fallback wake. Carrying the intent in the state instead
+	 * means whichever instance restores it does the kickoff, which is true for
+	 * every lifecycle the host might have.
+	 */
+	handoff?: true;
 }
 
 const MAX_PROMPT_LENGTH = 100_000;
@@ -135,6 +148,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	const lastFingerprint = optionalText(record.lastFingerprint);
 	if (lastFingerprint === false) return undefined;
 	if (record.expiring !== undefined && record.expiring !== true) return undefined;
+	if (record.handoff !== undefined && record.handoff !== true) return undefined;
 	return {
 		id,
 		status: status as LoopStatus,
@@ -154,6 +168,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(lastFingerprint === undefined ? {} : { lastFingerprint }),
 		...(pauseCause === undefined ? {} : { pauseCause }),
 		...(record.expiring === true ? { expiring: true as const } : {}),
+		...(record.handoff === true ? { handoff: true as const } : {}),
 	};
 }
 

package/src/widget.ts

@@ -1,15 +1,33 @@
 /**
- * The loop widget: a compact themed line above the editor mirroring the
- * footer status (interval · loop turns/cap · next wake), with the loop focus
+ * The loop widget: one themed line above the editor, with the loop's focus
  * dimmed below it when set.
  *
+ * Two rules shape what goes on that line.
+ *
+ * **Show progress, not consumption.** The line used to lead with the interval
+ * and then report turns against the turn cap. The interval is a fallback
+ * heartbeat — a settle-paced loop can run its whole life without delivering
+ * one — and turns-against-cap is budget burn, which says nothing about how
+ * much of the objective is done. Criteria met over criteria total is the
+ * progress number, and it leads.
+ *
+ * **One surface, one story.** The widget and the footer status render the same
+ * state, so they render it from the same function. They disagreed before:
+ * `setStatus` handled `loop.waiting` and the widget did not, so a loop blocked
+ * on CI showed an ordinary "next 17:53" above the editor while the footer said
+ * it was waiting.
+ *
+ * States are ordered by how much they want a human, because the top of that
+ * order is the whole reason to glance at the line: paused and blocked and
+ * expiring come before the ordinary running line.
+ *
  * Presentation only: every entry point tolerates a host without setWidget
  * (test fixtures, print mode) and swallows render-side failures, because a
  * widget must never interrupt loop state transitions.
  */
 
 import { Text } from "@earendil-works/pi-tui";
-import { formatClock, formatDuration } from "./interval.js";
+import { formatClock, formatElapsed } from "./interval.js";
 import type { LoopState } from "./state.js";
 
 export const LOOP_WIDGET_KEY = "loop";
@@ -21,27 +39,61 @@ interface WidgetTheme {
 
 type WidgetHost = { setWidget?: unknown };
 
-export interface LoopWidgetView {
+/** Criteria progress, absent when the loop has no readable ledger. */
+export interface CriteriaProgress {
+	met: number;
+	total: number;
+}
+
+/** The loop is being drafted with the user and has not started. */
+export interface LoopPlanningView {
+	kind: "planning";
+	/** Criteria in the proposed draft, once one has been put up for approval. */
+	proposedCriteria?: number;
+}
+
+export interface LoopRunningView {
+	kind: "loop";
 	loop: LoopState;
 	/** A wake is held for the next idle boundary. */
 	wakePending: boolean;
 	/** Epoch ms of the next scheduled tick, when armed. */
 	nextWakeAt: number | undefined;
+	criteria?: CriteriaProgress;
+	/**
+	 * How long the session has been busy with no completed turn. Set only past
+	 * the stall threshold, where a blocking prompt is the likely explanation.
+	 */
+	blockedForMs?: number;
+	/** Injected so the elapsed span is deterministic in tests. */
+	now?: number;
 }
 
+export type LoopWidgetView = LoopPlanningView | LoopRunningView;
+
+/** How urgently a line wants a human; picks the colour. */
+type Tone = "normal" | "attention" | "planning";
+
 export function updateLoopWidget(ui: WidgetHost, view: LoopWidgetView | undefined) {
 	const setWidget = resolveSetWidget(ui);
 	if (!setWidget) return;
 	try {
-		if (!view || view.loop.status === "stopped") {
+		if (!view || (view.kind === "loop" && view.loop.status === "stopped")) {
 			setWidget(LOOP_WIDGET_KEY, undefined);
 			return;
 		}
 		setWidget(LOOP_WIDGET_KEY, (_tui: unknown, theme: WidgetTheme) => {
 			const bold = theme.bold ?? identity;
+			const paint = (tone: Tone, text: string) => {
+				if (tone === "normal") return text;
+				return theme.fg?.(tone === "attention" ? "warning" : "accent", text) ?? text;
+			};
 			const dim = (text: string) => theme.fg?.("dim", text) ?? text;
-			const focus = view.loop.prompt ? `\n${dim(`  focus: ${view.loop.prompt}`)}` : "";
-			return new Text(`${bold(loopWidgetLine(view))}${focus}`);
+			const focus =
+				view.kind === "loop" && view.loop.prompt
+					? `\n${dim(`  focus: ${view.loop.prompt}`)}`
+					: "";
+			return new Text(`${paint(widgetTone(view), bold(loopWidgetLine(view)))}${focus}`);
 		});
 	} catch {
 		// Presentation only; a widget failure must never break a loop transition.
@@ -58,18 +110,56 @@ export function clearLoopWidget(ui: WidgetHost) {
 	}
 }
 
-export function loopWidgetLine(view: LoopWidgetView) {
+/** Exported for tests: the tone the line renders in. */
+export function widgetTone(view: LoopWidgetView): Tone {
+	if (view.kind === "planning") return "planning";
 	const loop = view.loop;
-	if (loop.status === "paused") return "⏸ loop paused";
+	if (loop.status === "paused" || loop.expiring || view.blockedForMs !== undefined) {
+		return "attention";
+	}
+	return "normal";
+}
+
+export function loopWidgetLine(view: LoopWidgetView): string {
+	if (view.kind === "planning") {
+		return view.proposedCriteria === undefined
+			? "◆ loop planning · drafting an objective"
+			: `◆ loop planning · ${view.proposedCriteria} criteria proposed · approve to start`;
+	}
+	const loop = view.loop;
+
+	// Ordered by how much the state wants a human. A paused or blocked loop is
+	// not making progress, so reporting progress numbers first would bury the
+	// only fact that matters.
+	if (loop.status === "paused") {
+		return `⏸ loop paused${loop.pauseCause ? ` · ${loop.pauseCause}` : ""}`;
+	}
+	if (loop.expiring) return "⚠ loop expiring · write your state into the ledger";
+	if (view.blockedForMs !== undefined) {
+		// The engine cannot see the prompt itself: it only knows the session has
+		// been busy without completing a turn, which a blocking prompt explains
+		// and ordinary long work also explains. Say which one is being reported.
+		return `⚠ loop blocked · no turn for ${formatElapsed(view.blockedForMs)} · a prompt may be waiting`;
+	}
+	if (loop.waiting) {
+		const until =
+			loop.waiting.resumeAt === undefined
+				? "no deadline"
+				: `until ${formatClock(loop.waiting.resumeAt)}`;
+		return `⏳ loop waiting · ${loop.waiting.reason} · ${until}`;
+	}
+
 	const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
 	const next = view.wakePending
 		? "next on idle"
 		: view.nextWakeAt !== undefined
 			? `next ${formatClock(view.nextWakeAt)}`
 			: "next unscheduled";
-	// The turn counter, not the wake counter: the cap counts turns, so a
-	// progress line against that cap has to count the same thing.
-	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`;
+	const elapsed = formatElapsed((view.now ?? Date.now()) - loop.startedAt);
+	// Progress leads when there is progress to report. Turns are still shown,
+	// but as the budget they are, not as the headline.
+	const progress = view.criteria ? `${view.criteria.met}/${view.criteria.total} done · ` : "";
+	return `⟳ loop ${progress}turn ${loop.automaticTurns}/${cap} · ${elapsed} · ${next}`;
 }
 
 function identity(text: string) {