@hank-warren/pi-loop 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @hank-warren/pi-loop
 
+## 1.2.0
+
+### Minor Changes
+
+- 1035138: Ship the craft documents by injected path instead of as skills.
+
+  The `pi-loop` and `pi-plan-mode` skills are gone. Their bodies now ship as
+  `docs/loop-craft.md` and `docs/plan-craft.md`, and the mode prompts inject the
+  file's absolute path (resolved from the installed package) at the moments the
+  guidance matters: while a loop is being drafted or completed, and while Plan
+  Mode is active. A skill's description line sits in every system prompt of every
+  session with the package loaded; across ~220 sessions after these two shipped,
+  every read of either file was triggered by the mode's own prompt and never by
+  the description, so the line was a tax on the ~95% of sessions that never
+  entered the mode. Same document, read at the same moments, at zero cost outside
+  them. Hosts that referenced the skills by name in settings should drop those
+  entries.
+
+- 1035138: Deprecated in favour of `@hank-warren/pi-orchestrator`.
+
+  pi-loop is a pacemaker for one session that cannot be trusted to pace itself. The
+  `pi-orchestrator` skill is a supervising pi session watching real pi sessions in
+  Herdr panes — reading their state, answering their prompts within policy,
+  steering, and verifying their claims — which does by judgment what the loop
+  engine did by pacing and gates. This package stays published and continues to
+  work; it is no longer loaded by the git install of the `pi-extensions`
+  repository and receives no new features. The README opens with the notice.
+
+## 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/README.md

@@ -1,5 +1,7 @@
 # pi-loop — long-running work for the Pi coding agent
 
+> **Deprecated.** pi-loop is no longer loaded by the git install of this repository and receives no new features. Its role — keeping autonomous work moving and gating completion on evidence — has moved to the [`pi-orchestrator`](../pi-orchestrator) skill package: a supervising pi session watching real pi sessions in Herdr panes, reading their state, answering their prompts within policy, steering them, and verifying their claims. A loop is a pacemaker for one session that cannot be trusted to pace itself; a supervisor with fresh context does that by judgment, and can see, attach to, and redirect each child. The package stays on npm and continues to install with `pi install npm:@hank-warren/pi-loop` for anyone who prefers it.
+
 Inspired by Claude Code's `/loop`, adapted to Pi: keep work moving across many turns, and keep long loops coherent across context compaction.
 
 A loop is a **pacemaker** that owns its own work: it carries an objective, completion criteria and ground rules, and ends when the model calls `loop_complete` with cited evidence, its expiry arrives, a cap you set is reached, or you stop it. Every loop is planned with you and started from an approval card. **No other extension is required.**
@@ -205,13 +207,13 @@ These were considered and cut, and the reasoning is recorded so they are not sil
 - **No judge model.** Grading completion with a second model is a larger, more expensive change than the criteria/evidence gate; the gate is the rung that ships.
 - **No `loop_blocked` tool.** `loop_wait` covers a real external dependency, and the no-progress breaker covers an impasse the model does not recognise as one. A third "I give up" tool mostly gives a model a way to stop early. `compaction.instructions` overrides the built-in template.
 
-## The companion skill
+## The loop-craft doc
 
-The package is a hybrid: it ships the extension **and** a `pi-loop` skill (`skills/pi-loop/SKILL.md`), which carries the judgment the engine cannot encode — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all.
+The engine cannot encode the judgment that decides whether a loop is worth running — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all. That lives in [`docs/loop-craft.md`](docs/loop-craft.md), which ships with the package.
 
-It is **loaded on demand**: the planning hint and `loop_complete`'s prompt guidelines point at it by name, exactly as `pi-processes` does, and the model reads the body when it judges it needs it. Nothing about the guidance enters a stored loop message or the system append — those bytes are the cache prefix, and `test/bytes.test.ts` fails if any of them so much as mentions a skill.
+It is **loaded on demand**: the planning hint and `loop_complete`'s prompt guidelines name it by absolute path (resolved from the installed package, so it works under any install layout) and the model reads it when it reaches those moments. Nothing about the guidance enters a stored loop message or the system append — those bytes are the cache prefix, and `test/bytes.test.ts` fails if any of them so much as mentions it.
 
-Skill and extension version as one artifact on purpose: a skill describing an engine the installed extension does not have is the coupling failure this repository already learned once.
+It used to be a skill. A skill's description line is in every system prompt, which buys exactly one thing an injected pointer cannot: the model proposing a loop unprompted. Across ~220 sessions after it shipped, every read of the file was triggered by the planning hint or the completion tool, never by the description, and the model never suggested `/loop` on its own — so the line was a tax on every session that never ran a loop (about 95% of them) that bought nothing. A hard path injected only while a loop is being drafted or completed is the same document at zero cost outside those moments.
 
 ## Install
 
@@ -221,6 +223,10 @@ pi install npm:@hank-warren/pi-loop
 
 **No other extension is required.** The only sibling state pi-loop reads is [pi-plan-mode](https://www.npmjs.com/package/@hank-warren/pi-plan-mode)'s, fail-open, so a loop never injects into a planning conversation — and it works fine without it.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT

package/{skills/pi-loop/SKILL.md → docs/loop-craft.md}

@@ -1,9 +1,3 @@
----
-name: pi-loop
-description: Draft loop objectives that become falsifiable criteria, set cadence and ground rules, and complete a loop with evidence the gate accepts. Use while drafting a loop in /loop planning, before calling loop_propose, before assembling loop_complete evidence, and when deciding whether work belongs in a loop at all.
-license: MIT
----
-
 # pi-loop
 
 The engine handles pacing, wakes, compaction, and the ledger. It cannot handle the three things that decide whether a loop is worth running: **what end state the objective names**, **what constraints bound the work**, and **what evidence proves it is done**. That is this file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "1.0.0",
+  "version": "1.2.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": [
@@ -29,15 +29,12 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ],
-    "skills": [
-      "./skills/pi-loop"
     ]
   },
   "files": [
     "index.ts",
     "src",
-    "skills",
+    "docs/loop-craft.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/src/command.ts

@@ -17,7 +17,7 @@
  * of having exactly one way in, and the menu is one keystroke away.
  */
 
-export type LoopCommand =
+type LoopCommand =
 	/** Bare `/loop`: open whichever menu the current state calls for. */
 	| { kind: "menu" }
 	/** `/loop <text>`: enter planning and send the text as the first message. */

package/src/complete-tool.ts

@@ -24,6 +24,7 @@
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { LOOP_CRAFT_DOC } from "./docs.js";
 import type { LoopController } from "./loop.js";
 import type { LoopCriterion } from "./ledger.js";
 
@@ -92,7 +93,7 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 				"Pass the exact loop_id from the active /loop objective in the system prompt. A mismatched id means the loop changed and the call is refused.",
 				"loop_complete stops scheduled wakeups only. It does not mean an unrelated goal or task is complete.",
 				"If the criteria are not met, do not call it: keep working and expect another continuation.",
-				"Before your first loop_complete this session, read the pi-loop skill: it describes what the evidence gate accepts as a citation and what it refuses.",
+				`Before your first loop_complete this session, read ${LOOP_CRAFT_DOC}: it describes what the evidence gate accepts as a citation and what it refuses.`,
 			],
 			parameters: Type.Object({
 				loop_id: Type.String({

package/src/decide.ts

@@ -37,9 +37,9 @@ function isWaiting(loop: LoopState, now: number): boolean {
  * An expiring loop gets one last turn to write its state into the ledger
  * before it stops; a loop already spending that turn stops immediately.
  */
-export type ExpiryReason = "loop-expired" | "expiry-final-wake";
+type ExpiryReason = "loop-expired" | "expiry-final-wake";
 
-export type SkipReason =
+type SkipReason =
 	| "plan-mode-active"
 	| "agent-busy"
 	| "compaction-in-flight"

package/src/docs.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+
+/**
+ * The loop-craft document: the judgment the engine cannot encode — how an
+ * objective becomes falsifiable criteria, what the evidence gate accepts as a
+ * citation, when to `loop_wait`, and when work belongs in no loop at all.
+ *
+ * It used to ship as a skill. A skill buys one thing an injected pointer
+ * cannot: a description line in every system prompt, so the model could
+ * propose a loop unprompted. Across ~220 sessions after it shipped, every read
+ * of the file was triggered by the planning hint or `loop_complete`'s
+ * guidelines — never by the description — and the model never suggested
+ * `/loop` on its own. So the line was a tax on every session that never ran a
+ * loop (~95% of them) and bought nothing. An absolute path, injected only
+ * while a loop is being drafted or completed, is the same document at zero
+ * cost outside those moments, and a hard path beats "if it is available".
+ *
+ * The path is resolved from this module's own location so it survives every
+ * install layout (git, npm, workspace symlink, `npm link`).
+ */
+export const LOOP_CRAFT_DOC = join(import.meta.dirname, "..", "docs", "loop-craft.md");

package/src/errors.ts

@@ -19,7 +19,7 @@ import {
 	type Usage,
 } from "@earendil-works/pi-ai";
 
-export type LoopInterruption =
+type LoopInterruption =
 	/** The turn finished normally. */
 	| "none"
 	/** The user (or another extension) aborted the turn. */

package/src/fresh-launch.ts

@@ -27,14 +27,14 @@ import { LOOP_STATE_ENTRY_TYPE } from "./state.js";
 type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
 type SessionManagerLike = Parameters<NonNullable<NewSessionOptions["setup"]>>[0];
 
-export type FreshLoopResult =
+type FreshLoopResult =
 	| { kind: "started" }
 	| { kind: "cancelled" }
 	/** The session exists and holds the loop, but it could not be kicked off. */
 	| { kind: "partial"; detail: string }
 	| { kind: "rejected"; detail: string };
 
-export interface FreshLoopRequest {
+interface FreshLoopRequest {
 	built: BuiltLoop;
 	/** Write the ledger for `built` before the handoff; returns a failure detail. */
 	prepareLedger(): string | undefined;

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/interval.ts

@@ -27,7 +27,7 @@ export function parseDuration(token: string): number | undefined {
 	return ms > MAX_INTERVAL_MS ? undefined : ms;
 }
 
-export interface ParsedInterval {
+interface ParsedInterval {
 	requestedMs: number;
 	/** Clamped to MIN_INTERVAL_MS; the caller must echo the effective value. */
 	effectiveMs: number;

package/src/ledger.ts

@@ -26,13 +26,13 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export const LEDGER_DIR_NAME = "loop";
+const LEDGER_DIR_NAME = "loop";
 export const CRITERIA_FILE = "criteria.json";
 export const PROGRESS_FILE = "PROGRESS.md";
 
 /** Cap on a loop's criteria: an objective is a paragraph, not a backlog. */
-export const MAX_CRITERIA = 12;
-export const MAX_DESCRIPTION_LENGTH = 500;
+const MAX_CRITERIA = 12;
+const MAX_DESCRIPTION_LENGTH = 500;
 
 export interface LoopCriterion {
 	id: string;
@@ -75,7 +75,7 @@ export const MAX_EVIDENCE_LENGTH = 4000;
 /** The template's placeholders, replaced rather than appended to on first write. */
 const PLACEHOLDERS = new Set(["not started.", "- (nothing yet)"]);
 
-export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
+function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
 	return join(agentDir, LEDGER_DIR_NAME, loopId);
 }
 
@@ -234,7 +234,7 @@ export function createLedger(
 	}
 }
 
-export function progressTemplate(objective: string): string {
+function progressTemplate(objective: string): string {
 	return [
 		"# Loop progress ledger",
 		"",
@@ -320,7 +320,7 @@ function headingText(line: string | undefined): string | undefined {
 	return match ? match[1].toLowerCase() : undefined;
 }
 
-export interface MarkCriterionResult {
+interface MarkCriterionResult {
 	ok: boolean;
 	message: string;
 	criteria?: LoopCriterion[];

package/src/loop-action-menus.ts

@@ -18,7 +18,7 @@ import type { ActionsScreen } from "@narumitw/pi-tui-kit";
 import { formatDuration } from "./interval.js";
 import type { LoopProposal } from "./planning.js";
 
-export type LoopApprovalAction =
+type LoopApprovalAction =
 	| "start-here"
 	| "start-fresh"
 	| "change-cadence"
@@ -27,7 +27,7 @@ export type LoopApprovalAction =
 
 type Screen = "approval";
 
-export interface LoopApprovalMenuOptions {
+interface LoopApprovalMenuOptions {
 	proposal: LoopProposal;
 	signal?: AbortSignal;
 	isCurrent?(): boolean;

package/src/loop-env.ts

@@ -25,8 +25,8 @@
 
 import type { LoopState } from "./state.js";
 
-export const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
-export const LOOP_ID_ENV = "PI_LOOP_ID";
+const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
+const LOOP_ID_ENV = "PI_LOOP_ID";
 
 /**
  * Publish (or withdraw) the loop-active signal for `loop`.

package/src/loop-launch-menu.ts

@@ -15,9 +15,9 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ActionsScreen, DetailScreen } from "@narumitw/pi-tui-kit";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export type LoopLaunchScreen = "main" | "how";
-export type LoopLaunchAction = "start-planning" | "settings";
-export type LoopPlanningAction = "request-proposal" | "cancel" | "settings";
+type LoopLaunchScreen = "main" | "how";
+type LoopLaunchAction = "start-planning" | "settings";
+type LoopPlanningAction = "request-proposal" | "cancel" | "settings";
 
 /**
  * What a loop actually is, for someone who has never run one.
@@ -95,7 +95,7 @@ export function loopPlanningScreen(): ActionsScreen<LoopLaunchScreen, LoopPlanni
 	};
 }
 
-export interface LoopLaunchMenuOptions {
+interface LoopLaunchMenuOptions {
 	signal?: AbortSignal;
 	isCurrent?(): boolean;
 	startPlanning(): void;
@@ -120,7 +120,7 @@ export async function showLoopLaunchMenu(ctx: ExtensionContext, options: LoopLau
 	return runMenu(ctx, menu, { getState: () => undefined, ...lifecycle(options) });
 }
 
-export interface LoopPlanningMenuOptions {
+interface LoopPlanningMenuOptions {
 	signal?: AbortSignal;
 	isCurrent?(): boolean;
 	requestProposal(): void;

package/src/loop-manager-menu.ts

@@ -18,8 +18,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ActionsScreen, DetailScreen, InputScreen } from "@narumitw/pi-tui-kit";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
-export type LoopManagerAction =
+type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
+type LoopManagerAction =
 	| "pause"
 	| "resume"
 	| "stop"
@@ -128,7 +128,7 @@ export function loopCadenceScreen(view: LoopManagerView): InputScreen<LoopManage
 	};
 }
 
-export interface LoopManagerMenuOptions {
+interface LoopManagerMenuOptions {
 	getView(): LoopManagerView | undefined;
 	signal?: AbortSignal;
 	isCurrent?(): boolean;

package/src/loop.ts

@@ -99,7 +99,7 @@ import {
 	updateLoopWidget,
 } from "./widget.js";
 
-export const LOOP_STATUS_KEY = "loop";
+const LOOP_STATUS_KEY = "loop";
 
 /** Custom message type of the kickoff anchor. */
 export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
@@ -109,7 +109,7 @@ export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
  * 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;
+const MAX_FALLBACK_BACKOFF = 4;
 
 /**
  * How long a single run may stay open before the widget calls it blocked.
@@ -121,9 +121,18 @@ 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.
+ */
+const EXPIRY_TURN_GRACE_MS = 60_000;
 
 /** Consecutive loop deliveries that produce no run before the loop pauses. */
-export const MAX_DEAD_DELIVERIES = 3;
+const MAX_DEAD_DELIVERIES = 3;
 
 /** Why the loop caused the run that is currently in flight. */
 type RunOrigin = "continuation" | "fallback";
@@ -136,7 +145,7 @@ type RunOrigin = "continuation" | "fallback";
  * 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 };
+type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
 
 /**
  * A loop that exists but is not running anywhere: everything `installLoop`
@@ -151,7 +160,7 @@ export interface BuiltLoop {
 	requestedMs: number;
 }
 
-export type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
+type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
 
 interface ContinuationIntent {
 	loopId: string;
@@ -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/manager.ts

@@ -160,7 +160,7 @@ function setCadence(
 	return true;
 }
 
-export async function showLoopSettings(
+async function showLoopSettings(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
 ): Promise<void> {

package/src/planning.ts

@@ -17,6 +17,7 @@
  * gone: both authored an acceptance gate in one line, unreviewed.
  */
 
+import { LOOP_CRAFT_DOC } from "./docs.js";
 import { deriveCriteria, type LoopCriterion } from "./ledger.js";
 import { formatDuration } from "./interval.js";
 
@@ -132,7 +133,7 @@ export function renderProposalCard(proposal: LoopProposal): string[] {
 export const LOOP_PLANNING_HINT = [
 	"<system-reminder>",
 	"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.",
+	`Before drafting, read ${LOOP_CRAFT_DOC}: 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.",

package/src/presentation.ts

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

package/src/progress-tool.ts

@@ -33,7 +33,7 @@ import {
 } from "./ledger.js";
 import type { LoopController } from "./loop.js";
 
-export const LOOP_PROGRESS_TOOL = "loop_progress";
+const LOOP_PROGRESS_TOOL = "loop_progress";
 
 export function registerLoopProgressTool(pi: ExtensionAPI, controller: LoopController) {
 	pi.registerTool(

package/src/propose-tool.ts

@@ -18,9 +18,13 @@ import { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import type { LoopController } from "./loop.js";
 import { MAX_GROUND_RULE_LENGTH, MAX_GROUND_RULES } from "./planning.js";
 
-export const LOOP_PROPOSE_TOOL = "loop_propose";
+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/safety.ts

@@ -20,7 +20,7 @@
 
 import { createHash } from "node:crypto";
 
-export interface NoProgressState {
+interface NoProgressState {
 	toolFreeRepeatCount: number;
 	lastFingerprint?: string;
 }

package/src/settings.ts

@@ -11,9 +11,9 @@ import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseDuration } from "./interval.js";
 
-export const LOOP_SETTINGS_FILE = "pi-loop.json";
+const LOOP_SETTINGS_FILE = "pi-loop.json";
 
-export interface LoopCompactionSettings {
+interface LoopCompactionSettings {
 	enabled: boolean;
 	/** Fraction of the context window that triggers a proactive compact. */
 	threshold: number;
@@ -82,7 +82,7 @@ export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
 	},
 };
 
-export type LoopSettingsLoadResult =
+type LoopSettingsLoadResult =
 	| { kind: "missing"; settings: LoopSettings }
 	| { kind: "invalid"; reason: string; settings: LoopSettings }
 	| { kind: "loaded"; settings: LoopSettings };

package/src/state.ts

@@ -11,8 +11,8 @@ export const PLAN_MODE_STATE_ENTRY_TYPE = "plan-mode-state";
 
 import { type LoopWait, normalizeLoopWait } from "./wait.js";
 
-export const LOOP_STATUSES = ["active", "paused", "stopped"] as const;
-export type LoopStatus = (typeof LOOP_STATUSES)[number];
+const LOOP_STATUSES = ["active", "paused", "stopped"] as const;
+type LoopStatus = (typeof LOOP_STATUSES)[number];
 
 export interface LoopState {
 	id: string;
@@ -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 } : {}),
 	};

package/src/widget.ts

@@ -45,13 +45,13 @@ interface WidgetTheme {
 type WidgetHost = { setWidget?: unknown };
 
 /** Criteria progress, absent when the loop has no readable ledger. */
-export interface CriteriaProgress {
+interface CriteriaProgress {
 	met: number;
 	total: number;
 }
 
 /** The loop is being drafted with the user and has not started. */
-export interface LoopPlanningView {
+interface LoopPlanningView {
 	kind: "planning";
 	/** Criteria in the proposed draft, once one has been put up for approval. */
 	proposedCriteria?: number;