@hank-warren/pi-loop 0.4.1 → 0.6.0

package/src/index.ts

@@ -1,34 +1,55 @@
 /**
- * pi-loop: Claude-Code-/loop-inspired pacemaker for Pi. A loop wakes the
- * session on an interval to keep an active pi-goal goal moving (stall rescue
- * and goal_wait wakes) with loop-aware compaction. Loops require an active
- * goal: the loop owns *when* the session wakes; @narumitw/pi-goal (or the
- * @hank-warren/pi-goal fork) owns *whether the work is done*, read through
- * its `goal-state` session entries only.
+ * pi-loop: Claude-Code-/loop-inspired long-running work for Pi. A loop
+ * carries its own objective and completion criteria, is paced by the session
+ * settling, keeps a durable ledger, compacts itself, and ends through
+ * `loop_complete`, a cap, its expiry, or the user. It depends on no other
+ * extension; the only sibling state it reads is pi-plan-mode's, fail-open, so
+ * a loop never injects into a planning conversation.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
+import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.js";
+import { registerLoopStartTool } from "./start-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.
+	// would invalidate the whole conversation cache. It refuses when no 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);
+	// Inline invocation: an `input` handler arms a one-turn system-prompt hint
+	// for a mid-prompt `/loop` token, `before_agent_start` appends it, and
+	// loop_start is the model-invoked start it points at — refused on any turn
+	// the hint did not arm. The user's message is never transformed.
+	const invocation = new InlineInvocationState();
+	registerInlineInvocation(pi, controller, invocation);
+	registerLoopStartTool(pi, controller, invocation);
 	// 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);
@@ -72,30 +93,111 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 							return;
 						}
 					}
-					controller.startLoop(ctx, command);
+					const result = controller.startLoop(ctx, command);
+					if (!result.ok) ctx.ui.notify(result.message, "error");
 					return;
 				}
 			}
 		},
 	});
 
+	// 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: 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
-	// what lets the poke messages stay pointer-sized. A goal-bound loop adds
-	// nothing here — pi-goal already owns that turn's append.
+	// 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) => {
 		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}` };
 	});

package/src/inline-command.ts

@@ -0,0 +1,159 @@
+/**
+ * Inline slash-command detection.
+ *
+ * Pi dispatches extension commands only when a message *starts* with the
+ * command token; a command mentioned mid-prompt arrives as plain text. This
+ * helper finds inline occurrences of a `/cmd` token (and `cmd:` prefix lines)
+ * so the caller can react — here, by appending a reminder that tells the model
+ * to invoke the corresponding tool. It never rewrites or re-sends the user's
+ * message.
+ *
+ * Ported from @hank-warren/pi-goal, which proved the mechanism before pi-loop
+ * absorbed it; the helper was always generic over the command name.
+ */
+
+export interface InlineCommandSplit {
+	/** Text before the command token, trailing whitespace removed. */
+	prose: string;
+	/** Everything after the command token to end of message, trimmed. */
+	commandArgs: string;
+}
+
+/**
+ * Find the first inline `/<commandName>` occurrence in `text`.
+ *
+ * Detection rules:
+ * - The token must be preceded by start-of-line or whitespace and followed by
+ *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
+ *   path-like `foo/cmd` never matches.
+ * - A token at position 0 is ignored: that is Pi's native dispatch position.
+ * - Occurrences inside backtick code (inline spans and fenced blocks) or
+ *   inside a single/double-quoted span are ignored. Code regions are
+ *   approximated by the CommonMark backtick-run rule: a run of N backticks
+ *   opens a region closed by the next run of exactly N backticks.
+ *
+ * Returns undefined when no qualifying occurrence exists.
+ */
+export function extractInlineCommand(
+	text: string,
+	commandName: string,
+): InlineCommandSplit | undefined {
+	const token = `/${commandName}`;
+	const ignored = ignoredRegions(text);
+	let searchFrom = 0;
+	while (searchFrom < text.length) {
+		const index = text.indexOf(token, searchFrom);
+		if (index === -1) return undefined;
+		searchFrom = index + 1;
+		if (index === 0) continue;
+		const before = text[index - 1];
+		if (before !== undefined && !/\s/.test(before)) continue;
+		const afterToken = text[index + token.length];
+		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
+		if (insideRegion(ignored, index)) continue;
+		const commandArgs = text.slice(index + token.length).trim();
+		if (!commandArgs) continue;
+		return {
+			prose: text.slice(0, index).trimEnd(),
+			commandArgs,
+		};
+	}
+	return undefined;
+}
+
+/**
+ * True when the message inline-invokes the command: a mid-message `/cmd`
+ * token with a remainder, or a `cmd:` prefix at the start of any line — both
+ * outside backtick code and quoted spans.
+ */
+export function detectsInlineInvocation(text: string, commandName: string): boolean {
+	if (extractInlineCommand(text, commandName) !== undefined) return true;
+	const ignored = ignoredRegions(text);
+	const prefixPattern = new RegExp(`^[ \\t]*${escapeRegExpText(commandName)}:[ \\t]+\\S`, "gim");
+	for (
+		let match = prefixPattern.exec(text);
+		match;
+		match = prefixPattern.exec(text)
+	) {
+		if (!insideRegion(ignored, match.index)) return true;
+	}
+	return false;
+}
+
+type Region = readonly [start: number, end: number];
+
+/**
+ * Backtick code regions plus single/double-quoted spans. Quoting a command is
+ * how people discuss one (`use "/loop 10m ship it" to start`), so a quoted
+ * token is a mention, not an invocation.
+ */
+function ignoredRegions(text: string): Region[] {
+	return [...codeRegions(text), ...quoteRegions(text)];
+}
+
+function codeRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	const runs: Array<{ index: number; length: number }> = [];
+	const runPattern = /`+/g;
+	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
+		runs.push({ index: match.index, length: match[0].length });
+	}
+	for (let open = 0; open < runs.length; open += 1) {
+		const opener = runs[open];
+		if (opener === undefined) continue;
+		for (let close = open + 1; close < runs.length; close += 1) {
+			const closer = runs[close];
+			if (closer === undefined || closer.length !== opener.length) continue;
+			regions.push([opener.index, closer.index + closer.length]);
+			open = close;
+			break;
+		}
+	}
+	return regions;
+}
+
+/**
+ * Single- and double-quoted spans, matched conservatively so an apostrophe
+ * inside a word (`don't`) never opens one: an opening quote follows nothing,
+ * whitespace, or an opening bracket and precedes a non-space; its closing
+ * quote is on the same line, follows a non-space, and precedes end-of-line,
+ * whitespace, or closing punctuation.
+ */
+function quoteRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	for (let index = 0; index < text.length; index += 1) {
+		const quote = text[index];
+		if (quote !== '"' && quote !== "'") continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before !== undefined && !/[\s([{<]/.test(before)) continue;
+		if (after === undefined || /\s/.test(after)) continue;
+		const close = closingQuoteIndex(text, index, quote);
+		if (close === undefined) continue;
+		regions.push([index, close + 1]);
+		index = close;
+	}
+	return regions;
+}
+
+function closingQuoteIndex(text: string, openIndex: number, quote: string): number | undefined {
+	for (let index = openIndex + 1; index < text.length; index += 1) {
+		const char = text[index];
+		if (char === "\n") return undefined;
+		if (char !== quote) continue;
+		const before = text[index - 1];
+		const after = text[index + 1];
+		if (before === undefined || /\s/.test(before)) continue;
+		if (after !== undefined && !/[\s.,;:!?)\]}>]/.test(after)) continue;
+		return index;
+	}
+	return undefined;
+}
+
+function insideRegion(regions: readonly Region[], index: number): boolean {
+	return regions.some(([start, end]) => index >= start && index < end);
+}
+
+function escapeRegExpText(value: string) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/inline-invocation.ts

@@ -0,0 +1,109 @@
+/**
+ * Inline `/loop` invocation, tool-mediated.
+ *
+ * Pi only dispatches `/loop` when it starts the message. When the user writes
+ * `quick check /loop 10m get CI green` or a `loop:` prefixed line mid-prompt,
+ * this module appends a one-turn reminder to the system prompt so the model
+ * reliably calls the `loop_start` tool with the objective. The user's message
+ * itself is never touched — no cutting, splitting, re-sending, or visible
+ * annotation — so there are no delivery races, no message loss, and no
+ * transcript noise: guidance is injected at agent-start time, not by
+ * rewriting input.
+ *
+ * Two hooks cooperate because neither alone is safe:
+ * - `input` carries a `source` and so can tell user-typed text from
+ *   extension-sent prompts, but any transform it returns rewrites the stored,
+ *   visible user message. It only records the armed text here.
+ * - `before_agent_start` can extend the system prompt, but fires for
+ *   extension-sent prompts too, and pi-loop's own kickoff and continuation
+ *   prompts contain phrases like "the active /loop objective" that the
+ *   detector would match. It injects only when the starting prompt *is* the
+ *   armed user message, and disarms on every start, matched or not.
+ *
+ * Two deliberate limits keep the armed window one turn wide:
+ * - Streaming-typed input (`streamingBehavior` set, i.e. steered or queued)
+ *   never arms. Pi returns from `prompt()` before `before_agent_start` for
+ *   those, so an armed flag would survive to a later, unrelated turn — the
+ *   window through which pi-loop's own continuation prompts could be matched.
+ * - The hint is a per-turn `systemPrompt` append, not a stored message, so
+ *   "call loop_start now" cannot linger in the conversation and fire on a
+ *   later turn.
+ *
+ * The armed flag is also the `loop_start` tool's gate: unlike pi-goal, which
+ * relied on prompt guidelines alone, a loop is self-continuing, so this
+ * extension *enforces* that the tool only runs on a turn the user explicitly
+ * invoked. See `InlineInvocationState.invokedThisTurn`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { detectsInlineInvocation } from "./inline-command.js";
+import type { LoopController } from "./loop.js";
+
+export const INLINE_LOOP_COMMAND = "loop";
+
+export const INLINE_LOOP_HINT =
+	"<system-reminder>The user's message this turn inline-invoked a loop (/loop or loop:). Call the loop_start tool now with the objective text that follows the token in that message, then begin working toward it. Do not answer the objective as prose without starting the loop. If the message is discussing, quoting, or documenting the /loop command rather than invoking it, do not call loop_start. This reminder applies only to the user's message this turn.</system-reminder>";
+
+/**
+ * The armed state, shared between the hooks and the `loop_start` tool.
+ *
+ * `invokedThisTurn` is the hard gate: set when `before_agent_start` matched
+ * the armed user message, cleared at `agent_end` and at every session
+ * boundary. `loop_start` refuses whenever it is false, so no amount of prompt
+ * drift, transcript replay, or model initiative can start a self-continuing
+ * loop the user did not ask for.
+ */
+export class InlineInvocationState {
+	invokedThisTurn = false;
+}
+
+export function registerInlineInvocation(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	state: InlineInvocationState,
+) {
+	let armedText: string | undefined;
+
+	pi.on("input", (event) => {
+		// Extension-sourced messages (loop kickoffs, continuations, pokes, other
+		// extensions' injections) never arm the hint.
+		if (event.source === "extension") return;
+		// Steered or queued input returns from prompt() without ever reaching
+		// before_agent_start, so arming it would leave stale text armed.
+		if (event.streamingBehavior !== undefined) return;
+		if (!controller.settings.inlineInvocation) return;
+		if (!detectsInlineInvocation(event.text, INLINE_LOOP_COMMAND)) return;
+		armedText = event.text;
+	});
+
+	pi.on("before_agent_start", (event) => {
+		const armed = armedText;
+		armedText = undefined;
+		// Every start closes the previous turn's window, so a turn that ends
+		// without an agent_end still cannot leave the tool unlocked.
+		state.invokedThisTurn = false;
+		if (armed === undefined) return;
+		if (!controller.settings.inlineInvocation) return;
+		if (!promptCarriesArmedMessage(event.prompt, armed)) return;
+		state.invokedThisTurn = true;
+		return { systemPrompt: `${event.systemPrompt}\n\n${INLINE_LOOP_HINT}` };
+	});
+
+	const disarm = () => {
+		armedText = undefined;
+		state.invokedThisTurn = false;
+	};
+	pi.on("agent_end", disarm);
+	pi.on("session_start", disarm);
+	pi.on("session_shutdown", disarm);
+}
+
+/**
+ * True when the starting prompt is the armed user message. Pi may wrap the
+ * text with expanded prefixes or suffixes, so the armed text has to be the
+ * whole prompt or one of its ends — mirroring how upstream recognises its own
+ * owned prompts at a terminal boundary.
+ */
+function promptCarriesArmedMessage(prompt: string, armed: string) {
+	return prompt === armed || prompt.startsWith(armed) || prompt.endsWith(armed);
+}

package/src/ledger.ts

@@ -0,0 +1,230 @@
+/**
+ * The loop ledger: `~/.pi/agent/loop/<loop-id>/`.
+ *
+ * A multi-day loop cannot keep its state in the conversation — compaction is
+ * lossy by construction, and every summary of a summary drifts further from
+ * what actually happened. So the conversation stays the working memory and
+ * two files on disk become the record:
+ *
+ * - `criteria.json` — the completion criteria, written by the extension. JSON
+ *   deliberately, not Markdown: models rewrite prose they are asked to
+ *   maintain far more readily than they rewrite a structured file, and the
+ *   only edit this file may receive is flipping `passes`.
+ * - `PROGRESS.md` — the agent-maintained ledger, created here with a fixed
+ *   schema so "update the ledger" means the same thing on every turn.
+ *
+ * Keyed by **loop id**, not session id: session ids are not stably exposed to
+ * extensions, and one session can run several loops in sequence.
+ *
+ * Every operation here is best-effort. A read-only home directory, a full
+ * disk, or a file the user hand-edited into invalid JSON must degrade the
+ * loop to "no ledger", never break it: the ledger is an anchor for the model,
+ * not a dependency of the engine.
+ */
+
+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";
+export const CRITERIA_FILE = "criteria.json";
+export const PROGRESS_FILE = "PROGRESS.md";
+
+/** Cap on derived criteria: an objective is a paragraph, not a backlog. */
+const MAX_CRITERIA = 12;
+const MAX_DESCRIPTION_LENGTH = 500;
+
+export interface LoopCriterion {
+	id: string;
+	description: string;
+	/**
+	 * How the criterion is verified. Empty means "audit against authoritative
+	 * current state"; the extension writes this field and the model may not
+	 * change it.
+	 */
+	check: string;
+	passes: boolean;
+}
+
+export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
+	return join(agentDir, LEDGER_DIR_NAME, loopId);
+}
+
+/**
+ * Split an objective into checkable criteria.
+ *
+ * Deterministic and dumb on purpose: bullets first (a user who wrote a list
+ * meant a list), otherwise sentences. An objective with no separable parts
+ * yields the single implicit criterion, so `criteria.json` is never empty and
+ * `loop_complete` always has something concrete to answer for.
+ */
+export function deriveCriteria(objective: string): LoopCriterion[] {
+	const trimmed = objective.trim();
+	if (!trimmed) return [implicitCriterion(objective)];
+	const bullets = trimmed
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => /^([-*+]|\d+[.)])\s+/.test(line))
+		.map((line) => line.replace(/^([-*+]|\d+[.)])\s+/, "").trim())
+		.filter(Boolean);
+	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
+	if (parts.length < 2) return [implicitCriterion(trimmed)];
+	return parts.slice(0, MAX_CRITERIA).map((description, index) => ({
+		id: `c${index + 1}`,
+		description: truncate(description),
+		check: "",
+		passes: false,
+	}));
+}
+
+function implicitCriterion(objective: string): LoopCriterion {
+	return {
+		id: "c1",
+		description: truncate(objective.trim()) || "objective met as stated",
+		check: "",
+		passes: false,
+	};
+}
+
+/**
+ * Sentence split that survives how objectives are actually typed: mostly
+ * lowercase, occasionally with an abbreviation in the middle. Splitting on
+ * any letter after a full stop would turn "e.g. run the tests" into two
+ * criteria, so a fragment following a known abbreviation is merged back.
+ */
+const ABBREVIATION = /\b(?:e\.g|i\.e|etc|vs|cf|approx|no|fig|dr|mr|ms|mrs|st)\.$/iu;
+
+function splitSentences(text: string): string[] {
+	const parts = text
+		.split(/(?<=[.!?])\s+(?=[\p{L}\d])/u)
+		.map((sentence) => sentence.trim().replace(/\s+/gu, " "))
+		.filter((sentence) => sentence.length > 2);
+	const merged: string[] = [];
+	for (const part of parts) {
+		const previous = merged.at(-1);
+		if (previous !== undefined && ABBREVIATION.test(previous)) {
+			merged[merged.length - 1] = `${previous} ${part}`;
+			continue;
+		}
+		merged.push(part);
+	}
+	return merged;
+}
+
+function truncate(value: string): string {
+	const collapsed = value.replace(/\s+/gu, " ").trim();
+	return collapsed.length <= MAX_DESCRIPTION_LENGTH
+		? collapsed
+		: `${collapsed.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`;
+}
+
+export interface LedgerPaths {
+	dir: string;
+	criteria: string;
+	progress: string;
+}
+
+export function ledgerPaths(loopId: string, agentDir?: string): LedgerPaths {
+	const dir = loopLedgerDir(loopId, agentDir);
+	return { dir, criteria: join(dir, CRITERIA_FILE), progress: join(dir, PROGRESS_FILE) };
+}
+
+/**
+ * Create the ledger for a loop. Returns the failure reason, or undefined on
+ * success — the caller warns once and carries on either way.
+ *
+ * `criteria.json` is authoritative and overwritten on start (a new loop has
+ * new criteria). `PROGRESS.md` is only ever created, never overwritten: it is
+ * the agent's file, and a session restart must not erase days of ledger.
+ */
+export function createLedger(
+	paths: LedgerPaths,
+	objective: string,
+	criteria: LoopCriterion[],
+): string | undefined {
+	try {
+		mkdirSync(paths.dir, { recursive: true });
+		writeFileSync(paths.criteria, `${JSON.stringify(criteria, null, 2)}\n`, "utf8");
+		try {
+			writeFileSync(paths.progress, progressTemplate(objective), { encoding: "utf8", flag: "wx" });
+		} catch (error) {
+			// EEXIST is the normal case on restore: keep the existing ledger.
+			if (!isNodeError(error) || error.code !== "EEXIST") throw error;
+		}
+		return undefined;
+	} catch (error) {
+		return formatError(error);
+	}
+}
+
+export function progressTemplate(objective: string): string {
+	return [
+		"# Loop progress ledger",
+		"",
+		`Objective: ${objective.replace(/\s+/gu, " ").trim()}`,
+		"",
+		"Maintained by the agent. Keep these four sections; replace their contents.",
+		"",
+		"## Current status",
+		"",
+		"Not started.",
+		"",
+		"## Completed",
+		"",
+		"- (nothing yet)",
+		"",
+		"## Failed approaches and why",
+		"",
+		"- (nothing yet)",
+		"",
+		"## Next actions",
+		"",
+		"- (nothing yet)",
+		"",
+	].join("\n");
+}
+
+/** Read the criteria back, fail-open: undefined when absent or unreadable. */
+export function readCriteria(paths: LedgerPaths): LoopCriterion[] | undefined {
+	let contents: string;
+	try {
+		contents = readFileSync(paths.criteria, "utf8");
+	} catch {
+		return undefined;
+	}
+	try {
+		const parsed: unknown = JSON.parse(contents);
+		if (!Array.isArray(parsed)) return undefined;
+		const criteria: LoopCriterion[] = [];
+		for (const value of parsed) {
+			const criterion = normalizeCriterion(value);
+			if (!criterion) return undefined;
+			criteria.push(criterion);
+		}
+		return criteria.length > 0 ? criteria : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeCriterion(value: unknown): LoopCriterion | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const id = typeof record.id === "string" ? record.id.trim() : "";
+	const description = typeof record.description === "string" ? record.description.trim() : "";
+	if (!id || !description) return undefined;
+	return {
+		id,
+		description,
+		check: typeof record.check === "string" ? record.check : "",
+		passes: record.passes === true,
+	};
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}