npm - pi-cc-loop - Versions diffs - 0.1.1 → 0.3.0 - Mend

pi-cc-loop 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/index.ts CHANGED Viewed

@@ -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,66 +15,64 @@
  *   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, invalidateConfig, loadConfig, saveConfig, type PiCcConfig } from "./config.ts";
 import {
-	describeCron,
 	humanSchedule,
-	intervalToCron,
 	isUnreachable,
 	parseCron,
-	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,
+	cronTickGuidelines,
+	LOOP_FILE_SENTINEL,
+	loopGuidelines,
+	missedJobsMessage,
+	monitorGuidelines,
+	provenance,
+	SCHEDULE_WAKEUP_DESCRIPTION,
+	scheduledTaskProvenance,
+	SCHEDULE_WAKEUP_SNIPPET,
+	loopCommandGuidelines,
+} from "./prompts.ts";
+import { formatClock, formatEta, renderScheduledMessage } 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 "./render.ts";
 const STATE_ENTRY = "pi-cc-loop-state";
-const TICK_MESSAGE_TYPE = "pi-cc-loop-tick";
-const WIDGET_KEY = "pi-cc-loop";
+/** pi-cc-monitor's notification type; its details name the loop a monitor belongs to. */
+const MONITOR_EVENT_TYPE = "Monitor";
+/** Footer status key, shared with every other extension's status line. */
+const STATUS_KEY = "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
@@ -88,81 +85,18 @@ 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[];
-	/** Whether the status widget is shown. Claude Code has no such widget. */
-	widget?: boolean;
 }
 function envNumber(name: string, fallback: number): number {
@@ -172,13 +106,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 +123,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();
-}
-/** 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 "";
+/** 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,
+	};
 }
-function formatDelay(seconds: number | undefined): string {
-	if (seconds === undefined) return "unknown";
-	if (seconds < 60) return `${seconds}s`;
-	return `${Math.round(seconds / 60)}m`;
+function durableSyncMs(): number {
+	return Math.max(0, envNumber("PI_LOOP_DURABLE_SYNC_MS", 5000));
 }
-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. */
@@ -285,53 +149,41 @@ export function getScheduler(): LoopScheduler | null {
 	return activeScheduler;
 }
-/**
- * Pull the `--durable` and `--max N` flags out of the command line.
- * Flags may appear anywhere; the remaining tokens are the prompt.
- */
-function extractFlags(raw: string): { body: string; durable: boolean; maxFires?: number } {
-	const tokens = raw.split(/\s+/).filter(Boolean);
-	const kept: string[] = [];
-	let durable = false;
-	let maxFires: number | undefined;
-	for (let i = 0; i < tokens.length; i++) {
-		const token = tokens[i];
-		if (token.toLowerCase() === "--durable") {
-			durable = true;
-			continue;
-		}
-		const inline = /^--max=(\d+)$/i.exec(token);
-		if (inline) {
-			maxFires = Math.max(1, Number(inline[1]));
-			continue;
-		}
-		if (/^--max$/i.test(token)) {
-			const next = tokens[i + 1];
-			if (next && /^\d+$/.test(next)) {
-				maxFires = Math.max(1, Number(next));
-				i++;
-			}
-			continue;
-		}
-		kept.push(token);
-	}
-	return { body: kept.join(" "), durable, 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>();
+	/** 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,
+	 * `cronId` the fixed-interval job whose tick started it, `armed` the chains
+	 * it armed, `tick` the tick number of a /loop run.
+	 */
+	let currentRun: { chainId?: string; cronId?: 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);
+			refreshStatus(jobs);
 		},
-		maxAgeMs,
-		jitterFraction,
-		jitterCapMs: () => 30 * 60 * 1000,
 		canDispatch: () => {
 			const ctx = lastCtx;
 			if (!ctx) return false;
@@ -341,151 +193,141 @@ 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);
+			// The countdown is coarse, so this is a string compare most seconds.
+			refreshStatus();
 		},
 	});
 	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]);
 		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 } satisfies PersistedState);
 		} catch {
 			// session persistence is best effort
 		}
+	}
+	function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
 		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");
+			if (ctx.hasUI) ctx.ui.notify(message, level);
 		} catch {
-			// durable persistence is best effort
+			// a stale context must never break the loop
 		}
 	}
-	function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
-		if (ctx.hasUI) ctx.ui.notify(message, level);
+	/**
+	 * Rules for a message we are about to send, keyed by its text. A user
+	 * message carries no details, so the run's guidelines and the loop it
+	 * belongs to wait here for before_agent_start to pick them up.
+	 */
+	const queuedRuns: Array<{ content: string; guidelines: string[]; chainId?: string; cronId?: string; tick?: number }> =
+		[];
+	function queueRun(run: (typeof queuedRuns)[number]): void {
+		queuedRuns.push(run);
+		if (queuedRuns.length > 8) queuedRuns.shift();
+	}
+	function takeQueuedRun(content: string): (typeof queuedRuns)[number] | undefined {
+		const index = queuedRuns.findIndex((run) => run.content === content);
+		return index < 0 ? undefined : queuedRuns.splice(index, 1)[0];
+	}
+	/**
+	 * One line in Pi's footer, the same place other extensions show status.
+	 * Claude Code has no loop status in its footer; a one-line summary is enough
+	 * to know that something is armed and when it next fires.
+	 */
+	function statusText(jobs: LoopJob[]): string | undefined {
+		if (!jobs.length) return undefined;
+		const now = Date.now();
+		const next = Math.min(
+			...jobs.map((job) => {
+				if (job.pending) return now;
+				const at = job.kind === "cron" ? job.nextFireAt : job.scheduledFor;
+				return at ?? now;
+			}),
+		);
+		return `loop ${jobs.length} \u00b7 next ${formatEta(Math.max(0, next - now))}`;
 	}
-	function refreshWidget(jobs: LoopJob[]): void {
+	let lastStatusText: string | undefined;
+	let statusSet = false;
+	function refreshStatus(jobs: LoopJob[] = scheduler.list()): void {
 		const ctx = lastCtx;
 		if (!ctx || !ctx.hasUI) return;
-		if (!widgetEnabled) {
-			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)}`),
-				);
-			}
+		try {
+			// Older Pi versions have no footer status API.
+			if (typeof ctx.ui.setStatus !== "function") return;
+			const text = loadConfig().footer ? statusText(jobs) : undefined;
+			// Every call repaints, even with the same text, so speak only on change.
+			if (text === lastStatusText && (text !== undefined || !statusSet)) return;
+			lastStatusText = text;
+			statusSet = text !== undefined;
+			ctx.ui.setStatus(STATUS_KEY, text);
+		} catch {
+			// a stale context must never break the loop
 		}
-		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,105 +335,133 @@ 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, prompt: lines.join("\n") },
+				},
+				{ deliverAs: "followUp" },
+			);
+		} 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",
+			);
 		}
 	}
 	/**
-	 * 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."
+	 * A scheduled fire is a custom message, not a user message: the provenance
+	 * line in its content is addressed to the model, and only a custom message
+	 * can draw something else for the reader (`renderScheduledMessage`).
+	 */
+	const TICK_MESSAGE_TYPE = "pi-cc-loop-tick";
+	/** 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: 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");
+		// A fixed-interval tick is what it is - a scheduled task - and a
+		// self-paced tick keeps the loop framing. The rules for the run are
+		// rebuilt from `details` in before_agent_start.
+		const cadence = job.kind === "cron" ? humanSchedule(job.cron ?? "* * * * *") : undefined;
+		const stamp = cadence ? scheduledTaskProvenance(job.id, cadence) : provenance(tick);
 		pi.sendMessage(
 			{
 				customType: TICK_MESSAGE_TYPE,
-				content,
+				content: `${stamp}\n${body}`,
 				display: true,
-				details: { jobId: job.id, tickCount: tick, cron: job.cron, scheduledAt: Date.now() },
+				details: {
+					kind: job.kind,
+					tickCount: tick,
+					jobId: job.id,
+					cron: job.cron,
+					prompt: body,
+					reason: job.reason,
+				},
 			},
+			// `triggerTurn` is what starts the run: without it the message is
+			// only recorded and nothing ever happens.
 			{ 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.
-	 *
-	 * 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.
-	 */
-	const tickCounters = new Map<string, number>();
-	function runNow(ctx: ExtensionContext, prompt: string, job?: LoopJob): 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(),
-			});
-		}
-		runChainId = job?.kind === "wakeup" ? job.id : undefined;
-		pi.sendMessage(
-			{
-				customType: TICK_MESSAGE_TYPE,
-				content: `${PROVENANCE.replace("{n}", String(tick))}\n${prompt}`,
-				display: true,
-				details: { jobId: job?.id, tickCount: tick, immediate: true, scheduledAt: Date.now() },
-			},
-			{ deliverAs: "steer", triggerTurn: true },
-		);
-	}
-	function scheduleNote(text: string): void {
-		pendingNote = text;
-	}
 	/** True when the pi-cc-monitor extension registered its Monitor tool. */
 	function monitorToolAvailable(): boolean {
 		try {
@@ -602,44 +472,84 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	}
 	/** The tool names to exclude from pi-cc-extensions' global styling. */
-	function piCcToolNames(): string[] {
-		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",
+		description: "Run a prompt repeatedly: /loop [interval] <prompt>, /loop <prompt>, /loop stop, /loop status.",
 		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()) {
-				case "stop":
-					await stopLoops(ctx, rest.join(" "));
-					return;
-				case "status":
-				case "list":
-				case "jobs":
-					showStatus(ctx);
-					return;
-				case "widget": {
+			// Settings configure the extension, not a loop: they stay in code.
+			switch ((head ?? "").toLowerCase()) {
+				case "footer":
+				case "statusline": {
 					const arg = (rest[0] ?? "").toLowerCase();
-					if (arg !== "on" && arg !== "off") {
-						notify(ctx, `Usage: /loop widget on|off (currently ${widgetEnabled ? "on" : "off"})`, "info");
+					if (!arg) {
+						notify(ctx, `Usage: /loop footer on|off (currently ${loadConfig().footer ? "on" : "off"})`, "info");
 						return;
 					}
-					widgetEnabled = arg === "on";
-					persist(scheduler.list());
-					refreshWidget(scheduler.list());
-					notify(ctx, `Loop status widget ${widgetEnabled ? "enabled" : "disabled"}`, "info");
+					setSetting(ctx, "footer", arg);
 					return;
 				}
 				case "settings":
@@ -654,11 +564,11 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 						setSetting(ctx, "messages", value);
 						return;
 					}
-					if (name === "tools" || name === "tool" || name === "rows") {
-						setSetting(ctx, "tools", value);
+					if (name === "footer" || name === "status") {
+						setSetting(ctx, "footer", value);
 						return;
 					}
-					notify(ctx, "Usage: /loop settings [messages|tools] [on|off]", "info");
+					notify(ctx, "Usage: /loop settings [messages|footer] [on|off]", "info");
 					return;
 				}
 				case "help":
@@ -670,210 +580,52 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 					break;
 			}
-			// Flags are stripped before parsing so they never interfere with the
-			// interval token.
-			const flags = extractFlags(raw);
-			const body = flags.body;
-			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();
-				}
-			}
-			// 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
-			await startLoop(ctx, intervalSeconds, prompt, flags.durable, flags.maxFires);
+			// Everything else becomes a normal user message, the way Claude Code's
+			// /loop skill does: the conversation keeps the request, and the model
+			// drives cron_create / cron_list / cron_delete / schedule_wakeup itself.
+			// The per-run rules travel with the run through before_agent_start.
+			const text = raw ? `/loop ${raw}` : "/loop";
+			queueRun({ content: text, guidelines: [loopCommandGuidelines(raw)] });
+			// Pi runs an extension command even while a turn is streaming, and its
+			// sendUserMessage throws unless a lane is named: "Agent is already
+			// processing. Specify streamingBehavior". `followUp` is that lane - the
+			// request waits for the current turn to end, which is where a /loop
+			// belongs anyway. When idle the option is ignored and the turn starts.
+			pi.sendUserMessage(text, { expandPromptTemplates: false, deliverAs: "followUp" });
 		},
 	});
-	async function startLoop(
-		ctx: ExtensionCommandContext,
-		intervalSeconds: number | null,
-		prompt: string,
-		durable: boolean,
-		maxFires: number | undefined,
-	): Promise<void> {
-		expireOldJobs(ctx);
-		// 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;
-			}
-		}
-		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}\`.`;
-			}
-			pendingScheduleRules = rules;
-			runNow(ctx, finalPrompt);
-			return;
-		}
-		const spec = intervalToCron(intervalSeconds);
-		if (!spec) {
-			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({
-			id: generateId(),
-			kind: "cron",
-			cron: spec.cron,
-			prompt: finalPrompt,
-			recurring: true,
-			createdAt: Date.now(),
-			durable,
-			maxFires,
-			label: humanSchedule(spec.cron),
-			source: "loop_command",
-		});
-		const expiryDays = Math.round(maxAgeMs() / 86_400_000);
-		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}` : ""),
-			"info",
-		);
-		scheduleNote(
-			`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}.` : ""),
-		);
-		runNow(ctx, finalPrompt, job);
-	}
-	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");
-				return;
-			}
-			if (job.kind === "wakeup") {
-				retireChain(job, "stopped by the user");
-			} else {
-				scheduler.remove(target);
-				notify(ctx, `Cancelled loop ${target}`, "info");
-			}
-			return;
-		}
-		const jobs = scheduler.list();
-		if (!jobs.length) {
-			notify(ctx, "No active loops", "info");
-			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);
-			}
-		}
-		notify(ctx, `Cancelled ${jobs.length} loop${jobs.length === 1 ? "" : "s"}`, "info");
-	}
-	function showStatus(ctx: ExtensionContext): void {
-		const jobs = scheduler.list();
-		if (!jobs.length) {
-			notify(ctx, "No active loops", "info");
-			return;
-		}
-		const lines = jobs.map((job) => {
-			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 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)}`;
-		});
-		if (ctx.hasUI) ctx.ui.notify(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 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",
+			"/loop [interval]            the .pi/loop.md tasks, or the built-in maintenance prompt",
+			"/loop footer on|off         show or hide the one-line summary in the footer",
 			"/loop settings              show UI settings",
 			"/loop settings messages on|off   compact two-line markers",
-			"/loop settings tools on|off      one-line tool results",
+			"/loop settings footer on|off     the one-line footer summary",
 			"",
+			"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"}`,
+			`  footer:    ${config.footer ? "summary" : "hidden"}`,
 			"",
 			"Usage: /loop settings messages on|off",
-			"       /loop settings tools on|off",
+			"       /loop settings footer 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 {
+	function setSetting(ctx: ExtensionContext, key: "messages" | "footer", raw: string | undefined): void {
 		const value = (raw ?? "").toLowerCase();
 		const on = value === "on" || value === "true" || value === "1";
 		const off = value === "off" || value === "false" || value === "0";
@@ -881,670 +633,526 @@ 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 } : { footer: on };
 		const next = saveConfig(patch);
-		let compatChanged = false;
-		if (key === "tools") {
-			compatChanged = syncPiCcExtensionsExcludes(piCcToolNames(), on);
-		}
 		try {
 			pi.events.emit(CONFIG_CHANNEL, next);
 		} catch {
 			// another extension must not break the command
 		}
-		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, `${key === "messages" ? "Compact message style" : "Footer summary"} ${on ? "enabled" : "disabled"}`, "info");
+		if (key === "footer") refreshStatus();
 	}
 	// ------------------------------------------------------------------ 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",
+		// Claude Code's tool names: the row reads "CronCreate(*/5 * * * *: ...)".
+		label: "CronCreate",
+		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: "CronDelete",
+		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" 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_list",
+		label: "CronList",
+		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: "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: "schedule_wakeup",
+		label: "ScheduleWakeup",
+		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, so be specific. Required unless stop is true.",
+				}),
+			),
+			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",
-							text:
-								`Scheduled ${job.id} (${job.label}, next run ${formatClock(job.nextFireAt)})\n` +
-								`Cancel it with cron_delete { "id": "${job.id}" }.`,
+							type: "text" as const,
+							text: chains.length
+								? `Loop stopped \u2014 cancelled ${chains.length} pending wakeup(s); no further dynamic-loop wakeups scheduled. ` +
+									"Any Monitor armed for this loop was stopped with it. Write the loop's outcome for the user, then end the turn."
+								: "Loop stopped \u2014 any dynamic loop in this session is ended; there was no pending wakeup to cancel. " +
+									"If you are running a fixed-interval /loop (a recurring cron), it is NOT stopped by this call \u2014 cancel it with cron_delete.",
 						},
 					],
-					details: {
-						id: job.id,
-						cron: job.cron,
-						recurring: job.recurring,
-						durable: job.durable,
-						nextFireAt: job.nextFireAt,
-						prompt: job.prompt,
-					},
+					details: { stopped: true, cancelledWakeups: chains.length },
 				};
-			},
-		});
+			}
-		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);
-				return {
-					content: [{ type: "text" as const, text: `Cancelled job ${params.id}.` }],
-					details: { cancelled: true, id: params.id },
-				};
-			},
-		});
+			if (typeof params.delaySeconds !== "number" || Number.isNaN(params.delaySeconds)) {
+				throw new Error("`delaySeconds` and `reason` are required when `stop` is not true.");
+			}
+			if (!params.reason || !params.reason.trim()) {
+				throw new Error("`delaySeconds` and `reason` are required when `stop` is not true.");
+			}
+			const prompt = params.prompt ? normalizePrompt(params.prompt) : "";
+			if (!prompt) {
+				throw new Error("`prompt` is required when `stop` is not true.");
+			}
-		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");
+			if (currentRun.cronId) {
+				// Not an error: the request is already satisfied by the schedule.
+				// Returning it as a result (instead of throwing) keeps the transcript
+				// calm and tells the model nothing is missing.
+				const cronJob = scheduler.get(currentRun.cronId);
 				return {
-					content: [{ type: "text" as const, text }],
-					details: { jobs },
+					content: [
+						{
+							type: "text" as const,
+							text:
+								`No wakeup needed: this tick belongs to the fixed-interval /loop ${currentRun.cronId}` +
+								`${cronJob?.cron ? ` (${humanSchedule(cronJob.cron)})` : ""}, which fires its own next tick. ` +
+								`Nothing was scheduled. To end the loop, call cron_delete with id ${currentRun.cronId}.`,
+						},
+					],
+					details: { suppressed: "fixed-interval", id: currentRun.cronId, stopped: false },
 				};
-			},
-		});
+			}
-		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");
-					}
+			// 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:
+									`Wakeup not scheduled. The loop reached its maximum duration (${maxAgeDays()} days) \u2014 the loop has ended; ` +
+									"do not re-issue. 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.");
-				}
-				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",
-					});
+			} 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.",
+					);
 				}
-				const scheduledFor = Date.now() + clamped * 1000;
-				scheduler.update(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,
-					},
+				chain = {
+					id: generateId(),
+					kind: "wakeup",
+					prompt,
+					recurring: false,
+					createdAt: now,
+					chainStartedAt: now,
+					durable: false,
+					tickCount: tickCounters.get(prompt) ?? currentRun.tick ?? 0,
+					source: "schedule_wakeup",
 				};
-			},
-		});
-	}
-	registerTools();
+				addJob(chain);
+			}
-	// ---------------------------------------------------------------- rendering
+			// 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,
+			});
-	/**
-	 * 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,
-					);
+			const note = wasClamped ? ` (clamped to ${delay}s from your requested value)` : "";
+			const clock = new Date(scheduledFor).toTimeString().slice(0, 8);
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text:
+							`Next wakeup scheduled for ${clock} (in ${delay}s)${note}. ` +
+							"This turn ends when this call returns \u2014 you are re-invoked when the wakeup fires or a monitor event arrives.",
+					},
+				],
+				details: {
+					id: chain.id,
+					scheduledFor,
+					clampedDelaySeconds: delay,
+					wasClamped,
+					stopped: false,
 				},
-			},
-		};
-		pi.registerToolRenderer((toolName, next) => {
-			if (!loadConfig().compactToolRows) return next();
-			return renderers[toolName] ?? next();
-		});
-	}
+				// 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,
+			};
+		},
+	});
-	registerToolRenderers();
 	// ----------------------------------------------------------------- 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.registerMessageRenderer(TICK_MESSAGE_TYPE, renderScheduledMessage);
 	pi.on("before_agent_start", (event, ctx) => {
 		lastCtx = ctx;
-		const notes: string[] = [];
-		if (pendingNote) {
-			notes.push(pendingNote);
-			pendingNote = undefined;
+		currentRun = {};
+		// Our own messages are ordinary user messages now, so the instructions
+		// for the run and the loop it belongs to travel with the queued entry.
+		if (event.messageType === "user") {
+			const queued = takeQueuedRun(event.prompt);
+			if (!queued) return;
+			currentRun = { chainId: queued.chainId, cronId: queued.cronId, tick: queued.tick };
+			if (!queued.guidelines.length) return;
+			const options = event.systemPromptOptions;
+			options.promptGuidelines = [...(options.promptGuidelines ?? []), ...queued.guidelines];
+			return;
 		}
-		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}"`));
+		if (event.messageType !== "custom") return;
+		if (event.message.customType === TICK_MESSAGE_TYPE) {
+			const details = (event.message.details ?? {}) as {
+				kind?: "cron" | "wakeup";
+				jobId?: string;
+				cron?: string;
+				tickCount?: number;
+			};
+			currentRun = {
+				chainId: details.kind === "wakeup" ? details.jobId : undefined,
+				cronId: details.kind === "cron" ? details.jobId : undefined,
+				tick: details.tickCount,
+			};
+			const guidelines =
+				details.kind === "cron" && details.jobId
+					? [cronTickGuidelines(details.jobId, humanSchedule(details.cron ?? "* * * * *"))]
+					: [];
+			if (details.kind === "wakeup") {
+				const chain = details.jobId ? scheduler.get(details.jobId) : undefined;
+				if (chain) {
+					guidelines.push(loopGuidelines(chain.prompt));
+					if (monitorToolAvailable()) guidelines.push(monitorGuidelines(chain.prompt));
 				}
 			}
+			if (!guidelines.length) return;
+			const options = event.systemPromptOptions;
+			options.promptGuidelines = [...(options.promptGuidelines ?? []), ...guidelines];
+			return;
 		}
-		if (pendingScheduleRules) {
-			notes.push(pendingScheduleRules);
-			pendingScheduleRules = undefined;
-			if (monitorToolAvailable()) {
-				notes.push(MONITOR_GUIDELINES.replace("{quoted}", `"the /loop prompt"`));
-			}
+		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 (!notes.length) return;
-		const options = event.systemPromptOptions;
-		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);
+		// Another process may have edited the shared settings file.
+		invalidateConfig();
+		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");
-		}
-		scheduler.clear(false);
 	});
 	pi.on("session_shutdown", async () => {
+		// Pi clears extension statuses when it unloads, but a reload should not
+		// leave a stale count behind until then.
+		try {
+			lastCtx?.ui?.setStatus?.(STATUS_KEY, undefined);
+		} catch {
+			// the context may already be invalid
+		}
 		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) {
+			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);
+		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();
 	}
 }