pi-cc-loop 0.1.1 → 0.2.0

package/index.ts

@@ -1,11 +1,10 @@
 /**
  * pi-cc-loop — a Claude Code compatible `/loop` for the Pi coding agent.
  *
- * Mirrors Claude Code v2.1.306:
- *
  *   /loop 5m check the deploy    fixed interval, driven by a 5-field cron
  *   /loop check the deploy       self-paced: the model picks the next delay
- *   /loop                        uses .pi/loop.md, or the built-in maintenance prompt
+ *   /loop 15m | /loop            the loop.md tasks (or the built-in maintenance
+ *                                prompt), on a fixed interval or self-paced
  *   /loop stop | status | list   manage the jobs
  *
  * Two mechanisms, same as Claude Code:
@@ -16,27 +15,21 @@
  *   self-paced      `schedule_wakeup` lets the model choose the next delay
  *                   (60-3600s). If the model forgets to reschedule, the runtime
  *                   arms one 20 minute keepalive; if it still forgets, the
- *                   chain ends.
+ *                   chain ends. Esc on one of its turns cancels it.
  *
  * The tools are named after their Claude Code counterparts:
- *   CronCreate  -> cron_create
- *   CronDelete  -> cron_delete
- *   CronList    -> cron_list
+ *   CronCreate -> cron_create, CronDelete -> cron_delete, CronList -> cron_list,
  *   ScheduleWakeup -> schedule_wakeup
+ *
+ * Module map: schedule.ts (job store, dispatch, run times), cron.ts (cron
+ * syntax, intervals, labels), prompts.ts (model-facing text), loopfile.ts
+ * (loop.md), durable.ts (.pi/scheduled_tasks.json and its lock), renderers.ts
+ * (tool rows, tick message).
  */
 
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import type {
-	ExtensionAPI,
-	ExtensionCommandContext,
-	ExtensionContext,
-	Theme,
-	ToolRenderers,
-} from "@earendil-works/pi-coding-agent";
-import { Container, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { configPath, loadConfig, saveConfig, syncPiCcExtensionsExcludes, type PiCcConfig } from "./config.ts";
 import {
 	describeCron,
 	humanSchedule,
@@ -46,37 +39,45 @@ import {
 	parseEveryClause,
 	parseIntervalToken,
 } from "./cron.ts";
+import { DurableRuntime, type Placement } from "./durable.ts";
+import { displayPrompt, isLoopFileSentinel, LoopFileDelivery, type TickMode } from "./loopfile.ts";
 import {
-	configPath,
-	loadConfig,
-	saveConfig,
-	syncPiCcExtensionsExcludes,
-	type PiCcConfig,
-} from "./config.ts";
-import { generateId, LoopScheduler, type LoopJob } from "./schedule.ts";
+	CRON_CREATE_DESCRIPTION,
+	CRON_CREATE_SNIPPET,
+	CRON_DELETE_DESCRIPTION,
+	CRON_DELETE_SNIPPET,
+	CRON_LIST_DESCRIPTION,
+	CRON_LIST_SNIPPET,
+	LOOP_FILE_SENTINEL,
+	loopGuidelines,
+	missedJobsMessage,
+	monitorGuidelines,
+	provenance,
+	SCHEDULE_WAKEUP_DESCRIPTION,
+	SCHEDULE_WAKEUP_SNIPPET,
+	scheduleRules,
+} from "./prompts.ts";
+import { formatClock, loopToolRenderers, renderTickMessage } from "./renderers.ts";
 import {
-	bodyLines,
-	contentText,
-	firstLine,
-	formatStamp,
-	renderBlock,
-	renderCard,
-	stripProvenance,
-} from "./render.ts";
+	DEFAULT_TIMING,
+	generateId,
+	LoopScheduler,
+	nextRunTime,
+	storedJob,
+	type LoopJob,
+	type TimingConfig,
+} from "./schedule.ts";
+import { truncate } from "./tool-rows.ts";
 
 const STATE_ENTRY = "pi-cc-loop-state";
-const TICK_MESSAGE_TYPE = "pi-cc-loop-tick";
+export const TICK_MESSAGE_TYPE = "pi-cc-loop-tick";
+/** pi-cc-monitor's notification type; its details name the loop a monitor belongs to. */
+const MONITOR_EVENT_TYPE = "pi-cc-monitor-event";
 const WIDGET_KEY = "pi-cc-loop";
 const CONFIG_CHANNEL = "pi-cc:config";
 const LOOP_TOOL_NAMES = ["cron_create", "cron_delete", "cron_list", "schedule_wakeup"];
 const ALL_PI_CC_TOOLS = [...LOOP_TOOL_NAMES, "Monitor", "monitor_stop", "monitor_list"];
 
-/**
- * The event channel pi-cc-monitor publishes on. When a monitor names a loop
- * chain, its events supersede that chain's fallback heartbeat.
- */
-const MONITOR_WAKE_CHANNEL = "monitor:wake";
-
 /**
  * The event channel this extension publishes on when a chain ends. pi-cc-monitor
  * listens to it and stops any monitor that belongs to the chain, the way
@@ -88,76 +89,15 @@ const LOOP_STOPPED_CHANNEL = "loop:stopped";
 const MAX_JOBS = 50;
 const MIN_DELAY_SECONDS = 60;
 const MAX_DELAY_SECONDS = 3600;
+/** A wakeup just under the 5 minute prompt cache lifetime is pulled inside it. */
 const DEFAULT_KEEPALIVE_SECONDS = 1200;
-const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-
-const MAINTENANCE_PROMPT = [
-	"You are running a scheduled maintenance pass.",
-	"Work through the following, in order:",
-	"1. Continue any unfinished work from the conversation.",
-	"2. Tend to the current branch's pull request: review comments, failed CI runs, merge conflicts.",
-	"3. Run cleanup passes such as bug hunts or simplification when nothing else is pending.",
-	"Do not start new initiatives outside that scope, and only perform irreversible actions",
-	"(push, delete) that the transcript already authorized.",
-].join("\n");
-
-/**
- * The rules for a loop whose interval the command layer could not parse.
- *
- * Claude Code's /loop is a skill: the model reads the user's input and
- * applies the skill's rules itself, so an interval written in any language is
- * understood. The command layer here only recognises the English token forms
- * (`5m`, `every 20m`); when it finds none, these rules take over so the model
- * can work the schedule out itself.
- */
-const LOOP_SCHEDULE_RULES = [
-	"This is a `/loop` request. Its prompt is: {prompt}",
-	"",
-	"Decide how it should repeat, then set it up.",
-	"",
-	"**If the prompt asks for a fixed interval** (\"every 30 seconds\", \"each 5 minutes\",",
-	"\"every hour\", \"5m\", \"every 5m\"): create a recurring job with the `cron_create` tool.",
-	"- Convert the interval to a 5-field cron expression in local time (\"M H DoM Mon DoW\").",
-	"  `s` rounds up to the nearest minute (the scheduler's minimum granularity is 1 minute),",
-	"  `m` are minutes, `h` are hours, `d` are days. Examples: `5m` -> `*/5 * * * *`,",
-	"  `1h` -> `0 * * * *`, `1d` -> `0 0 * * *`. If the interval does not cleanly divide its",
-	"  unit, round to the nearest clean interval and tell the user what you rounded to.",
-	"- Then confirm to the user: what is scheduled, the cron expression, the human-readable",
-	"  cadence, that recurring jobs auto-expire after 7 days, and the job id they can cancel",
-	"  with `cron_delete`.",
-	"",
-	"**Otherwise the interval is open-ended.** After each iteration, call the `schedule_wakeup`",
-	"tool with:",
-	"- `delaySeconds`: seconds until the next iteration (60-3600). Default to 1200-1800; pick",
-	"  something shorter only when you observed fast-changing external state.",
-	"- `reason`: one short sentence on why you picked that delay.",
-	"- `prompt`: the same /loop prompt verbatim: {quoted}",
-	"If the task is complete or can no longer make progress, call `schedule_wakeup` with",
-	"`stop: true` instead of scheduling another iteration.",
-].join("\n");
-
-const LOOP_GUIDELINES = [
-	"A `/loop` chain is active. Its prompt is: {prompt}",
-	"After this iteration finishes, call the `schedule_wakeup` tool with:",
-	"- `delaySeconds`: seconds until the next iteration (60-3600). Default to 1200-1800;",
-	"  pick something shorter only when you observed fast-changing external state.",
-	"- `reason`: one short sentence on why you picked that delay.",
-	"- `prompt`: the same /loop prompt verbatim: {quoted}",
-	"If the task is complete or can no longer make progress, call `schedule_wakeup` with",
-	"`stop: true` instead of scheduling another iteration.",
-].join("\n");
-
-const MONITOR_GUIDELINES = [
-	"This iteration is waiting on an external event.",
-	"Arm the `Monitor` tool with `loopPrompt` set to {quoted} so the event wakes this chain",
-	"immediately instead of waiting for the next heartbeat. Keep the `schedule_wakeup` call too:",
-	"its delay is then only the fallback heartbeat for the case where no event ever arrives.",
-].join("\n");
-
-const PROVENANCE = "[loop tick #{n} · scheduled by /loop, not typed by the user]";
+const DEFAULT_MAX_AGE_DAYS = 7;
+/** How many stopped prompts are remembered (and persisted). */
+const MAX_STOPPED_PROMPTS = 20;
 
 interface PersistedState {
 	version: 1;
+	/** Session-only jobs; durable jobs live in .pi/scheduled_tasks.json. */
 	jobs: LoopJob[];
 	/** Prompts whose chain was stopped and must not be rescheduled. */
 	stopped?: string[];
@@ -172,13 +112,12 @@ function envNumber(name: string, fallback: number): number {
 	return Number.isFinite(value) ? value : fallback;
 }
 
-function maxAgeMs(): number {
-	const days = envNumber("PI_LOOP_MAX_AGE_DAYS", DEFAULT_MAX_AGE_MS / 86_400_000);
-	return Math.max(0, days) * 86_400_000;
+function maxAgeDays(): number {
+	return Math.max(0, envNumber("PI_LOOP_MAX_AGE_DAYS", DEFAULT_MAX_AGE_DAYS));
 }
 
-function jitterFraction(): number {
-	return Math.min(1, Math.max(0, envNumber("PI_LOOP_JITTER", 0)));
+function maxAgeMs(): number {
+	return maxAgeDays() * 86_400_000;
 }
 
 /**
@@ -190,92 +129,23 @@ function keepaliveSeconds(): number {
 	return Math.max(0, envNumber("PI_LOOP_KEEPALIVE_SECONDS", DEFAULT_KEEPALIVE_SECONDS));
 }
 
-function formatDuration(ms: number): string {
-	if (!Number.isFinite(ms) || ms < 0) return "unknown";
-	const totalSeconds = Math.round(ms / 1000);
-	if (totalSeconds < 60) return `${totalSeconds}s`;
-	const minutes = Math.floor(totalSeconds / 60);
-	const seconds = totalSeconds % 60;
-	if (minutes < 60) return seconds ? `${minutes}m${seconds}s` : `${minutes}m`;
-	const hours = Math.floor(minutes / 60);
-	const restMinutes = minutes % 60;
-	if (hours < 24) return restMinutes ? `${hours}h${restMinutes}m` : `${hours}h`;
-	const days = Math.floor(hours / 24);
-	return `${days}d${hours % 24}h`;
-}
-
-function formatClock(epochMs: number | undefined): string {
-	if (!epochMs) return "unknown";
-	return new Date(epochMs).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
-}
-
-function truncate(text: string, max: number): string {
-	const clean = text.replace(/\s+/g, " ").trim();
-	return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
-}
-
-/** A compact one-line call row for a tool. */
-function toolCall(label: string, detail: string, theme: Theme): Text {
-	const title = theme.fg("toolTitle", theme.bold(label));
-	return new Text(detail ? `${title} ${theme.fg("muted", detail)}` : title, 0, 0);
-}
-
-/** A compact one-line result row for a tool. */
-function toolResult(
-	summary: string,
-	detail: string | undefined,
-	options: { expanded: boolean; isPartial: boolean; isError: boolean },
-	theme: Theme,
-): Text {
-	if (options.isPartial) return new Text(theme.fg("warning", "Working…"), 0, 0);
-	const prefix = options.isError ? theme.fg("error", "✗ ") : theme.fg("success", "✓ ");
-	const body = options.isError ? theme.fg("error", summary) : theme.fg("toolOutput", summary);
-	const text = prefix + body;
-	if (options.expanded && detail) return new Text(`${text}\n${theme.fg("dim", detail)}`, 0, 0);
-	return new Text(text, 0, 0);
-}
-
-/** Hide the call row once the result has arrived, leaving one result line. */
-function completedCall(): Container {
-	return new Container();
+/** Claude Code's offsets; `PI_LOOP_JITTER=0` runs jobs exactly on their cron minute. */
+function timingConfig(): TimingConfig {
+	const fraction = Math.min(1, Math.max(0, envNumber("PI_LOOP_JITTER", DEFAULT_TIMING.recurringFrac)));
+	return {
+		...DEFAULT_TIMING,
+		recurringFrac: fraction,
+		oneShotMaxMs: fraction > 0 ? DEFAULT_TIMING.oneShotMaxMs : 0,
+	};
 }
 
-/** The first text line of a tool result, used as a fallback summary. */
-function resultText(result: { content?: Array<{ type?: string; text?: string }> }): string {
-	for (const block of result.content ?? []) {
-		if (block?.type === "text" && typeof block.text === "string") {
-			return block.text.split("\n")[0] ?? "";
-		}
-	}
-	return "";
+function durableSyncMs(): number {
+	return Math.max(0, envNumber("PI_LOOP_DURABLE_SYNC_MS", 5000));
 }
 
-function formatDelay(seconds: number | undefined): string {
-	if (seconds === undefined) return "unknown";
-	if (seconds < 60) return `${seconds}s`;
-	return `${Math.round(seconds / 60)}m`;
-}
-
-function jobSummary(job: LoopJob): string {
-	if (job.kind === "cron" && job.cron) {
-		return `${job.id} ${humanSchedule(job.cron)} · next ${formatClock(job.nextFireAt)}`;
-	}
-	return `${job.id} self-paced · ${job.scheduledFor ? `next ${formatClock(job.scheduledFor)}` : "unscheduled"}`;
-}
-
-function resolveLoopFile(cwd: string): { path: string; content: string } | null {
-	const candidates = [path.join(cwd, ".pi", "loop.md"), path.join(os.homedir(), ".pi", "loop.md")];
-	for (const candidate of candidates) {
-		try {
-			if (fs.existsSync(candidate)) {
-				const content = fs.readFileSync(candidate, "utf8");
-				if (content.trim()) return { path: candidate, content };
-			}
-		} catch {
-			// ignore unreadable candidates
-		}
-	}
-	return null;
+/** Models used to Claude Code may echo the prompt with its `/loop ` prefix. */
+function normalizePrompt(prompt: string): string {
+	return prompt.trim().replace(/^\/loop\s+/i, "").trim();
 }
 
 /** The live scheduler, for tests. */
@@ -321,17 +191,44 @@ function extractFlags(raw: string): { body: string; durable: boolean; maxFires?:
 }
 
 export default function piCcLoopExtension(pi: ExtensionAPI): void {
+	/** Cached context for UI helpers. */
+	let lastCtx: ExtensionContext | undefined;
+	/**
+	 * Prompts whose chain was stopped. A stopped chain must not be resurrected
+	 * by a late `schedule_wakeup` call from a turn that a still-running monitor
+	 * woke up.
+	 */
+	const stoppedPrompts = new Set<string>();
+	/**
+	 * Whether the status widget is shown. Claude Code's main session shows no
+	 * loop status at all, so it is off by default; `/loop widget on` turns it on.
+	 */
+	let widgetEnabled = process.env.PI_LOOP_WIDGET === "1";
+	/** Signature of the last persisted state, to avoid redundant session entries. */
+	let lastPersistedSignature = "";
+	/**
+	 * How many times each prompt has been run as a loop tick. The immediate run
+	 * of `/loop` and the fires of the job created afterwards share a counter.
+	 */
+	const tickCounters = new Map<string, number>();
+	const loopFile = new LoopFileDelivery();
+	let durable: DurableRuntime | undefined;
+	/**
+	 * What the current run belongs to, derived from its starting message:
+	 * `chainId` is the self-paced chain whose tick (or monitor) started it,
+	 * `armed` the chains it armed, `tick` the tick number of a /loop run.
+	 */
+	let currentRun: { chainId?: string; armed?: Set<string>; tick?: number } = {};
+
 	const scheduler = new LoopScheduler({
-		dispatch: (job) => {
-			deliverTick(job);
+		dispatch: (job) => deliverTick(job),
+		afterDispatch: (job, finished) => {
+			if (job.durable) durable?.afterFire(job, finished);
 		},
 		onChange: (jobs) => {
 			persist(jobs);
 			refreshWidget(jobs);
 		},
-		maxAgeMs,
-		jitterFraction,
-		jitterCapMs: () => 30 * 60 * 1000,
 		canDispatch: () => {
 			const ctx = lastCtx;
 			if (!ctx) return false;
@@ -341,104 +238,60 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				return false;
 			}
 		},
+		timing: timingConfig,
+		maxAgeMs,
 		onExpire: (job) => {
-			if (job.kind === "wakeup") {
-				// The job is already gone from the store; retire it so the chain
-				// cannot come back and the monitor stops with it.
-				stoppedPrompts.add(job.prompt);
-				try {
-					pi.events.emit(LOOP_STOPPED_CHANNEL, { prompt: job.prompt, reason: "expired" });
-				} catch {
-					// ignore
-				}
-			}
+			const ctx = lastCtx;
+			if (ctx) notify(ctx, `loop ${job.id} ran its final time: recurring jobs expire after ${maxAgeDays()} days`);
 		},
+		onScan: (now) => durable?.maintain(now),
 	});
 	activeScheduler = scheduler;
 
-	/** Chain that the current run belongs to, injected as a system guideline. */
-	let runChainId: string | undefined;
-	/**
-	 * Rules for a loop whose interval the command line did not contain. The
-	 * model applies them itself, the way Claude Code's /loop skill does.
-	 */
-	let pendingScheduleRules: string | undefined;
-	/** One-off note attached to the next run. */
-	let pendingNote: string | undefined;
-	/** Cached context for UI helpers. */
-	let lastCtx: ExtensionContext | undefined;
-	/**
-	 * Prompts whose chain was stopped. A stopped chain must not be resurrected
-	 * by a late `schedule_wakeup` call from a turn that a still-running monitor
-	 * woke up.
-	 */
-	const stoppedPrompts = new Set<string>();
-	/**
-	 * Whether the status widget is shown.
-	 *
-	 * Claude Code's main session shows no loop status at all: the job id only
-	 * appears once, in the CronCreate tool result, and the countdown only in
-	 * agent view. The widget is therefore off by default here too; `/loop
-	 * widget on` turns it on for people who want the at-a-glance status that
-	 * agent view provides in Claude Code.
-	 */
-	let widgetEnabled = process.env.PI_LOOP_WIDGET === "1";
-	/** Signature of the last persisted state, to avoid empty session entries. */
-	let lastPersistedSignature = "";
-
 	// ---------------------------------------------------------------- helpers
 
+	/** What a job's persisted signature depends on; per-fire bookkeeping is left out. */
+	function signatureOf(job: LoopJob): unknown[] {
+		if (job.kind === "wakeup") {
+			return [job.id, job.kind, job.prompt, job.scheduledFor ?? null, job.keepaliveUsed ?? false, job.chainStartedAt ?? null];
+		}
+		return [
+			job.id,
+			job.kind,
+			job.cron,
+			job.prompt,
+			job.recurring,
+			job.createdAt,
+			job.maxFires ?? null,
+			job.maxFires !== undefined ? (job.fireCount ?? 0) : null,
+		];
+	}
+
+	/**
+	 * Save the session's jobs as a session entry. Durable jobs are left out:
+	 * they live in .pi/scheduled_tasks.json, and restoring them from a session
+	 * would run them twice. A new entry is only written when something that
+	 * matters for a restore changed, not on every fire.
+	 */
 	function persist(jobs: LoopJob[]): void {
-		const signature = JSON.stringify(
-			jobs.map((job) => [
-				job.id,
-				job.kind,
-				job.cron,
-				job.prompt,
-				job.recurring,
-				job.nextFireAt,
-				job.scheduledFor,
-				job.keepaliveUsed,
-				job.awaitingReschedule,
-				job.durable,
-				job.reason,
-				job.maxFires,
-				job.fireCount,
-			]),
-		);
+		const kept = jobs.filter((job) => !job.durable).map(storedJob);
+		const stopped = [...stoppedPrompts];
+		const signature = JSON.stringify([kept.map(signatureOf), stopped, widgetEnabled]);
 		if (signature === lastPersistedSignature) return;
 		lastPersistedSignature = signature;
-
-		const durable = jobs.filter((job) => job.durable);
 		try {
-			pi.appendEntry(STATE_ENTRY, {
-				version: 1,
-				jobs,
-				stopped: [...stoppedPrompts],
-				widget: widgetEnabled,
-			} satisfies PersistedState);
+			pi.appendEntry(STATE_ENTRY, { version: 1, jobs: kept, stopped, widget: widgetEnabled } satisfies PersistedState);
 		} catch {
 			// session persistence is best effort
 		}
-		try {
-			// Use the session cwd, not process.cwd(): the user can move the session
-			// with /cd without restarting the process.
-			const dir = path.join(lastCtx?.cwd ?? process.cwd(), ".pi");
-			const file = path.join(dir, "scheduled_tasks.json");
-			if (durable.length === 0) {
-				if (fs.existsSync(file)) fs.rmSync(file);
-				return;
-			}
-			fs.mkdirSync(dir, { recursive: true });
-			const payload: PersistedState = { version: 1, jobs: durable };
-			fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-		} catch {
-			// durable persistence is best effort
-		}
 	}
 
 	function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
-		if (ctx.hasUI) ctx.ui.notify(message, level);
+		try {
+			if (ctx.hasUI) ctx.ui.notify(message, level);
+		} catch {
+			// a stale context must never break the loop
+		}
 	}
 
 	function refreshWidget(jobs: LoopJob[]): void {
@@ -448,44 +301,35 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			ctx.ui.setWidget(WIDGET_KEY, undefined);
 			return;
 		}
-		const lines: string[] = [];
-		for (const job of jobs) {
-			if (job.kind === "cron") {
-				const at = job.nextFireAt;
-				const inText = at ? `in ${formatDuration(at - Date.now())}` : "pending";
-				lines.push(
-					ctx.ui.theme.fg(
-						"accent",
-						`loop ${job.id} · fixed ${job.cron} · next ${formatClock(at)} (${inText}) · ${truncate(job.prompt, 28)}`,
-					),
-				);
-			} else {
-				const at = job.scheduledFor;
-				const inText = at && at > Date.now() ? `next in ${formatDuration(at - Date.now())}` : "awaiting reschedule";
-				lines.push(
-					ctx.ui.theme.fg("accent", `loop ${job.id} · self-paced · ${inText} · ${truncate(job.prompt, 28)}`),
-				);
-			}
-		}
+		// Absolute times only: the widget is not redrawn every second.
+		const lines = jobs.map((job) => {
+			const at = job.kind === "cron" ? job.nextFireAt : job.scheduledFor;
+			const when = at ? `next ${formatClock(at)}` : job.kind === "wakeup" ? "awaiting reschedule" : "pending";
+			const kind = job.kind === "cron" ? `fixed ${job.cron}` : "self-paced";
+			return ctx.ui.theme.fg("accent", `loop ${job.id} \u00b7 ${kind} \u00b7 ${when} \u00b7 ${truncate(displayPrompt(job.prompt), 28)}`);
+		});
 		ctx.ui.setWidget(WIDGET_KEY, lines.length ? lines : undefined);
 	}
 
-	function findChain(prompt: string): LoopJob | undefined {
-		return scheduler.findChain(prompt);
+	function rememberStopped(prompt: string): void {
+		stoppedPrompts.delete(prompt);
+		stoppedPrompts.add(prompt);
+		while (stoppedPrompts.size > MAX_STOPPED_PROMPTS) {
+			const oldest = stoppedPrompts.values().next().value;
+			if (oldest === undefined) break;
+			stoppedPrompts.delete(oldest);
+		}
 	}
 
 	/**
-	 * End a chain for good.
-	 *
-	 * Retiring means: the job is removed, the prompt is remembered so a late
-	 * `schedule_wakeup` cannot resurrect the chain, and pi-cc-monitor is told to
-	 * stop any monitor that belongs to it. Claude Code requires the last part:
-	 * "call ScheduleWakeup with stop: true and TaskStop any Monitor you armed".
-	 * Without it, a monitor that keeps firing wakes the agent, the agent
+	 * End a self-paced chain for good: the job is removed, the prompt is
+	 * remembered so a late `schedule_wakeup` cannot resurrect it, and
+	 * pi-cc-monitor is told to stop the monitors that belong to it. Without the
+	 * last part a monitor that keeps firing wakes the agent, the agent
 	 * reschedules, and the loop the user just stopped comes back.
 	 */
-	function retireChain(chain: LoopJob, reason: string): void {
-		stoppedPrompts.add(chain.prompt);
+	function retireChain(chain: LoopJob, reason: string, options: { silent?: boolean } = {}): void {
+		rememberStopped(chain.prompt);
 		scheduler.remove(chain.id);
 		try {
 			pi.events.emit(LOOP_STOPPED_CHANNEL, { prompt: chain.prompt, reason });
@@ -493,103 +337,140 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			// a listener must never break the loop
 		}
 		const ctx = lastCtx;
-		if (ctx) notify(ctx, `loop ${chain.id} ended: ${reason}`, "info");
+		if (ctx && !options.silent) notify(ctx, `loop ${chain.id} ended: ${reason}`, "info");
 	}
 
-	function endChain(chain: LoopJob, reason: string): void {
-		retireChain(chain, reason);
+	function ensureDurable(): DurableRuntime {
+		durable ??= createDurable(lastCtx?.cwd ?? process.cwd());
+		return durable;
 	}
 
-	function expireOldJobs(ctx: ExtensionContext): void {
-		const limit = maxAgeMs();
-		if (limit <= 0) return;
-		const now = Date.now();
-		for (const job of scheduler.list()) {
-			if (now - job.createdAt < limit) continue;
-			if (job.kind === "wakeup") {
-				retireChain(job, "expired");
-			} else {
-				scheduler.remove(job.id);
-				notify(ctx, `loop ${job.id} expired after ${Math.round(limit / 86_400_000)} days`, "info");
-			}
+	function createDurable(cwd: string): DurableRuntime {
+		return new DurableRuntime({
+			cwd,
+			scheduler,
+			timing: timingConfig,
+			maxAgeMs,
+			syncMs: durableSyncMs,
+			onMissed: reportMissed,
+		});
+	}
+
+	/** Add a job; a durable job is saved to disk and may run in another session. */
+	function addJob(job: LoopJob): Placement {
+		if (job.durable) return ensureDurable().add(job);
+		scheduler.add(job);
+		return { runsHere: true };
+	}
+
+	function removeJob(job: LoopJob): void {
+		scheduler.remove(job.id);
+		if (job.durable) durable?.remove(job.id);
+	}
+
+	/** This session's jobs plus the durable jobs it can see but does not run. */
+	function listJobs(): Array<LoopJob & { foreignReason?: "other-session" | "other-folder" }> {
+		return [...scheduler.list(), ...(durable?.foreignJobs() ?? [])];
+	}
+
+	function foreignNote(job: { foreignReason?: string }): string {
+		if (job.foreignReason === "other-folder") return "  (copied from another folder: listed, not run here)";
+		if (job.foreignReason === "other-session") return "  (run by another Pi session in this project)";
+		return "";
+	}
+
+	/** Durable one-shots that came due while no session ran them: ask before running. */
+	function reportMissed(jobs: LoopJob[]): void {
+		const lines = jobs.map((job) => {
+			const due = nextRunTime(job, job.createdAt, timingConfig());
+			const when = due
+				? ` (was due ${new Date(due).toLocaleString(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })})`
+				: "";
+			return `- job ${job.id}${when}: ${displayPrompt(job.prompt)}`;
+		});
+		try {
+			// Attached to the next turn rather than starting one at startup.
+			pi.sendMessage(
+				{
+					customType: TICK_MESSAGE_TYPE,
+					content: missedJobsMessage(lines),
+					display: true,
+					details: { missed: true, jobIds: jobs.map((job) => job.id) },
+				},
+				{ deliverAs: "nextTurn" },
+			);
+		} catch {
+			// best effort
+		}
+		const ctx = lastCtx;
+		if (ctx) {
+			notify(
+				ctx,
+				`${jobs.length} durable one-shot job${jobs.length === 1 ? " was" : "s were"} missed while Pi was closed; you will be asked before ${jobs.length === 1 ? "it runs" : "they run"}`,
+				"warning",
+			);
 		}
 	}
 
+	/** The text the model gets for a prompt: the loop.md sentinel expands at fire time. */
+	function resolvePrompt(prompt: string, mode: TickMode): string {
+		return isLoopFileSentinel(prompt) ? loopFile.resolve(lastCtx?.cwd ?? process.cwd(), mode) : prompt;
+	}
+
 	/**
-	 * Deliver a scheduled tick.
-	 *
-	 * `followUp` is the low-priority lane: when the agent is busy the message
-	 * waits until the current turn ends instead of cutting into it. That is
-	 * Claude Code's "A scheduled prompt fires between your turns, not while
-	 * Claude is mid-response."
+	 * Deliver a scheduled tick. `followUp` is the low-priority lane: Claude
+	 * Code's "A scheduled prompt fires between your turns, not while Claude is
+	 * mid-response."
 	 */
 	function deliverTick(job: LoopJob): void {
-		// Continue the shared per-prompt counter: the immediate run of /loop and
-		// the first fire of the job the model created afterwards are one loop.
 		const tick = Math.max(tickCounters.get(job.prompt) ?? 0, job.tickCount ?? 0) + 1;
 		tickCounters.set(job.prompt, tick);
-		scheduler.update(job.id, { tickCount: tick, lastTickAt: Date.now() });
-		const content = `${PROVENANCE.replace("{n}", String(tick))}\n${job.prompt}`;
-		// A self-paced tick needs the chain guidelines too, so the model knows
-		// it has to schedule the next iteration.
-		runChainId = job.kind === "wakeup" ? job.id : undefined;
+		job.tickCount = tick;
+		const body = resolvePrompt(job.prompt, job.kind === "cron" ? "cron" : "wakeup");
+		// before_agent_start finds the job through `details.jobId` and gives a
+		// self-paced tick its chain guidelines.
 		pi.sendMessage(
 			{
 				customType: TICK_MESSAGE_TYPE,
-				content,
+				content: `${provenance(tick)}\n${body}`,
 				display: true,
 				details: { jobId: job.id, tickCount: tick, cron: job.cron, scheduledAt: Date.now() },
 			},
 			{ deliverAs: "followUp", triggerTurn: true },
 		);
 
-		const cap = job.maxFires;
-		if (cap !== undefined && (job.fireCount ?? 0) >= cap) {
+		if (job.maxFires !== undefined && (job.fireCount ?? 0) >= job.maxFires) {
 			const ctx = lastCtx;
-			if (ctx) notify(ctx, `loop ${job.id} reached its cap of ${cap} fires`, "info");
+			if (ctx) notify(ctx, `loop ${job.id} reached its cap of ${job.maxFires} fires`, "info");
 		}
 	}
 
 	/**
-	 * Run the prompt right away, the way Claude Code's skill does
-	 * ("Then immediately execute the parsed prompt now").
-	 *
-	 * `steer` is the right lane here: it lands in the current turn when the
-	 * agent is already working, which is what executing the prompt inside the
-	 * skill turn means.
-	 */
-	/**
-	 * How many times each prompt has been run as a loop tick.
+	 * Run the prompt right away, the way Claude Code's skill does ("Then
+	 * immediately execute the parsed prompt now").
 	 *
-	 * The immediate run of `/loop` and the first fire of the job the model
-	 * creates afterwards belong to the same loop, so they share one counter.
+	 * `guidelines` are the instructions for this one run. They travel on the
+	 * message (`details` never reaches the model) and before_agent_start adds
+	 * them to the run the message starts, so they cannot leak into another run.
+	 * The caller waits until the agent is idle, so the message starts its own run.
 	 */
-	const tickCounters = new Map<string, number>();
-
-	function runNow(ctx: ExtensionContext, prompt: string, job?: LoopJob): void {
+	function runNow(ctx: ExtensionContext, prompt: string, job: LoopJob | undefined, guidelines: string[]): void {
 		const tick = (tickCounters.get(prompt) ?? 0) + 1;
 		tickCounters.set(prompt, tick);
-		if (job) {
-			scheduler.update(job.id, {
-				tickCount: tick,
-				fireCount: (job.fireCount ?? 0) + 1,
-				lastTickAt: Date.now(),
-			});
+		if (job && scheduler.get(job.id)) {
+			scheduler.update(job.id, { tickCount: tick, fireCount: (job.fireCount ?? 0) + 1, lastFiredAt: Date.now() });
 		}
-		runChainId = job?.kind === "wakeup" ? job.id : undefined;
+		const body = resolvePrompt(prompt, job?.kind === "cron" ? "cron" : "wakeup");
 		pi.sendMessage(
 			{
 				customType: TICK_MESSAGE_TYPE,
-				content: `${PROVENANCE.replace("{n}", String(tick))}\n${prompt}`,
+				content: `${provenance(tick)}\n${body}`,
 				display: true,
-				details: { jobId: job?.id, tickCount: tick, immediate: true, scheduledAt: Date.now() },
+				details: { jobId: job?.id, tickCount: tick, immediate: true, scheduledAt: Date.now(), guidelines },
 			},
 			{ deliverAs: "steer", triggerTurn: true },
 		);
-	}
-
-	function scheduleNote(text: string): void {
-		pendingNote = text;
+		lastCtx = ctx;
 	}
 
 	/** True when the pi-cc-monitor extension registered its Monitor tool. */
@@ -606,22 +487,76 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		return monitorToolAvailable() ? ALL_PI_CC_TOOLS : LOOP_TOOL_NAMES;
 	}
 
+	/**
+	 * A run finished without an abort: self-paced chains whose tick the model
+	 * did not reschedule get their one keepalive, or end.
+	 */
+	function settleChains(ctx: ExtensionContext): void {
+		const now = Date.now();
+		for (const chain of scheduler.byKind("wakeup")) {
+			// The keepalive turn is the model's last chance to reschedule.
+			if (chain.keepaliveTurn) {
+				retireChain(chain, "keepalive budget exhausted (the model did not reschedule twice)");
+				continue;
+			}
+			if (!chain.awaitingReschedule) continue;
+
+			const limit = maxAgeMs();
+			if (limit > 0 && now - (chain.chainStartedAt ?? chain.createdAt) >= limit) {
+				retireChain(chain, `reached its ${maxAgeDays()}-day limit`);
+				continue;
+			}
+			if (chain.keepaliveUsed) continue;
+
+			const fallback = keepaliveSeconds();
+			if (fallback <= 0) {
+				retireChain(chain, "the model did not reschedule (keepalive disabled)");
+				continue;
+			}
+			scheduler.update(chain.id, {
+				scheduledFor: now + fallback * 1000,
+				keepaliveUsed: true,
+				awaitingReschedule: false,
+			});
+			notify(
+				ctx,
+				`loop ${chain.id}: the model did not reschedule \u2014 keepalive armed (${Math.round(fallback / 60)} min)`,
+				"warning",
+			);
+		}
+	}
+
+	/**
+	 * Esc interrupted a turn that belongs to a self-paced loop (its tick, the
+	 * /loop run that armed it, or a turn its monitor woke): cancel that loop,
+	 * with Claude Code's notice ("A `Pending wakeup cancelled` notice confirms
+	 * that the loop won't fire again").
+	 *
+	 * Claude Code cancels every self-paced loop on any Esc, idle or not. Here
+	 * an interrupted unrelated turn leaves the loops alone; `/loop stop` stops
+	 * them. Fixed-interval jobs keep running either way, as in Claude Code.
+	 */
+	function cancelCurrentLoop(ctx: ExtensionContext): void {
+		const ids = new Set([...(currentRun.chainId ? [currentRun.chainId] : []), ...(currentRun.armed ?? [])]);
+		const chains = [...ids]
+			.map((id) => scheduler.get(id))
+			.filter((chain): chain is LoopJob => chain?.kind === "wakeup");
+		if (!chains.length) return;
+		for (const chain of chains) retireChain(chain, "pending wakeup cancelled (Esc)", { silent: true });
+		notify(ctx, `Pending wakeup cancelled \u00b7 loop ${chains.map((chain) => chain.id).join(", ")} ended`, "info");
+	}
+
 	// ---------------------------------------------------------------- command
 
 	pi.registerCommand("loop", {
 		description:
-			"Run a prompt repeatedly. Usage: /loop [interval] <prompt> | /loop <prompt> | /loop stop [id] | /loop status | /loop settings",
+			"Run a prompt repeatedly. Usage: /loop [interval] <prompt> | /loop <prompt> | /loop [interval] | /loop stop [id] | /loop status | /loop settings",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			lastCtx = ctx;
 			const raw = args.trim();
 
-			if (!raw) {
-				await startLoop(ctx, null, "", false, undefined);
-				return;
-			}
-
 			const [head, ...rest] = raw.split(/\s+/);
-			switch (head.toLowerCase()) {
+			switch ((head ?? "").toLowerCase()) {
 				case "stop":
 					await stopLoops(ctx, rest.join(" "));
 					return;
@@ -678,26 +613,32 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			let intervalSeconds: number | null = null;
 			let prompt = body;
 
-			// Rule 1: leading interval token, e.g. "5m check the deploy"
-			const leading = /^(\S+)\s+([\s\S]+)$/.exec(body);
-			if (leading) {
-				const parsed = parseIntervalToken(leading[1]);
-				if (parsed !== null) {
-					intervalSeconds = parsed;
-					prompt = leading[2].trim();
+			const intervalOnly = parseIntervalToken(body);
+			if (intervalOnly !== null) {
+				// "/loop 15m": the loop.md tasks (or maintenance) on a fixed schedule.
+				intervalSeconds = intervalOnly;
+				prompt = "";
+			} else {
+				// Rule 1: leading interval token, e.g. "5m check the deploy"
+				const leading = /^(\S+)\s+([\s\S]+)$/.exec(body);
+				if (leading) {
+					const parsed = parseIntervalToken(leading[1]);
+					if (parsed !== null) {
+						intervalSeconds = parsed;
+						prompt = leading[2].trim();
+					}
 				}
-			}
-
-			// Rule 2: trailing "every N units", e.g. "check the deploy every 20m"
-			if (intervalSeconds === null) {
-				const every = parseEveryClause(body);
-				if (every) {
-					intervalSeconds = every.interval;
-					prompt = every.prompt;
+				// Rule 2: trailing "every N units", e.g. "check the deploy every 20m"
+				if (intervalSeconds === null) {
+					const every = parseEveryClause(body);
+					if (every) {
+						intervalSeconds = every.interval;
+						prompt = every.prompt;
+					}
 				}
 			}
 
-			// Rule 3: no interval -> self-paced
+			// Rule 3: no interval -> the model decides (self-paced unless it asks for one)
 			await startLoop(ctx, intervalSeconds, prompt, flags.durable, flags.maxFires);
 		},
 	});
@@ -706,105 +647,115 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		ctx: ExtensionCommandContext,
 		intervalSeconds: number | null,
 		prompt: string,
-		durable: boolean,
+		durableFlag: boolean,
 		maxFires: number | undefined,
 	): Promise<void> {
-		expireOldJobs(ctx);
+		// Claude Code queues a /loop typed while it is busy. Wait for the current
+		// turn rather than steering into it: the immediate run has to start its
+		// own turn, or its instructions would never reach the model.
+		if (!ctx.isIdle()) {
+			notify(ctx, "/loop starts when the current turn finishes", "info");
+			await ctx.waitForIdle();
+		}
 
+		// Without a prompt the loop runs the loop.md tasks, resolved at each fire.
+		const finalPrompt = prompt || LOOP_FILE_SENTINEL;
 		// Starting a chain again clears the stop marker: the user asked for it.
-		stoppedPrompts.delete(prompt);
-
-		let finalPrompt = prompt;
-
-		if (!finalPrompt) {
-			const loopFile = resolveLoopFile(ctx.cwd);
-			if (loopFile) {
-				finalPrompt = `Work the tasks from the loop file at ${loopFile.path}:\n\n${loopFile.content}`;
-			} else {
-				finalPrompt = MAINTENANCE_PROMPT;
-			}
-		}
+		stoppedPrompts.delete(finalPrompt);
+		// A new loop starts by sending the full task list again.
+		if (isLoopFileSentinel(finalPrompt)) loopFile.reset();
 
 		if (intervalSeconds === null) {
-			// The interval could not be parsed from the command line. Claude Code's
-			// /loop is a skill, so the model reads the input and works the schedule
-			// out itself; the rules below let it do the same here. No chain is
-			// created up front: the model picks cron_create (fixed interval) or
-			// schedule_wakeup (open ended), and schedule_wakeup creates the chain.
-			let rules = LOOP_SCHEDULE_RULES.replace("{prompt}", finalPrompt).replace(
-				"{quoted}",
-				`"${finalPrompt}"`,
-			);
-			if (durable) {
-				rules +=
-					"\n- The user asked for the job to survive a restart: create it with `durable: true`.";
-			}
-			if (maxFires !== undefined) {
-				rules +=
-					`\n- The user asked for the job to stop after ${maxFires} fires: create it with \`maxFires: ${maxFires}\`.`;
+			let guidelines: string[];
+			if (!prompt) {
+				// A bare /loop is self-paced, like Claude Code's.
+				guidelines = [loopGuidelines(finalPrompt)];
+				if (monitorToolAvailable()) guidelines.push(monitorGuidelines(finalPrompt));
+			} else {
+				// The interval could not be parsed from the command line. Claude
+				// Code's /loop is a skill, so the model reads the input and works
+				// the schedule out itself; the rules below let it do the same here.
+				let rules = scheduleRules(finalPrompt);
+				if (durableFlag) {
+					rules += "\n- The user asked for the job to survive a restart: create it with `durable: true`.";
+				}
+				if (maxFires !== undefined) {
+					rules += `\n- The user asked for the job to stop after ${maxFires} fires: create it with \`maxFires: ${maxFires}\`.`;
+				}
+				guidelines = [rules];
+				if (monitorToolAvailable()) {
+					guidelines.push(`If you choose the open-ended mode:\n${monitorGuidelines(finalPrompt)}`);
+				}
 			}
-			pendingScheduleRules = rules;
-			runNow(ctx, finalPrompt);
+			runNow(ctx, finalPrompt, undefined, guidelines);
 			return;
 		}
 
 		const spec = intervalToCron(intervalSeconds);
-		if (!spec) {
+		if (!spec || !parseCron(spec.cron)) {
 			notify(ctx, `Invalid interval: ${intervalSeconds}s`, "error");
 			return;
 		}
-		if (!parseCron(spec.cron)) {
-			notify(ctx, `Could not build a cron expression for ${intervalSeconds}s`, "error");
-			return;
-		}
 		if (scheduler.size >= MAX_JOBS) {
 			notify(ctx, `Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`, "error");
 			return;
 		}
 
-		const job = scheduler.add({
+		const job: LoopJob = {
 			id: generateId(),
 			kind: "cron",
 			cron: spec.cron,
 			prompt: finalPrompt,
 			recurring: true,
 			createdAt: Date.now(),
-			durable,
+			durable: durableFlag,
 			maxFires,
 			label: humanSchedule(spec.cron),
 			source: "loop_command",
-		});
+		};
+		let placement: Placement;
+		try {
+			placement = addJob(job);
+		} catch (error) {
+			notify(ctx, error instanceof Error ? error.message : String(error), "error");
+			return;
+		}
+		const nextAt = job.nextFireAt ?? nextRunTime(job, job.createdAt, timingConfig()) ?? undefined;
 
-		const expiryDays = Math.round(maxAgeMs() / 86_400_000);
+		const days = maxAgeDays();
 		notify(
 			ctx,
-			`Scheduled ${job.id} (${job.label}, next run ${formatClock(job.nextFireAt)}) · ${spec.cron} · expires in ${expiryDays}d · cancel with /loop stop ${job.id}` +
-				(spec.note ? ` · ${spec.note}` : ""),
+			`Scheduled ${job.id} (${job.label}, next run ${formatClock(nextAt)}) \u00b7 ${spec.cron} \u00b7 expires in ${days}d \u00b7 cancel with /loop stop ${job.id}` +
+				(spec.note ? ` \u00b7 ${spec.note}` : "") +
+				(placement.runsHere ? "" : ` \u00b7 runs in the Pi session holding the project lock (pid ${placement.holderPid ?? "?"})`),
 			"info",
 		);
-		scheduleNote(
+		const note =
 			`A recurring /loop job was created: id ${job.id}, cron \`${spec.cron}\` (${spec.human}), ` +
-				`next run ${formatClock(job.nextFireAt)}, auto-expires after ${expiryDays} days. ` +
-				`The user cancels it with \`/loop stop ${job.id}\`.` +
-				(spec.note ? ` The requested interval was adjusted: ${spec.note}.` : ""),
-		);
+			`next run ${formatClock(nextAt)}, auto-expires after ${days} days (it runs one final time, then it is deleted). ` +
+			`The user cancels it with \`/loop stop ${job.id}\`.` +
+			(spec.note ? ` The requested interval was adjusted: ${spec.note}.` : "");
 
-		runNow(ctx, finalPrompt, job);
+		runNow(ctx, finalPrompt, job, [note]);
 	}
 
 	async function stopLoops(ctx: ExtensionContext, target: string): Promise<void> {
 		if (target) {
 			const job = scheduler.get(target);
-			if (!job) {
-				notify(ctx, `No loop with id ${target}`, "warning");
+			if (job) {
+				if (job.kind === "wakeup") {
+					retireChain(job, "stopped by the user");
+				} else {
+					removeJob(job);
+					notify(ctx, `Cancelled loop ${target}`, "info");
+				}
 				return;
 			}
-			if (job.kind === "wakeup") {
-				retireChain(job, "stopped by the user");
-			} else {
-				scheduler.remove(target);
-				notify(ctx, `Cancelled loop ${target}`, "info");
+			if (durable?.remove(target)) {
+				notify(ctx, `Cancelled durable job ${target}`, "info");
+				return;
 			}
+			notify(ctx, `No loop with id ${target}`, "warning");
 			return;
 		}
 		const jobs = scheduler.list();
@@ -813,40 +764,38 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			return;
 		}
 		for (const job of jobs) {
-			if (job.kind === "wakeup") {
-				// Retiring also tells pi-cc-monitor to stop the monitors that
-				// belong to this chain.
-				retireChain(job, "stopped by the user");
-			} else {
-				scheduler.remove(job.id);
-			}
+			// Retiring also tells pi-cc-monitor to stop the chain's monitors.
+			if (job.kind === "wakeup") retireChain(job, "stopped by the user");
+			else removeJob(job);
 		}
 		notify(ctx, `Cancelled ${jobs.length} loop${jobs.length === 1 ? "" : "s"}`, "info");
 	}
 
 	function showStatus(ctx: ExtensionContext): void {
-		const jobs = scheduler.list();
+		const jobs = listJobs();
 		if (!jobs.length) {
 			notify(ctx, "No active loops", "info");
 			return;
 		}
 		const lines = jobs.map((job) => {
+			const prompt = truncate(displayPrompt(job.prompt), 60);
 			if (job.kind === "cron") {
-				const cap = job.maxFires !== undefined ? ` · ${job.fireCount ?? 0}/${job.maxFires} fires` : "";
-				return `${job.id}  cron  ${job.cron}  (${job.label ?? describeCron(job.cron ?? "")})  next ${formatClock(job.nextFireAt)}${cap}  ${truncate(job.prompt, 60)}`;
+				const cap = job.maxFires !== undefined ? ` \u00b7 ${job.fireCount ?? 0}/${job.maxFires} fires` : "";
+				const label = job.label ?? describeCron(job.cron ?? "");
+				return `${job.id}  cron  ${job.cron}  (${label})  next ${formatClock(job.nextFireAt)}${cap}${job.durable ? "  durable" : ""}${foreignNote(job)}  ${prompt}`;
 			}
 			const at = job.scheduledFor;
-			const inText = at && at > Date.now() ? `next in ${formatDuration(at - Date.now())}` : "awaiting reschedule";
-			return `${job.id}  self-paced  ${inText}  ${truncate(job.prompt, 60)}`;
+			const when = at && at > Date.now() ? `next ${formatClock(at)}` : "awaiting reschedule";
+			return `${job.id}  self-paced  ${when}  ${prompt}`;
 		});
-		if (ctx.hasUI) ctx.ui.notify(lines.join("\n"), "info");
+		notify(ctx, lines.join("\n"), "info");
 	}
 
 	function showHelp(ctx: ExtensionContext): void {
 		const help = [
 			"/loop [interval] <prompt>   run <prompt> every <interval> (e.g. 30s, 5m, 2h, 1d)",
 			"/loop <prompt>              self-paced: the agent picks the next delay",
-			"/loop                       use .pi/loop.md, or the built-in maintenance prompt",
+			"/loop [interval]            the .pi/loop.md tasks, or the built-in maintenance prompt",
 			"/loop stop [id]             cancel one loop, or all of them",
 			"/loop status                list the active loops",
 			"/loop widget on|off         show or hide the status line above the editor",
@@ -854,23 +803,24 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			"/loop settings messages on|off   compact two-line markers",
 			"/loop settings tools on|off      one-line tool results",
 			"",
+			"Esc on a self-paced loop's own turn cancels that loop; fixed-interval loops keep running.",
 			"Flags: --durable  write the job to .pi/scheduled_tasks.json so it survives a restart.",
 			"       --max N   stop the loop after N fires.",
 		].join("\n");
-		if (ctx.hasUI) ctx.ui.notify(help, "info");
+		notify(ctx, help, "info");
 	}
 
 	function showSettings(ctx: ExtensionContext): void {
 		const config = loadConfig();
 		const lines = [
-			`pi-cc settings · ${configPath()}`,
+			`pi-cc settings \u00b7 ${configPath()}`,
 			`  messages:  ${config.compactMessages ? "compact" : "card"}`,
 			`  tool rows: ${config.compactToolRows ? "compact" : "default"}`,
 			"",
 			"Usage: /loop settings messages on|off",
 			"       /loop settings tools on|off",
 		];
-		if (ctx.hasUI) ctx.ui.notify(lines.join("\n"), "info");
+		notify(ctx, lines.join("\n"), "info");
 	}
 
 	function setSetting(ctx: ExtensionContext, key: "messages" | "tools", raw: string | undefined): void {
@@ -881,8 +831,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			showSettings(ctx);
 			return;
 		}
-		const patch: Partial<PiCcConfig> =
-			key === "messages" ? { compactMessages: on } : { compactToolRows: on };
+		const patch: Partial<PiCcConfig> = key === "messages" ? { compactMessages: on } : { compactToolRows: on };
 		const next = saveConfig(patch);
 		let compatChanged = false;
 		if (key === "tools") {
@@ -895,518 +844,355 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		}
 		notify(ctx, `${key === "messages" ? "Compact message style" : "Compact tool rows"} ${on ? "enabled" : "disabled"}`, "info");
 		if (compatChanged) {
-			notify(ctx, "pi-cc-extensions excludeRenderers updated · /reload to apply", "info");
+			notify(ctx, "pi-cc-extensions excludeRenderers updated \u00b7 /reload to apply", "info");
 		}
 	}
 
 	// ------------------------------------------------------------------ tools
 
-	function registerTools(): void {
-
-		pi.registerTool({
-			name: "cron_create",
-			label: "Create Scheduled Job",
-			description:
-				"Schedule a prompt to run on a 5-field cron expression in local time. Use this for fixed-interval " +
-				"work such as polling a deployment or re-running a check. One-shot reminders should set " +
-				"recurring to false. The job id can be cancelled with cron_delete.",
-			parameters: Type.Object({
-				cron: Type.String({
+	pi.registerTool({
+		name: "cron_create",
+		label: "Create Scheduled Job",
+		description: CRON_CREATE_DESCRIPTION,
+		promptSnippet: CRON_CREATE_SNIPPET,
+		parameters: Type.Object({
+			cron: Type.String({
+				description:
+					'Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes).',
+			}),
+			prompt: Type.String({ description: "The prompt to enqueue at each fire time." }),
+			recurring: Type.Optional(
+				Type.Boolean({
 					description:
-						'Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes).',
+						"true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete.",
 				}),
-				prompt: Type.String({ description: "The prompt to enqueue at each fire time." }),
-				recurring: Type.Optional(
-					Type.Boolean({
-						description:
-							"true (default) = fire on every cron match until deleted or auto-expired. false = fire once at the next match, then auto-delete.",
-					}),
-				),
-				durable: Type.Optional(
-					Type.Boolean({ description: "Write the job to .pi/scheduled_tasks.json so it survives a restart." }),
-				),
-				maxFires: Type.Optional(
-					Type.Number({
-						minimum: 1,
-						description: "Stop the job after this many fires. Claude Code has no such cap; it is an addition here.",
-					}),
-				),
-			}),
-			annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-				lastCtx = ctx;
-				const fields = parseCron(params.cron);
-				if (!fields) {
-					throw new Error(
-						`Invalid cron expression '${params.cron}'. Expected 5 fields: M H DoM Mon DoW.`,
-					);
-				}
-				if (isUnreachable(params.cron)) {
-					throw new Error(`Cron expression '${params.cron}' does not match any date within the next year.`);
-				}
-				if (scheduler.size >= MAX_JOBS) {
-					throw new Error(`Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`);
-				}
-				if (!params.prompt?.trim()) {
-					throw new Error("prompt must not be empty.");
-				}
+			),
+			durable: Type.Optional(
+				Type.Boolean({
+					description:
+						"true = persist to .pi/scheduled_tasks.json and survive restarts. false (default) = this session only. Use true only when the user asks the task to survive across sessions.",
+				}),
+			),
+			maxFires: Type.Optional(
+				Type.Integer({
+					minimum: 1,
+					description: "Stop the job after this many fires. Claude Code has no such cap; it is an addition here.",
+				}),
+			),
+		}),
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			lastCtx = ctx;
+			if (!parseCron(params.cron)) {
+				throw new Error(`Invalid cron expression '${params.cron}'. Expected 5 fields: M H DoM Mon DoW.`);
+			}
+			if (isUnreachable(params.cron)) {
+				throw new Error(`Cron expression '${params.cron}' does not match any date within the next year.`);
+			}
+			if (scheduler.size >= MAX_JOBS) {
+				throw new Error(`Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`);
+			}
+			if (!params.prompt?.trim()) {
+				throw new Error("prompt must not be empty.");
+			}
 
-				const job = scheduler.add({
-					id: generateId(),
-					kind: "cron",
-					cron: params.cron.trim(),
-					prompt: params.prompt,
-					recurring: params.recurring ?? true,
-					createdAt: Date.now(),
-					durable: params.durable ?? false,
-					maxFires: params.maxFires,
-					// Continue the tick numbering of the /loop run that led here.
-					tickCount: tickCounters.get(params.prompt) ?? 0,
-					label: humanSchedule(params.cron),
-					source: "cron_create",
-				});
+			const recurring = params.recurring ?? true;
+			const job: LoopJob = {
+				id: generateId(),
+				kind: "cron",
+				cron: params.cron.trim(),
+				prompt: params.prompt,
+				recurring,
+				createdAt: Date.now(),
+				durable: params.durable ?? false,
+				maxFires: params.maxFires,
+				// Continue the tick numbering of the /loop run that led here.
+				tickCount: tickCounters.get(params.prompt) ?? currentRun.tick ?? 0,
+				label: humanSchedule(params.cron),
+				source: "cron_create",
+			};
+			const placement = addJob(job);
+			const nextAt = job.nextFireAt ?? nextRunTime(job, job.createdAt, timingConfig()) ?? undefined;
+
+			const lines = [`Scheduled ${job.id} (${job.label}, next run ${formatClock(nextAt)})`];
+			if (job.durable) {
+				lines.push(
+					placement.runsHere
+						? "Durable: saved to .pi/scheduled_tasks.json, survives restarts."
+						: `Durable: saved to .pi/scheduled_tasks.json. Another Pi session in this project (pid ${placement.holderPid ?? "?"}) holds the scheduler lock and runs it.`,
+				);
+			} else {
+				lines.push("Session-only: restored if this session is resumed, gone otherwise.");
+			}
+			if (recurring) {
+				lines.push(`Recurring jobs auto-expire after ${maxAgeDays()} days: the job runs one final time, then it is deleted.`);
+			}
+			lines.push(`Cancel it with cron_delete { "id": "${job.id}" }.`);
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: {
+					id: job.id,
+					cron: job.cron,
+					recurring: job.recurring,
+					durable: job.durable,
+					nextFireAt: nextAt,
+					prompt: job.prompt,
+					runsHere: placement.runsHere,
+				},
+			};
+		},
+	});
 
+	pi.registerTool({
+		name: "cron_delete",
+		label: "Cancel Scheduled Job",
+		description: CRON_DELETE_DESCRIPTION,
+		promptSnippet: CRON_DELETE_SNIPPET,
+		parameters: Type.Object({
+			id: Type.String({ description: "The job id returned by cron_create, or the id of a self-paced loop." }),
+		}),
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			lastCtx = ctx;
+			const job = scheduler.get(params.id);
+			if (job) {
+				// A self-paced chain ends the same way /loop stop ends it.
+				if (job.kind === "wakeup") retireChain(job, "cancelled with cron_delete");
+				else removeJob(job);
+			} else if (!durable?.remove(params.id)) {
 				return {
-					content: [
-						{
-							type: "text",
-							text:
-								`Scheduled ${job.id} (${job.label}, next run ${formatClock(job.nextFireAt)})\n` +
-								`Cancel it with cron_delete { "id": "${job.id}" }.`,
-						},
-					],
-					details: {
-						id: job.id,
-						cron: job.cron,
-						recurring: job.recurring,
-						durable: job.durable,
-						nextFireAt: job.nextFireAt,
-						prompt: job.prompt,
-					},
+					content: [{ type: "text" as const, text: `No scheduled job with id ${params.id}.` }],
+					details: { cancelled: false, id: params.id },
 				};
-			},
-		});
+			}
+			return {
+				content: [{ type: "text" as const, text: `Cancelled job ${params.id}.` }],
+				details: { cancelled: true, id: params.id },
+			};
+		},
+	});
 
-		pi.registerTool({
-			name: "cron_delete",
-			label: "Cancel Scheduled Job",
-			description: "Cancel a scheduled job by its id. Use it to stop a recurring /loop.",
-			parameters: Type.Object({
-				id: Type.String({ description: "The job id returned by cron_create." }),
-			}),
-			annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-				lastCtx = ctx;
-				const job = scheduler.get(params.id);
-				if (!job) {
-					return {
-						content: [{ type: "text" as const, text: `No scheduled job with id ${params.id}.` }],
-						details: { cancelled: false, id: params.id },
-					};
-				}
-				scheduler.remove(params.id);
+	pi.registerTool({
+		name: "cron_list",
+		label: "List Scheduled Jobs",
+		description: CRON_LIST_DESCRIPTION,
+		promptSnippet: CRON_LIST_SNIPPET,
+		parameters: Type.Object({}),
+		annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			lastCtx = ctx;
+			const jobs = listJobs();
+			if (!jobs.length) {
 				return {
-					content: [{ type: "text" as const, text: `Cancelled job ${params.id}.` }],
-					details: { cancelled: true, id: params.id },
+					content: [{ type: "text" as const, text: "No scheduled jobs." }],
+					details: { jobs: [] },
 				};
-			},
-		});
+			}
+			const text = jobs
+				.map((job) => {
+					const prompt = truncate(displayPrompt(job.prompt), 80);
+					if (job.kind === "cron") {
+						return `${job.id}  cron ${job.cron}  ${humanSchedule(job.cron ?? "")}  recurring=${job.recurring}  next ${formatClock(job.nextFireAt)}${job.durable ? "  durable" : ""}${foreignNote(job)}  ${prompt}`;
+					}
+					return `${job.id}  self-paced  next ${job.scheduledFor ? formatClock(job.scheduledFor) : "unscheduled"}  ${prompt}`;
+				})
+				.join("\n");
+			return {
+				content: [{ type: "text" as const, text }],
+				details: { jobs: jobs.map((job) => storedJob(job)) },
+			};
+		},
+	});
 
-		pi.registerTool({
-			name: "cron_list",
-			label: "List Scheduled Jobs",
-			description: "List the scheduled jobs of this session with their ids, cron expressions and next run times.",
-			parameters: Type.Object({}),
-			annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-			async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-				lastCtx = ctx;
-				const jobs = scheduler.list();
-				if (!jobs.length) {
-					return {
-						content: [{ type: "text" as const, text: "No scheduled jobs." }],
-						details: { jobs: [] },
-					};
-				}
-				const text = jobs
-					.map((job) =>
-						job.kind === "cron"
-							? `${job.id}  cron ${job.cron}  recurring=${job.recurring}  next ${formatClock(job.nextFireAt)}  ${truncate(job.prompt, 80)}`
-							: `${job.id}  self-paced  next ${job.scheduledFor ? formatClock(job.scheduledFor) : "unscheduled"}  ${truncate(job.prompt, 80)}`,
-					)
-					.join("\n");
+	pi.registerTool({
+		name: "schedule_wakeup",
+		label: "Schedule Next Loop Iteration",
+		description: SCHEDULE_WAKEUP_DESCRIPTION,
+		promptSnippet: SCHEDULE_WAKEUP_SNIPPET,
+		parameters: Type.Object({
+			delaySeconds: Type.Optional(
+				Type.Number({
+					description: "Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless stop is true.",
+				}),
+			),
+			reason: Type.Optional(
+				Type.String({ description: "One short sentence explaining the chosen delay. Shown to the user." }),
+			),
+			prompt: Type.Optional(
+				Type.String({
+					description: `The /loop input to fire on wake-up, verbatim, so the next firing repeats the task. For a bare /loop pass the literal sentinel "${LOOP_FILE_SENTINEL}".`,
+				}),
+			),
+			stop: Type.Optional(
+				Type.Boolean({
+					description: "Set to true to end the self-paced loop immediately. Omit every other field.",
+				}),
+			),
+		}),
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			lastCtx = ctx;
+
+			if (params.stop === true) {
+				// Stop the loop this turn belongs to; otherwise the named one, or all.
+				const current = currentRun.chainId ? scheduler.get(currentRun.chainId) : undefined;
+				const named = params.prompt ? scheduler.findChain(normalizePrompt(params.prompt)) : undefined;
+				const chains = current ? [current] : named ? [named] : scheduler.byKind("wakeup");
+				for (const chain of chains) retireChain(chain, "stopped by the agent");
 				return {
-					content: [{ type: "text" as const, text }],
-					details: { jobs },
+					content: [
+						{
+							type: "text" as const,
+							text: chains.length
+								? `Loop ended. ${chains.length} pending wakeup(s) cancelled.`
+								: "Loop ended. Nothing was pending.",
+						},
+					],
+					details: { stopped: true, cancelledWakeups: chains.length },
 				};
-			},
-		});
+			}
 
-		pi.registerTool({
-			name: "schedule_wakeup",
-			label: "Schedule Next Loop Iteration",
-			description:
-				"Schedule the next iteration of a self-paced /loop, or end the loop. " +
-				"Pass delaySeconds (60-3600), a one-sentence reason, and the same /loop prompt verbatim. " +
-				"Pass stop: true when the task is complete or can no longer make progress.",
-			parameters: Type.Object({
-				delaySeconds: Type.Optional(
-					Type.Number({
-						description:
-							"Seconds from now to wake up. Clamped to [60, 3600] by the runtime. Required unless stop is true.",
-					}),
-				),
-				reason: Type.Optional(
-					Type.String({ description: "One short sentence explaining the chosen delay. Shown to the user." }),
-				),
-				prompt: Type.Optional(
-					Type.String({
-						description:
-							"The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing continues the loop.",
-					}),
-				),
-				stop: Type.Optional(
-					Type.Boolean({
-						description: "Set to true to end the self-paced loop immediately. All other fields are ignored.",
-					}),
-				),
-			}),
-			annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-				lastCtx = ctx;
-
-				if (params.stop === true) {
-					const chains = scheduler.byKind("wakeup");
-					for (const chain of chains) {
-						// Retiring also stops the monitors that belong to this chain.
-						retireChain(chain, "stopped by the agent");
-					}
+			if (typeof params.delaySeconds !== "number" || Number.isNaN(params.delaySeconds)) {
+				throw new Error("delaySeconds is required unless stop is true.");
+			}
+			const prompt = params.prompt ? normalizePrompt(params.prompt) : "";
+			if (!prompt) {
+				throw new Error("prompt is required unless stop is true.");
+			}
+
+			// Claude Code rounds and clamps; only a change after rounding counts as clamped.
+			const requested = params.delaySeconds;
+			const rounded = Number.isFinite(requested) ? Math.round(requested) : requested > 0 ? MAX_DELAY_SECONDS : MIN_DELAY_SECONDS;
+			let delay = Math.min(MAX_DELAY_SECONDS, Math.max(MIN_DELAY_SECONDS, rounded));
+			const wasClamped = !Number.isFinite(requested) || delay !== rounded;
+
+			const now = Date.now();
+			// A tick of a chain re-arms that chain even if the model reworded the prompt.
+			let chain =
+				scheduler.findChain(prompt) ?? (currentRun.chainId ? scheduler.get(currentRun.chainId) : undefined);
+			if (chain) {
+				const limit = maxAgeMs();
+				if (limit > 0 && now - (chain.chainStartedAt ?? chain.createdAt) >= limit) {
+					retireChain(chain, `reached its ${maxAgeDays()}-day limit`);
 					return {
 						content: [
 							{
 								type: "text" as const,
-								text: chains.length
-									? `Loop ended. ${chains.length} pending wakeup(s) cancelled.`
-									: "Loop ended. Nothing was pending.",
+								text:
+									`The /loop has reached its ${maxAgeDays()}-day limit and has ended. Do not reschedule it; ` +
+									"tell the user they can start a new /loop.",
 							},
 						],
-						details: { stopped: true, cancelledWakeups: chains.length },
+						details: { stopped: true, agedOut: true, id: chain.id, cancelledWakeups: 1 },
 					};
 				}
-
-				if (typeof params.delaySeconds !== "number" || !Number.isFinite(params.delaySeconds)) {
-					throw new Error("delaySeconds is required unless stop is true.");
-				}
-				const prompt = params.prompt?.trim();
-				if (!prompt) {
-					throw new Error("prompt is required unless stop is true.");
+			} else {
+				if (stoppedPrompts.has(prompt)) {
+					throw new Error(
+						`The /loop chain for "${prompt}" was stopped and must not be rescheduled. ` +
+							"Do not call schedule_wakeup for it again. If the work should continue, ask the user to start a new /loop.",
+					);
 				}
+				chain = {
+					id: generateId(),
+					kind: "wakeup",
+					prompt,
+					recurring: false,
+					createdAt: now,
+					chainStartedAt: now,
+					durable: false,
+					tickCount: tickCounters.get(prompt) ?? currentRun.tick ?? 0,
+					source: "schedule_wakeup",
+				};
+				addJob(chain);
+			}
 
-				const requested = params.delaySeconds;
-				const clamped = Math.min(MAX_DELAY_SECONDS, Math.max(MIN_DELAY_SECONDS, requested));
-				const wasClamped = clamped !== requested;
-
-				let chain = findChain(prompt);
-				if (!chain) {
-					if (stoppedPrompts.has(prompt)) {
-						throw new Error(
-							`The /loop chain for "${prompt}" was stopped and must not be rescheduled. ` +
-								"Do not call schedule_wakeup for it again. If the work should continue, ask the user to start a new /loop.",
-						);
-					}
-					chain = scheduler.add({
-						id: generateId(),
-						kind: "wakeup",
-						prompt,
-						recurring: false,
-						createdAt: Date.now(),
-						chainStartedAt: Date.now(),
-						durable: false,
-						source: "schedule_wakeup",
-					});
-				}
+			// The run that arms a chain belongs to it: Esc in this run cancels it.
+			(currentRun.armed ??= new Set()).add(chain.id);
+			const scheduledFor = now + delay * 1000;
+			scheduler.update(chain.id, {
+				scheduledFor,
+				keepaliveUsed: false,
+				keepaliveTurn: false,
+				awaitingReschedule: false,
+				reason: params.reason,
+			});
 
-				const scheduledFor = Date.now() + clamped * 1000;
-				scheduler.update(chain.id, {
+			const note = wasClamped ? ` (clamped from ${requested}s)` : "";
+			return {
+				content: [{ type: "text" as const, text: `Next iteration scheduled in ${delay}s${note} for loop ${chain.id}.` }],
+				details: {
+					id: chain.id,
 					scheduledFor,
-					keepaliveUsed: false,
-					keepaliveTurn: false,
-					awaitingReschedule: false,
-					reason: params.reason,
-				});
-
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text:
-								`Next iteration scheduled in ${clamped}s` +
-								(wasClamped ? ` (clamped from ${requested}s)` : "") +
-								` for loop ${chain.id}.`,
-						},
-					],
-					details: {
-						id: chain.id,
-						scheduledFor,
-						clampedDelaySeconds: clamped,
-						wasClamped,
-						stopped: false,
-					},
-				};
-			},
-		});
-	}
-
-	registerTools();
+					clampedDelaySeconds: delay,
+					wasClamped,
+					stopped: false,
+				},
+				// Claude Code ends the turn when ScheduleWakeup returns (on models
+				// that support it); the guidelines ask for the update first. Pi only
+				// ends the turn when every tool in the batch agrees.
+				terminate: true,
+			};
+		},
+	});
 
 	// ---------------------------------------------------------------- rendering
 
-	/**
-	 * Compact one-line tool rows.
-	 *
-	 * The resolver is consulted every time a tool row renders, so setting
-	 * `compactToolRows` to false falls back to Pi's default rendering without
-	 * re-registering the tool or reloading the extension.
-	 */
-	function registerToolRenderers(): void {
-		if (typeof pi.registerToolRenderer !== "function") return;
-		const renderers: Record<string, ToolRenderers> = {
-			cron_create: {
-				renderCall(args: any, theme: Theme, context: any) {
-					if (!context.isPartial && context.executionStarted) return completedCall();
-					return toolCall("Schedule", `${args.cron ?? ""} · ${truncate(args.prompt ?? "", 40)}`, theme);
-				},
-				renderResult(result: any, options: any, theme: Theme, context: any) {
-					if (context.isError) {
-						return toolResult(
-							resultText(result) || "Failed",
-							undefined,
-							{ expanded: options.expanded, isPartial: options.isPartial, isError: true },
-							theme,
-						);
-					}
-					const d = (result.details ?? {}) as {
-						id?: string;
-						cron?: string;
-						nextFireAt?: number;
-						recurring?: boolean;
-						durable?: boolean;
-						prompt?: string;
-					};
-					const summary =
-						`Scheduled ${d.id ?? "?"} · ${humanSchedule(d.cron ?? "")} · next ${formatClock(d.nextFireAt)}` +
-						(d.recurring === false ? " · one-shot" : "") +
-						(d.durable ? " · durable" : "");
-					return toolResult(
-						summary,
-						d.prompt,
-						{ expanded: options.expanded, isPartial: options.isPartial, isError: context.isError },
-						theme,
-					);
-				},
-			},
-			cron_delete: {
-				renderCall(args: any, theme: Theme, context: any) {
-					if (!context.isPartial && context.executionStarted) return completedCall();
-					return toolCall("Cancel", args.id ?? "", theme);
-				},
-				renderResult(result: any, options: any, theme: Theme, context: any) {
-					if (context.isError) {
-						return toolResult(
-							resultText(result) || "Failed",
-							undefined,
-							{ expanded: options.expanded, isPartial: options.isPartial, isError: true },
-							theme,
-						);
-					}
-					const d = (result.details ?? {}) as { cancelled?: boolean; id?: string };
-					const summary = d.cancelled ? `Cancelled ${d.id ?? "?"}` : `No job ${d.id ?? "?"}`;
-					return toolResult(
-						summary,
-						undefined,
-						{ expanded: options.expanded, isPartial: options.isPartial, isError: context.isError },
-						theme,
-					);
-				},
-			},
-			cron_list: {
-				renderCall(_args: any, theme: Theme, context: any) {
-					if (!context.isPartial && context.executionStarted) return completedCall();
-					return toolCall("List scheduled jobs", "", theme);
-				},
-				renderResult(result: any, options: any, theme: Theme, context: any) {
-					if (context.isError) {
-						return toolResult(
-							resultText(result) || "Failed",
-							undefined,
-							{ expanded: options.expanded, isPartial: options.isPartial, isError: true },
-							theme,
-						);
-					}
-					const d = (result.details ?? {}) as { jobs?: LoopJob[] };
-					const jobs = d.jobs ?? [];
-					let summary: string;
-					if (!jobs.length) summary = "No scheduled jobs";
-					else if (jobs.length === 1) summary = `1 job · ${jobSummary(jobs[0])}`;
-					else {
-						const shown = jobs.slice(0, 2).map(jobSummary).join(" · ");
-						summary = `${jobs.length} jobs · ${shown}${jobs.length > 2 ? " …" : ""}`;
-					}
-					const detail = options.expanded
-						? jobs.map((job) => `${jobSummary(job)} · ${truncate(job.prompt, 60)}`).join("\n")
-						: undefined;
-					return toolResult(
-						summary || resultText(result),
-						detail,
-						{ expanded: options.expanded, isPartial: options.isPartial, isError: context.isError },
-						theme,
-					);
-				},
-			},
-			schedule_wakeup: {
-				renderCall(args: any, theme: Theme, context: any) {
-					if (!context.isPartial && context.executionStarted) return completedCall();
-					if (args.stop === true) return toolCall("Stop loop", "", theme);
-					const reason = args.reason ? ` · ${truncate(args.reason, 40)}` : "";
-					return toolCall("Wakeup", `${formatDelay(args.delaySeconds)}${reason}`, theme);
-				},
-				renderResult(result: any, options: any, theme: Theme, context: any) {
-					if (context.isError) {
-						return toolResult(
-							resultText(result) || "Failed",
-							undefined,
-							{ expanded: options.expanded, isPartial: options.isPartial, isError: true },
-							theme,
-						);
-					}
-					const d = (result.details ?? {}) as {
-						id?: string;
-						scheduledFor?: number;
-						clampedDelaySeconds?: number;
-						wasClamped?: boolean;
-						stopped?: boolean;
-						cancelledWakeups?: number;
-					};
-					const summary = d.stopped
-						? `Stopped · ${d.cancelledWakeups ?? 0} wakeup${d.cancelledWakeups === 1 ? "" : "s"} cancelled`
-						: `Wakeup in ${formatDelay(d.clampedDelaySeconds)} · loop ${d.id ?? "?"}${d.wasClamped ? " (clamped)" : ""}`;
-					const detail = options.expanded
-						? [context.args.reason, d.scheduledFor ? `at ${formatClock(d.scheduledFor)}` : undefined]
-								.filter(Boolean)
-								.join(" · ")
-						: undefined;
-					return toolResult(
-						summary,
-						detail || undefined,
-						{ expanded: options.expanded, isPartial: options.isPartial, isError: context.isError },
-						theme,
-					);
-				},
-			},
-		};
-
+	if (typeof pi.registerToolRenderer === "function") {
+		const renderers = loopToolRenderers();
+		// The resolver runs every time a row renders, so the setting applies
+		// without re-registering anything.
 		pi.registerToolRenderer((toolName, next) => {
 			if (!loadConfig().compactToolRows) return next();
 			return renderers[toolName] ?? next();
 		});
 	}
 
-	registerToolRenderers();
+	pi.registerMessageRenderer(TICK_MESSAGE_TYPE, renderTickMessage);
 
 	// ----------------------------------------------------------------- events
 
 	/**
-	 * Draw the tick as a quiet two-line block instead of Pi's default
-	 * `[pi-cc-loop-tick]` title.
-	 */
-	pi.registerMessageRenderer(TICK_MESSAGE_TYPE, (message, options, theme) => {
-		const details = (message.details ?? {}) as {
-			tickCount?: number;
-			jobId?: string;
-			cron?: string;
-			immediate?: boolean;
-		};
-		const text = contentText(message.content);
-		const prompt = stripProvenance(text, /^\[loop tick[^\]]*\]\n?/);
-		if (!loadConfig().compactMessages) {
-			const summary = firstLine(prompt);
-			const header = `loop tick #${details.tickCount ?? "?"}${summary ? ` · ${summary}` : ""}`;
-			return renderCard({
-				header,
-				body: prompt,
-				expanded: options.expanded,
-				outputPad: options.outputPad,
-				theme,
-			});
-		}
-		const label = details.tickCount !== undefined ? `loop #${details.tickCount}` : "loop";
-		const stamp = formatStamp(message.timestamp);
-		const header = stamp
-			? `${theme.fg("accent", theme.bold(label))}${theme.fg("dim", " · ")}${theme.fg("muted", stamp)}`
-			: theme.fg("accent", theme.bold(label));
-
-		const meta: string[] = [];
-		if (details.jobId) meta.push(`job ${details.jobId}`);
-		if (details.cron) meta.push(`cron ${details.cron}`);
-		else if (details.immediate) meta.push("immediate run");
-		else meta.push("self-paced");
-		meta.push("scheduled by /loop");
-
-		return renderBlock({
-			header,
-			body: bodyLines(prompt),
-			meta,
-			expanded: options.expanded,
-			outputPad: options.outputPad,
-			theme,
-			maxBodyLines: 3,
-		});
-	});
-
-	/**
-	 * A monitor event supersedes the chain's pending fallback heartbeat.
+	 * Give a run the instructions of the loop message that started it, and
+	 * remember which chain (if any) the run belongs to.
 	 *
-	 * The handler is deliberately synchronous: pi-cc-monitor emits the bus
-	 * event before it sends the notification, so this must land before the
-	 * woken turn starts. Otherwise the turn would end, find no reschedule, and
-	 * arm a keepalive on top of the event that just arrived.
+	 * A monitor event does not touch the chain: like Claude Code, the pending
+	 * wakeup stays armed as the fallback heartbeat, and the model re-arms it if
+	 * it wants a different time.
 	 */
-	pi.events.on(MONITOR_WAKE_CHANNEL, (data) => {
-		const wake = data as { loopPrompt?: string } | undefined;
-		if (!wake?.loopPrompt) return;
-		const chain = scheduler.findChain(wake.loopPrompt);
-		if (!chain) return;
-		scheduler.update(chain.id, { scheduledFor: undefined, awaitingReschedule: true });
-	});
-
 	pi.on("before_agent_start", (event, ctx) => {
 		lastCtx = ctx;
-		const notes: string[] = [];
-
-		if (pendingNote) {
-			notes.push(pendingNote);
-			pendingNote = undefined;
-		}
-
-		const chainId = runChainId;
-		runChainId = undefined;
-		if (chainId) {
-			const chain = scheduler.get(chainId);
-			if (chain) {
-				notes.push(LOOP_GUIDELINES.replace("{prompt}", chain.prompt).replace("{quoted}", `"${chain.prompt}"`));
-				// Self-paced chains can be woken by an event instead of the timer.
-				// Only mention the Monitor tool when it is actually installed.
-				if (chain.kind === "wakeup" && monitorToolAvailable()) {
-					notes.push(MONITOR_GUIDELINES.replace("{quoted}", `"${chain.prompt}"`));
-				}
-			}
+		currentRun = {};
+		if (event.messageType !== "custom") return;
+
+		if (event.message.customType === MONITOR_EVENT_TYPE) {
+			// A monitor bound to a loop woke the agent: the run belongs to that loop.
+			const loopPrompt = (event.message.details as { loopPrompt?: unknown } | undefined)?.loopPrompt;
+			const chain = typeof loopPrompt === "string" ? scheduler.findChain(loopPrompt) : undefined;
+			if (chain) currentRun.chainId = chain.id;
+			return;
 		}
+		if (event.message.customType !== TICK_MESSAGE_TYPE) return;
 
-		if (pendingScheduleRules) {
-			notes.push(pendingScheduleRules);
-			pendingScheduleRules = undefined;
-			if (monitorToolAvailable()) {
-				notes.push(MONITOR_GUIDELINES.replace("{quoted}", `"the /loop prompt"`));
-			}
+		const details = (event.message.details ?? {}) as {
+			jobId?: string;
+			guidelines?: unknown;
+			immediate?: boolean;
+			tickCount?: number;
+		};
+		const notes = Array.isArray(details.guidelines)
+			? details.guidelines.filter((note): note is string => typeof note === "string")
+			: [];
+		if (details.immediate && typeof details.tickCount === "number") currentRun.tick = details.tickCount;
+
+		// A self-paced tick has to schedule the next iteration.
+		const chain = details.jobId ? scheduler.get(details.jobId) : undefined;
+		if (chain?.kind === "wakeup") {
+			currentRun.chainId = chain.id;
+			notes.push(loopGuidelines(chain.prompt));
+			// Only mention the Monitor tool when it is actually installed.
+			if (monitorToolAvailable()) notes.push(monitorGuidelines(chain.prompt));
 		}
 
 		if (!notes.length) return;
@@ -1414,137 +1200,118 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		options.promptGuidelines = [...(options.promptGuidelines ?? []), ...notes];
 	});
 
-	pi.on("agent_start", async (_event, ctx) => {
-		lastCtx = ctx;
-		scheduler.noteTurnStarted();
-	});
-
-	pi.on("agent_end", async (_event, ctx) => {
+	/**
+	 * The run is over and Pi will not continue on its own. Esc on a loop's own
+	 * turn cancels that loop; chains whose tick was not rescheduled get their
+	 * keepalive. Then a pending tick may go out.
+	 */
+	pi.on("agent_settled", async (event, ctx) => {
 		lastCtx = ctx;
-		expireOldJobs(ctx);
-
-		const now = Date.now();
-		for (const chain of scheduler.byKind("wakeup")) {
-			// The keepalive turn is the model's last chance to reschedule.
-			if (chain.keepaliveTurn) {
-				scheduler.update(chain.id, { keepaliveTurn: false, awaitingReschedule: false });
-				endChain(chain, "keepalive budget exhausted (the model did not reschedule twice)");
-				continue;
-			}
-
-			// The model rescheduled: it armed the next wakeup itself.
-			if (!chain.awaitingReschedule) continue;
-
-			const limit = maxAgeMs();
-			if (limit > 0 && chain.chainStartedAt !== undefined && now - chain.chainStartedAt >= limit) {
-				scheduler.update(chain.id, { awaitingReschedule: false });
-				endChain(chain, "aged out");
-				continue;
-			}
-
-			if (chain.keepaliveUsed) continue;
-
-			const fallback = keepaliveSeconds();
-			if (fallback <= 0) {
-				scheduler.update(chain.id, { awaitingReschedule: false });
-				endChain(chain, "the model did not reschedule (keepalive disabled)");
-				continue;
-			}
-
-			scheduler.update(chain.id, {
-				scheduledFor: now + fallback * 1000,
-				keepaliveUsed: true,
-				awaitingReschedule: false,
-			});
-			notify(
-				ctx,
-				`loop ${chain.id}: the model did not reschedule — keepalive armed (${Math.round(fallback / 60)} min)`,
-				"warning",
-			);
-		}
+		if ((event as { aborted?: boolean } | undefined)?.aborted) cancelCurrentLoop(ctx);
+		settleChains(ctx);
+		currentRun = {};
+		scheduler.notifyIdle();
 	});
 
-	pi.on("agent_settled", async (_event, ctx) => {
-		lastCtx = ctx;
-		// The agent is idle now: a pending tick may go out.
-		scheduler.notifyIdle();
+	/** After a compaction, send the full loop.md tasks again on the next tick. */
+	pi.on("session_compact", async () => {
+		loopFile.reset();
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		lastCtx = ctx;
-		restoreState(ctx);
-		expireOldJobs(ctx);
+		durable?.stop();
+		restoreState(ctx, (event as { reason?: string } | undefined)?.reason);
+		durable = createDurable(ctx.cwd);
+		durable.start();
 		scheduler.start();
 		if (syncPiCcExtensionsExcludes(piCcToolNames(), loadConfig().compactToolRows)) {
-			notify(ctx, "pi-cc-extensions excludeRenderers updated · /reload to apply", "info");
-		}
-	});
-
-	pi.on("session_before_switch", async () => {
-		for (const chain of scheduler.byKind("wakeup")) {
-			retireChain(chain, "the session was switched");
+			notify(ctx, "pi-cc-extensions excludeRenderers updated \u00b7 /reload to apply", "info");
 		}
-		scheduler.clear(false);
 	});
 
 	pi.on("session_shutdown", async () => {
 		scheduler.stop();
+		durable?.stop();
+		durable = undefined;
 		scheduler.clear(false);
 	});
 
 	// -------------------------------------------------------------- restoring
 
-	function restoreState(ctx: ExtensionContext): void {
+	/**
+	 * Restore the session's jobs from its last state entry, following Claude
+	 * Code's resume rules: "restores the tasks scheduled with CronCreate,
+	 * except recurring tasks that have expired and one-shot tasks whose
+	 * scheduled time has passed. A self-paced /loop isn't restored". A restored
+	 * recurring job does not catch up on missed runs.
+	 *
+	 * `/reload` is different: the process keeps running, so a self-paced
+	 * wakeup that is still in the future is kept (Claude Code re-arms a pending
+	 * wakeup when its process restarts in time).
+	 */
+	function restoreState(ctx: ExtensionContext, reason: string | undefined): void {
 		scheduler.clear(false);
+		lastPersistedSignature = "";
 
 		const entries = ctx.sessionManager.getEntries();
+		let data: PersistedState | undefined;
 		for (let i = entries.length - 1; i >= 0; i--) {
 			const entry = entries[i] as { type?: string; customType?: string; data?: PersistedState };
 			if (entry.type === "custom" && entry.customType === STATE_ENTRY && entry.data?.jobs) {
-				for (const prompt of entry.data.stopped ?? []) stoppedPrompts.add(prompt);
-				if (typeof entry.data.widget === "boolean") widgetEnabled = entry.data.widget;
-				for (const job of entry.data.jobs) {
-					if (job.kind === "wakeup") {
-						// A self-paced chain is not restored: the wakeup that was pending
-						// died with the previous process.
-						scheduler.restore({ ...job, scheduledFor: undefined, keepaliveUsed: true });
-					} else {
-						scheduler.restore(job);
-						scheduler.arm(job);
-					}
-				}
+				data = entry.data;
 				break;
 			}
 		}
+		if (!data) {
+			refreshWidget(scheduler.list());
+			return;
+		}
 
-		// Durable jobs live in .pi/scheduled_tasks.json and are restored even
-		// across a restart.
-		const file = path.join(ctx.cwd, ".pi", "scheduled_tasks.json");
-		try {
-			if (fs.existsSync(file)) {
-				const payload = JSON.parse(fs.readFileSync(file, "utf8")) as PersistedState;
-				for (const job of payload.jobs ?? []) {
-					if (scheduler.get(job.id)) continue;
-					if (job.kind === "wakeup") {
-						scheduler.restore({ ...job, scheduledFor: undefined, keepaliveUsed: true });
-					} else {
-						scheduler.restore(job);
-						scheduler.arm(job);
-					}
+		for (const prompt of data.stopped ?? []) rememberStopped(prompt);
+		if (typeof data.widget === "boolean") widgetEnabled = data.widget;
+
+		const now = Date.now();
+		const limit = maxAgeMs();
+		let droppedChains = 0;
+		let droppedOneShots = 0;
+		for (const saved of data.jobs) {
+			// Durable jobs come from .pi/scheduled_tasks.json, never from a session.
+			if (saved.durable) continue;
+			const job = storedJob(saved);
+			if (job.kind === "wakeup") {
+				if (reason === "reload" && job.scheduledFor !== undefined && job.scheduledFor > now) {
+					scheduler.restore(job);
+				} else {
+					droppedChains++;
 				}
+				continue;
 			}
-		} catch {
-			// ignore a malformed file
+			if (!job.recurring) {
+				const due = nextRunTime(job, job.createdAt, timingConfig());
+				if (due === null || due <= now) {
+					droppedOneShots++;
+					continue;
+				}
+			} else if (limit > 0 && now - job.createdAt >= limit) {
+				continue;
+			}
+			scheduler.restore(job);
+			scheduler.arm(job, now);
 		}
 
-		const pending = scheduler.byKind("wakeup");
-		if (pending.length) {
-			notify(
-				ctx,
-				`${pending.length} self-paced loop(s) were not restored: their wakeup did not survive the restart. Re-run /loop to restart them.`,
-				"warning",
+		const notes: string[] = [];
+		if (droppedChains) {
+			notes.push(
+				`${droppedChains} self-paced loop${droppedChains === 1 ? " was" : "s were"} not restored: run /loop again to restart ${droppedChains === 1 ? "it" : "them"}`,
+			);
+		}
+		if (droppedOneShots) {
+			notes.push(
+				`${droppedOneShots} one-shot job${droppedOneShots === 1 ? "" : "s"} dropped: the scheduled time passed while the session was closed`,
 			);
 		}
-		refreshWidget(scheduler.list());
+		if (notes.length) notify(ctx, notes.join(" \u00b7 "), "warning");
+		scheduler.refresh();
 	}
 }