@hank-warren/pi-loop 0.9.0 → 1.1.0

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

package/src/messages.ts

@@ -20,7 +20,7 @@ export type ContinuationKind = "kickoff" | "continue" | "reanchor";
  * 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.
+ * to the *user*, in the widget and the /loop status screen, which is who it is for.
  */
 function formatWakeOrdinal(loop: LoopState): string {
 	return `${loop.iteration + 1}`;

package/src/objective.ts

@@ -32,6 +32,7 @@ export function buildLoopObjectivePrompt(
 		"<loop_objective>",
 		escapeXmlText(loop.objective),
 		"</loop_objective>",
+		...groundRuleLines(loop),
 		`<loop_id>\n${escapeXmlText(loop.id)}\n</loop_id>`,
 		"This loop_id is only the loop_complete tool's stale-loop guard, not part of the objective.",
 		"",
@@ -73,6 +74,30 @@ export function buildLoopObjectivePrompt(
 		.trimEnd();
 }
 
+/**
+ * The approved ground rules, as a block the model cannot mistake for the
+ * objective.
+ *
+ * They sit next to the objective rather than inside it because they are a
+ * different kind of thing: the objective is what the loop is trying to reach
+ * and what `loop_complete` answers for, while these bound how it may get
+ * there. Folding them into the objective would make them criteria, and a
+ * constraint that has to be "met" is a constraint nobody can satisfy.
+ *
+ * Approved by the user on the card, so unlike the objective they are not
+ * merely task data to consider — they outrank the loop's own judgement about
+ * what is expedient at 3am on turn 200.
+ */
+function groundRuleLines(loop: LoopState): string[] {
+	if (!loop.groundRules || loop.groundRules.length === 0) return [];
+	return [
+		"",
+		"Ground rules (hard constraints, never violate):",
+		...loop.groundRules.map((rule) => `- ${escapeXmlText(rule)}`),
+		"The user approved these with the objective. They bound how the work may be done, they are never satisfied or completed, and no amount of progress justifies breaking one. If the only way forward violates a ground rule, stop and call loop_wait.",
+	];
+}
+
 /**
  * The ledger contract. Stable per loop (the path is derived from the loop
  * id), so it keeps the append byte-identical across turns.

package/src/planning.ts

@@ -7,26 +7,38 @@
  * 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.
+ * So `/loop` opens a menu whose first item is a drafting conversation, 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, the
+ * caps and the ground rules are on it and editable there, no command grammar
+ * has to carry them. 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.
+ * Planning is now the only door. The typed start and the inline token are
+ * gone: both authored an acceptance gate in one line, unreviewed.
  */
 
 import { deriveCriteria, type LoopCriterion } from "./ledger.js";
 import { formatDuration } from "./interval.js";
 
+/** Bounds on drafted ground rules: enough for real constraints, not a manifesto. */
+export const MAX_GROUND_RULES = 10;
+export const MAX_GROUND_RULE_LENGTH = 500;
+
 /** 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[];
+	/**
+	 * Hard constraints the loop must never violate.
+	 *
+	 * Constraints, not criteria: they never enter `criteria.json` and never
+	 * gate completion. A loop is unattended, so the useful thing to fix in
+	 * advance is not only what done looks like but what it must not do on the
+	 * way there — don't touch prod, don't force-push, don't rewrite the fixture
+	 * to make the test pass.
+	 */
+	groundRules?: string[];
 	intervalMs: number;
 	maxTurns: number | null;
 	expiresInMs: number;
@@ -50,17 +62,26 @@ export interface LoopPlanningState {
 	cardShownAt?: number;
 }
 
+export interface LoopProposalOverrides {
+	intervalMs?: number;
+	maxTurns?: number | null;
+	expiresInMs?: number;
+	groundRules?: string[];
+}
+
 export function buildProposal(
 	objective: string,
 	defaults: { intervalMs: number; maxTurns: number | null; expiresInMs: number },
 	now: number,
-	overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } = {},
+	overrides: LoopProposalOverrides = {},
 ): LoopProposal {
+	const groundRules = normalizeGroundRules(overrides.groundRules);
 	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),
+		...(groundRules ? { groundRules } : {}),
 		intervalMs: overrides.intervalMs ?? defaults.intervalMs,
 		maxTurns: overrides.maxTurns === undefined ? defaults.maxTurns : overrides.maxTurns,
 		expiresInMs: overrides.expiresInMs ?? defaults.expiresInMs,
@@ -68,6 +89,21 @@ export function buildProposal(
 	};
 }
 
+/**
+ * Trim, drop the empties, and bound a drafted ground-rule list. Returns
+ * undefined when nothing survives, so an empty array never becomes an empty
+ * section on the card or an empty block in the system append.
+ */
+export function normalizeGroundRules(rules: readonly string[] | undefined): string[] | undefined {
+	if (!rules) return undefined;
+	const cleaned = rules
+		.map((rule) => rule.trim())
+		.filter((rule) => rule.length > 0)
+		.slice(0, MAX_GROUND_RULES)
+		.map((rule) => (rule.length > MAX_GROUND_RULE_LENGTH ? rule.slice(0, MAX_GROUND_RULE_LENGTH) : rule));
+	return cleaned.length > 0 ? cleaned : undefined;
+}
+
 /** The approval card, as transcript lines. */
 export function renderProposalCard(proposal: LoopProposal): string[] {
 	return [
@@ -79,6 +115,13 @@ export function renderProposalCard(proposal: LoopProposal): string[] {
 		`**Criteria the gate will hold you to** (${proposal.criteria.length})`,
 		...proposal.criteria.map((criterion) => `- \`${criterion.id}\`  ${criterion.description}`),
 		"",
+		...(proposal.groundRules
+			? [
+					`**Ground rules the loop must never violate** (${proposal.groundRules.length})`,
+					...proposal.groundRules.map((rule) => `- ${rule}`),
+					"",
+				]
+			: []),
 		`**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)}`,
 		"",
@@ -88,19 +131,20 @@ export function renderProposalCard(proposal: LoopProposal): string[] {
 
 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 opened loop planning. You are drafting a loop with them; no loop is running and none starts until they approve one on the card.",
+	"Read the pi-loop skill before drafting if it is available: it carries the objective, criteria, cadence and evidence craft in depth.",
+	"Cover three things in the conversation, then call loop_propose:",
+	"- The objective, written as an acceptance test. One requirement per 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'). The two questions that fix most objectives: how will we know it is done, and what command proves it?",
+	"- The cadence: how long the loop may run before it expires, and the fallback heartbeat for a session that goes quiet. The loop advances whenever the session settles, so the heartbeat only matters when it is waiting on something.",
+	"- The ground rules: hard constraints it must never violate while unattended, such as which systems are off limits, what must never be force-pushed or deleted, and which files may not be edited to make a check pass. Ask for them; a loop runs with nobody watching, so an unstated constraint is one nobody enforces.",
+	"Ground rules are constraints, not criteria. They never gate completion — they bound how the work may be done.",
+	"When the draft is ready, call loop_propose with the objective and any ground rules. 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 a prohibition instead. A conversational
+	// request for a loop pattern-matches onto 'do not start loops on your own',
+	// and the model answers by telling the user to type a command, which is
+	// precisely the dead end planning exists to remove. Observed live in a
+	// canary session.
+	"loop_propose starts nothing, so no rule against starting a loop on your own applies 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 run a command 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.",

package/src/presentation.ts

@@ -1,5 +1,5 @@
 /**
- * The approval card, as a framed transcript block.
+ * The approval card, as a display-only session entry.
  *
  * 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
@@ -8,18 +8,59 @@
  * 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.
+ * It is now a custom *entry* with a registered renderer, not a message. That
+ * is what buys the property a message could not: Pi maps a `custom` entry to
+ * no context messages at all and skips it during compaction, so the card stays
+ * visible and restorable in the transcript while never entering model context
+ * and never costing a compaction budget. The model is told a proposal exists
+ * by the tool result; it never re-reads the rendered card.
+ *
+ * pi-plan-mode's completed-plan card is the same mechanism for the same
+ * reason (`packages/pi-plan-mode/src/presentation.ts`), and `plan_mode_complete`
+ * likewise returns a one-line `Plan saved to <path>.` pointer instead of the
+ * plan body.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	getMarkdownTheme,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Markdown, Text } from "@earendil-works/pi-tui";
 import { type LoopProposal, renderProposalCard } from "./planning.js";
 
-export const LOOP_PROPOSAL_MESSAGE_TYPE = "loop-proposal";
+/**
+ * The card is a custom *entry*, not a custom message, and it carries a new
+ * type name to say so. The old `LOOP_PROPOSAL_MESSAGE_TYPE` export is gone
+ * rather than aliased: an alias would keep consumers compiling while silently
+ * pointing them at a channel proposals no longer travel on, which is worse
+ * than the compile error that tells them to look.
+ */
+export const LOOP_PROPOSAL_ENTRY_TYPE = "loop-proposal-card";
+
+type LoopProposalCardData = { markdown: string; criteria: number; proposedAt: number };
+
+/**
+ * Persisted entry data is input, not a guarantee.
+ *
+ * The renderer runs against whatever is on disk, which may predate a field, be
+ * truncated by a partial write, or have been hand-edited. Pi contains a
+ * renderer throw as an inline `[loop-proposal-card] renderer failed: …` box —
+ * survivable, but a needlessly ugly way to say "this card is old".
+ */
+function loopProposalCardData(value: unknown): LoopProposalCardData | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const { markdown } = value as { markdown?: unknown };
+	return typeof markdown === "string" ? (value as LoopProposalCardData) : undefined;
+}
+
+export function registerLoopProposalRenderer(pi: ExtensionAPI): void {
+	pi.registerEntryRenderer(LOOP_PROPOSAL_ENTRY_TYPE, (entry) => {
+		const data = loopProposalCardData(entry.data);
+		if (!data) return new Text("Loop proposal card unavailable.", 0, 0);
+		return new Markdown(data.markdown, 0, 0, getMarkdownTheme());
+	});
+}
 
 /**
  * Emit the card. Returns false when Pi refused it, in which case the caller
@@ -32,15 +73,11 @@ export function showLoopProposalCard(
 	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 },
-		);
+		pi.appendEntry<LoopProposalCardData>(LOOP_PROPOSAL_ENTRY_TYPE, {
+			markdown: renderProposalCard(proposal).join("\n"),
+			criteria: proposal.criteria.length,
+			proposedAt: proposal.proposedAt,
+		});
 		return true;
 	} catch (error) {
 		const detail = error instanceof Error ? error.message : String(error);

package/src/progress-tool.ts

@@ -87,7 +87,7 @@ export function registerLoopProgressTool(pi: ExtensionAPI, controller: LoopContr
 				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>.",
+						"No /loop with an objective is active, so there is no ledger to write. Run /loop to plan and approve one.",
 					);
 				}
 				const paths = controller.ledger;