pi-cc-loop 0.2.0 → 0.4.0

package/index.ts

@@ -29,15 +29,11 @@
 
 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 { 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";
@@ -53,11 +49,14 @@ import {
 	missedJobsMessage,
 	monitorGuidelines,
 	provenance,
+	RULES_PROVENANCE,
+	RUN_NOW_HINT,
 	SCHEDULE_WAKEUP_DESCRIPTION,
+	scheduledTaskProvenance,
 	SCHEDULE_WAKEUP_SNIPPET,
-	scheduleRules,
+	loopCommandGuidelines,
 } from "./prompts.ts";
-import { formatClock, loopToolRenderers, renderTickMessage } from "./renderers.ts";
+import { formatClock, formatEta, renderScheduledMessage } from "./renderers.ts";
 import {
 	DEFAULT_TIMING,
 	generateId,
@@ -67,16 +66,14 @@ import {
 	type LoopJob,
 	type TimingConfig,
 } from "./schedule.ts";
-import { truncate } from "./tool-rows.ts";
+import { truncate } from "./render.ts";
 
 const STATE_ENTRY = "pi-cc-loop-state";
-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 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 this extension publishes on when a chain ends. pi-cc-monitor
@@ -101,8 +98,6 @@ interface PersistedState {
 	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 {
@@ -155,41 +150,6 @@ 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;
@@ -199,11 +159,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 * 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 = "";
 	/**
@@ -216,9 +171,11 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	/**
 	 * 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.
+	 * `cronId` the fixed-interval job whose tick started it, `armed` the chains
+	 * it armed, `tick` the tick number of a /loop run, `loopRequest` set when a
+	 * typed /loop started it (its rules already say to do the task now).
 	 */
-	let currentRun: { chainId?: string; armed?: Set<string>; tick?: number } = {};
+	let currentRun: { chainId?: string; cronId?: string; armed?: Set<string>; tick?: number; loopRequest?: boolean } = {};
 
 	const scheduler = new LoopScheduler({
 		dispatch: (job) => deliverTick(job),
@@ -227,7 +184,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		},
 		onChange: (jobs) => {
 			persist(jobs);
-			refreshWidget(jobs);
+			refreshStatus(jobs);
 		},
 		canDispatch: () => {
 			const ctx = lastCtx;
@@ -244,7 +201,15 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			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),
+		onDispatchError: (job, error) => {
+			const ctx = lastCtx;
+			if (ctx) notify(ctx, `loop ${job.id}: this tick could not be delivered and was skipped (${error.message})`, "warning");
+		},
+		onScan: (now) => {
+			durable?.maintain(now);
+			// The countdown is coarse, so this is a string compare most seconds.
+			refreshStatus();
+		},
 	});
 	activeScheduler = scheduler;
 
@@ -276,11 +241,11 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	function persist(jobs: LoopJob[]): void {
 		const kept = jobs.filter((job) => !job.durable).map(storedJob);
 		const stopped = [...stoppedPrompts];
-		const signature = JSON.stringify([kept.map(signatureOf), stopped, widgetEnabled]);
+		const signature = JSON.stringify([kept.map(signatureOf), stopped]);
 		if (signature === lastPersistedSignature) return;
 		lastPersistedSignature = signature;
 		try {
-			pi.appendEntry(STATE_ENTRY, { version: 1, jobs: kept, stopped, widget: widgetEnabled } satisfies PersistedState);
+			pi.appendEntry(STATE_ENTRY, { version: 1, jobs: kept, stopped } satisfies PersistedState);
 		} catch {
 			// session persistence is best effort
 		}
@@ -294,21 +259,60 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	function refreshWidget(jobs: LoopJob[]): void {
+	/**
+	 * 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))}`;
+	}
+
+	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;
+		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
 		}
-		// 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 rememberStopped(prompt: string): void {
@@ -395,9 +399,9 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 					customType: TICK_MESSAGE_TYPE,
 					content: missedJobsMessage(lines),
 					display: true,
-					details: { missed: true, jobIds: jobs.map((job) => job.id) },
+					details: { missed: true, prompt: lines.join("\n") },
 				},
-				{ deliverAs: "nextTurn" },
+				{ deliverAs: "followUp" },
 			);
 		} catch {
 			// best effort
@@ -412,6 +416,34 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		}
 	}
 
+	/**
+	 * 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 per-run rules, appended to the run as a hidden message instead of
+	 * being written into the system prompt. Providers that cannot carry a system
+	 * message mid-conversation get the leading system prompt rebuilt from every
+	 * change, so a rule that comes and goes with each tick would invalidate the
+	 * whole cached prefix on the way into the run and again on the way out.
+	 * Claude Code does the same: its /loop instructions are part of the message.
+	 */
+	const RULES_MESSAGE_TYPE = "pi-cc-loop-rules";
+
+	function rulesFor(guidelines: string[]) {
+		if (!guidelines.length) return undefined;
+		return {
+			message: {
+				customType: RULES_MESSAGE_TYPE,
+				content: [RULES_PROVENANCE, ...guidelines].join("\n\n"),
+				display: false,
+			},
+		};
+	}
+
 	/** 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;
@@ -424,20 +456,34 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 */
 	function deliverTick(job: LoopJob): void {
 		const tick = Math.max(tickCounters.get(job.prompt) ?? 0, job.tickCount ?? 0) + 1;
-		tickCounters.set(job.prompt, tick);
-		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.
+		// 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: `${provenance(tick)}\n${body}`,
+				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 },
 		);
+		// Counted only once the message is in: a throw here means the tick never
+		// happened, so it must not use up a number.
+		tickCounters.set(job.prompt, tick);
+		job.tickCount = tick;
 
 		if (job.maxFires !== undefined && (job.fireCount ?? 0) >= job.maxFires) {
 			const ctx = lastCtx;
@@ -445,34 +491,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	/**
-	 * Run the prompt right away, the way Claude Code's skill does ("Then
-	 * immediately execute the parsed prompt now").
-	 *
-	 * `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.
-	 */
-	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.get(job.id)) {
-			scheduler.update(job.id, { tickCount: tick, fireCount: (job.fireCount ?? 0) + 1, lastFiredAt: Date.now() });
-		}
-		const body = resolvePrompt(prompt, job?.kind === "cron" ? "cron" : "wakeup");
-		pi.sendMessage(
-			{
-				customType: TICK_MESSAGE_TYPE,
-				content: `${provenance(tick)}\n${body}`,
-				display: true,
-				details: { jobId: job?.id, tickCount: tick, immediate: true, scheduledAt: Date.now(), guidelines },
-			},
-			{ deliverAs: "steer", triggerTurn: true },
-		);
-		lastCtx = ctx;
-	}
-
 	/** True when the pi-cc-monitor extension registered its Monitor tool. */
 	function monitorToolAvailable(): boolean {
 		try {
@@ -482,11 +500,6 @@ 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.
@@ -549,32 +562,22 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	// ---------------------------------------------------------------- command
 
 	pi.registerCommand("loop", {
-		description:
-			"Run a prompt repeatedly. Usage: /loop [interval] <prompt> | /loop <prompt> | /loop [interval] | /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();
-
 			const [head, ...rest] = raw.split(/\s+/);
+
+			// Settings configure the extension, not a loop: they stay in code.
 			switch ((head ?? "").toLowerCase()) {
-				case "stop":
-					await stopLoops(ctx, rest.join(" "));
-					return;
-				case "status":
-				case "list":
-				case "jobs":
-					showStatus(ctx);
-					return;
-				case "widget": {
+				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":
@@ -589,11 +592,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":
@@ -605,203 +608,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;
-
-			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 3: no interval -> the model decides (self-paced unless it asks for one)
-			await startLoop(ctx, intervalSeconds, prompt, flags.durable, flags.maxFires);
-		},
-	});
-
-	async function startLoop(
-		ctx: ExtensionCommandContext,
-		intervalSeconds: number | null,
-		prompt: string,
-		durableFlag: boolean,
-		maxFires: number | undefined,
-	): Promise<void> {
-		// 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(finalPrompt);
-		// A new loop starts by sending the full task list again.
-		if (isLoopFileSentinel(finalPrompt)) loopFile.reset();
-
-		if (intervalSeconds === null) {
-			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)}`);
+			// 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";
+			const guidelines = [loopCommandGuidelines(raw)];
+			const send = () => {
+				// The user asking for this loop again is a new loop: the mark that
+				// keeps a late schedule_wakeup from reviving a stopped chain must
+				// not block it.
+				stoppedPrompts.delete(normalizePrompt(raw) || LOOP_FILE_SENTINEL);
+				queueRun({ content: text, guidelines });
+				try {
+					pi.sendUserMessage(text, { expandPromptTemplates: false, deliverAs: "followUp" });
+				} catch {
+					// The session was replaced while this request waited.
 				}
-			}
-			runNow(ctx, finalPrompt, undefined, guidelines);
-			return;
-		}
-
-		const spec = intervalToCron(intervalSeconds);
-		if (!spec || !parseCron(spec.cron)) {
-			notify(ctx, `Invalid interval: ${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: LoopJob = {
-			id: generateId(),
-			kind: "cron",
-			cron: spec.cron,
-			prompt: finalPrompt,
-			recurring: true,
-			createdAt: Date.now(),
-			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 days = maxAgeDays();
-		notify(
-			ctx,
-			`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",
-		);
-		const note =
-			`A recurring /loop job was created: id ${job.id}, cron \`${spec.cron}\` (${spec.human}), ` +
-			`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, [note]);
-	}
+			};
 
-	async function stopLoops(ctx: ExtensionContext, target: string): Promise<void> {
-		if (target) {
-			const job = scheduler.get(target);
-			if (job) {
-				if (job.kind === "wakeup") {
-					retireChain(job, "stopped by the user");
-				} else {
-					removeJob(job);
-					notify(ctx, `Cancelled loop ${target}`, "info");
-				}
-				return;
-			}
-			if (durable?.remove(target)) {
-				notify(ctx, `Cancelled durable job ${target}`, "info");
+			// A run that is already streaming has passed before_agent_start, so
+			// sending now would split the request in two: the text would be queued
+			// into that run without its rules, and the model would work through it
+			// twice. Wait for the run to end and start a clean one instead - the
+			// same wait a follow-up lane would impose, without losing the rules.
+			if (!ctx.isIdle() && typeof ctx.waitForIdle === "function") {
+				notify(ctx, `${text} will start when the current turn ends`, "info");
+				void ctx.waitForIdle().then(send, () => {});
 				return;
 			}
-			notify(ctx, `No loop with id ${target}`, "warning");
-			return;
-		}
-		const jobs = scheduler.list();
-		if (!jobs.length) {
-			notify(ctx, "No active loops", "info");
-			return;
-		}
-		for (const job of jobs) {
-			// 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 = 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 ? ` \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 when = at && at > Date.now() ? `next ${formatClock(at)}` : "awaiting reschedule";
-			return `${job.id}  self-paced  ${when}  ${prompt}`;
-		});
-		notify(ctx, lines.join("\n"), "info");
-	}
+			// The followUp lane is the fallback for a Pi without waitForIdle: a
+			// sendUserMessage from a streaming turn throws without one ("Agent is
+			// already processing. Specify streamingBehavior"). When idle the option
+			// is ignored and the turn starts.
+			send();
+		},
+	});
 
 	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 [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",
+			"/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.",
@@ -815,15 +667,15 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		const lines = [
 			`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",
 		];
 		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";
@@ -831,28 +683,23 @@ 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 \u00b7 /reload to apply", "info");
-		}
+		notify(ctx, `${key === "messages" ? "Compact message style" : "Footer summary"} ${on ? "enabled" : "disabled"}`, "info");
+		if (key === "footer") refreshStatus();
 	}
 
 	// ------------------------------------------------------------------ tools
 
 	pi.registerTool({
 		name: "cron_create",
-		label: "Create Scheduled Job",
+		// Claude Code's tool names: the row reads "CronCreate(*/5 * * * *: ...)".
+		label: "CronCreate",
 		description: CRON_CREATE_DESCRIPTION,
 		promptSnippet: CRON_CREATE_SNIPPET,
 		parameters: Type.Object({
@@ -928,6 +775,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				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}" }.`);
+			// Asked for in plain words, not through /loop: do it once now, as /loop would.
+			if (recurring && !currentRun.loopRequest && !currentRun.cronId && !currentRun.chainId) lines.push(RUN_NOW_HINT);
 
 			return {
 				content: [{ type: "text", text: lines.join("\n") }],
@@ -946,7 +795,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 
 	pi.registerTool({
 		name: "cron_delete",
-		label: "Cancel Scheduled Job",
+		label: "CronDelete",
 		description: CRON_DELETE_DESCRIPTION,
 		promptSnippet: CRON_DELETE_SNIPPET,
 		parameters: Type.Object({
@@ -975,7 +824,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 
 	pi.registerTool({
 		name: "cron_list",
-		label: "List Scheduled Jobs",
+		label: "CronList",
 		description: CRON_LIST_DESCRIPTION,
 		promptSnippet: CRON_LIST_SNIPPET,
 		parameters: Type.Object({}),
@@ -1007,7 +856,7 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 
 	pi.registerTool({
 		name: "schedule_wakeup",
-		label: "Schedule Next Loop Iteration",
+		label: "ScheduleWakeup",
 		description: SCHEDULE_WAKEUP_DESCRIPTION,
 		promptSnippet: SCHEDULE_WAKEUP_SNIPPET,
 		parameters: Type.Object({
@@ -1017,7 +866,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				}),
 			),
 			reason: Type.Optional(
-				Type.String({ description: "One short sentence explaining the chosen delay. Shown to the user." }),
+				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({
@@ -1045,8 +897,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 						{
 							type: "text" as const,
 							text: chains.length
-								? `Loop ended. ${chains.length} pending wakeup(s) cancelled.`
-								: "Loop ended. Nothing was pending.",
+								? `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: { stopped: true, cancelledWakeups: chains.length },
@@ -1054,11 +908,33 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			}
 
 			if (typeof params.delaySeconds !== "number" || Number.isNaN(params.delaySeconds)) {
-				throw new Error("delaySeconds is required unless stop is true.");
+				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 unless stop is true.");
+				throw new Error("`prompt` is required when `stop` is not true.");
+			}
+
+			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:
+								`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 },
+				};
 			}
 
 			// Claude Code rounds and clamps; only a change after rounding counts as clamped.
@@ -1080,8 +956,8 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 							{
 								type: "text" as const,
 								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.",
+									`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, agedOut: true, id: chain.id, cancelledWakeups: 1 },
@@ -1119,9 +995,17 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 				reason: params.reason,
 			});
 
-			const note = wasClamped ? ` (clamped from ${requested}s)` : "";
+			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 iteration scheduled in ${delay}s${note} for loop ${chain.id}.` }],
+				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,
@@ -1137,19 +1021,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	// ---------------------------------------------------------------- rendering
-
-	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();
-		});
-	}
-
-	pi.registerMessageRenderer(TICK_MESSAGE_TYPE, renderTickMessage);
 
 	// ----------------------------------------------------------------- events
 
@@ -1161,11 +1032,46 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 	 * wakeup stays armed as the fallback heartbeat, and the model re-arms it if
 	 * it wants a different time.
 	 */
+	pi.registerMessageRenderer(TICK_MESSAGE_TYPE, renderScheduledMessage);
+
 	pi.on("before_agent_start", (event, ctx) => {
 		lastCtx = ctx;
 		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, loopRequest: true };
+			return rulesFor(queued.guidelines);
+		}
 		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,
+			};
+			// A cron fire needs nothing beyond its envelope ("it fires the next tick
+			// on its own, so do not call schedule_wakeup; to cancel it, call
+			// cron_delete"): an extra message every minute would only grow the
+			// context. A self-paced tick carries the rules that keep the loop alive.
+			if (details.kind !== "wakeup") return;
+			const chain = details.jobId ? scheduler.get(details.jobId) : undefined;
+			if (!chain) return;
+			const guidelines = [loopGuidelines(chain.prompt)];
+			if (monitorToolAvailable()) guidelines.push(monitorGuidelines(chain.prompt));
+			return rulesFor(guidelines);
+		}
+
 		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;
@@ -1173,31 +1079,6 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			if (chain) currentRun.chainId = chain.id;
 			return;
 		}
-		if (event.message.customType !== TICK_MESSAGE_TYPE) return;
-
-		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;
-		const options = event.systemPromptOptions;
-		options.promptGuidelines = [...(options.promptGuidelines ?? []), ...notes];
 	});
 
 	/**
@@ -1220,17 +1101,23 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (event, ctx) => {
 		lastCtx = 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 \u00b7 /reload to apply", "info");
-		}
 	});
 
 	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;
@@ -1264,12 +1151,10 @@ export default function piCcLoopExtension(pi: ExtensionAPI): void {
 			}
 		}
 		if (!data) {
-			refreshWidget(scheduler.list());
 			return;
 		}
 
 		for (const prompt of data.stopped ?? []) rememberStopped(prompt);
-		if (typeof data.widget === "boolean") widgetEnabled = data.widget;
 
 		const now = Date.now();
 		const limit = maxAgeMs();