@hank-warren/pi-loop 0.9.0 → 1.0.0

package/src/loop-manager-menu.ts

@@ -0,0 +1,191 @@
+/**
+ * The manager: every lifecycle control a running loop has.
+ *
+ * Pause, resume, stop, status, focus and cadence used to be typed
+ * subcommands (`/loop pause`, `/loop status`, …). They are here instead,
+ * because a lifecycle control nobody can discover is a control nobody uses,
+ * and because the loop is the kind of thing you reach for when you want to
+ * *look* at it — at which point a menu that shows the state and offers the
+ * actions beats remembering six words.
+ *
+ * Pause and Resume are mutually exclusive by construction: the screen is
+ * built from the loop's status, so a paused loop never offers Pause and an
+ * active one never offers Resume. Pinned in the tests, because an item that
+ * silently does nothing is the failure mode a menu invites.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ActionsScreen, DetailScreen, InputScreen } from "@narumitw/pi-tui-kit";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+
+export type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
+export type LoopManagerAction =
+	| "pause"
+	| "resume"
+	| "stop"
+	| "settings"
+	| "set-focus"
+	| "set-cadence";
+
+/** What the manager renders: the loop as the menu needs to see it. */
+export interface LoopManagerView {
+	/** `stopped` never reaches here; the menu only exists for a live loop. */
+	status: "active" | "paused";
+	/** The widget line, so the manager and the footer tell the same story. */
+	headline: string;
+	/** Full status detail, one line each. */
+	statusLines: readonly string[];
+	/** The loop's recurring focus, when it has one. */
+	focus?: string;
+	/** The current fallback heartbeat, formatted. */
+	interval: string;
+}
+
+export function loopManagerScreen(
+	view: LoopManagerView,
+): ActionsScreen<LoopManagerScreen, LoopManagerAction> {
+	return {
+		kind: "actions",
+		title: `Loop · ${view.status}`,
+		lines: [view.headline],
+		items: [
+			{ id: "status", label: "Status", description: "The loop's full state.", to: "status" },
+			...(view.status === "active"
+				? ([
+						{
+							id: "pause",
+							label: "Pause",
+							description: "Stop continuing and waking. The loop keeps its state.",
+							action: "pause" as const,
+						},
+					] as const)
+				: ([
+						{
+							id: "resume",
+							label: "Resume",
+							description: "Continue the objective now, and re-arm the heartbeat.",
+							action: "resume" as const,
+						},
+					] as const)),
+			{
+				id: "focus",
+				label: "Edit focus…",
+				description: "A recurring note restated on every loop message.",
+				to: "focus",
+			},
+			{
+				id: "cadence",
+				label: "Edit cadence…",
+				description: `Fallback heartbeat, currently every ${view.interval}.`,
+				to: "cadence",
+			},
+			{
+				id: "stop",
+				label: "Stop",
+				description: "End the loop. The ledger stays on disk.",
+				action: "stop",
+			},
+			{ id: "settings", label: "Settings", action: "settings" },
+		],
+		hint: "close",
+	};
+}
+
+export function loopStatusScreen(view: LoopManagerView): DetailScreen {
+	return {
+		kind: "detail",
+		title: "Loop status",
+		lines: [...view.statusLines],
+		hint: "back",
+	};
+}
+
+export function loopFocusScreen(view: LoopManagerView): InputScreen<LoopManagerAction> {
+	return {
+		kind: "input",
+		title: "Loop focus",
+		lines: [
+			view.focus ? `Currently: ${view.focus}` : "No focus set.",
+			"Restated on every loop message. Leave empty to clear it.",
+		],
+		placeholder: view.focus ?? "e.g. keep the diff small and reversible",
+		action: "set-focus",
+		hint: "back",
+	};
+}
+
+export function loopCadenceScreen(view: LoopManagerView): InputScreen<LoopManagerAction> {
+	return {
+		kind: "input",
+		title: "Fallback heartbeat",
+		lines: [
+			`Currently every ${view.interval}.`,
+			"The loop advances whenever the session settles; this only fires when it has gone quiet.",
+		],
+		placeholder: view.interval,
+		action: "set-cadence",
+		hint: "back",
+	};
+}
+
+export interface LoopManagerMenuOptions {
+	getView(): LoopManagerView | undefined;
+	signal?: AbortSignal;
+	isCurrent?(): boolean;
+	pause(): void;
+	resume(): void;
+	stop(): void;
+	settings(signal: AbortSignal): Promise<void>;
+	/** Returns false when the value was rejected, so the input screen stays open. */
+	setFocus(value: string): boolean;
+	setCadence(value: string): boolean;
+}
+
+export async function showLoopManagerMenu(ctx: ExtensionContext, options: LoopManagerMenuOptions) {
+	const first = options.getView();
+	if (!first) return;
+	// The view is re-read on every render: a pause taken from this menu has to
+	// turn the Pause item into Resume without closing and reopening it.
+	const view = () => options.getView() ?? first;
+	const menu = defineMenu<
+		LoopManagerView,
+		LoopManagerScreen,
+		LoopManagerAction,
+		ExtensionContext
+	>({
+		start: "main",
+		screens: {
+			main: ({ state }) => loopManagerScreen(state),
+			status: ({ state }) => loopStatusScreen(state),
+			focus: ({ state }) => loopFocusScreen(state),
+			cadence: ({ state }) => loopCadenceScreen(state),
+		},
+		actions: {
+			pause: async () => {
+				options.pause();
+				return { kind: "stay" };
+			},
+			resume: async () => {
+				options.resume();
+				return { kind: "stay" };
+			},
+			stop: async () => {
+				options.stop();
+				return { kind: "close" };
+			},
+			settings: async ({ signal }) => {
+				await options.settings(signal);
+				return { kind: "stay" };
+			},
+			"set-focus": async ({ value }) =>
+				options.setFocus(value ?? "") ? { kind: "to", screen: "main" } : { kind: "rejected" },
+			"set-cadence": async ({ value }) =>
+				options.setCadence(value ?? "") ? { kind: "to", screen: "main" } : { kind: "rejected" },
+		},
+	});
+	return runMenu(ctx, menu, {
+		getState: view,
+		...(options.signal ? { signal: options.signal } : {}),
+		...(options.isCurrent ? { isCurrent: options.isCurrent } : {}),
+	});
+}

package/src/loop.ts

@@ -89,6 +89,8 @@ import {
 	buildProposal,
 	type LoopPlanningState,
 	type LoopProposal,
+	type LoopProposalOverrides,
+	normalizeGroundRules,
 } from "./planning.js";
 import {
 	clearLoopWidget,
@@ -130,10 +132,9 @@ type RunOrigin = "continuation" | "fallback";
  * The outcome of a start attempt.
  *
  * `startLoop` used to report its refusals by calling `ctx.ui.notify` itself,
- * which tied the only start path to a UI. Two callers now share that path —
- * the `/loop` command and the `loop_start` tool — and the tool has to turn
- * the same refusal into tool content rather than a toast, so the decision is
- * returned and each caller renders it.
+ * which tied the only start path to a UI. The approval card's two start
+ * actions share that path — one installs the loop here, the other hands it to
+ * a fresh session — so the decision is returned and each caller renders it.
  */
 export type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
 
@@ -293,7 +294,7 @@ export class LoopController {
 		this.state = rest;
 		this.persist();
 		ctx.ui.notify(
-			"Loop started in this session: only the objective crossed over, not the planning conversation. It works from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop.",
+			"Loop started in this session: only the objective crossed over, not the planning conversation. It works from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you stop it from the /loop menu.",
 			"info",
 		);
 		this.sendKickoffAnchor(ctx);
@@ -371,14 +372,14 @@ export class LoopController {
 			case "usage-limited":
 				this.transition(
 					"paused",
-					"the provider reports the usage limit is reached; resume with /loop resume once it resets",
+					"the provider reports the usage limit is reached; resume it from the /loop menu once it resets",
 					"usage limit reached",
 				);
 				return true;
 			case "fatal":
 				this.transition(
 					"paused",
-					"the turn failed with an error a retry cannot fix; resolve it, then /loop resume",
+					"the turn failed with an error a retry cannot fix; resolve it, then resume it from the /loop menu",
 					"unrecoverable provider error",
 				);
 				return true;
@@ -386,7 +387,7 @@ export class LoopController {
 				// Esc, or another extension stopping the turn. A loop-caused run
 				// that the user interrupted must not be immediately re-sent.
 				if (origin === undefined) return false;
-				this.transition("paused", "the turn was interrupted; resume with /loop resume", "interrupted");
+				this.transition("paused", "the turn was interrupted; resume it from the /loop menu", "interrupted");
 				return true;
 			case "context-overflow":
 				// The request no longer fits: compact first, then continue. The
@@ -408,7 +409,7 @@ export class LoopController {
 	 * The no-progress breaker: consecutive tool-free loop turns with identical
 	 * visible output pause the loop instead of waking it again forever. It
 	 * pauses rather than stops, so the loop stays configured and one
-	 * `/loop resume` (or the next user prompt) puts it back to work.
+	 * Resuming from the /loop menu (or the next user prompt) puts it back to work.
 	 */
 	private enforceNoProgress(
 		ctx: ExtensionContext,
@@ -451,7 +452,7 @@ export class LoopController {
 		void ctx;
 		this.transition(
 			"paused",
-			`${next.toolFreeRepeatCount} loop turns in a row produced the same answer and called no tools; the loop is still configured, so /loop resume (or your next message) continues it`,
+			`${next.toolFreeRepeatCount} loop turns in a row produced the same answer and called no tools; the loop is still configured, so resuming from the /loop menu (or your next message) continues it`,
 			"no progress",
 		);
 		return true;
@@ -534,7 +535,7 @@ export class LoopController {
 		if (!objective) {
 			this.transition(
 				"paused",
-				"it was bound to a goal that is gone and has no objective of its own; start a new loop with /loop <interval> <objective>",
+				"it was bound to a goal that is gone and has no objective of its own; run /loop to plan and approve a new one",
 				"loop with no objective",
 			);
 			return true;
@@ -564,7 +565,7 @@ export class LoopController {
 		if (this.completeToolAvailable()) return false;
 		this.transition(
 			"paused",
-			`the ${LOOP_COMPLETE_TOOL} tool is not available in this session, so the loop could never end itself; re-enable it, then /loop resume`,
+			`the ${LOOP_COMPLETE_TOOL} tool is not available in this session, so the loop could never end itself; re-enable it, then resume the loop from the /loop menu`,
 			"loop_complete unavailable",
 		);
 		void ctx;
@@ -598,7 +599,7 @@ export class LoopController {
 		if (this.deadDeliveries < MAX_DEAD_DELIVERIES) return false;
 		this.transition(
 			"paused",
-			`${this.deadDeliveries} loop messages in a row produced no turn at all, so something is refusing every request; fix it, then /loop resume`,
+			`${this.deadDeliveries} loop messages in a row produced no turn at all, so something is refusing every request; fix it, then resume the loop from the /loop menu`,
 			"deliveries produce no turns",
 		);
 		return true;
@@ -679,7 +680,7 @@ export class LoopController {
 	 * 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
+	 * `criteria` is passed at start: the criteria approved with the draft, 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
@@ -817,7 +818,7 @@ export class LoopController {
 			// Nothing is scheduled once the timer has fired. `runTick` re-arms it
 			// through `scheduleTick` when it pokes, but a busy or compacting
 			// session coalesces into `wakePending` instead — and leaving the old
-			// deadline here made `/loop status` report a clock time that had
+			// deadline here made the /loop status screen report a clock time that had
 			// already passed.
 			this.nextWakeAt = undefined;
 			const ctx = this.sessionCtx;
@@ -1128,7 +1129,7 @@ export class LoopController {
 
 	statusLines(ctx: ExtensionContext): string[] {
 		const loop = this.state;
-		if (!loop) return ["No loop in this session. Start one with /loop <interval> [prompt]."];
+		if (!loop) return ["No loop in this session. Run /loop to plan one."];
 		const lines = [
 			`Status: ${loop.status}${loop.pauseCause ? ` (${loop.pauseCause})` : ""}`,
 			...(loop.waiting
@@ -1208,10 +1209,7 @@ export class LoopController {
 	}
 
 	/** Record a drafted loop for approval, replacing any previous draft. */
-	propose(
-		objective: string,
-		overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
-	): LoopProposal {
+	propose(objective: string, overrides: LoopProposalOverrides = {}): LoopProposal {
 		const proposal = buildProposal(
 			objective,
 			{
@@ -1287,7 +1285,7 @@ export class LoopController {
 			return {
 				ok: false,
 				message:
-					"A loop needs something to work on. Give it an objective: /loop <interval> <objective with completion criteria>.",
+					"A loop needs something to work on. Run /loop and draft an objective with completion criteria first.",
 			};
 		}
 		// A loop with no way to call loop_complete would work, finish, and then be
@@ -1307,10 +1305,12 @@ export class LoopController {
 				: this.settings.compaction.enabled
 					? this.settings.compaction.threshold
 					: null;
+		const groundRules = normalizeGroundRules(start.groundRules);
 		const loop: LoopState = {
 			id: randomUUID().slice(0, 8),
 			status: "active",
 			objective,
+			...(groundRules ? { groundRules } : {}),
 			intervalMs: start.intervalMs,
 			maxTurns: start.maxTurns !== undefined ? start.maxTurns : this.settings.maxTurns,
 			compactAt,
@@ -1356,7 +1356,7 @@ export class LoopController {
 			? ` (requested ${formatDuration(built.requestedMs)}, clamped to the ${formatDuration(started.intervalMs)} minimum)`
 			: "";
 		ctx.ui.notify(
-			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you run /loop stop. Fallback wake every ${formatDuration(started.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(built.expiryMs)} (one final turn to write its state down, then it stops).`,
+			`Loop started: working its objective from now, continuing at every idle boundary until the criteria are met (loop_complete), a cap is reached, or you stop it from the /loop menu. Fallback wake every ${formatDuration(started.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(built.expiryMs)} (one final turn to write its state down, then it stops).`,
 			"info",
 		);
 		if (this.ledger) {

package/src/manager.ts

@@ -1,10 +1,16 @@
 /**
- * Bare-/loop manager and /loop settings, built on Pi's native dialog
- * primitives (ui.select / ui.input / ui.confirm). Non-TUI modes get status
- * notifications instead of menus.
+ * The `/loop` surfaces, wired to the controller: the manager for a live loop,
+ * the approval card's actions, and the settings editor.
+ *
+ * The top-level menus are tui-kit screens (see `loop-manager-menu.ts` and
+ * `loop-launch-menu.ts`), so the family renders the same way pi-plan-mode
+ * does. The settings editor keeps its `ui.select`/`ui.input` internals: it is
+ * a value editor, not a navigation surface, and rewriting it would change
+ * nothing a user can see. Non-TUI modes get status notifications instead of
+ * menus, exactly as before.
  */
 
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { formatDuration, parseInterval } from "./interval.js";
 import type { LoopController } from "./loop.js";
 import {
@@ -17,134 +23,141 @@ import { parseDuration } from "./interval.js";
 import type { LoopStartArguments } from "./command.js";
 import { startLoopInFreshSession } from "./fresh-launch.js";
 import { showLoopApprovalMenu } from "./loop-action-menus.js";
+import { type LoopManagerView, showLoopManagerMenu } from "./loop-manager-menu.js";
+import { showLoopLaunchMenu, showLoopPlanningMenu } from "./loop-launch-menu.js";
 import type { LoopProposal } from "./planning.js";
+import { loopWidgetLine } from "./widget.js";
 
-export async function showLoopManager(
+/** The launch menu: no loop, no draft, nothing planning. */
+export async function showLoopLaunch(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
+	startPlanning: () => void,
 ): Promise<void> {
 	if (ctx.mode !== "tui") {
-		notifyStatus(controller, ctx);
+		ctx.ui.notify(
+			"No loop in this session. The interactive /loop menu is unavailable in print and JSON modes.",
+			"info",
+		);
 		return;
 	}
-	for (;;) {
-		const loop = controller.state;
-		const options: string[] = ["Status"];
-		if (loop?.status === "active") options.push("Pause", "Edit focus", "Edit interval", "Stop");
-		else if (loop?.status === "paused") options.push("Resume", "Edit focus", "Edit interval", "Stop");
-		else options.push("Start a loop…");
-		options.push("Settings");
-		const choice = await ctx.ui.select(`Pi Loop${loop ? ` · ${loop.status}` : ""}`, options);
-		if (choice === undefined) return;
-		switch (choice) {
-			case "Status":
-				notifyStatus(controller, ctx);
-				break;
-			case "Pause":
-				controller.pauseLoop(ctx);
-				break;
-			case "Resume":
-				controller.resumeLoop(ctx);
-				break;
-			case "Stop":
-				controller.stopLoop(ctx);
-				break;
-			case "Start a loop…":
-				await startFromMenu(controller, ctx);
-				break;
-			case "Edit focus":
-				await editPrompt(controller, ctx);
-				break;
-			case "Edit interval":
-				await editInterval(controller, ctx);
-				break;
-			case "Settings":
-				await showLoopSettings(controller, ctx);
-				break;
-			default:
-				return;
-		}
-	}
-}
-
-function notifyStatus(controller: LoopController, ctx: ExtensionCommandContext): void {
-	ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+	await showLoopLaunchMenu(ctx, {
+		startPlanning,
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+	});
 }
 
-async function startFromMenu(
+/** The planning menu: a drafting conversation is open with no draft yet. */
+export async function showLoopPlanning(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
+	options: { requestProposal: () => void },
 ): Promise<void> {
-	const intervalText = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", "5m");
-	if (intervalText === undefined) return;
-	const interval = parseInterval(intervalText.trim() || "5m");
-	if (!interval) {
-		ctx.ui.notify(`Invalid interval: ${intervalText}. Use <number><unit>, e.g. 5m.`, "error");
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(
+			"Loop planning is open: describe the objective, and the agent will put a loop up for approval.",
+			"info",
+		);
 		return;
 	}
-	// The loop owns its objective, so the text is required — asking for it here
-	// is what replaces the old dead-end refusal.
-	const promptText = await ctx.ui.input(
-		"Objective, including how the loop knows it is done",
-		"e.g. get CI green on main, verified by a passing run",
-	);
-	if (promptText === undefined) return;
-	const prompt = promptText.trim();
-	if (!prompt) {
-		ctx.ui.notify("A loop needs an objective, so no loop was started.", "warning");
+	await showLoopPlanningMenu(ctx, {
+		requestProposal: options.requestProposal,
+		cancelPlanning: () => {
+			controller.endPlanning();
+			ctx.ui.notify("Loop planning cancelled. Nothing was started.", "info");
+		},
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+	});
+}
+
+export async function showLoopManager(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		notifyStatus(controller, ctx);
 		return;
 	}
-	const result = controller.startLoop(ctx, {
-		kind: "start",
-		requestedMs: interval.requestedMs,
-		intervalMs: interval.effectiveMs,
-		clamped: interval.clamped,
-		...(prompt ? { prompt } : {}),
+	await showLoopManagerMenu(ctx, {
+		getView: () => managerView(controller, ctx),
+		pause: () => controller.pauseLoop(ctx),
+		resume: () => controller.resumeLoop(ctx),
+		stop: () => controller.stopLoop(ctx),
+		settings: async () => {
+			await showLoopSettings(controller, ctx);
+		},
+		setFocus: (value) => setFocus(controller, ctx, value),
+		setCadence: (value) => setCadence(controller, ctx, value),
 	});
-	if (!result.ok) ctx.ui.notify(result.message, "error");
 }
 
-async function editPrompt(controller: LoopController, ctx: ExtensionCommandContext): Promise<void> {
+/** The live loop as the manager needs it, or undefined once it has stopped. */
+function managerView(
+	controller: LoopController,
+	ctx: ExtensionContext,
+): LoopManagerView | undefined {
 	const loop = controller.state;
-	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input(
-		"Loop focus (optional, restated on every loop message)",
-		loop.prompt ?? "",
-	);
-	if (next === undefined) return;
-	const prompt = next.trim();
+	if (!loop || loop.status === "stopped") return undefined;
+	const view = controller.widgetView();
+	return {
+		status: loop.status,
+		headline: view ? loopWidgetLine(view) : `loop ${loop.status}`,
+		statusLines: controller.statusLines(ctx),
+		...(loop.prompt ? { focus: loop.prompt } : {}),
+		interval: formatDuration(loop.intervalMs),
+	};
+}
+
+function notifyStatus(controller: LoopController, ctx: ExtensionCommandContext): void {
+	ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+}
+
+/** An empty value clears the focus; anything else replaces it. */
+function setFocus(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	value: string,
+): boolean {
+	const loop = controller.state;
+	if (!loop || loop.status === "stopped") return false;
+	const prompt = value.trim();
 	if (prompt) controller.state = { ...loop, prompt };
 	else {
 		const { prompt: _dropped, ...rest } = loop;
 		controller.state = rest;
 	}
 	controller.persist();
-	ctx.ui.notify("Loop focus updated.", "info");
+	controller.updateWidget();
+	ctx.ui.notify(prompt ? "Loop focus updated." : "Loop focus cleared.", "info");
+	return true;
 }
 
-async function editInterval(
+function setCadence(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
-): Promise<void> {
+	value: string,
+): boolean {
 	const loop = controller.state;
-	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", formatDuration(loop.intervalMs));
-	if (next === undefined) return;
-	const interval = parseInterval(next.trim());
+	if (!loop || loop.status === "stopped") return false;
+	const interval = parseInterval(value.trim());
 	if (!interval) {
-		ctx.ui.notify(`Invalid interval: ${next}. Use <number><unit>, e.g. 5m.`, "error");
-		return;
+		ctx.ui.notify(`Invalid interval: ${value}. Use <number><unit>, e.g. 5m.`, "error");
+		return false;
 	}
 	controller.state = { ...loop, intervalMs: interval.effectiveMs };
 	controller.persist();
-	if (loop.status === "active") {
-		// Re-arm on the new cadence from now.
-		controller.resumeAfterEdit();
-	}
+	// Re-arm on the new cadence from now.
+	if (loop.status === "active") controller.resumeAfterEdit();
+	else controller.updateWidget();
 	ctx.ui.notify(
 		`Loop interval set to ${formatDuration(interval.effectiveMs)}${interval.clamped ? " (clamped to the minimum)" : ""}.`,
 		"info",
 	);
+	return true;
 }
 
 export async function showLoopSettings(
@@ -169,7 +182,8 @@ export async function showLoopSettings(
 		const next = structuredClone(s);
 		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.
+			// text box: it is only reachable by discovery otherwise. It is also the
+			// default, so this editor is where a user opts *into* a budget.
 			const cap = await editCap(ctx, "Max loop turns", "no turn cap", s.maxTurns);
 			if (cap === undefined) continue;
 			next.maxTurns = cap === "unlimited" ? null : cap;
@@ -217,8 +231,7 @@ export async function showLoopSettings(
 /**
  * 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.
+ * otherwise. The typed word still works too.
  */
 async function editCap(
 	ctx: ExtensionCommandContext,
@@ -275,11 +288,11 @@ function applySettings(
  * 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.
+ * 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 ground rules, the cadence and the caps, is the strongest evidence of
+ * intent there is — stronger than any token the model could also emit — so it
+ * starts the loop directly rather than routing back through a tool.
  */
 export async function showLoopApproval(
 	controller: LoopController,
@@ -292,10 +305,7 @@ export async function showLoopApproval(
 	// this only renders one when the user reached the approval some other way.
 	controller.showProposalCard(ctx);
 	if (ctx.mode !== "tui") {
-		ctx.ui.notify(
-			"Approve it from a TUI session, or start it directly with /loop <interval> <objective>.",
-			"info",
-		);
+		ctx.ui.notify("Approve it from a TUI session; a loop cannot be started headless.", "info");
 		return;
 	}
 	await showLoopApprovalMenu(ctx, {
@@ -331,6 +341,9 @@ function startArgumentsFor(proposal: LoopProposal): LoopStartArguments {
 		maxTurns: proposal.maxTurns,
 		expiresInMs: proposal.expiresInMs,
 		prompt: proposal.objective,
+		// The approved constraints cross with the objective; they are part of what
+		// the user said yes to.
+		...(proposal.groundRules ? { groundRules: proposal.groundRules } : {}),
 	};
 }
 
@@ -389,6 +402,7 @@ async function changeCadence(
 		intervalMs: interval.effectiveMs,
 		maxTurns: proposal.maxTurns,
 		expiresInMs: proposal.expiresInMs,
+		...(proposal.groundRules ? { groundRules: proposal.groundRules } : {}),
 	});
 	await showLoopApproval(controller, ctx);
 }