@hank-warren/pi-loop 0.4.0 → 0.5.0

package/src/complete-tool.ts

@@ -1,13 +1,19 @@
 /**
  * `loop_complete`: the standalone loop's terminal tool.
  *
- * Deliberately thin. pi-goal's `goal_complete` carries a long evidence-audit
- * rules block and a stale-turn guard because a premature goal completion
- * abandons autonomous work and asserts the task is done. Stopping a loop
- * early only stops the pacemaker — the user restarts it — so the same
- * hardening would be duplicated cost for a much smaller blast radius. The one
- * guard kept is the loop_id match, which is cheap and prevents a stale turn
- * from stopping a newer loop.
+ * It used to be deliberately thin, on the argument that stopping a pacemaker
+ * has a small blast radius: the user just restarts it. That argument does not
+ * survive the loop becoming the *only* long-work mechanism. A premature
+ * completion now abandons autonomous work outright, and the model doing the
+ * abandoning is the same one that decided the work was done.
+ *
+ * So completion is gated on the loop's own `criteria.json`: every criterion
+ * must be answered with cited evidence, and a criterion the file still
+ * records as unmet must be addressed by name. The gate is deliberately
+ * mechanical — it cannot judge whether the evidence is *good*, only that the
+ * model was made to look at every requirement and say something specific
+ * about each. The audit rules that make the evidence worth citing live in the
+ * tool description and the system append.
  *
  * Registered unconditionally, never added or removed with loop state: tools
  * are part of the cached request prefix, so mutating the tool set mid-session
@@ -19,10 +25,29 @@
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { LoopController } from "./loop.js";
+import type { LoopCriterion } from "./ledger.js";
 
 export const LOOP_COMPLETE_TOOL = "loop_complete";
 
 const MAX_SUMMARY_LENGTH = 4_000;
+const MAX_EVIDENCE_LENGTH = 4_000;
+/** Shorter than this is an assertion, not a citation. */
+const MIN_EVIDENCE_LENGTH = 12;
+const EMPTY_EVIDENCE = new Set([
+	"done",
+	"ok",
+	"okay",
+	"yes",
+	"true",
+	"passes",
+	"passed",
+	"complete",
+	"completed",
+	"verified",
+	"confirmed",
+	"n/a",
+	"none",
+]);
 
 export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopController) {
 	pi.registerTool(
@@ -30,13 +55,18 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 			name: LOOP_COMPLETE_TOOL,
 			label: "Loop Complete",
 			description:
-				"Stop the active /loop when its objective's completion criteria are demonstrably met. Only for a standalone loop that carries its own objective; it stops the scheduled wakeups and does not assert that unrelated work is finished.",
-			promptSnippet: "Stop the active standalone /loop once its completion criteria are met",
+				"Stop the active /loop when every completion criterion in the loop's criteria.json is proven by authoritative evidence. Requires one cited piece of evidence per criterion id. It stops the scheduled wakeups and does not assert that unrelated work is finished.",
+			promptSnippet: "Stop the active standalone /loop once every criterion is proven",
 			promptGuidelines: [
-				"Call loop_complete only when the completion criteria stated in the loop objective are demonstrably met, verified against authoritative current state.",
+				"Call loop_complete only when every criterion in the loop's criteria.json is demonstrably met, verified against authoritative current state.",
+				"Before calling it, treat completion as unproven and audit requirement by requirement: for every criterion, inspect authoritative evidence and match the verification scope to the requirement scope.",
+				"Authoritative means the current worktree, command output, test results, runtime behaviour, PR state, or external state. Previous conversation, plans, and summaries are context, not proof.",
+				"Weak, indirect, missing, or merely consistent evidence is not enough; gather stronger evidence and keep working.",
+				"Effort exhaustion is not completion. Running long, running out of ideas, or reaching a cap is never a reason to call loop_complete.",
+				"Pass evidence as a map of criterion id to a specific citation (the command you ran and what it printed, the file and what it now contains, the URL and its state). Every criterion id must appear.",
 				"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 scheduled wake.",
+				"If the criteria are not met, do not call it: keep working and expect another continuation.",
 			],
 			parameters: Type.Object({
 				loop_id: Type.String({
@@ -44,6 +74,14 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 					maxLength: 200,
 					description: "The exact loop_id from the active /loop objective in the system prompt.",
 				}),
+				evidence: Type.Record(
+					Type.String(),
+					Type.String({ maxLength: MAX_EVIDENCE_LENGTH }),
+					{
+						description:
+							"Map of criterion id (c1, c2, …, from the loop's criteria.json) to the authoritative evidence proving it: the command run and its output, the file and its current contents, the external state and how it was checked.",
+					},
+				),
 				summary: Type.Optional(
 					Type.String({
 						maxLength: MAX_SUMMARY_LENGTH,
@@ -78,19 +116,88 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 						isError: true,
 					};
 				}
+				const evidence = normalizeEvidence(params.evidence);
+				const refusal = auditEvidence(controller.criteria(), evidence);
+				if (refusal) {
+					return {
+						content: toolContent(refusal),
+						details: { loopId: loop.id, criteria: controller.criteria() ?? [] },
+						isError: true,
+					};
+				}
 				const summary = params.summary?.trim();
 				controller.completeLoop(summary);
 				return {
 					content: toolContent(
-						`Loop stopped: completion criteria met.${summary ? ` ${summary}` : ""}`,
+						`Loop stopped: every criterion answered with evidence.${summary ? ` ${summary}` : ""}`,
 					),
-					details: { loopId: loop.id, ...(summary ? { summary } : {}) },
+					details: { loopId: loop.id, evidence, ...(summary ? { summary } : {}) },
 				};
 			},
 		}),
 	);
 }
 
+function normalizeEvidence(evidence: Record<string, string>): Record<string, string> {
+	const normalized: Record<string, string> = {};
+	for (const [id, value] of Object.entries(evidence)) {
+		const trimmed = typeof value === "string" ? value.trim() : "";
+		if (!trimmed) continue;
+		normalized[id.trim()] = trimmed;
+	}
+	return normalized;
+}
+
+/**
+ * The mechanical half of the completion gate. Returns the refusal text, or
+ * undefined when the call may proceed.
+ *
+ * With no readable criteria the loop cannot say what completion means, so the
+ * gate degrades to "cite something specific" rather than blocking a loop
+ * whose ledger is missing — the ledger is fail-open everywhere else too.
+ */
+export function auditEvidence(
+	criteria: LoopCriterion[] | undefined,
+	evidence: Record<string, string>,
+): string | undefined {
+	const answeredIds = new Set(Object.keys(evidence));
+	if (!criteria) {
+		return Object.values(evidence).some(isSubstantive)
+			? undefined
+			: "This loop has no readable criteria.json, so loop_complete still needs at least one specific citation: the command you ran and what it printed, or the state you inspected and what it showed.";
+	}
+	const missing = criteria.filter((criterion) => !answeredIds.has(criterion.id));
+	if (missing.length > 0) {
+		return [
+			`loop_complete refused: ${missing.length} of ${criteria.length} criteria have no cited evidence.`,
+			...missing.map(
+				(criterion) =>
+					`- ${criterion.id}${criterion.passes ? "" : " (still recorded as unmet)"}: ${criterion.description}`,
+			),
+			"Audit each one against authoritative current state — command output, file contents, external state — and pass the evidence keyed by criterion id. Weak or merely consistent evidence is not enough, and effort exhaustion is not completion.",
+		].join("\n");
+	}
+	const unknown = [...answeredIds].filter(
+		(id) => !criteria.some((criterion) => criterion.id === id),
+	);
+	if (unknown.length > 0) {
+		return `loop_complete refused: evidence cites unknown criterion id(s) ${unknown.join(", ")}. Use the ids from the loop's criteria.json (${criteria.map((criterion) => criterion.id).join(", ")}).`;
+	}
+	const weak = Object.entries(evidence)
+		.filter(([id]) => criteria.some((criterion) => criterion.id === id))
+		.filter(([, value]) => !isSubstantive(value));
+	if (weak.length > 0) {
+		return `loop_complete refused: the evidence for ${weak.map(([id]) => id).join(", ")} asserts completion instead of citing it. Give the command and its output, the file and its contents, or the external state and how it was checked.`;
+	}
+	return undefined;
+}
+
+function isSubstantive(value: string): boolean {
+	const trimmed = value.trim();
+	if (trimmed.length < MIN_EVIDENCE_LENGTH) return false;
+	return !EMPTY_EVIDENCE.has(trimmed.toLowerCase().replace(/[.!]+$/u, ""));
+}
+
 function toolContent(text: string) {
 	return [{ type: "text" as const, text }];
 }

package/src/decide.ts

@@ -1,17 +1,22 @@
 /**
- * Pure tick decision. The engine gathers the environment and this function
- * decides what a wakeup does, so the full decision matrix is unit-testable
- * without timers or a Pi runtime.
+ * Pure decisions for the two things that can move a loop forward, so the full
+ * matrix is unit-testable without timers or a Pi runtime:
  *
- * Precedence: loop liveness → expiry → plan mode → busy → mode-specific stop
- * criteria → iteration cap → poke.
+ * - `decideContinuation` runs at every settled idle boundary and is the
+ *   primary driver of a standalone loop. The session going idle with the
+ *   objective unfinished *is* the signal to continue; no clock is involved.
+ * - `decideTick` runs when the fallback heartbeat fires. It is the fault
+ *   handler for a lost continuation or an external wait, not the pacemaker.
+ *
+ * Both share one precedence prefix: loop liveness → expiry → plan mode →
+ * compaction → busy → mode-specific stop criteria → caps → act.
  *
  * The mode-specific step is the whole difference between the two kinds of
  * loop. A goal-bound loop delegates "is the work done" to pi-goal and reads
- * its `goal-state`, so a missing goal pauses it and a safety state holds it.
- * A standalone loop owns its own objective, reads no goal state at all, and
- * ends only through `loop_complete`, a cap, or the user — so pi-goal being
- * absent is not an error for it.
+ * its `goal-state`, so a missing goal pauses it and a safety state holds it;
+ * pi-goal also owns its settle continuations, so `decideContinuation` never
+ * acts for one. A standalone loop owns its own objective, reads no goal state
+ * at all, and ends only through `loop_complete`, a cap, or the user.
  */
 
 import { GOAL_SAFETY_STATUSES, type GoalSnapshot, isStandaloneLoop, type LoopState } from "./state.js";
@@ -26,30 +31,115 @@ export interface TickEnvironment {
 	goal: GoalSnapshot | undefined;
 }
 
+/** A `loop_wait` whose deadline has passed is due, not waiting. */
+function isWaiting(loop: LoopState, now: number): boolean {
+	const waiting = loop.waiting;
+	if (!waiting) return false;
+	return waiting.resumeAt === undefined || now < waiting.resumeAt;
+}
+
+/**
+ * An expiring standalone loop gets one last turn to write its state into the
+ * ledger before it stops; every other expiry stops immediately.
+ */
+export type ExpiryReason = "loop-expired" | "expiry-final-wake";
+
+export type SkipReason =
+	| "plan-mode-active"
+	| "agent-busy"
+	| "compaction-in-flight"
+	| "loop-waiting";
+
 export type TickDecision =
 	| { action: "none"; reason: "loop-not-active" }
-	| { action: "expire"; reason: "loop-expired" }
-	| { action: "skip"; reason: "plan-mode-active" | "agent-busy" | "compaction-in-flight" }
-	| { action: "stop"; reason: "goal-complete" | "max-iterations" }
+	| { action: "expire"; reason: ExpiryReason }
+	| { action: "skip"; reason: SkipReason }
+	| { action: "stop"; reason: "goal-complete" | "max-iterations" | "max-automatic-turns" }
 	| { action: "pause"; reason: "goal-safety"; cause: string }
 	| { action: "pause"; reason: "goal-missing" }
-	| { action: "poke"; reason: "goal-stalled" | "goal-waiting" | "objective-stalled" };
+	| {
+			action: "poke";
+			reason: "goal-stalled" | "goal-waiting" | "objective-stalled" | "wait-elapsed";
+	  };
 
-export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
+export type ContinuationDecision =
+	| { action: "none"; reason: "loop-not-active" | "goal-bound" }
+	| { action: "expire"; reason: ExpiryReason }
+	| { action: "skip"; reason: SkipReason }
+	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "continue"; reason: "settled-idle" };
+
+/** Shared prefix: everything that holds or ends a loop before mode matters. */
+function decideCommonPrefix(
+	loop: LoopState,
+	env: TickEnvironment,
+): Extract<TickDecision, { action: "none" | "expire" | "skip" }> | undefined {
 	if (loop.status !== "active") return { action: "none", reason: "loop-not-active" };
-	if (env.now >= loop.expiresAt) return { action: "expire", reason: "loop-expired" };
+	if (env.now >= loop.expiresAt) {
+		// The final wake is a standalone loop's own summarise-and-stop turn; a
+		// goal-bound loop has no ledger of its own to write, and pi-goal owns
+		// that conversation.
+		return {
+			action: "expire",
+			reason:
+				isStandaloneLoop(loop) && !loop.expiring ? "expiry-final-wake" : "loop-expired",
+		};
+	}
 	if (env.planModeEnabled) return { action: "skip", reason: "plan-mode-active" };
 	if (env.compacting) return { action: "skip", reason: "compaction-in-flight" };
 	if (env.busy) return { action: "skip", reason: "agent-busy" };
+	// A declared external wait holds both drivers: the loop is not stalled, it
+	// is waiting on the world, and its own deadline is the next thing to speak.
+	if (isWaiting(loop, env.now)) return { action: "skip", reason: "loop-waiting" };
+	return undefined;
+}
+
+/**
+ * Caps are checked in a fixed order so a loop that trips both reports the
+ * wake cap first — it is the one the user configured with `--max`.
+ */
+function decideCaps(
+	loop: LoopState,
+): { action: "stop"; reason: "max-iterations" | "max-automatic-turns" } | undefined {
+	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
+		return { action: "stop", reason: "max-iterations" };
+	}
+	if (loop.maxAutomaticTurns !== null && loop.automaticTurns >= loop.maxAutomaticTurns) {
+		return { action: "stop", reason: "max-automatic-turns" };
+	}
+	return undefined;
+}
+
+/**
+ * The settled-idle boundary of a standalone loop: the session finished a turn
+ * with the objective unfinished, so the loop continues immediately instead of
+ * waiting out an interval of idle wall time.
+ */
+export function decideContinuation(loop: LoopState, env: TickEnvironment): ContinuationDecision {
+	const prefix = decideCommonPrefix(loop, env);
+	if (prefix) return prefix;
+	// pi-goal drives its own settle continuations for a goal-bound loop; two
+	// extensions continuing the same session would double every turn.
+	if (!isStandaloneLoop(loop)) return { action: "none", reason: "goal-bound" };
+	const capped = decideCaps(loop);
+	if (capped) return capped;
+	return { action: "continue", reason: "settled-idle" };
+}
+
+export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
+	const prefix = decideCommonPrefix(loop, env);
+	if (prefix) return prefix;
 
 	// A standalone loop carries its own objective, so it never consults
 	// pi-goal: it runs until loop_complete stops it, a cap is reached, or the
 	// user intervenes.
 	if (isStandaloneLoop(loop)) {
-		if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
-			return { action: "stop", reason: "max-iterations" };
-		}
-		return { action: "poke", reason: "objective-stalled" };
+		const capped = decideCaps(loop);
+		if (capped) return capped;
+		// The prefix already let a still-waiting loop skip, so a wait surviving
+		// to here is one whose deadline has come due: this wake is the wake it
+		// asked for, and it counts against the wake cap like any other.
+		return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
 	}
 
 	const goal = env.goal;
@@ -67,9 +157,8 @@ export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision
 		return { action: "pause", reason: "goal-safety", cause: goal.status };
 	}
 
-	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
-		return { action: "stop", reason: "max-iterations" };
-	}
+	const capped = decideCaps(loop);
+	if (capped) return capped;
 
 	// An idle session with an active goal is exactly the stall/wait case:
 	// pi-goal continues on its own at every idle boundary, so idleness at

package/src/errors.ts

@@ -0,0 +1,131 @@
+/**
+ * Classification of an interrupted loop turn.
+ *
+ * Without this every provider hiccup looks the same to a loop, and the loop
+ * answers all of them identically: continue. That is wrong in both
+ * directions. Retrying into an exhausted usage quota burns the loop's caps
+ * against a window that has not reset, and pausing on a transient 503 strands
+ * a multi-day loop on a blip. Context overflow is a third answer again: the
+ * turn failed because the conversation is too big, so the fix is a
+ * compaction, not a retry of the same oversized request.
+ *
+ * Ported from pi-goal's classifier, trimmed to what a loop acts on.
+ */
+
+import {
+	isContextOverflow,
+	isRetryableAssistantError,
+	type AssistantMessage,
+	type Usage,
+} from "@earendil-works/pi-ai";
+
+export type LoopInterruption =
+	/** The turn finished normally. */
+	| "none"
+	/** The user (or another extension) aborted the turn. */
+	| "aborted"
+	/** Provider quota or billing exhaustion: retrying cannot help. */
+	| "usage-limited"
+	/** The request no longer fits: compact, then continue. */
+	| "context-overflow"
+	/** Transient: continue as usual. */
+	| "retryable"
+	/** Auth or another error a retry cannot fix. */
+	| "fatal";
+
+const USAGE_LIMIT_PATTERNS = [
+	/usage[_\s-]*(?:limit|cap)|chatgpt.{0,32}usage/i,
+	// Exhaustion phrased as spent allowance rather than a named limit. These
+	// matter most when the provider reports them as a 429, because the
+	// retryable patterns match the status code and the loop would otherwise
+	// retry against a quota window that has not reset. Deliberately narrow: a
+	// plain "rate limit, try again later" 429 must stay retryable.
+	/used all (?:the |your )?(?:included |available |free |remaining )*usage/i,
+	/draw from your extra usage/i,
+	/quota.{0,32}(?:reached|exceeded|exhausted|depleted)|(?:reached|exceeded|exhausted|depleted).{0,32}quota/i,
+	/insufficient[_\s-]*(?:quota|credits?)|out of credits|out of budget|available balance|payment required/i,
+	/(?:credit|balance).{0,32}(?:low|exhausted|depleted)|billing/i,
+] as const;
+
+const NON_RETRYABLE_PATTERN =
+	/multi-auth rotation failed|credentials tried|unauthori[sz]ed|invalid api key/i;
+
+const RETRYABLE_PATTERNS = [
+	/overloaded|rate.?limit|too many requests|\b(?:429|500|502|503|504)\b|service.?unavailable|server.?error|internal.?error/i,
+	/provider.?returned.?error|you can retry your request|try your request again|please retry your request/i,
+	/network.?error|connection.?(?:error|refused|lost)|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up/i,
+	/timed? out|timeout|terminated|websocket.?(?:closed|error)|ended without|stream ended before message_stop|http2 request did not get a response|retry delay/i,
+	/context[_\s-]*length[_\s-]*exceeded|input exceeds the context window/i,
+] as const;
+
+interface AssistantLike {
+	stopReason?: string;
+	errorMessage?: string;
+	content?: unknown;
+	api?: string;
+	provider?: string;
+	model?: string;
+}
+
+export function classifyInterruption(messages: readonly unknown[]): LoopInterruption {
+	const assistant = findFinalAssistantMessage(messages);
+	if (!assistant) return "none";
+	if (assistant.stopReason === "aborted") return "aborted";
+	if (assistant.stopReason !== "error") return "none";
+	const errorMessage = assistant.errorMessage ?? "";
+	// Usage limits are checked first on purpose: providers report them as 429,
+	// which the retryable patterns also match.
+	if (USAGE_LIMIT_PATTERNS.some((pattern) => pattern.test(errorMessage))) return "usage-limited";
+	if (NON_RETRYABLE_PATTERN.test(errorMessage)) return "fatal";
+	if (isContextOverflow(toPiAssistantMessage(assistant))) return "context-overflow";
+	if (
+		isRetryableAssistantError(toPiAssistantMessage(assistant)) ||
+		RETRYABLE_PATTERNS.some((pattern) => pattern.test(errorMessage))
+	) {
+		return "retryable";
+	}
+	return "fatal";
+}
+
+function findFinalAssistantMessage(messages: readonly unknown[]): AssistantLike | undefined {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+		const record = message as Record<string, unknown>;
+		if (record.role !== "assistant") continue;
+		return {
+			...(typeof record.stopReason === "string" ? { stopReason: record.stopReason } : {}),
+			...(typeof record.errorMessage === "string" ? { errorMessage: record.errorMessage } : {}),
+			...(Array.isArray(record.content) ? { content: record.content } : {}),
+			...(typeof record.api === "string" ? { api: record.api } : {}),
+			...(typeof record.provider === "string" ? { provider: record.provider } : {}),
+			...(typeof record.model === "string" ? { model: record.model } : {}),
+		};
+	}
+	return undefined;
+}
+
+function toPiAssistantMessage(assistant: AssistantLike): AssistantMessage {
+	return {
+		role: "assistant",
+		content: (assistant.content ?? []) as AssistantMessage["content"],
+		api: (assistant.api ?? "openai-responses") as AssistantMessage["api"],
+		provider: assistant.provider ?? "unknown",
+		model: assistant.model ?? "unknown",
+		usage: zeroUsage(),
+		stopReason: "error",
+		errorMessage: assistant.errorMessage,
+		timestamp: Date.now(),
+	};
+}
+
+function zeroUsage(): Usage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}

package/src/index.ts

@@ -10,25 +10,37 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
+import { registerLoopWaitTool } from "./wait-tool.js";
 import { LoopController, type LoopControllerOptions } from "./loop.js";
 import { showLoopManager, showLoopSettings } from "./manager.js";
 import { buildLoopObjectivePrompt } from "./objective.js";
 import { registerLoopMessageRendering } from "./render.js";
+import { completeScheduleArguments, parseScheduleCommand } from "./schedule/command.js";
+import { describeTask, listTasks, showScheduleManager } from "./schedule/manager.js";
+import { describeSchedule } from "./schedule/model.js";
+import { Scheduler } from "./schedule/runner.js";
 
 export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
 	const controller = new LoopController(pi, options);
+	const scheduler = new Scheduler(pi, {
+		...(options.agentDir === undefined ? {} : { agentDir: options.agentDir }),
+		...(options.now === undefined ? {} : { now: options.now }),
+	});
 	// 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
 	// standalone loop is active.
 	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);
 	// Collapse loop pokes into one-line transcript chips (display-only; the
 	// stored message and model context are untouched).
 	registerLoopMessageRendering(pi);
 
 	pi.registerCommand("loop", {
 		description:
-			"Wake the session on an interval to keep the active /goal moving: /loop [--max N] [--compact-at 60%] <interval> [focus]",
+			"Work an objective across many turns, waking the session if it goes quiet: /loop [--max N] [--compact-at 60%] [--expires 3d] <interval> [objective]",
 		getArgumentCompletions: (prefix: string) => completeLoopArguments(prefix),
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const command = parseLoopCommand(args);
@@ -79,14 +91,95 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		},
 	});
 
+	// The scheduler is user-typed only, exactly like /loop: the model gets no
+	// scheduling tools, because a model that can schedule its own future turns
+	// can schedule its way around every limit the loop imposes.
+	pi.registerCommand("schedule", {
+		description:
+			'Schedule prompts and headless runs: /schedule [every <dur>|at <time>|cron "<expr>"] [--run] <prompt>, or list/pause/resume/run/status/delete',
+		getArgumentCompletions: (prefix: string) => completeScheduleArguments(prefix),
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const command = parseScheduleCommand(args, { cwd: ctx.cwd });
+			switch (command.kind) {
+				case "show":
+					await showScheduleManager(scheduler, ctx);
+					return;
+				case "list":
+					ctx.ui.notify(listTasks(scheduler).join("\n"), "info");
+					return;
+				case "error":
+					ctx.ui.notify(command.message, "error");
+					return;
+				case "create": {
+					const { task, warning } = scheduler.create(command);
+					if (warning) {
+						ctx.ui.notify(`Scheduled task not persisted: ${warning}`, "warning");
+					}
+					if (command.clampedFrom !== undefined) {
+						ctx.ui.notify("Intervals below 1 minute are raised to the minimum.", "warning");
+					}
+					ctx.ui.notify(
+						[
+							`Scheduled "${task.name}" (${task.id}): ${describeSchedule(task.schedule)}.`,
+							task.task.kind === "run"
+								? `Runs headlessly in ${task.task.cwd}; wakes this session on ${task.task.wakeOn}.`
+								: "Injects a prompt into this session at an idle boundary; it dies with the session.",
+							`Runs: ${task.maxRuns === null ? "unlimited" : `at most ${task.maxRuns}`}; expires ${new Date(task.expiresAt).toLocaleDateString()}.`,
+						].join("\n"),
+						"info",
+					);
+					return;
+				}
+				default: {
+					const task = scheduler.find(command.id);
+					if (!task) {
+						ctx.ui.notify(
+							`No scheduled task matches ${command.id}. Run /schedule list to see them.`,
+							"error",
+						);
+						return;
+					}
+					if (command.kind === "status") {
+						ctx.ui.notify(describeTask(task).join("\n"), "info");
+						return;
+					}
+					if (command.kind === "pause" || command.kind === "resume") {
+						const status = command.kind === "pause" ? "paused" : "active";
+						scheduler.update({ ...task, status });
+						ctx.ui.notify(`Task "${task.name}" is now ${status}.`, "info");
+						return;
+					}
+					if (command.kind === "run") {
+						scheduler.fireNow(task);
+						ctx.ui.notify(`Running "${task.name}" now.`, "info");
+						return;
+					}
+					scheduler.remove(task.id);
+					ctx.ui.notify(`Deleted "${task.name}".`, "info");
+				}
+			}
+		},
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		controller.onSessionStart(ctx);
+		scheduler.onSessionStart(ctx);
 	});
 	pi.on("session_shutdown", async () => {
 		controller.onSessionShutdown();
+		scheduler.onSessionShutdown();
+	});
+	// The pacemaker of a standalone loop: agent_end records the intent to
+	// continue, agent_settled delivers it once Pi will accept a message.
+	pi.on("agent_start", async (_event, ctx) => {
+		controller.onAgentStart(ctx);
+	});
+	pi.on("agent_end", async (event, ctx) => {
+		controller.onAgentEnd(ctx, event.messages ?? []);
 	});
 	pi.on("agent_settled", async (_event, ctx) => {
 		controller.onAgentSettled(ctx);
+		scheduler.onAgentSettled(ctx);
 	});
 	// A standalone loop carries its own objective, so it injects it the way
 	// pi-goal does for a goal-bound one: a byte-stable system append, which is
@@ -95,7 +188,7 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	pi.on("before_agent_start", (event) => {
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;
-		const objectivePrompt = buildLoopObjectivePrompt(loop);
+		const objectivePrompt = buildLoopObjectivePrompt(loop, controller.ledger);
 		if (objectivePrompt === undefined) return;
 		return { systemPrompt: `${event.systemPrompt}\n\n${objectivePrompt}` };
 	});