@hank-warren/pi-loop 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @hank-warren/pi-loop
 
+## 0.8.0
+
+### Minor Changes
+
+- 2a04a46: Plan mode, a ledger write tool, and a widget that shows progress.
+
+  **Breaking: `/schedule` is removed.** It lived here because the machinery was the same
+  machinery — an idle-gated delivery path, coalescing, caps, an expiry. True, and still the
+  wrong home: a loop pursues one objective until it is done and then stops, while a schedule
+  fires forever on a clock. Persisted tasks in `~/.pi/agent/loop/schedules.json` are no longer
+  read and the `schedules.lease` lockfile is no longer taken.
+
+  **`/loop` now opens planning.** With nothing running it starts a drafting conversation
+  instead of printing "No loop in this session". The model drafts the objective as an
+  acceptance test, then calls the new `loop_propose` tool, which renders an approval card
+  showing the exact criteria the split will produce, the cadence and the caps — and starts
+  nothing. You start it, change the cadence, keep editing, or cancel. The criteria used to be
+  frozen before anyone had ever seen them; the card is the moment they can still be fixed.
+  `/loop 30m <objective>` and inline `loop:` are unchanged.
+
+  **Fixed: a wrapped bullet silently truncated its criterion.** `deriveCriteria` kept lines
+  carrying a bullet marker and discarded the rest, so a bullet longer than a terminal width
+  lost everything after its first line — while the criterion still looked well-formed. The
+  acceptance gate was quietly weakened to whatever survived, with no signal.
+
+  **New `loop_progress` tool, the only supported ledger write path.** The ledger is the one
+  thing that survives compaction, and the model was told to maintain it with no tool to do so,
+  so it reached for a shell heredoc — and one `cat > PROGRESS.md` replaced the objective line,
+  the other sections and every failed-approach note. `loop_progress` edits one section and
+  leaves every other byte alone, and marks a criterion met with the citation that justified
+  it, stored alongside it. Only `passes` ever changes, now by construction rather than by
+  prose in a skill file.
+
+  **A blocking prompt no longer deadlocks the loop invisibly.** A session waiting on a modal
+  is `busy`, which makes every continuation and every fallback tick skip; no turn completes,
+  so the cap never trips and the no-progress breaker never fires. Expiry was the only thing
+  left — up to seven days — while the widget showed a next-wake time throughout. Loops now
+  carry an autonomy posture (decide and record rather than ask, `loop_wait` as the only
+  non-deadlocking way to ask, never reshape a command to get past a permission prompt, prefer
+  the undoable), and a run left open past fifteen minutes flips the widget to an attention
+  state. The loop never answers the prompt.
+
+  **The widget was redesigned around progress.** It led with the interval — a fallback
+  heartbeat a settle-paced loop may never deliver — and reported turns against the cap, which
+  is budget burn. Criteria met over total now leads, with the turn budget, the loop's age and
+  the next wake after it. The widget and the footer render the same function: they had drifted,
+  so a loop waiting on CI showed an ordinary next-wake time above the editor while the footer
+  said it was waiting, and a paused loop dropped the cause that `/loop status` printed.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -156,42 +156,6 @@ Long loops die by context exhaustion, not by failing. pi-loop owns the compactio
 - **Loop-owned re-anchor**: when a compaction completes mid-loop, pi-loop dispatches one pointer-sized continuation at the next settle — re-read `PROGRESS.md` and `criteria.json`, continue from authoritative state, plus the next 1-3 actions lifted out of the summary that just replaced the conversation. The loop no longer goes quiet until the next wake. A re-anchor supersedes an ordinary continuation already queued: after a compaction, "re-read the ledger" is strictly the better instruction.
 - Loop state itself lives in custom session entries, which compaction never touches, and survives session restarts (the timer re-arms on resume; expired loops are dropped with a notice).
 
-## `/schedule`: recurring prompts and headless runs
-
-The same extension also schedules work, because the machinery is the same machinery: an idle-gated delivery path, coalescing, caps, and an expiry.
-
-```
-/schedule                                        manager TUI
-/schedule list
-/schedule every 30m check the release queue      in-session prompt, every 30 minutes
-/schedule at +2h remind me to cut the RC         once, two hours from now
-/schedule at 2026-01-31T09:00 monthly report     once, at an ISO timestamp
-/schedule cron "0 9 * * 1" weekly triage         Monday mornings
-/schedule every 6h --run --cwd /srv/app sync     headless `pi -p` run
-/schedule pause|resume|run|status|delete <id>
-```
-
-Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlimited>`, `--wake always|failure|success|never`, `--name <text>`.
-
-**Two task kinds, deliberately different lifetimes:**
-
-- **`prompt`** injects a prompt into the owning session, delivered exactly like a loop wake — only at a settled idle boundary, queued while the agent is busy. It is **session-scoped**: it lives in memory and dies with the session, because a prompt with no session to arrive in is not a task, it is a leak.
-- **`run`** spawns a headless `pi -p "<prompt>"` in a working directory, tees stdout and stderr to `~/.pi/agent/loop/runs/<task-id>/<timestamp>.log`, and records the exit code. It never touches the conversation unless `wakeOn` says to report back (default: only failures). These are the only tasks persisted, in `~/.pi/agent/loop/schedules.json`.
-
-  A headless run is a **fresh `pi` invocation**, so it uses your *default* model and settings, not the model the scheduling session happens to be using. If a run needs a specific model, say so in the prompt's environment — or check the run log, which records the command, cwd, prompt, and exit code precisely so a surprise like this is one `cat` away.
-
-**One fire per occurrence, not one per open session.** Headless firing is arbitrated by a lockfile lease (`schedules.lease`) holding a pid and a heartbeat: without it, a task scheduled for 09:00 fires once in every Pi session that happens to be open. A holder that dies stops renewing and the next session takes over after 90 seconds. It is not a distributed lock — the failure it must prevent is duplicate work, and the worst it can produce is one skipped tick.
-
-**Missed occurrences coalesce into a single fire.** A laptop asleep for a weekend wakes to one catch-up, never one turn per missed interval.
-
-**Every task is bounded twice**: `maxRuns` (default 25, `--max unlimited` is an explicit opt-in) and a hard 90-day expiry.
-
-**Cron** is five numeric fields at minute granularity (`minute hour day-of-month month day-of-week`), supporting `*`, `n`, `a-b`, `a,b`, and `/step`. No names, no `@daily`, no seconds, no timezones beyond the host's local clock — each of those is a place where two implementations disagree, and a scheduler with debatable semantics is worse than one that refuses the expression. When both day fields are restricted, a day matching *either* fires, as in every crontab in the world.
-
-`/schedule` is **user-typed only**, exactly like `/loop`: the model gets no scheduling tools. A model that can schedule its own future turns can schedule its way around every limit the loop imposes.
-
-> **Never co-install [`@jl1990/pi-scheduler`](https://www.npmjs.com/package/@jl1990/pi-scheduler).** Both register `/schedule`; the commands and the concepts collide.
-
 ## Settings
 
 `~/.pi/agent/pi-loop.json` (absent file = defaults, never created implicitly; saves are atomic and preserve unknown fields), or `/loop settings`:
@@ -223,7 +187,7 @@ These were considered and cut, and the reasoning is recorded so they are not sil
 
 ## The companion skill
 
-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 `/schedule` or in no loop at all.
+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.
 
 It is **loaded on demand**: one line in each of `loop_start` and `loop_complete`'s prompt guidelines points 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.
 

package/package.json

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

package/skills/pi-loop/SKILL.md

@@ -70,6 +70,47 @@ c2: "gh pr checks 171 → all 3 checks passed (ci/gate, ci/typecheck, ci/scan-se
 
 Audit requirement by requirement before calling it, and match the verification scope to the requirement scope: a criterion about the whole suite is not proven by one test file. **Effort exhaustion is not completion** — running long, running out of ideas, or nearing a cap is never a reason to call the tool. If the criteria are not met, keep working; another continuation is coming.
 
+## A loop runs unattended, so a question is a deadlock
+
+Outside a loop, asking the user costs a few seconds of their attention. Inside one they are not
+there by construction, and the cost is not a slow answer — it is the loop's death.
+
+A session blocked on a modal prompt is **busy**, and `busy` is the third test in the decision
+prefix both drivers share:
+
+```
+loop liveness -> expiry -> plan mode -> compaction -> busy -> wait -> the turn cap -> act
+```
+
+So `agent_settled` never fires and no continuation is queued; every fallback tick returns
+`skip: agent-busy`; `automaticTurns` never increments, so the turn cap never trips; and the
+no-progress breaker needs tool-free *turns*, of which there are none. **Expiry is the only thing
+left, up to seven days later** — and the widget shows the next wake time the whole time.
+
+This is why the guidance is a posture rather than a list of forbidden tools. Your other
+extensions are unknowable and a blacklist goes stale the moment one of them ships a new prompt.
+The rule follows from the mechanics instead:
+
+1. **Decide, do not ask.** Take the reversible option, write the decision *and the reasoning*
+   into `PROGRESS.md`, and keep going. The user reads it when they return and the loop never
+   stopped. A decision recorded beats a question unanswered.
+2. **`loop_wait` is the loop-safe form of asking.** It is the one way to say "I need a human"
+   that does not deadlock: continuations stop, the reason shows in the widget and `/loop status`,
+   and any wake resumes it. Use it exactly where you would otherwise open a modal, and put the
+   options in the ledger first so the answer can be one word.
+3. **Never reshape a command to get past a permission prompt.** This is the dangerous one. An
+   agent under a turn cap has real incentive to rewrite a blocked command into something the
+   guardian waves through, and that failure *looks like progress*. A blocked command means stop
+   and ask through `loop_wait` — never find another way around it.
+4. **Prefer the undoable.** Nobody is watching to catch a bad call, so when two paths are close,
+   take the one that is cheap to reverse: a worktree over the clone, additive over destructive, a
+   draft pull request over a merge.
+5. **Ask only when proceeding is irreversible *and* the choice is load-bearing.** Then use
+   `loop_wait`, not a prompt.
+
+Autonomy is not permission to be reckless. It is the opposite: the absence of a human in the loop
+is exactly why the reversible path is the right default.
+
 ## Waiting on the world
 
 When progress depends on something outside the session — a CI run, a deploy, a human reply — call `loop_wait` with a one-sentence reason. Do not spend continuations re-checking, and never sleep in a shell to pass time.
@@ -87,7 +128,9 @@ The ledger lives at `~/.pi/agent/loop/<loop-id>/`, and `PROGRESS.md` has four fi
 
 The failed-approaches section carries the most value, because it is the only thing that survives compaction and the only thing that stops the next continuation — or the next engineer — from re-running an experiment that already failed. "Tried X, it failed because Y" is the whole point; "tried several things" is worth nothing.
 
-`criteria.json` sits next to it. You may flip an entry's `passes` field when authoritative evidence proves it, citing that evidence in `PROGRESS.md`. You may **never** add, remove, reword, or re-id an entry: a model that can rewrite its acceptance criteria eventually rewrites them into something it has already achieved.
+Write both files with the **`loop_progress`** tool, never with the file or shell tools. `loop_progress` edits one section and leaves every other byte alone; a whole-file write takes out the objective line, the other three sections, and however many days of failed-approach notes were in them. That is not a hypothetical — it is what a `cat > PROGRESS.md <<EOF` does on the first ledger update, and `createLedger` opens the file with `flag: "wx"` precisely so the engine can never do it.
+
+`criteria.json` sits next to it. Mark an entry met with `loop_progress`, which flips `passes` and stores the citation that justified it alongside the criterion, where `loop_complete` can be held to it later. Only `passes` ever changes: you may **never** add, remove, reword, or re-id an entry, and never hand-edit the file. A model that can rewrite its acceptance criteria eventually rewrites them into something it has already achieved.
 
 Both files are best-effort. If the ledger could not be created the loop still runs; it just has no memory outside the conversation.
 
@@ -103,7 +146,7 @@ The interval is a fallback heartbeat, not the pacemaker — the loop advances wh
 
 An inline invocation *permits* a loop; it does not oblige you to start one. When the work is a bad fit, say so in one line and offer the alternative instead:
 
-- **Recurring cadence** ("check the release queue every morning") → `/schedule`, which owns cron, one-shots, and headless runs. A loop pursues one objective until it is done; it is not a timer.
+- **Recurring cadence** ("check the release queue every morning") → not a loop. A loop pursues one objective until it is done and then stops; it is not a timer, and an objective that is never "done" only produces turns until a cap. Use whatever scheduling your setup provides.
 - **Genuine open exploration** ("figure out why memory grows") → do the investigation in the conversation. A loop's value is the gate at the end; an investigation has no end state to gate on, so the loop only supplies unwanted turns. Once the investigation names a fix, *that* is a loop objective.
 - **Work that finishes this turn** → just do it, and say why no loop was needed.
 

package/src/index.ts

@@ -11,23 +11,18 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { completeLoopArguments, parseLoopCommand } from "./command.js";
 import { registerLoopCompleteTool } from "./complete-tool.js";
 import { InlineInvocationState, registerInlineInvocation } from "./inline-invocation.js";
+import { registerLoopProgressTool } from "./progress-tool.js";
+import { registerLoopProposeTool } from "./propose-tool.js";
+import { LOOP_PLANNING_HINT } from "./planning.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 { showLoopApproval, 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 loop is
@@ -36,6 +31,8 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	// 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);
 	// 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
@@ -54,9 +51,34 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const command = parseLoopCommand(args);
 			switch (command.kind) {
-				case "show":
-					await showLoopManager(controller, ctx);
+				case "show": {
+					// Bare /loop is the front door. With a loop running it is the
+					// manager, as before. With a draft awaiting approval it is the
+					// card. With neither it opens planning, which is what used to be
+					// a one-line "no loop in this session" dead end.
+					const running = controller.state && controller.state.status !== "stopped";
+					if (running) {
+						await showLoopManager(controller, ctx);
+						return;
+					}
+					if (controller.planning.proposal) {
+						await showLoopApproval(controller, ctx);
+						return;
+					}
+					if (controller.planning.active) {
+						ctx.ui.notify(
+							"Still planning: describe the objective, and the agent will put a loop up for approval.",
+							"info",
+						);
+						return;
+					}
+					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.",
+						"info",
+					);
 					return;
+				}
 				case "status":
 					ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
 					return;
@@ -101,83 +123,11 @@ 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: agent_end records the intent to continue, agent_settled
 	// delivers it once Pi will accept a message.
@@ -189,12 +139,16 @@ export default function loop(pi: ExtensionAPI, options: LoopControllerOptions =
 	});
 	pi.on("agent_settled", async (_event, ctx) => {
 		controller.onAgentSettled(ctx);
-		scheduler.onAgentSettled(ctx);
 	});
 	// 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) => {
+		// 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) {
+			return { systemPrompt: `${event.systemPrompt}\n\n${LOOP_PLANNING_HINT}` };
+		}
 		const loop = controller.state;
 		if (!loop || loop.status !== "active") return;
 		const objectivePrompt = buildLoopObjectivePrompt(loop, controller.ledger);

package/src/interval.ts

@@ -54,6 +54,31 @@ export function formatDuration(ms: number): string {
 	return `${Math.round(ms / 1_000)}s`;
 }
 
+/**
+ * Render an elapsed span approximately, for display only.
+ *
+ * `formatDuration` renders the *canonical token* for a configured interval and
+ * only ever emits one unit on an exact multiple, so an arbitrary elapsed span
+ * falls through it to seconds — 2h12m comes back as "7920s". An age needs the
+ * opposite trade: two units at most, truncated, never exact.
+ */
+export function formatElapsed(ms: number): string {
+	const clamped = Math.max(0, ms);
+	if (clamped < UNIT_MS.m) return `${Math.floor(clamped / 1_000)}s`;
+	for (const [big, small] of [
+		["d", "h"],
+		["h", "m"],
+	] as const) {
+		const bigMs = UNIT_MS[big];
+		const smallMs = UNIT_MS[small];
+		if (bigMs === undefined || smallMs === undefined || clamped < bigMs) continue;
+		const whole = Math.floor(clamped / bigMs);
+		const rest = Math.floor((clamped % bigMs) / smallMs);
+		return rest > 0 ? `${whole}${big}${rest}${small}` : `${whole}${big}`;
+	}
+	return `${Math.floor(clamped / UNIT_MS.m)}m`;
+}
+
 /** Render a wall-clock time as HH:MM for the status widget. */
 export function formatClock(timestamp: number): string {
 	const date = new Date(timestamp);

package/src/ledger.ts

@@ -44,8 +44,37 @@ export interface LoopCriterion {
 	 */
 	check: string;
 	passes: boolean;
+	/**
+	 * The citation given when `passes` was flipped, recorded by the extension
+	 * at flip time. Absent on a criterion still unmet, and on one flipped by a
+	 * hand-edit rather than through `loop_progress`.
+	 */
+	evidence?: string;
+	/** Epoch ms of the flip that recorded `evidence`. */
+	evidenceAt?: number;
 }
 
+/**
+ * The fixed headings of `PROGRESS.md`. The schema is the point: "update the
+ * ledger" means the same thing on every turn only while the sections are the
+ * same on every turn, so writes are section-scoped and a section that is not
+ * one of these is refused rather than created.
+ */
+export const PROGRESS_SECTIONS = [
+	"current status",
+	"completed",
+	"failed approaches and why",
+	"next actions",
+] as const;
+export type ProgressSection = (typeof PROGRESS_SECTIONS)[number];
+
+/** Cap on one ledger write: a progress note is a paragraph, not a transcript. */
+export const MAX_PROGRESS_TEXT_LENGTH = 4000;
+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 {
 	return join(agentDir, LEDGER_DIR_NAME, loopId);
 }
@@ -61,12 +90,7 @@ export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string
 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 bullets = collectBullets(trimmed);
 	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
 	if (parts.length < 2) return [implicitCriterion(trimmed)];
 	return criteriaFromDescriptions(parts);
@@ -90,6 +114,46 @@ export function criteriaFromDescriptions(descriptions: readonly string[]): LoopC
 	}));
 }
 
+const BULLET_MARKER = /^([-*+]|\d+[.)])\s+/;
+
+/**
+ * Bullets, each folded back together with the lines it wrapped onto.
+ *
+ * A bullet longer than the terminal width is typed — or pasted — across
+ * several lines, and only the first carries the marker. Matching markers and
+ * discarding everything else silently truncated such a bullet at its first
+ * line, which is worse than mis-splitting it: the criterion still looked
+ * well-formed, so a requirement could vanish out of the gate with no signal.
+ * A non-blank line that starts no new bullet therefore continues the previous
+ * one. Text before the first bullet is still ignored (it is a preamble, not a
+ * requirement), and a blank line ends the bullet it follows so a trailing
+ * paragraph cannot be glued onto the last item.
+ */
+function collectBullets(text: string): string[] {
+	const bullets: string[] = [];
+	let open = false;
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line) {
+			open = false;
+			continue;
+		}
+		if (BULLET_MARKER.test(line)) {
+			const body = line.replace(BULLET_MARKER, "").trim();
+			if (body) {
+				bullets.push(body);
+				open = true;
+			} else {
+				// A bare marker has no body to continue.
+				open = false;
+			}
+			continue;
+		}
+		if (open) bullets[bullets.length - 1] += ` ${line}`;
+	}
+	return bullets;
+}
+
 function implicitCriterion(objective: string): LoopCriterion {
 	return {
 		id: "c1",
@@ -197,6 +261,119 @@ export function progressTemplate(objective: string): string {
 	].join("\n");
 }
 
+/**
+ * Append to (or replace) one section of `PROGRESS.md`, leaving every other
+ * section byte-identical.
+ *
+ * This exists because the alternative the model reaches for otherwise is a
+ * whole-file overwrite, which takes out the objective line and the other
+ * three sections along with it. `createLedger` already refuses to overwrite
+ * this file for exactly that reason; the agent's write path has to honour the
+ * same rule or the protection is decorative.
+ *
+ * Returns the failure reason, or undefined on success.
+ */
+export function writeProgressSection(
+	paths: LedgerPaths,
+	section: ProgressSection,
+	text: string,
+): string | undefined {
+	const entry = text.trim();
+	if (!entry) return "the text to record was empty";
+	let contents: string;
+	try {
+		contents = readFileSync(paths.progress, "utf8");
+	} catch (error) {
+		return formatError(error);
+	}
+	const lines = contents.split(/\r?\n/);
+	const start = lines.findIndex((line) => headingText(line) === section);
+	if (start === -1) {
+		return `PROGRESS.md has no "## ${section}" section (it was renamed or removed by hand)`;
+	}
+	let end = start + 1;
+	while (end < lines.length && headingText(lines[end]) === undefined) end += 1;
+	const body = lines.slice(start + 1, end);
+	while (body.length > 0 && !body[0].trim()) body.shift();
+	while (body.length > 0 && !body[body.length - 1].trim()) body.pop();
+	const placeholder =
+		body.length === 1 && PLACEHOLDERS.has(body[0].trim().toLowerCase()) ? true : body.length === 0;
+	// Whether a write replaces or extends is a property of the section, not a
+	// choice: "current status" is a single current value and the other three are
+	// running lists. Deriving it keeps the decision out of the tool schema,
+	// where the model could get it wrong on a file nothing else can repair.
+	const next =
+		section === "current status" || placeholder
+			? entry.split("\n")
+			: [...body, "", ...entry.split("\n")];
+	const rebuilt = [...lines.slice(0, start + 1), "", ...next, "", ...lines.slice(end)];
+	try {
+		writeFileSync(paths.progress, `${rebuilt.join("\n").replace(/\n{3,}$/u, "\n")}`, "utf8");
+		return undefined;
+	} catch (error) {
+		return formatError(error);
+	}
+}
+
+function headingText(line: string | undefined): string | undefined {
+	const match = /^##\s+(.+?)\s*$/u.exec(line ?? "");
+	return match ? match[1].toLowerCase() : undefined;
+}
+
+export interface MarkCriterionResult {
+	ok: boolean;
+	message: string;
+	criteria?: LoopCriterion[];
+}
+
+/**
+ * Flip one criterion's `passes` and record the citation that justified it.
+ *
+ * The only mutation `criteria.json` accepts. Descriptions, ids, checks and the
+ * set of entries are rewritten by nothing here, so "a model may not rewrite
+ * its own acceptance criteria" stops being a rule in a skill file and becomes
+ * a property of the only available write path.
+ */
+export function markCriterion(
+	paths: LedgerPaths,
+	id: string,
+	evidence: string,
+	passes: boolean,
+	now: number,
+): MarkCriterionResult {
+	const criteria = readCriteria(paths);
+	if (!criteria) return { ok: false, message: "criteria.json is absent or unreadable" };
+	const target = criteria.find((criterion) => criterion.id === id);
+	if (!target) {
+		return {
+			ok: false,
+			message: `no criterion ${id}; this loop has ${criteria.map((c) => c.id).join(", ")}`,
+		};
+	}
+	const cited = evidence.trim();
+	if (passes && !cited) return { ok: false, message: "marking a criterion met requires evidence" };
+	const updated = criteria.map((criterion) =>
+		criterion.id === id
+			? {
+					...criterion,
+					passes,
+					...(passes ? { evidence: cited, evidenceAt: now } : {}),
+				}
+			: criterion,
+	);
+	try {
+		writeFileSync(paths.criteria, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
+	} catch (error) {
+		return { ok: false, message: formatError(error) };
+	}
+	const met = updated.filter((criterion) => criterion.passes).length;
+	return {
+		ok: true,
+		message: `${id} marked ${passes ? "met" : "unmet"} (${met}/${updated.length} now passing)`,
+		criteria: updated,
+	};
+}
+
 /** Read the criteria back, fail-open: undefined when absent or unreadable. */
 export function readCriteria(paths: LedgerPaths): LoopCriterion[] | undefined {
 	let contents: string;
@@ -226,11 +403,15 @@ function normalizeCriterion(value: unknown): LoopCriterion | undefined {
 	const id = typeof record.id === "string" ? record.id.trim() : "";
 	const description = typeof record.description === "string" ? record.description.trim() : "";
 	if (!id || !description) return undefined;
+	const evidence = typeof record.evidence === "string" ? record.evidence.trim() : "";
+	const evidenceAt = record.evidenceAt;
 	return {
 		id,
 		description,
 		check: typeof record.check === "string" ? record.check : "",
 		passes: record.passes === true,
+		...(evidence ? { evidence } : {}),
+		...(typeof evidenceAt === "number" && Number.isSafeInteger(evidenceAt) ? { evidenceAt } : {}),
 	};
 }