@hank-warren/pi-loop 0.6.0 → 0.8.0

package/src/loop.ts

@@ -34,12 +34,20 @@ 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,
 	deriveCriteria,
 	type LedgerPaths,
 	ledgerPaths,
+	type LoopCriterion,
 	readCriteria,
 } from "./ledger.js";
 import {
@@ -75,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";
 
@@ -89,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;
 
@@ -152,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;
@@ -173,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);
@@ -222,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;
@@ -570,14 +631,21 @@ export class LoopController {
 	 * Create (or adopt) the loop's ledger. Best-effort by design: a loop with
 	 * no writable ledger still runs, it just loses the durable record, so the
 	 * failure is warned once and never repeated.
+	 *
+	 * `criteria` is passed at start: the criteria proposed at `loop_start`, or
+	 * the deterministic split of the objective. On restore it is omitted, and
+	 * the criteria already on disk are authoritative — they are the ones the
+	 * user saw echoed, and re-deriving them would both discard a proposed set
+	 * and reset whatever `passes` flips the loop has earned.
 	 */
-	private openLedger(loop: LoopState): void {
+	private openLedger(loop: LoopState, criteria?: LoopCriterion[]): void {
 		if (loop.objective === undefined) {
 			this.ledger = undefined;
 			return;
 		}
 		const paths = ledgerPaths(loop.id, this.agentDir);
-		const failure = createLedger(paths, loop.objective, deriveCriteria(loop.objective));
+		const contents = criteria ?? readCriteria(paths) ?? deriveCriteria(loop.objective);
+		const failure = createLedger(paths, loop.objective, contents);
 		if (failure) {
 			this.ledger = undefined;
 			if (!this.ledgerWarned) {
@@ -735,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;
@@ -757,12 +832,7 @@ export class LoopController {
 				this.transition("stopped", "loop expired (the expiry was reached)");
 				return;
 			case "stop":
-				this.transition(
-					"stopped",
-					decision.reason === "max-automatic-turns"
-						? `the ${loop.maxAutomaticTurns}-automatic-turn cap was reached`
-						: `the ${loop.maxIterations}-iteration cap was reached`,
-				);
+				this.transition("stopped", `the ${loop.maxTurns}-turn cap was reached`);
 				return;
 		}
 	}
@@ -809,9 +879,9 @@ export class LoopController {
 
 	/**
 	 * Send first, then account. Pi can refuse the delivery (a busy or compacting
-	 * session), and an iteration persisted before the send would burn the
-	 * maxIterations cap on a poke that never arrived; on a throw the loop re-arms
-	 * on the same cadence and retries at the next wake.
+	 * session), and a turn persisted before the send would burn the cap on a
+	 * poke that never arrived; on a throw the loop re-arms on the same cadence
+	 * and retries at the next wake.
 	 */
 	private deliverPoke(now: number, reason: "objective-stalled" | "wait-elapsed"): void {
 		const loop = this.state;
@@ -933,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.maxIterations === null ? "∞" : `${loop.maxIterations}`;
-		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.iteration}/${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[] {
@@ -991,8 +1080,8 @@ export class LoopController {
 				? [`Cancelled wait (reported on the next wake): ${loop.cancelledWaitReason}`]
 				: []),
 			`Interval: every ${formatDuration(loop.intervalMs)}`,
-			`Wakes: ${loop.iteration}${loop.maxIterations === null ? " (unlimited)" : ` of ${loop.maxIterations}`}`,
-			`Automatic turns: ${loop.automaticTurns}${loop.maxAutomaticTurns === null ? " (unlimited)" : ` of ${loop.maxAutomaticTurns}`}`,
+			`Loop turns: ${loop.automaticTurns}${loop.maxTurns === null ? " (unlimited)" : ` of ${loop.maxTurns}`}`,
+			`Fallback wakes delivered: ${loop.iteration}`,
 			`Started: ${new Date(loop.startedAt).toLocaleString()}`,
 			`Expires: ${new Date(loop.expiresAt).toLocaleString()}`,
 			`Proactive compaction: ${loop.compactAt === null ? "off" : `at ${Math.round(loop.compactAt * 100)}% of context`}`,
@@ -1019,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
@@ -1039,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 ---
 
 	/**
@@ -1079,9 +1208,7 @@ export class LoopController {
 			status: "active",
 			objective,
 			intervalMs: start.intervalMs,
-			maxIterations:
-				start.maxIterations !== undefined ? start.maxIterations : this.settings.maxIterations,
-			maxAutomaticTurns: this.settings.automaticTurns,
+			maxTurns: start.maxTurns !== undefined ? start.maxTurns : this.settings.maxTurns,
 			compactAt,
 			iteration: 0,
 			automaticTurns: 0,
@@ -1093,7 +1220,10 @@ export class LoopController {
 		this.continuationIntent = undefined;
 		this.noOpStreak = 0;
 		this.ledgerWarned = false;
-		this.openLedger(this.state);
+		this.openLedger(
+			this.state,
+			start.criteria ? criteriaFromDescriptions(start.criteria) : deriveCriteria(objective),
+		);
 		this.persist();
 		this.scheduleTick(start.intervalMs);
 		this.updateWidget();

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,
@@ -154,8 +155,7 @@ export async function showLoopSettings(
 	for (;;) {
 		const s = controller.settings;
 		const items = [
-			`Max wakes: ${s.maxIterations === null ? "Unlimited" : s.maxIterations}`,
-			`Max automatic turns: ${s.automaticTurns === null ? "Unlimited" : s.automaticTurns}`,
+			`Max loop turns: ${s.maxTurns === null ? "Unlimited" : s.maxTurns}`,
 			`No-progress breaker: ${s.noProgressTurns === null ? "Off" : `after ${s.noProgressTurns} repeats`}`,
 			`Max loop duration: ${s.maxLoopDuration}`,
 			`Proactive compaction: ${s.compaction.enabled ? `On at ${Math.round(s.compaction.threshold * 100)}%` : "Off"}`,
@@ -167,14 +167,10 @@ export async function showLoopSettings(
 		if (index === 0) {
 			// Unlimited is a first-class choice, not a magic word typed into a free
 			// text box: it is only reachable by discovery otherwise.
-			const cap = await editCap(ctx, "Max wakes", "no wake cap", s.maxIterations);
+			const cap = await editCap(ctx, "Max loop turns", "no turn cap", s.maxTurns);
 			if (cap === undefined) continue;
-			next.maxIterations = cap === "unlimited" ? null : cap;
+			next.maxTurns = cap === "unlimited" ? null : cap;
 		} else if (index === 1) {
-			const cap = await editCap(ctx, "Max automatic turns", "no turn cap", s.automaticTurns);
-			if (cap === undefined) continue;
-			next.automaticTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 2) {
 			const cap = await editCap(
 				ctx,
 				"No-progress breaker",
@@ -183,7 +179,7 @@ export async function showLoopSettings(
 			);
 			if (cap === undefined) continue;
 			next.noProgressTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 3) {
+		} else if (index === 2) {
 			const value = await ctx.ui.input("Max loop duration (e.g. 7d)", s.maxLoopDuration);
 			if (value === undefined) continue;
 			if (parseDuration(value.trim()) === undefined) {
@@ -191,7 +187,7 @@ export async function showLoopSettings(
 				continue;
 			}
 			next.maxLoopDuration = value.trim();
-		} else if (index === 4) {
+		} else if (index === 3) {
 			if (s.compaction.enabled) next.compaction.enabled = false;
 			else {
 				const value = await ctx.ui.input(
@@ -216,7 +212,7 @@ export async function showLoopSettings(
 }
 
 /**
- * One cap editor for both counters. Unlimited is a first-class choice, not a
+ * One cap editor for every cap. Unlimited is a first-class choice, not a
  * magic word typed into a free text box: it is only reachable by discovery
  * otherwise. The typed word still works, so the /loop --max vocabulary and
  * muscle memory keep working.
@@ -271,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/messages.ts

@@ -15,23 +15,30 @@ import type { LoopState } from "./state.js";
 /** Why the loop is talking: the first turn, an ordinary turn, or after a compaction. */
 export type ContinuationKind = "kickoff" | "continue" | "reanchor";
 
-function formatIteration(loop: LoopState): string {
-	const cap = loop.maxIterations === null ? "unlimited" : `${loop.maxIterations}`;
-	return `${loop.iteration + 1}/${cap}`;
+/**
+ * The wake ordinal, and only the ordinal. It used to read `4/25`, the wake
+ * counter against the delivered-wake cap; that cap is gone, collapsed into
+ * the single loop-turn cap, and pairing a wake number with a turn cap would
+ * have been a number that reads as a budget and is not one. The cap is shown
+ * to the *user*, in the widget and `/loop status`, which is who it is for.
+ */
+function formatWakeOrdinal(loop: LoopState): string {
+	return `${loop.iteration + 1}`;
 }
 
 /**
  * The poke. Deliberately slim: the loop's own objective injection puts the
  * objective and loop-mode rules in the system prompt of every turn, so
  * restating them here would store a duplicate copy on every wake. Only the
- * dynamic per-wake state (iteration, reason) belongs in this tail message.
+ * dynamic per-wake state (the wake ordinal, the reason) belongs in this tail
+ * message.
  */
 export function buildObjectivePoke(
 	loop: LoopState,
 	reason: "objective-stalled" | "wait-elapsed" = "objective-stalled",
 ): string {
 	const lines = [
-		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
+		`Scheduled loop wakeup ${formatWakeOrdinal(loop)} (every ${formatDuration(loop.intervalMs)}).`,
 		reason === "wait-elapsed"
 			? "The wait you asked for has elapsed. Re-check the external state it depended on and continue — the objective and loop-mode rules are in the system prompt."
 			: "The session went idle but the loop objective's completion criteria are not met. Continue working it — the objective and loop-mode rules are in the system prompt.",

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");