@hank-warren/pi-loop 0.4.1 → 0.5.0

package/src/loop.ts

@@ -3,11 +3,19 @@
  * loop-aware compaction, wired to Pi's extension events.
  *
  * Design invariants (approved plan):
- * - Timers are armed in session_start or a command handler, never the factory,
- *   and cleared in an idempotent session_shutdown.
+ * - The settled idle boundary is the pacemaker for a standalone loop: an
+ *   agent_end records a continuation *intent*, and the next fully settled
+ *   boundary dispatches it. The interval is a fallback heartbeat, re-armed
+ *   from the last settle, that fires only when the session has been idle a
+ *   whole interval with the objective unfinished (a lost continuation, or an
+ *   external wait). A goal-bound loop is unchanged: pi-goal owns its settle
+ *   continuations, and the interval is still that loop's only driver.
+ * - Timers are armed in session_start, a settle, or a command handler, never
+ *   the factory, and cleared in an idempotent session_shutdown.
  * - Pokes deliver only at a fully idle boundary; a tick that lands while the
  *   agent is busy coalesces into a single pending wake delivered at the next
- *   agent_settled. Missed ticks never stack.
+ *   agent_settled. Missed ticks never stack, and a continuation supersedes a
+ *   coalesced wake rather than delivering both.
  * - Loops require an active pi-goal goal to operate: pi-goal owns "whether
  *   the work is done". Its safety states pause the loop, its completion stops
  *   it, and a missing goal pauses the loop. Coupling is read-only session
@@ -27,9 +35,31 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import type { LoopStartArguments } from "./command.js";
-import { decideTick, type TickDecision, type TickEnvironment } from "./decide.js";
-import { formatClock, formatDuration, parseDuration } from "./interval.js";
-import { buildCompactionInstructions, buildGoalPoke, buildObjectivePoke } from "./messages.js";
+import {
+	type ContinuationDecision,
+	decideContinuation,
+	decideTick,
+	type TickDecision,
+	type TickEnvironment,
+} from "./decide.js";
+import { formatClock, formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
+import {
+	createLedger,
+	deriveCriteria,
+	type LedgerPaths,
+	ledgerPaths,
+	readCriteria,
+} from "./ledger.js";
+import {
+	buildCompactionInstructions,
+	buildContinuation,
+	buildExpiryWake,
+	buildGoalPoke,
+	buildKickoffAnchor,
+	buildObjectivePoke,
+	type ContinuationKind,
+	extractNextActions,
+} from "./messages.js";
 import {
 	DEFAULT_LOOP_SETTINGS,
 	type LoopSettings,
@@ -44,13 +74,50 @@ import {
 	readPlanModeEnabled,
 	restoreLoopState,
 } from "./state.js";
+import { isLoopOkAck } from "./ack.js";
+import { calledTool, hasAssistantToolCall, nextNoProgressState } from "./safety.js";
+import { classifyInterruption } from "./errors.js";
+import { LOOP_WAIT_TOOL } from "./wait-tool.js";
+import {
+	createLoopWait,
+	type LoopWait,
+	LoopWaitTimer,
+	resolveWaitDelay,
+	type ResolvedWaitDelay,
+} from "./wait.js";
+import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
 import { clearLoopWidget, updateLoopWidget } from "./widget.js";
 
 export const LOOP_STATUS_KEY = "loop";
 
+/** Custom message type of the kickoff anchor. */
+export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
+
+/**
+ * A fallback wake that produces a no-op turn doubles the next fallback delay,
+ * capped here. Deterministic and small: the point is to stop re-waking a loop
+ * that has nothing to do, not to invent an adaptive scheduler.
+ */
+export const MAX_FALLBACK_BACKOFF = 4;
+
+/** Consecutive loop deliveries that produce no run before the loop pauses. */
+export const MAX_DEAD_DELIVERIES = 3;
+
+/** Why the loop caused the run that is currently in flight. */
+type RunOrigin = "continuation" | "fallback";
+
+interface ContinuationIntent {
+	loopId: string;
+	kind: ContinuationKind;
+	/** Next actions carried out of a compaction summary, for a re-anchor. */
+	nextActions?: string;
+}
+
 export interface LoopControllerOptions {
 	settingsPath?: string;
 	now?: () => number;
+	/** Root for the loop ledger; defaults to Pi's agent dir. Tests override it. */
+	agentDir?: string;
 }
 
 export class LoopController {
@@ -66,11 +133,31 @@ export class LoopController {
 	private nextWakeAt: number | undefined;
 	private wakePending = false;
 	private sessionCtx: ExtensionContext | undefined;
+	private continuationIntent: ContinuationIntent | undefined;
+	private runOrigin: RunOrigin | undefined;
+	/** The active loop's ledger, or undefined when it could not be created. */
+	ledger: LedgerPaths | undefined;
+	private ledgerWarned = false;
+	private readonly agentDir: string | undefined;
+	/** Consecutive fallback wakes that produced a no-op turn. */
+	noOpStreak = 0;
+	lastContinuation: (ContinuationDecision & { at: number }) | undefined;
+	private readonly waitTimer = new LoopWaitTimer();
+	/**
+	 * Loop-caused deliveries that never produced an agent run. A provider that
+	 * refuses before the first token — no API key, a torn-down runner — never
+	 * reaches agent_end, so no classifier ever sees it.
+	 */
+	private deadDeliveries = 0;
+	private awaitingRun = false;
+	/** Set when an interrupted turn needs a compaction before the loop continues. */
+	private compactionRequested = false;
 
 	constructor(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 		this.pi = pi;
 		this.now = options.now ?? Date.now;
 		this.settingsPath = options.settingsPath ?? loopSettingsPath();
+		this.agentDir = options.agentDir;
 	}
 
 	// --- lifecycle ---
@@ -80,6 +167,12 @@ export class LoopController {
 		this.wakePending = false;
 		this.compacting = false;
 		this.lastDecision = undefined;
+		this.lastContinuation = undefined;
+		this.continuationIntent = undefined;
+		this.runOrigin = undefined;
+		this.noOpStreak = 0;
+		this.deadDeliveries = 0;
+		this.awaitingRun = false;
 		this.sessionCtx = ctx;
 
 		const loaded = readLoopSettings(this.settingsPath);
@@ -88,34 +181,210 @@ export class LoopController {
 			ctx.ui.notify(`pi-loop settings ignored: ${loaded.reason}. Using defaults.`, "warning");
 		}
 
+		this.ledger = undefined;
+		this.ledgerWarned = false;
 		this.state = restoreLoopState(ctx.sessionManager.getBranch());
 		if (this.state && this.state.status === "active") {
 			if (this.now() >= this.state.expiresAt) {
 				this.transition("stopped", "loop expired while the session was away");
 				return;
 			}
-			this.scheduleTick(this.state.intervalMs);
+			if (!isStandaloneLoop(this.state) && this.migrateGoalBoundLoop(ctx)) return;
+			// A restored loop keeps its ledger: createLedger only ever creates
+			// PROGRESS.md, so days of agent-written state survive a restart.
+			this.openLedger(this.state);
+			// A wait whose deadline passed while the session was away is due now.
+			this.restoreWaitTimer();
+			this.armFallback();
 		}
 		this.updateWidget();
 	}
 
 	onSessionShutdown(): void {
 		this.clearTimer();
+		this.waitTimer.clear();
 		this.wakePending = false;
+		this.continuationIntent = undefined;
+		this.runOrigin = undefined;
 		if (this.sessionCtx) clearLoopWidget(this.sessionCtx.ui);
 		this.sessionCtx = undefined;
 	}
 
+	/**
+	 * A finished agent run with an active standalone loop is the signal that
+	 * paces the loop: record the *intent* to continue here and let the settled
+	 * boundary decide whether it may be delivered. Recording at agent_end (not
+	 * at settle) is what makes the intent survive Pi's own retries and
+	 * auto-compaction, which run between the two events.
+	 */
+	/** A run started, so the delivery that caused it was not a dead one. */
+	onAgentStart(ctx: ExtensionContext): void {
+		this.sessionCtx = ctx;
+		this.awaitingRun = false;
+		this.deadDeliveries = 0;
+	}
+
+	onAgentEnd(ctx: ExtensionContext, messages: readonly unknown[] = []): void {
+		this.sessionCtx = ctx;
+		this.awaitingRun = false;
+		const origin = this.runOrigin;
+		this.runOrigin = undefined;
+		const loop = this.state;
+		if (!loop || loop.status !== "active" || !isStandaloneLoop(loop)) return;
+		if (this.enforceToolAvailability(ctx)) return;
+		// The expiry's final turn is the last one: never queue a continuation
+		// behind it. The settle that follows stops the loop.
+		if (loop.expiring) return;
+		// A user turn cancels a wait: whatever they just said outranks it. The
+		// reason survives as a hint on the next loop message.
+		if (origin === undefined && loop.waiting) this.cancelWait("a user message arrived");
+		this.recordProgress(origin, messages);
+		if (this.classifyAndHandleInterruption(ctx, messages, origin)) return;
+		if (this.enforceNoProgress(ctx, messages, origin)) return;
+		// A turn that ended in loop_wait asked not to be continued.
+		if (this.state?.waiting) return;
+		if (this.state) this.requestContinuation(this.state);
+	}
+
+	/**
+	 * Act on how the turn ended. A loop that answers every provider failure
+	 * with "continue" retries into exhausted quotas and re-sends requests that
+	 * are too large to succeed; each class needs its own answer. Returns true
+	 * when the interruption was handled and no continuation should be recorded.
+	 */
+	private classifyAndHandleInterruption(
+		ctx: ExtensionContext,
+		messages: readonly unknown[],
+		origin: RunOrigin | undefined,
+	): boolean {
+		const loop = this.state;
+		if (!loop) return true;
+		switch (classifyInterruption(messages)) {
+			case "usage-limited":
+				this.transition(
+					"paused",
+					"the provider reports the usage limit is reached; resume with /loop resume 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",
+					"unrecoverable provider error",
+				);
+				return true;
+			case "aborted":
+				// 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");
+				return true;
+			case "context-overflow":
+				// The request no longer fits: compact first, then continue. The
+				// re-anchor that follows the compaction is the continuation.
+				this.compactionRequested = true;
+				ctx.ui.notify(
+					"pi-loop: the turn overflowed the context window; compacting before continuing.",
+					"warning",
+				);
+				return true;
+			default:
+				// "none" and "retryable" both continue: a transient provider error
+				// is exactly what the next continuation retries.
+				return false;
+		}
+	}
+
+	/**
+	 * 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.
+	 */
+	private enforceNoProgress(
+		ctx: ExtensionContext,
+		messages: readonly unknown[],
+		origin: RunOrigin | undefined,
+	): boolean {
+		const loop = this.state;
+		if (!loop) return true;
+		const limit = this.settings.noProgressTurns;
+		if (origin === undefined) {
+			// Any user input resets the safety epoch: the user has seen the
+			// output and chosen to keep going.
+			if (loop.toolFreeRepeatCount !== undefined || loop.lastFingerprint !== undefined) {
+				this.state = { ...loop, toolFreeRepeatCount: 0, lastFingerprint: undefined };
+				this.persist();
+			}
+			return false;
+		}
+		if (limit === null) return false;
+		// A turn that called loop_wait declared a wait; that is a decision, not a
+		// stall, and counting it is the classic false positive.
+		const toolAttempted = hasAssistantToolCall(messages) || calledTool(messages, LOOP_WAIT_TOOL);
+		const next = nextNoProgressState(
+			{
+				toolFreeRepeatCount: loop.toolFreeRepeatCount ?? 0,
+				...(loop.lastFingerprint === undefined ? {} : { lastFingerprint: loop.lastFingerprint }),
+			},
+			messages,
+			toolAttempted,
+		);
+		this.state = {
+			...loop,
+			toolFreeRepeatCount: next.toolFreeRepeatCount,
+			...(next.lastFingerprint === undefined ? {} : { lastFingerprint: next.lastFingerprint }),
+		};
+		if (next.toolFreeRepeatCount < limit) {
+			this.persist();
+			return false;
+		}
+		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`,
+			"no progress",
+		);
+		return true;
+	}
+
+	/**
+	 * Fallback backoff bookkeeping. A user-driven turn, or any loop-caused turn
+	 * that actually did something, resets the streak; only a fallback wake that
+	 * produced a no-op turn grows the next fallback delay.
+	 */
+	private recordProgress(origin: RunOrigin | undefined, messages: readonly unknown[]): void {
+		if (origin === undefined) {
+			// A turn the user drove: the loop is not the thing spinning.
+			this.noOpStreak = 0;
+			return;
+		}
+		// An explicit LOOP_OK is the deterministic version of the same signal:
+		// the model looked and there was nothing to do. It counts even when the
+		// turn used a tool to look.
+		if (!isNoOpRun(messages) && !isLoopOkAck(messages)) {
+			this.noOpStreak = 0;
+			return;
+		}
+		if (origin === "fallback") this.noOpStreak += 1;
+	}
+
 	onAgentSettled(ctx: ExtensionContext): void {
 		this.sessionCtx = ctx;
 		if (!this.state || this.state.status !== "active") return;
 		if (this.maybeStartCompaction(ctx)) return;
+		if (this.settleTerminalState(ctx)) return;
+		if (this.dispatchContinuationIfSettled(ctx)) return;
 		if (this.wakePending) {
 			this.wakePending = false;
 			this.runTick(ctx);
 			return;
 		}
-		this.settleTerminalState(ctx);
+		// Re-arm the heartbeat from this settle, so it can only fire after a full
+		// interval of genuine idleness. A goal-bound loop keeps the old cadence:
+		// its timer is the only driver it has.
+		if (isStandaloneLoop(this.state)) this.armFallback();
 	}
 
 	/**
@@ -125,20 +394,309 @@ export class LoopController {
 	 * later. Poke and skip decisions are deliberately ignored here: only the
 	 * timer pokes, and settling is not a schedule.
 	 */
-	private settleTerminalState(ctx: ExtensionContext): void {
+	private settleTerminalState(ctx: ExtensionContext): boolean {
 		const loop = this.state;
-		if (!loop) return;
+		if (!loop) return false;
 		const env = this.gatherEnvironment(ctx);
 		const decision = decideTick(loop, env);
 		if (decision.action !== "expire" && decision.action !== "stop" && decision.action !== "pause") {
-			return;
+			return false;
 		}
 		this.lastDecision = { ...decision, at: env.now };
 		this.applyTerminalDecision(loop, decision);
+		return true;
+	}
+
+	/**
+	 * Migration for goal-bound loops, which are deprecated.
+	 *
+	 * A goal-bound loop delegated "is the work done" to pi-goal. Now that a
+	 * standalone loop owns completion itself, that delegation is the deprecated
+	 * path, and this converts one in place at restore rather than leaving the
+	 * user with a loop that pauses forever the moment its goal is gone.
+	 *
+	 * The one case it must *not* convert is a still-active goal: pi-goal is
+	 * driving that session's continuations, and a standalone loop driving them
+	 * too would send two messages at every settle. That loop keeps its old
+	 * behaviour and gets the notice instead.
+	 *
+	 * Returns true when the loop was stopped or paused and needs no timer.
+	 */
+	private migrateGoalBoundLoop(ctx: ExtensionContext): boolean {
+		const loop = this.state;
+		if (!loop) return true;
+		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+		if (goal?.status === "active") {
+			ctx.ui.notify(
+				"This loop is bound to a /goal, which is deprecated: pi-loop now owns long-running work on its own. It keeps working as before for now — start future loops with /loop <interval> <objective>.",
+				"warning",
+			);
+			return false;
+		}
+		if (goal?.status === "complete") {
+			this.transition("stopped", "the goal completed");
+			return true;
+		}
+		// The goal is gone or held: nothing is driving this loop any more, so
+		// adopt whatever objective text is still readable and carry on.
+		const objective = goal?.text ?? loop.prompt;
+		if (!objective) {
+			this.transition(
+				"paused",
+				"it was bound to a goal that is gone, and it has no objective text of its own to adopt; start a new loop with /loop <interval> <objective>",
+				"goal-bound loop with no objective",
+			);
+			return true;
+		}
+		const { prompt: _prompt, ...rest } = loop;
+		this.state = { ...rest, objective };
+		this.persist();
+		ctx.ui.notify(
+			`Goal-bound loops are deprecated; this one now owns its objective directly: ${objective}`,
+			"info",
+		);
+		return false;
+	}
+
+	/**
+	 * A standalone loop that cannot call `loop_complete` cannot end itself: it
+	 * will work, finish, and then be told to keep working until it hits a cap.
+	 * That happens whenever the tool set is restricted (`--tools`, `--no-tools`,
+	 * a policy that drops extension tools), and it is invisible from inside the
+	 * loop — so check the live tool set and pause instead of spinning.
+	 *
+	 * Returns true when the loop was paused.
+	 */
+	private enforceToolAvailability(ctx: ExtensionContext): boolean {
+		const loop = this.state;
+		if (!loop || loop.status !== "active" || !isStandaloneLoop(loop)) return false;
+		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`,
+			"loop_complete unavailable",
+		);
+		void ctx;
+		return true;
+	}
+
+	private completeToolAvailable(): boolean {
+		const getActiveTools = (this.pi as { getActiveTools?: () => string[] }).getActiveTools;
+		if (typeof getActiveTools !== "function") return true;
+		try {
+			// Fail open: a host that cannot report its tools is not evidence that
+			// the tool is missing.
+			return getActiveTools.call(this.pi).includes(LOOP_COMPLETE_TOOL);
+		} catch {
+			return true;
+		}
+	}
+
+	/**
+	 * Count a delivery that never became a run, and pause once the loop is
+	 * plainly shouting into a void. Without this a session whose provider
+	 * refuses every request (no API key, a revoked token) keeps waking on the
+	 * heartbeat until it exhausts its wake cap, because a run that fails before
+	 * the first token never reaches agent_end and so is never classified.
+	 *
+	 * Returns true when the loop was paused.
+	 */
+	private noteDelivery(): boolean {
+		if (this.awaitingRun) this.deadDeliveries += 1;
+		this.awaitingRun = true;
+		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`,
+			"deliveries produce no turns",
+		);
+		return true;
+	}
+
+	// --- loop_wait ---
+
+	/**
+	 * Enter an external wait. The pacemaker is deliberately left armed: a wait
+	 * supersedes the *next* fallback wake, it does not disable the heartbeat,
+	 * so a wait whose event never arrives still ends in a wake rather than in
+	 * silence.
+	 */
+	enterWait(reason: string, resumeAfterMs: number | undefined): ResolvedWaitDelay | undefined {
+		const loop = this.state;
+		if (!loop || loop.status !== "active" || !isStandaloneLoop(loop)) return undefined;
+		const resolved = resolveWaitDelay(resumeAfterMs);
+		const waiting = createLoopWait(reason, resumeAfterMs, this.now());
+		// The wait replaces any continuation already recorded for this turn.
+		this.continuationIntent = undefined;
+		const { cancelledWaitReason: _cancelled, ...rest } = loop;
+		this.state = { ...rest, waiting };
+		this.persist();
+		this.restoreWaitTimer();
+		this.updateWidget();
+		return resolved;
+	}
+
+	/**
+	 * Drop a wait that something other than its own deadline ended, keeping its
+	 * reason as a one-shot hint for the next loop message. There is no cancel
+	 * tool: the events that legitimately cancel a wait are not the model's to
+	 * report.
+	 */
+	private cancelWait(_why: string): void {
+		const loop = this.state;
+		if (!loop?.waiting) return;
+		const { waiting, ...rest } = loop;
+		this.waitTimer.clear();
+		this.state = { ...rest, cancelledWaitReason: waiting.reason };
+		this.persist();
+		this.updateWidget();
+	}
+
+	/** Re-arm the wait deadline, including after a restore or a compaction. */
+	private restoreWaitTimer(): void {
+		this.waitTimer.clear();
+		const loop = this.state;
+		const resumeAt = loop?.status === "active" ? loop.waiting?.resumeAt : undefined;
+		if (resumeAt === undefined) return;
+		const loopId = loop?.id;
+		this.waitTimer.schedule(
+			resumeAt,
+			() => {
+				const ctx = this.sessionCtx;
+				if (!ctx || this.state?.id !== loopId) return;
+				try {
+					this.runTick(ctx);
+				} catch (error) {
+					ctx.ui.notify(`pi-loop wait deadline failed: ${formatError(error)}`, "warning");
+				}
+			},
+			this.now(),
+		);
+	}
+
+	/** The wait a delivered wake consumed, cleared as the wake goes out. */
+	private consumeWait(loop: LoopState): LoopState {
+		const { waiting: _waiting, cancelledWaitReason: _cancelled, ...rest } = loop;
+		this.waitTimer.clear();
+		return rest;
+	}
+
+	// --- ledger ---
+
+	/**
+	 * Create (or adopt) the ledger for a standalone loop. Best-effort by
+	 * design: a loop with no writable ledger still runs, it just loses the
+	 * durable record, so the failure is warned once and never repeated.
+	 */
+	private openLedger(loop: LoopState): void {
+		if (loop.objective === undefined) {
+			this.ledger = undefined;
+			return;
+		}
+		const paths = ledgerPaths(loop.id, this.agentDir);
+		const failure = createLedger(paths, loop.objective, deriveCriteria(loop.objective));
+		if (failure) {
+			this.ledger = undefined;
+			if (!this.ledgerWarned) {
+				this.ledgerWarned = true;
+				this.sessionCtx?.ui.notify(
+					`pi-loop could not write its ledger (${failure}). The loop runs without one.`,
+					"warning",
+				);
+			}
+			return;
+		}
+		this.ledger = paths;
+	}
+
+	/** The loop's criteria as last written to disk, fail-open. */
+	criteria() {
+		return this.ledger ? readCriteria(this.ledger) : undefined;
+	}
+
+	// --- settle-driven continuation ---
+
+	/** Record the intent to continue; the settled boundary decides delivery. */
+	private requestContinuation(
+		loop: LoopState,
+		kind: ContinuationKind = "continue",
+		nextActions?: string,
+	): void {
+		// A re-anchor outranks an ordinary continuation already queued: after a
+		// compaction, "re-read the ledger" is strictly the better instruction.
+		if (this.continuationIntent?.loopId === loop.id && kind !== "reanchor") return;
+		this.continuationIntent = { loopId: loop.id, kind, ...(nextActions ? { nextActions } : {}) };
+	}
+
+	/**
+	 * Deliver a recorded continuation, but only at a boundary where Pi will
+	 * actually accept it. A skip leaves the intent in place for the next
+	 * settle; a terminal decision consumes it.
+	 */
+	dispatchContinuationIfSettled(ctx: ExtensionContext): boolean {
+		const intent = this.continuationIntent;
+		if (!intent) return false;
+		const loop = this.state;
+		if (!loop || loop.id !== intent.loopId) {
+			this.continuationIntent = undefined;
+			return false;
+		}
+		const env = this.gatherEnvironment(ctx);
+		const decision = decideContinuation(loop, env);
+		this.lastContinuation = { ...decision, at: env.now };
+		if (decision.action === "none") {
+			this.continuationIntent = undefined;
+			return false;
+		}
+		if (decision.action === "skip") return false;
+		if (decision.action !== "continue") {
+			this.continuationIntent = undefined;
+			this.lastDecision = { ...decision, at: env.now };
+			this.applyTerminalDecision(loop, decision);
+			return true;
+		}
+		try {
+			this.pi.sendUserMessage(buildContinuation(loop, intent.kind, intent.nextActions));
+		} catch (error) {
+			// Keep the intent: the next settle retries it, and the fallback
+			// heartbeat covers the case where no further settle arrives.
+			this.sessionCtx?.ui.notify(
+				`pi-loop could not continue the loop: ${formatError(error)}. Retrying at the next idle boundary.`,
+				"warning",
+			);
+			this.armFallback();
+			this.updateWidget();
+			return false;
+		}
+		this.continuationIntent = undefined;
+		this.runOrigin = "continuation";
+		if (this.noteDelivery()) return true;
+		// A continuation is the work the coalesced wake would have asked for.
+		this.wakePending = false;
+		this.state = { ...loop, automaticTurns: loop.automaticTurns + 1 };
+		this.persist();
+		this.armFallback();
+		this.updateWidget();
+		return true;
 	}
 
 	// --- tick machinery ---
 
+	/**
+	 * Arm the fallback heartbeat, backing off while consecutive fallback wakes
+	 * keep producing no-op turns.
+	 */
+	private armFallback(): void {
+		const loop = this.state;
+		if (!loop || loop.status !== "active") return;
+		this.scheduleTick(this.fallbackDelayMs(loop));
+	}
+
+	fallbackDelayMs(loop: LoopState): number {
+		const multiplier = Math.min(MAX_FALLBACK_BACKOFF, 2 ** this.noOpStreak);
+		return Math.min(MAX_INTERVAL_MS, loop.intervalMs * multiplier);
+	}
+
 	private scheduleTick(delayMs: number): void {
 		this.clearTimer();
 		this.nextWakeAt = this.now() + delayMs;
@@ -185,10 +743,12 @@ export class LoopController {
 			case "none":
 				return;
 			case "skip":
-				if (decision.reason === "plan-mode-active") {
-					// Plan mode may end without an agent_settled we can use, so
-					// keep ticking until it does.
-					this.scheduleTick(loop.intervalMs);
+				if (decision.reason === "plan-mode-active" || decision.reason === "loop-waiting") {
+					// Plan mode may end without an agent_settled we can use, and a
+					// wait supersedes only this one fallback wake — in both cases
+					// keep the heartbeat armed rather than coalescing a wake that
+					// would fire the moment the hold ends.
+					this.armFallback();
 				} else {
 					// Busy or compacting: coalesce into one pending wake that
 					// the next agent_settled (or compaction onComplete) delivers.
@@ -211,14 +771,17 @@ export class LoopController {
 	): void {
 		switch (decision.action) {
 			case "expire":
-				this.transition("stopped", "loop expired (maxLoopDuration reached)");
+				if (decision.reason === "expiry-final-wake" && this.deliverExpiryWake(loop)) return;
+				this.transition("stopped", "loop expired (the expiry was reached)");
 				return;
 			case "stop":
 				this.transition(
 					"stopped",
 					decision.reason === "goal-complete"
 						? "the goal completed"
-						: `the ${loop.maxIterations}-iteration cap was reached`,
+						: decision.reason === "max-automatic-turns"
+							? `the ${loop.maxAutomaticTurns}-automatic-turn cap was reached`
+							: `the ${loop.maxIterations}-iteration cap was reached`,
 				);
 				return;
 			case "pause":
@@ -232,6 +795,46 @@ export class LoopController {
 		}
 	}
 
+	/**
+	 * One last turn at expiry, so the loop's most recent state lands in the
+	 * ledger instead of only in a conversation that is about to be closed. The
+	 * loop stays active for exactly that turn — the objective append has to be
+	 * present while it writes — and `expiring` makes the next settle stop it.
+	 *
+	 * Returns false when the wake could not be delivered, in which case the
+	 * caller stops the loop immediately rather than leaving it alive past its
+	 * expiry waiting for a turn that will not happen.
+	 */
+	private deliverExpiryWake(loop: LoopState): boolean {
+		if (loop.expiring) return false;
+		try {
+			this.pi.sendUserMessage(buildExpiryWake(loop, this.ledger));
+		} catch (error) {
+			this.sessionCtx?.ui.notify(
+				`pi-loop could not deliver the expiry wake: ${formatError(error)}. Stopping the loop.`,
+				"warning",
+			);
+			return false;
+		}
+		this.runOrigin = "fallback";
+		this.continuationIntent = undefined;
+		this.state = {
+			...this.consumeWait(loop),
+			iteration: loop.iteration + 1,
+			automaticTurns: loop.automaticTurns + 1,
+			lastWakeAt: this.now(),
+			expiring: true,
+		};
+		this.clearTimer();
+		this.persist();
+		this.updateWidget();
+		this.sessionCtx?.ui.notify(
+			"Loop expired: one final turn to write the current state down, then it stops.",
+			"info",
+		);
+		return true;
+	}
+
 	/**
 	 * Send first, then account. Pi can refuse the delivery (a busy or compacting
 	 * session), and an iteration persisted before the send would burn the
@@ -240,29 +843,39 @@ export class LoopController {
 	 */
 	private deliverPoke(
 		env: TickEnvironment,
-		reason: "goal-stalled" | "goal-waiting" | "objective-stalled",
+		reason: "goal-stalled" | "goal-waiting" | "objective-stalled" | "wait-elapsed",
 	): void {
 		const loop = this.state;
 		if (!loop) return;
+		const standalone = reason === "objective-stalled" || reason === "wait-elapsed";
 		// A goal-bound poke restates nothing, so it is only meaningful while the
 		// goal it points at is readable; a standalone poke needs no goal at all.
-		if (reason !== "objective-stalled" && !env.goal) return;
+		if (!standalone && !env.goal) return;
 		try {
 			this.pi.sendUserMessage(
-				reason === "objective-stalled" ? buildObjectivePoke(loop) : buildGoalPoke(loop, reason),
+				standalone ? buildObjectivePoke(loop, reason) : buildGoalPoke(loop, reason),
 			);
 		} catch (error) {
 			this.sessionCtx?.ui.notify(
 				`pi-loop could not deliver a wake: ${formatError(error)}. Retrying at the next interval.`,
 				"warning",
 			);
-			this.scheduleTick(loop.intervalMs);
+			this.armFallback();
 			this.updateWidget();
 			return;
 		}
-		this.state = { ...loop, iteration: loop.iteration + 1, lastWakeAt: env.now };
+		this.runOrigin = "fallback";
+		if (this.noteDelivery()) return;
+		// The wake consumed the wait it was arranged for, and any one-shot
+		// cancelled-wait hint it just carried.
+		this.state = {
+			...this.consumeWait(loop),
+			iteration: loop.iteration + 1,
+			automaticTurns: loop.automaticTurns + 1,
+			lastWakeAt: env.now,
+		};
 		this.persist();
-		this.scheduleTick(this.state.intervalMs);
+		this.armFallback();
 		this.updateWidget();
 	}
 
@@ -271,9 +884,16 @@ export class LoopController {
 		if (!loop || loop.status !== "active" || loop.compactAt === null) return false;
 		if (!this.settings.compaction.enabled || this.compacting) return false;
 		if (!ctx.isIdle() || ctx.hasPendingMessages()) return false;
-		const usage = ctx.getContextUsage();
-		if (!usage || typeof usage.tokens !== "number" || !usage.contextWindow) return false;
-		if (usage.tokens / usage.contextWindow < loop.compactAt) return false;
+		// A turn that overflowed the context window compacts regardless of the
+		// threshold: the usage reading that would gate it is exactly the reading
+		// the failed request just disproved.
+		const requested = this.compactionRequested;
+		this.compactionRequested = false;
+		if (!requested) {
+			const usage = ctx.getContextUsage();
+			if (!usage || typeof usage.tokens !== "number" || !usage.contextWindow) return false;
+			if (usage.tokens / usage.contextWindow < loop.compactAt) return false;
+		}
 		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
 		this.compacting = true;
 		try {
@@ -284,9 +904,11 @@ export class LoopController {
 					// objective the summary must preserve.
 					goal?.status === "active" ? goal : undefined,
 					this.settings.compaction.instructions,
+					this.ledger,
 				),
-				onComplete: () => {
+				onComplete: (result) => {
 					this.compacting = false;
+					this.requestReAnchor(result);
 					this.nudgeHeldWake();
 				},
 				onError: (error) => {
@@ -307,21 +929,41 @@ export class LoopController {
 	}
 
 	/**
-	 * A wake held during compaction delivers at the next settled boundary;
-	 * nudge in case that boundary already passed while compaction ran.
+	 * Own the post-compaction re-anchor instead of leaving the loop silent
+	 * until the next fallback wake. One pointer-sized continuation at the next
+	 * settle: the objective is in the system append, the record is in the
+	 * ledger, and the next actions ride out of the summary that just replaced
+	 * the conversation.
+	 */
+	private requestReAnchor(result: unknown): void {
+		const loop = this.state;
+		if (!loop || loop.status !== "active" || !isStandaloneLoop(loop)) return;
+		const summary =
+			isRecord(result) && typeof result.summary === "string" ? result.summary : undefined;
+		this.requestContinuation(loop, "reanchor", summary ? extractNextActions(summary) : undefined);
+	}
+
+	/**
+	 * A wake or continuation held during compaction delivers at the next
+	 * settled boundary; nudge in case that boundary already passed while
+	 * compaction ran.
 	 */
 	private nudgeHeldWake(): void {
 		const ctx = this.sessionCtx;
-		if (ctx && this.wakePending) this.onAgentSettled(ctx);
+		if (ctx && (this.wakePending || this.continuationIntent)) this.onAgentSettled(ctx);
 	}
 
 	// --- state transitions & presentation ---
 
-	private transition(status: "paused" | "stopped", why: string): void {
+	private transition(status: "paused" | "stopped", why: string, cause?: string): void {
 		if (!this.state) return;
-		this.state = { ...this.state, status };
+		const { waiting: _waiting, pauseCause: _pauseCause, ...rest } = this.state;
+		this.state = { ...rest, status, ...(cause ? { pauseCause: cause } : {}) };
 		this.clearTimer();
+		this.waitTimer.clear();
 		this.wakePending = false;
+		this.continuationIntent = undefined;
+		this.runOrigin = undefined;
 		this.persist();
 		this.sessionCtx?.ui.notify(`Loop ${status}: ${why}.`, "info");
 		this.updateWidget();
@@ -345,7 +987,19 @@ export class LoopController {
 			return;
 		}
 		if (loop.status === "paused") {
-			ui.setStatus(LOOP_STATUS_KEY, "loop paused");
+			ui.setStatus(
+				LOOP_STATUS_KEY,
+				loop.pauseCause ? `loop paused · ${loop.pauseCause}` : "loop paused",
+			);
+			return;
+		}
+		if (loop.waiting) {
+			ui.setStatus(
+				LOOP_STATUS_KEY,
+				`loop waiting · ${loop.waiting.reason}${
+					loop.waiting.resumeAt ? ` · until ${formatClock(loop.waiting.resumeAt)}` : ""
+				}`,
+			);
 			return;
 		}
 		const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
@@ -364,9 +1018,22 @@ export class LoopController {
 		const loop = this.state;
 		if (!loop) return ["No loop in this session. Start one with /loop <interval> [prompt]."];
 		const lines = [
-			`Status: ${loop.status}`,
+			`Status: ${loop.status}${loop.pauseCause ? ` (${loop.pauseCause})` : ""}`,
+			...(loop.waiting
+				? [
+						`Waiting: ${loop.waiting.reason}${
+							loop.waiting.resumeAt
+								? ` (wakes ${formatClock(loop.waiting.resumeAt)})`
+								: " (no deadline)"
+						}`,
+				  ]
+				: []),
+			...(loop.cancelledWaitReason
+				? [`Cancelled wait (reported on the next wake): ${loop.cancelledWaitReason}`]
+				: []),
 			`Interval: every ${formatDuration(loop.intervalMs)}`,
-			`Iterations: ${loop.iteration}${loop.maxIterations === null ? " (unlimited)" : ` of ${loop.maxIterations}`}`,
+			`Wakes: ${loop.iteration}${loop.maxIterations === null ? " (unlimited)" : ` of ${loop.maxIterations}`}`,
+			`Automatic turns: ${loop.automaticTurns}${loop.maxAutomaticTurns === null ? " (unlimited)" : ` of ${loop.maxAutomaticTurns}`}`,
 			`Started: ${new Date(loop.startedAt).toLocaleString()}`,
 			`Expires: ${new Date(loop.expiresAt).toLocaleString()}`,
 			`Proactive compaction: ${loop.compactAt === null ? "off" : `at ${Math.round(loop.compactAt * 100)}% of context`}`,
@@ -374,6 +1041,24 @@ export class LoopController {
 		if (loop.objective) {
 			lines.push("Mode: standalone (this loop owns its completion criteria)");
 			lines.push(`Objective: ${loop.objective}`);
+			if (this.ledger) {
+				const criteria = this.criteria();
+				lines.push(`Ledger: ${this.ledger.dir}`);
+				if (criteria) {
+					const met = criteria.filter((criterion) => criterion.passes).length;
+					lines.push(`Criteria: ${met}/${criteria.length} marked passing`);
+					lines.push(
+						...criteria.map(
+							(criterion) =>
+								`  [${criterion.passes ? "x" : " "}] ${criterion.id}. ${criterion.description}`,
+						),
+					);
+				} else {
+					lines.push("Criteria: unreadable (the loop runs without them)");
+				}
+			} else {
+				lines.push("Ledger: unavailable (the loop runs without one)");
+			}
 		} else {
 			lines.push("Mode: goal-bound (pi-goal owns completion)");
 		}
@@ -383,7 +1068,16 @@ export class LoopController {
 			: readGoalSnapshot(ctx.sessionManager.getBranch());
 		if (goal) lines.push(`Goal (pi-goal): ${goal.status} — ${goal.text}`);
 		if (this.nextWakeAt && loop.status === "active") {
-			lines.push(`Next wake: ${formatClock(this.nextWakeAt)}`);
+			lines.push(
+				`${isStandaloneLoop(loop) ? "Next fallback wake" : "Next wake"}: ${formatClock(this.nextWakeAt)}${
+					this.noOpStreak > 0
+						? ` (backed off ×${Math.min(MAX_FALLBACK_BACKOFF, 2 ** this.noOpStreak)} after ${this.noOpStreak} no-op wake${this.noOpStreak === 1 ? "" : "s"})`
+						: ""
+				}`,
+			);
+		}
+		if (this.continuationIntent) {
+			lines.push("A continuation is queued for the next idle boundary.");
 		}
 		if (this.wakePending) lines.push("A wake is pending delivery at the next idle boundary.");
 		if (this.lastDecision) {
@@ -417,7 +1111,18 @@ export class LoopController {
 			);
 			return;
 		}
-		const expiryMs = parseDuration(this.settings.maxLoopDuration) ?? 604_800_000;
+		// A standalone loop with no way to call loop_complete would work, finish,
+		// and then be told to keep working until it hit a cap. Refuse at the door
+		// rather than after the first turn.
+		if (objective && !this.completeToolAvailable()) {
+			ctx.ui.notify(
+				`This session has no ${LOOP_COMPLETE_TOOL} tool, so a loop could never end itself. Re-enable it (it is excluded by --tools/--no-tools or a tool policy) and start the loop again.`,
+				"error",
+			);
+			return;
+		}
+		const expiryMs =
+			start.expiresInMs ?? parseDuration(this.settings.maxLoopDuration) ?? 604_800_000;
 		const compactAt =
 			start.compactAt !== undefined
 				? start.compactAt
@@ -434,24 +1139,85 @@ export class LoopController {
 			intervalMs: start.intervalMs,
 			maxIterations:
 				start.maxIterations !== undefined ? start.maxIterations : this.settings.maxIterations,
+			maxAutomaticTurns: this.settings.automaticTurns,
 			compactAt,
 			iteration: 0,
+			automaticTurns: 0,
 			startedAt: now,
 			expiresAt: now + expiryMs,
 		};
 		this.wakePending = false;
+		this.continuationIntent = undefined;
+		this.noOpStreak = 0;
+		this.ledgerWarned = false;
+		this.openLedger(this.state);
 		this.persist();
 		this.scheduleTick(start.intervalMs);
 		this.updateWidget();
 		const clampNote = start.clamped
 			? ` (requested ${formatDuration(start.requestedMs)}, clamped to the ${formatDuration(start.intervalMs)} minimum)`
 			: "";
+		if (goalBound) {
+			ctx.ui.notify(
+				"Binding a loop to an active /goal is deprecated and will be removed. pi-loop now owns long-running work on its own: stop the goal and run /loop <interval> <objective> instead.",
+				"warning",
+			);
+		}
 		ctx.ui.notify(
 			goalBound
 				? `Loop started: every ${formatDuration(start.intervalMs)}${clampNote}, first wake at ${formatClock(now + start.intervalMs)}, poking the active goal${start.prompt ? " with the loop focus" : ""}. Stop with /loop stop.`
-				: `Loop started: every ${formatDuration(start.intervalMs)}${clampNote}, first wake at ${formatClock(now + start.intervalMs)}, working its own objective until the criteria are met (loop_complete), the cap is reached, or you run /loop stop.`,
+				: `Loop started: working its own 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(start.intervalMs)}${clampNote} if the session goes quiet. Expires in ${formatDuration(expiryMs)} (one final turn to write its state down, then it stops).`,
 			"info",
 		);
+		if (this.ledger) {
+			const criteria = this.criteria() ?? [];
+			ctx.ui.notify(
+				[
+					`Loop ledger: ${this.ledger.dir}`,
+					`Completion criteria (${criteria.length}) — loop_complete answers for these:`,
+					...criteria.map((criterion) => `  ${criterion.id}. ${criterion.description}`),
+				].join("\n"),
+				"info",
+			);
+		}
+		// The kickoff anchor: one stored message per loop holding the objective
+		// data, because the system append exists only while the loop is active.
+		this.sendKickoffAnchor(ctx);
+		// Immediate kickoff: a standalone loop starts working now instead of
+		// burning its first interval idle. A busy session keeps the intent and
+		// delivers it at the settle.
+		if (this.state && isStandaloneLoop(this.state)) {
+			this.requestContinuation(this.state, "kickoff");
+			this.dispatchContinuationIfSettled(ctx);
+		}
+	}
+
+	/**
+	 * Store the objective as an ordinary message so it outlives the loop.
+	 *
+	 * At an idle boundary `sendMessage` appends the message with no turn, which
+	 * is exactly an anchor. While the agent streams the same call would *steer*
+	 * the running turn, so a busy session gets `nextTurn` instead: queued as
+	 * context alongside the next prompt, interrupting nothing.
+	 */
+	private sendKickoffAnchor(ctx: ExtensionContext): void {
+		const loop = this.state;
+		if (!loop || !isStandaloneLoop(loop) || !this.ledger) return;
+		const idle = ctx.isIdle() && !ctx.hasPendingMessages();
+		try {
+			this.pi.sendMessage(
+				{
+					customType: LOOP_ANCHOR_MESSAGE_TYPE,
+					content: buildKickoffAnchor(loop, this.ledger),
+					display: true,
+					details: { loopId: loop.id },
+				},
+				idle ? {} : { deliverAs: "nextTurn" },
+			);
+		} catch (error) {
+			// The anchor is a durability nicety; the loop runs without it.
+			ctx.ui.notify(`pi-loop could not anchor the objective: ${formatError(error)}.`, "warning");
+		}
 	}
 
 	pauseLoop(ctx: ExtensionContext): void {
@@ -488,14 +1254,25 @@ export class LoopController {
 			);
 			return;
 		}
-		this.state = { ...loop, status: "active" };
+		// Resuming starts a fresh safety epoch: the user has seen why it paused
+		// and chosen to continue, so the breaker must not trip on stale counters.
+		const { pauseCause: _cause, lastFingerprint: _fingerprint, ...rest } = loop;
+		this.state = { ...rest, status: "active", toolFreeRepeatCount: 0 };
+		this.noOpStreak = 0;
 		this.persist();
 		this.scheduleTick(loop.intervalMs);
 		this.updateWidget();
 		ctx.ui.notify(
-			`Loop resumed: next wake at ${formatClock(this.now() + loop.intervalMs)}.`,
+			isStandaloneLoop(loop)
+				? `Loop resumed: continuing now, with a fallback wake every ${formatDuration(loop.intervalMs)}.`
+				: `Loop resumed: next wake at ${formatClock(this.now() + loop.intervalMs)}.`,
 			"info",
 		);
+		// Resuming a standalone loop resumes the work, not just the heartbeat.
+		if (this.state && isStandaloneLoop(this.state)) {
+			this.requestContinuation(this.state);
+			this.dispatchContinuationIfSettled(ctx);
+		}
 	}
 
 	/** Re-arm the timer after an interval edit while active. */
@@ -525,3 +1302,22 @@ export class LoopController {
 function formatError(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
+
+/**
+ * A run that called no tool did nothing to the world. It is the signal the
+ * fallback backoff needs today; Stage 6's `LOOP_OK` acknowledgement refines
+ * the same counter rather than replacing it.
+ */
+function isNoOpRun(messages: readonly unknown[]): boolean {
+	for (const message of messages) {
+		if (!isRecord(message) || message.role !== "assistant" || !Array.isArray(message.content)) {
+			continue;
+		}
+		if (message.content.some((block) => isRecord(block) && block.type === "toolCall")) return false;
+	}
+	return true;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}