@hank-warren/pi-loop 0.8.0 → 1.0.0

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;
@@ -38,19 +50,38 @@ export interface LoopPlanningState {
 	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 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,
@@ -58,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 [
@@ -69,28 +115,36 @@ 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)}`,
 		"",
-		"Run `/loop` to approve and start, keep editing, or cancel.",
+		"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 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

@@ -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

@@ -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;

package/src/propose-tool.ts

@@ -2,11 +2,11 @@
  * `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.
+ * approves, and the approval is what starts the loop. A loop is
+ * self-continuing and must never begin on model initiative, so this is the
+ * only way a model can put one in front of a user: a card showing the
+ * objective, the criteria, the ground rules, the cadence and the caps, with
+ * the start reserved to the human reading 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.
@@ -14,9 +14,9 @@
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import type { LoopController } from "./loop.js";
-import { renderProposalCard } from "./planning.js";
+import { MAX_GROUND_RULE_LENGTH, MAX_GROUND_RULES } from "./planning.js";
 
 export const LOOP_PROPOSE_TOOL = "loop_propose";
 
@@ -26,13 +26,13 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 			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.",
+				"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, plus any ground rules. 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.",
+				"Pass ground_rules for the hard constraints the loop must never violate while unattended. They bound how the work may be done and never gate completion, so they belong there rather than in the objective.",
+				"loop_propose starts nothing, so no rule against starting loops on your own applies 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 run a command instead.",
 			],
 			parameters: Type.Object({
 				objective: Type.String({
@@ -58,8 +58,15 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 						description: "Loop lifetime as <number><unit>, e.g. 3d. Omit for the default.",
 					}),
 				),
+				ground_rules: Type.Optional(
+					Type.Array(Type.String({ minLength: 1, maxLength: MAX_GROUND_RULE_LENGTH }), {
+						maxItems: MAX_GROUND_RULES,
+						description:
+							"Hard constraints the loop must never violate, one per entry (e.g. 'never touch production', 'never force-push', 'never edit a test to make it pass'). Constraints, not criteria: they never gate completion.",
+					}),
+				),
 			}),
-			async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			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.",
@@ -67,14 +74,22 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 				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.",
+						"A loop is already running in this session. Stop it from the /loop menu 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 } =
-					{};
+				const overrides: {
+					intervalMs?: number;
+					maxTurns?: number | null;
+					expiresInMs?: number;
+					groundRules?: string[];
+				} = {};
+				// Bounded and trimmed in buildProposal, so an over-long or empty entry
+				// is normalized rather than refused: a rejected proposal costs the whole
+				// draft, and the card is where the user reviews them anyway.
+				if (params.ground_rules !== undefined) overrides.groundRules = params.ground_rules;
 				if (params.interval !== undefined) {
 					const parsed = parseDuration(params.interval);
 					if (parsed === undefined) {
@@ -101,12 +116,24 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 
 				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: renderProposalCard(proposal).join("\n") }],
+					content: [
+						{
+							type: "text" as const,
+							text: `Approval card rendered: ${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}${proposal.groundRules ? `, ${proposal.groundRules.length} ground rule${proposal.groundRules.length === 1 ? "" : "s"}` : ""}, 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,
+						groundRules: proposal.groundRules?.length ?? 0,
 					},
 				};
 			},

package/src/settings.ts

@@ -29,12 +29,28 @@ export interface LoopCompactionSettings {
  */
 const LEGACY_CAP_KEYS = ["maxIterations", "automaticTurns"] as const;
 
+/**
+ * Settings that no longer exist. They are tolerated on read (an unknown field
+ * is ignored, never a reason to reject the file) and dropped on the next save,
+ * so a settings file written by an older version keeps working and quietly
+ * stops advertising a switch that controls nothing.
+ *
+ * `inlineInvocation` toggled mid-prompt `/loop` detection, which was removed
+ * along with the `loop_start` tool it pointed at.
+ */
+const REMOVED_KEYS = ["inlineInvocation"] as const;
+
 export interface LoopSettings {
 	/**
 	 * Cap on the turns the loop itself causes (settle continuations plus
-	 * fallback pokes); null means unlimited (explicit opt-in). The only cap
-	 * there is: one wake can yield many turns, so counting turns is what
-	 * actually bounds a loop.
+	 * fallback pokes); null means unlimited, and unlimited is the default. The
+	 * only cap there is: one wake can yield many turns, so counting turns is
+	 * what actually bounds a loop.
+	 *
+	 * A turn budget is a proxy for cost, not for progress, and a loop that hits
+	 * one stops in the middle of the work with nothing decided. The real bounds
+	 * are the expiry and the no-progress breaker, which stop a loop for reasons
+	 * a user can act on. Set a number here to opt back into a budget.
 	 */
 	maxTurns: number | null;
 	/**
@@ -45,26 +61,19 @@ export interface LoopSettings {
 	/** Wall-clock expiry for a loop, e.g. "7d" (research: bound forgotten loops). */
 	maxLoopDuration: string;
 	/**
-	 * Detect an inline `/loop` token or a `loop:` prefixed line mid-prompt and
-	 * point the model at the `loop_start` tool. Pi only dispatches `/loop` from
-	 * position 0, so without this a mid-prompt invocation is silently prose.
-	 */
-	inlineInvocation: boolean;
-	/**
-	 * Fallback heartbeat used by an inline invocation that names no interval.
-	 * In a settle-paced loop the interval is only a fallback — the settle
-	 * boundary is the pacemaker — so this value is far less consequential than
-	 * it looks; it is still clamped to MIN_INTERVAL_MS.
+	 * Fallback heartbeat used by a proposal that names no interval. In a
+	 * settle-paced loop the interval is only a fallback — the settle boundary is
+	 * the pacemaker — so this value is far less consequential than it looks; it
+	 * is still clamped to MIN_INTERVAL_MS.
 	 */
 	defaultInterval: string;
 	compaction: LoopCompactionSettings;
 }
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
-	maxTurns: 25,
+	maxTurns: null,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
-	inlineInvocation: true,
 	defaultInterval: "10m",
 	compaction: {
 		enabled: true,
@@ -98,11 +107,6 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		return undefined;
 	}
 
-	const inlineInvocation = Object.hasOwn(record, "inlineInvocation")
-		? record.inlineInvocation
-		: DEFAULT_LOOP_SETTINGS.inlineInvocation;
-	if (typeof inlineInvocation !== "boolean") return undefined;
-
 	const defaultInterval = Object.hasOwn(record, "defaultInterval")
 		? record.defaultInterval
 		: DEFAULT_LOOP_SETTINGS.defaultInterval;
@@ -140,7 +144,6 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		maxTurns,
 		noProgressTurns,
 		maxLoopDuration,
-		inlineInvocation,
 		defaultInterval,
 		compaction: { enabled, threshold, instructions },
 	};
@@ -253,13 +256,15 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 	// unknown: leaving them next to a cap that supersedes them would show the
 	// user two numbers where only one applies.
 	for (const key of LEGACY_CAP_KEYS) delete raw[key];
+	// Removed settings are dropped rather than preserved: keeping a switch that
+	// controls nothing is worse than losing it.
+	for (const key of REMOVED_KEYS) delete raw[key];
 	const document = `${JSON.stringify(
 		{
 			...raw,
 			maxTurns: normalized.maxTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
-			inlineInvocation: normalized.inlineInvocation,
 			defaultInterval: normalized.defaultInterval,
 			compaction: { ...compaction, ...normalized.compaction },
 		},

package/src/state.ts

@@ -29,6 +29,12 @@ export interface LoopState {
 	 * before 0.6.0 may predate it — every loop started now has one.
 	 */
 	objective?: string;
+	/**
+	 * Hard constraints, approved with the objective and injected alongside it on
+	 * every active turn. Optional: a loop started before ground rules existed,
+	 * or approved without any, simply has none.
+	 */
+	groundRules?: string[];
 	intervalMs: number;
 	/**
 	 * Cap on the turns this loop causes (continuations plus pokes); null means
@@ -63,6 +69,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;
@@ -87,6 +106,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		objective = record.objective.trim();
 		if (!objective || objective.length > MAX_PROMPT_LENGTH) return undefined;
 	}
+	const groundRules = normalizeGroundRuleList(record.groundRules);
+	if (groundRules === false) return undefined;
 	const intervalMs = record.intervalMs;
 	if (!isPositiveSafeInteger(intervalMs)) return undefined;
 	const maxTurns = readTurnCap(record);
@@ -135,11 +156,13 @@ 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,
 		...(prompt === undefined ? {} : { prompt }),
 		...(objective === undefined ? {} : { objective }),
+		...(groundRules === undefined ? {} : { groundRules }),
 		intervalMs,
 		maxTurns,
 		compactAt: compactAt as number | null,
@@ -154,6 +177,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 } : {}),
 	};
 }
 
@@ -220,6 +244,25 @@ function ownRecord(value: unknown): Record<string, unknown> | undefined {
 		: undefined;
 }
 
+/**
+ * A present-but-optional ground-rule list: the list, undefined when absent,
+ * false when invalid. Empty survives as undefined so an approved loop with no
+ * rules and a restored one are the same state.
+ */
+function normalizeGroundRuleList(value: unknown): string[] | undefined | false {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) return false;
+	const rules: string[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") return false;
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		if (trimmed.length > MAX_PROMPT_LENGTH) return false;
+		rules.push(trimmed);
+	}
+	return rules.length > 0 ? rules : undefined;
+}
+
 /** A present-but-optional string: the value, undefined when absent, false when invalid. */
 function optionalText(value: unknown): string | undefined | false {
 	if (value === undefined) return undefined;

package/src/wait-tool.ts

@@ -59,7 +59,7 @@ export function registerLoopWaitTool(pi: ExtensionAPI, controller: LoopControlle
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No /loop with an objective is active, so there is nothing to wait on. Start one with /loop <interval> <objective>.",
+							"No /loop with an objective is active, so there is nothing to wait on. Run /loop to plan and approve one.",
 						),
 						details: {},
 						isError: true,

package/src/widget.ts

@@ -21,6 +21,11 @@
  * order is the whole reason to glance at the line: paused and blocked and
  * expiring come before the ordinary running line.
  *
+ * The glyph vocabulary is shared with pi-plan-mode by convention, not by
+ * import — `◆` planning or ready, `▶` implementing, `⟳` running, `⏸` paused,
+ * `⏳` waiting, `⚠` attention. Six characters are not worth a package; a user
+ * reading a footer is worth the consistency.
+ *
  * 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.
@@ -122,9 +127,8 @@ export function widgetTone(view: LoopWidgetView): Tone {
 
 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`;
+		if (view.proposedCriteria === undefined) return "◆ loop · drafting objective";
+		return `◆ loop · ${view.proposedCriteria} ${view.proposedCriteria === 1 ? "criterion" : "criteria"} proposed · approve to start`;
 	}
 	const loop = view.loop;