@hank-warren/pi-loop 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @hank-warren/pi-loop
 
+## 1.1.0
+
+### Minor Changes
+
+- c079c51: Stage the loop tools behind the workflow that needs them, and stop a loop that outlives its deadline.
+
+  `loop_propose` activates when planning opens and the runtime trio (`loop_complete`, `loop_progress`, `loop_wait`) when a valid proposal exists, so a session that never touches `/loop` no longer carries four Loop-only schemas in its cached prompt prefix. Every tool stays registered, so a historical transcript still resolves it. An active loop re-asserts its runtime tools on every turn, which is what lets a paused loop restored in a later session be resumed and still finish itself.
+
+  An expiry watchdog armed on the exact `expiresAt` now ends a loop that has gone quiet past its deadline, independently of the fallback interval, and a bounded grace period stops a loop whose final expiry turn never starts — `sendUserMessage` is fire-and-forget, so an accepted wake is not a delivered one. Terminal states persist a `terminalReason`, and callbacks are loop-identity guarded.
+
+  Plan mode now owns the prompt outright: while it is enabled the loop injects neither its planning hint nor its objective, and resumes on the first turn after `/plan exit` without rewriting persisted state.
+
+  The approval card is a display-only session entry rendered through `registerEntryRenderer` rather than a message, so it stays visible and restorable while never entering model context or compaction. The internal `LOOP_PROPOSAL_MESSAGE_TYPE` constant is replaced by `LOOP_PROPOSAL_ENTRY_TYPE`; it was never exported from the package entry point.
+
 ## 1.0.0
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Long-running work for Pi: settle-paced loops with a durable ledger, adaptive waits, no-progress breakers, evidence-gated completion, and a task scheduler.",
   "type": "module",
   "keywords": [

package/src/index.ts

@@ -12,6 +12,7 @@ import { parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
 import { registerLoopProgressTool } from "./progress-tool.js";
 import { registerLoopProposeTool } from "./propose-tool.js";
+import { registerLoopProposalRenderer } from "./presentation.js";
 import { LOOP_PLANNING_HINT } from "./planning.js";
 import { registerLoopWaitTool } from "./wait-tool.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
@@ -23,6 +24,7 @@ import {
 } from "./manager.js";
 import { buildLoopObjectivePrompt } from "./objective.js";
 import { registerLoopMessageRendering } from "./render.js";
+import { readPlanModeEnabled } from "./state.js";
 
 /** What the planning menu's "Request proposal now" asks for. */
 export const REQUEST_PROPOSAL_MESSAGE =
@@ -30,16 +32,36 @@ export const REQUEST_PROPOSAL_MESSAGE =
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
-	// Registered unconditionally and never toggled with loop state: tools are
-	// part of the cached request prefix, so mutating the tool set mid-session
-	// would invalidate the whole conversation cache. It refuses when no loop is
-	// active.
+	const proposeTools = ["loop_propose"];
+	const runtimeTools = ["loop_complete", "loop_progress", "loop_wait"];
+	let proposeActivated = false;
+	let runtimeActivated = false;
+	const reconcileTools = () => {
+		const active = pi.getActiveTools();
+		const wanted = new Set(active);
+		for (const name of proposeTools) proposeActivated ? wanted.add(name) : wanted.delete(name);
+		for (const name of runtimeTools) runtimeActivated ? wanted.add(name) : wanted.delete(name);
+		const next = [...wanted];
+		if (next.length !== active.length || next.some((name, index) => name !== active[index])) {
+			pi.setActiveTools(next);
+		}
+	};
+	const activatePropose = () => {
+		proposeActivated = true;
+		reconcileTools();
+	};
+	const activateRuntime = () => {
+		runtimeActivated = true;
+		reconcileTools();
+	};
+
 	registerLoopCompleteTool(pi, controller);
-	// Registered on the same terms and for the same reason: the tool set is
-	// part of the cached prefix, so it never changes with loop state.
 	registerLoopWaitTool(pi, controller);
 	registerLoopProgressTool(pi, controller);
-	registerLoopProposeTool(pi, controller);
+	registerLoopProposeTool(pi, controller, activateRuntime);
+	registerLoopProposalRenderer(pi);
+	// Narrowing happens at session_start, never here: Pi refuses action methods
+	// (getActiveTools/setActiveTools among them) during extension loading.
 	// Collapse loop pokes into one-line transcript chips (display-only; the
 	// stored message and model context are untouched).
 	registerLoopMessageRendering(pi);
@@ -61,6 +83,7 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 
 	const beginPlanning = (ctx: ExtensionCommandContext): void => {
 		if (controller.planning.active) return;
+		activatePropose();
 		controller.beginPlanning();
 		ctx.ui.notify(
 			"Loop planning. Describe what you want the loop to achieve and how you will know it is done; the agent drafts it and puts it up for approval. Nothing starts until you approve it.",
@@ -110,7 +133,11 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		proposeActivated = false;
+		runtimeActivated = false;
 		controller.onSessionStart(ctx);
+		if (controller.state?.status === "active") activateRuntime();
+		else reconcileTools();
 	});
 	pi.on("session_shutdown", async () => {
 		controller.onSessionShutdown();
@@ -129,7 +156,21 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	// A loop carries its own objective and injects it as a byte-stable system
 	// append, which is what lets the poke and continuation messages stay
 	// pointer-sized.
-	pi.on("before_agent_start", (event) => {
+	pi.on("before_agent_start", (event, ctx) => {
+		// Self-heal the runtime tool set every turn an active loop takes, not just
+		// at session_start. `resumeLoop` flips a restored *paused* loop to active
+		// and dispatches a continuation from the /loop menu, which has no way to
+		// reach activateRuntime — so without this the resumed loop would run with
+		// loop_complete stripped, be told by its own objective append to call it,
+		// and then be re-paused by enforceToolAvailability blaming --tools for
+		// something this extension did to itself. Activation is monotonic, so this
+		// covers resumeAfterEdit and the fresh-session handoff too, and costs a
+		// no-op set comparison on every other turn.
+		if (controller.state?.status === "active") activateRuntime();
+		// Plan mode owns the prompt while active. Loop scheduling is already held
+		// by the same persisted state; suppressing the append removes the remaining
+		// mixed-workflow instruction surface.
+		if (readPlanModeEnabled(ctx.sessionManager.getBranch())) return;
 		// Planning precedes any loop, so its guidance is injected on the same hook
 		// and is mutually exclusive with the objective append below.
 		if (controller.planning.active) {

package/src/loop.ts

@@ -121,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;
@@ -165,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 {
@@ -177,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;
@@ -186,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;
@@ -229,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;
@@ -274,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);
 		}
@@ -306,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;
@@ -835,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 {
@@ -922,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,
@@ -930,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(
@@ -1048,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;
@@ -1131,7 +1224,7 @@ export class LoopController {
 		const loop = this.state;
 		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}${
@@ -1351,6 +1444,7 @@ 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)`
@@ -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)}.`,

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/propose-tool.ts

@@ -20,7 +20,11 @@ import { MAX_GROUND_RULE_LENGTH, MAX_GROUND_RULES } from "./planning.js";
 
 export const LOOP_PROPOSE_TOOL = "loop_propose";
 
-export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopController) {
+export function registerLoopProposeTool(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	onProposed?: () => void,
+) {
 	pi.registerTool(
 		defineTool({
 			name: LOOP_PROPOSE_TOOL,
@@ -116,6 +120,7 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 
 				const proposal = controller.propose(objective, overrides);
+				onProposed?.();
 				// 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

package/src/state.ts

@@ -63,6 +63,8 @@ export interface LoopState {
 	lastFingerprint?: string;
 	/** Why a paused loop paused, for the widget and status after a restore. */
 	pauseCause?: string;
+	/** Durable reason recorded when the loop enters its terminal stopped state. */
+	terminalReason?: string;
 	/**
 	 * Set once the expiry's final wake has been delivered. The loop is still
 	 * active for exactly that one turn, so the objective append is present
@@ -144,6 +146,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	if (cancelledWaitReason === false) return undefined;
 	const pauseCause = optionalText(record.pauseCause);
 	if (pauseCause === false) return undefined;
+	const terminalReason = optionalText(record.terminalReason);
+	if (terminalReason === false) return undefined;
 	const toolFreeRepeatCount = record.toolFreeRepeatCount;
 	if (
 		toolFreeRepeatCount !== undefined &&
@@ -176,6 +180,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(toolFreeRepeatCount === undefined ? {} : { toolFreeRepeatCount }),
 		...(lastFingerprint === undefined ? {} : { lastFingerprint }),
 		...(pauseCause === undefined ? {} : { pauseCause }),
+		...(terminalReason === undefined ? {} : { terminalReason }),
 		...(record.expiring === true ? { expiring: true as const } : {}),
 		...(record.handoff === true ? { handoff: true as const } : {}),
 	};