@hank-warren/pi-loop 0.9.0 → 1.1.0

package/src/loop.ts

@@ -89,6 +89,8 @@ import {
 	buildProposal,
 	type LoopPlanningState,
 	type LoopProposal,
+	type LoopProposalOverrides,
+	normalizeGroundRules,
 } from "./planning.js";
 import {
 	clearLoopWidget,
@@ -119,6 +121,15 @@ export const MAX_FALLBACK_BACKOFF = 4;
  * would otherwise be the first sign anything was wrong.
  */
 export const STALL_ATTENTION_MS = 900_000;
+/**
+ * How long the expiry wake has to become a turn before the loop stops anyway.
+ *
+ * `sendUserMessage` is fire-and-forget: Pi swallows an asynchronous delivery
+ * failure (an expired credential, a torn-down runner), so a successful return
+ * is not proof a turn will start. The ordinary dead-delivery counter cannot
+ * catch this one, because after expiry there is no next delivery to count.
+ */
+export const EXPIRY_TURN_GRACE_MS = 60_000;
 
 /** Consecutive loop deliveries that produce no run before the loop pauses. */
 export const MAX_DEAD_DELIVERIES = 3;
@@ -130,10 +141,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 };
 
@@ -164,6 +174,8 @@ export interface LoopControllerOptions {
 	now?: () => number;
 	/** Root for the loop ledger; defaults to Pi's agent dir. Tests override it. */
 	agentDir?: string;
+	/** How long the final expiry turn has to start before the loop gives up. */
+	expiryTurnGraceMs?: number;
 }
 
 export class LoopController {
@@ -176,6 +188,7 @@ export class LoopController {
 	private readonly now: () => number;
 	readonly settingsPath: string;
 	private timer: NodeJS.Timeout | undefined;
+	private expiryTimer: NodeJS.Timeout | undefined;
 	private nextWakeAt: number | undefined;
 	private wakePending = false;
 	private sessionCtx: ExtensionContext | undefined;
@@ -185,6 +198,7 @@ export class LoopController {
 	ledger: LedgerPaths | undefined;
 	private ledgerWarned = false;
 	private readonly agentDir: string | undefined;
+	private readonly expiryTurnGraceMs: number;
 	/** Consecutive fallback wakes that produced a no-op turn. */
 	noOpStreak = 0;
 	lastContinuation: (ContinuationDecision & { at: number }) | undefined;
@@ -228,12 +242,14 @@ export class LoopController {
 		this.now = options.now ?? Date.now;
 		this.settingsPath = options.settingsPath ?? loopSettingsPath();
 		this.agentDir = options.agentDir;
+		this.expiryTurnGraceMs = options.expiryTurnGraceMs ?? EXPIRY_TURN_GRACE_MS;
 	}
 
 	// --- lifecycle ---
 
 	onSessionStart(ctx: ExtensionContext): void {
 		this.clearTimer();
+		this.clearExpiryWatchdog();
 		this.wakePending = false;
 		this.compacting = false;
 		this.lastDecision = undefined;
@@ -273,6 +289,7 @@ export class LoopController {
 			// A wait whose deadline passed while the session was away is due now.
 			this.restoreWaitTimer();
 			this.armFallback();
+			this.armExpiryWatchdog();
 			// A loop handed over from another session has never had its first turn.
 			if (this.state.handoff) this.consumeHandoff(ctx);
 		}
@@ -293,7 +310,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);
@@ -305,6 +322,7 @@ export class LoopController {
 		// Withdraw the signal: the process may outlive this session.
 		publishLoopEnv(undefined);
 		this.clearTimer();
+		this.clearExpiryWatchdog();
 		this.waitTimer.clear();
 		this.wakePending = false;
 		this.continuationIntent = undefined;
@@ -371,14 +389,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 +404,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 +426,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 +469,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 +552,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 +582,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 +616,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 +697,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 +835,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;
@@ -834,6 +852,63 @@ export class LoopController {
 		this.nextWakeAt = undefined;
 	}
 
+	private armExpiryWatchdog(): void {
+		this.clearExpiryWatchdog();
+		const loop = this.state;
+		if (!loop || loop.status !== "active") return;
+		const loopId = loop.id;
+		const delay = Math.min(MAX_INTERVAL_MS, Math.max(0, loop.expiresAt - this.now()));
+		this.expiryTimer = setTimeout(() => {
+			this.expiryTimer = undefined;
+			const current = this.state;
+			if (!current || current.id !== loopId || current.status !== "active") return;
+			if (this.now() < current.expiresAt) {
+				this.armExpiryWatchdog();
+				return;
+			}
+			const ctx = this.sessionCtx;
+			if (!ctx) {
+				this.transition("stopped", "loop expired without an active session context");
+				return;
+			}
+			const planActive = readPlanModeEnabled(ctx.sessionManager.getBranch());
+			const busy = !ctx.isIdle() || ctx.hasPendingMessages();
+			if (planActive || busy) {
+				this.transition(
+					"stopped",
+					planActive
+						? "loop expired while Plan mode was active"
+						: "loop expired while the agent was busy",
+				);
+				return;
+			}
+			this.runTick(ctx);
+		}, delay);
+		this.expiryTimer.unref?.();
+	}
+
+	private clearExpiryWatchdog(): void {
+		if (this.expiryTimer) clearTimeout(this.expiryTimer);
+		this.expiryTimer = undefined;
+	}
+
+	/**
+	 * The other half of expiry: the wake was handed to Pi, and this stops the
+	 * loop if it never becomes a run. A run that *did* start leaves
+	 * `awaitingRun` false, and the settle after it stops the loop normally.
+	 */
+	private armExpiryTurnGuard(loopId: string): void {
+		this.clearExpiryWatchdog();
+		this.expiryTimer = setTimeout(() => {
+			this.expiryTimer = undefined;
+			const current = this.state;
+			if (!current || current.id !== loopId || current.status !== "active") return;
+			if (!this.awaitingRun) return;
+			this.transition("stopped", "the final expiry turn never started");
+		}, this.expiryTurnGraceMs);
+		this.expiryTimer.unref?.();
+	}
+
 	private gatherEnvironment(ctx: ExtensionContext): TickEnvironment {
 		const branch = ctx.sessionManager.getBranch();
 		return {
@@ -921,6 +996,10 @@ export class LoopController {
 		}
 		this.runOrigin = "fallback";
 		this.continuationIntent = undefined;
+		// Marked directly rather than through noteDelivery(): the dead-delivery
+		// counter pauses a loop that should keep trying, and this one is already
+		// ending. The guard below is what acts on it.
+		this.awaitingRun = true;
 		this.state = {
 			...this.consumeWait(loop),
 			iteration: loop.iteration + 1,
@@ -929,6 +1008,10 @@ export class LoopController {
 			expiring: true,
 		};
 		this.clearTimer();
+		// The wake was accepted, not delivered. Hold one bounded guard so a final
+		// turn that never starts still ends the loop instead of leaving it active
+		// past its deadline with every timer cleared.
+		this.armExpiryTurnGuard(loop.id);
 		this.persist();
 		this.updateWidget();
 		this.sessionCtx?.ui.notify(
@@ -1047,9 +1130,20 @@ export class LoopController {
 
 	private transition(status: "paused" | "stopped", why: string, cause?: string): void {
 		if (!this.state) return;
-		const { waiting: _waiting, pauseCause: _pauseCause, ...rest } = this.state;
-		this.state = { ...rest, status, ...(cause ? { pauseCause: cause } : {}) };
+		const {
+			waiting: _waiting,
+			pauseCause: _pauseCause,
+			terminalReason: _terminalReason,
+			...rest
+		} = this.state;
+		this.state = {
+			...rest,
+			status,
+			...(cause ? { pauseCause: cause } : {}),
+			...(status === "stopped" ? { terminalReason: why } : {}),
+		};
 		this.clearTimer();
+		this.clearExpiryWatchdog();
 		this.waitTimer.clear();
 		this.wakePending = false;
 		this.continuationIntent = undefined;
@@ -1128,9 +1222,9 @@ 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})` : ""}`,
+			`Status: ${loop.status}${loop.pauseCause ? ` (${loop.pauseCause})` : loop.terminalReason ? ` (${loop.terminalReason})` : ""}`,
 			...(loop.waiting
 				? [
 						`Waiting: ${loop.waiting.reason}${
@@ -1208,10 +1302,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 +1378,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 +1398,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,
@@ -1351,12 +1444,13 @@ export class LoopController {
 		this.openLedger(started, built.criteria);
 		this.persist();
 		this.scheduleTick(started.intervalMs);
+		this.armExpiryWatchdog();
 		this.updateWidget();
 		const clampNote = built.clamped
 			? ` (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) {
@@ -1439,6 +1533,7 @@ export class LoopController {
 		this.noOpStreak = 0;
 		this.persist();
 		this.scheduleTick(loop.intervalMs);
+		this.armExpiryWatchdog();
 		this.updateWidget();
 		ctx.ui.notify(
 			`Loop resumed: continuing now, with a fallback wake every ${formatDuration(loop.intervalMs)}.`,