@hank-warren/pi-loop 0.1.0

package/src/loop.ts

@@ -0,0 +1,426 @@
+/**
+ * The loop engine: timer lifecycle, tick evaluation, poke delivery, and
+ * loop-aware compaction, wired to Pi's extension events.
+ *
+ * Design invariants (approved plan):
+ * - Timers are armed in session_start or a command handler, never the factory,
+ *   and cleared in an idempotent session_shutdown.
+ * - Pokes deliver only at a fully idle boundary; a tick that lands while the
+ *   agent is busy coalesces into a single pending wake delivered at the next
+ *   agent_settled. Missed ticks never stack.
+ * - pi-goal owns "whether the work is done": its safety states pause the loop,
+ *   its completion stops it, and its thresholds ride along in the
+ *   post-compaction continuation. Coupling is read-only session entries.
+ * - The loop's proactive compaction is the normal compaction path; Pi's
+ *   reserve-token auto-compaction is the fault handler.
+ */
+
+import { randomUUID } from "node:crypto";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { LoopStartArguments } from "./command.js";
+import { decideTick, type TickDecision, type TickEnvironment } from "./decide.js";
+import { formatClock, formatDuration, parseDuration } from "./interval.js";
+import {
+	buildCompactionInstructions,
+	buildGoalPoke,
+	buildPostCompactContinuation,
+	buildPromptPoke,
+} from "./messages.js";
+import {
+	DEFAULT_LOOP_SETTINGS,
+	type LoopSettings,
+	loopSettingsPath,
+	readLoopSettings,
+} from "./settings.js";
+import {
+	LOOP_STATE_ENTRY_TYPE,
+	type LoopState,
+	readGoalSnapshot,
+	readPlanModeEnabled,
+	restoreLoopState,
+} from "./state.js";
+
+export const LOOP_STATUS_KEY = "loop";
+
+export interface LoopControllerOptions {
+	settingsPath?: string;
+	now?: () => number;
+}
+
+export class LoopController {
+	settings: LoopSettings = structuredClone(DEFAULT_LOOP_SETTINGS);
+	state: LoopState | undefined;
+	compacting = false;
+	lastDecision: (TickDecision & { at: number }) | undefined;
+
+	private readonly pi: ExtensionAPI;
+	private readonly now: () => number;
+	readonly settingsPath: string;
+	private timer: NodeJS.Timeout | undefined;
+	private nextWakeAt: number | undefined;
+	private wakePending = false;
+	private pendingLoopId: string | undefined;
+	private sessionCtx: ExtensionContext | undefined;
+
+	constructor(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
+		this.pi = pi;
+		this.now = options.now ?? Date.now;
+		this.settingsPath = options.settingsPath ?? loopSettingsPath();
+	}
+
+	// --- lifecycle ---
+
+	onSessionStart(ctx: ExtensionContext): void {
+		this.clearTimer();
+		this.wakePending = false;
+		this.pendingLoopId = undefined;
+		this.compacting = false;
+		this.lastDecision = undefined;
+		this.sessionCtx = ctx;
+
+		const loaded = readLoopSettings(this.settingsPath);
+		this.settings = loaded.settings;
+		if (loaded.kind === "invalid") {
+			ctx.ui.notify(`pi-loop settings ignored: ${loaded.reason}. Using defaults.`, "warning");
+		}
+
+		this.state = restoreLoopState(ctx.sessionManager.getBranch());
+		if (this.state && this.state.status === "active") {
+			if (this.now() >= this.state.expiresAt) {
+				this.transition("stopped", "loop expired while the session was away");
+				return;
+			}
+			this.scheduleTick(this.state.intervalMs);
+		}
+		this.updateWidget();
+	}
+
+	onSessionShutdown(): void {
+		this.clearTimer();
+		this.wakePending = false;
+		this.pendingLoopId = undefined;
+		this.sessionCtx = undefined;
+	}
+
+	onAgentSettled(ctx: ExtensionContext): void {
+		this.sessionCtx = ctx;
+		if (!this.state || this.state.status !== "active") return;
+		if (this.maybeStartCompaction(ctx)) return;
+		if (this.wakePending) {
+			if (this.pendingLoopId !== this.state.id) {
+				// Stale wake from a replaced loop: drop it (research: CC #57660).
+				this.wakePending = false;
+				this.pendingLoopId = undefined;
+				return;
+			}
+			this.wakePending = false;
+			this.pendingLoopId = undefined;
+			this.runTick(ctx);
+		}
+	}
+
+	onSessionCompact(ctx: ExtensionContext): void {
+		this.sessionCtx = ctx;
+		if (!this.state || this.state.status !== "active") return;
+		if (!this.settings.compaction.postCompactContinuation) return;
+		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+		this.pi.sendUserMessage(buildPostCompactContinuation(this.state, goal), {
+			deliverAs: "followUp",
+		});
+	}
+
+	// --- tick machinery ---
+
+	private scheduleTick(delayMs: number): void {
+		this.clearTimer();
+		this.nextWakeAt = this.now() + delayMs;
+		this.timer = setTimeout(() => {
+			this.timer = undefined;
+			const ctx = this.sessionCtx;
+			if (!ctx) return;
+			this.runTick(ctx);
+		}, delayMs);
+		// Never hold the process open for a wakeup.
+		this.timer.unref?.();
+	}
+
+	private clearTimer(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.nextWakeAt = undefined;
+	}
+
+	private gatherEnvironment(ctx: ExtensionContext): TickEnvironment {
+		const branch = ctx.sessionManager.getBranch();
+		return {
+			now: this.now(),
+			busy: !ctx.isIdle() || ctx.hasPendingMessages(),
+			compacting: this.compacting,
+			planModeEnabled: readPlanModeEnabled(branch),
+			goal: readGoalSnapshot(branch),
+		};
+	}
+
+	runTick(ctx: ExtensionContext): void {
+		const loop = this.state;
+		if (!loop) return;
+		const env = this.gatherEnvironment(ctx);
+		const decision = decideTick(loop, env);
+		this.lastDecision = { ...decision, at: env.now };
+		switch (decision.action) {
+			case "none":
+				return;
+			case "expire":
+				this.transition("stopped", "loop expired (maxLoopDuration reached)");
+				return;
+			case "skip":
+				if (decision.reason === "plan-mode-active") {
+					// Plan mode may end without an agent_settled we can use, so
+					// keep ticking until it does.
+					this.scheduleTick(loop.intervalMs);
+				} else {
+					// Busy or compacting: coalesce into one pending wake that
+					// the next agent_settled (or compaction onComplete) delivers.
+					this.wakePending = true;
+					this.pendingLoopId = loop.id;
+				}
+				this.updateWidget();
+				return;
+			case "stop":
+				this.transition(
+					"stopped",
+					decision.reason === "goal-complete"
+						? "the goal completed"
+						: `the ${loop.maxIterations}-iteration cap was reached`,
+				);
+				return;
+			case "pause":
+				this.transition(
+					"paused",
+					`pi-goal reports the goal is ${decision.cause}; resolve it, then /loop resume`,
+				);
+				return;
+			case "poke":
+				this.deliverPoke(ctx, env, decision.reason);
+				return;
+		}
+	}
+
+	private deliverPoke(
+		ctx: ExtensionContext,
+		env: TickEnvironment,
+		reason: "recurring-prompt" | "goal-stalled" | "goal-waiting",
+	): void {
+		const loop = this.state;
+		if (!loop) return;
+		const message =
+			reason === "recurring-prompt" || !env.goal
+				? buildPromptPoke(loop, this.settings.pokePreamble)
+				: buildGoalPoke(loop, env.goal, reason === "goal-waiting" ? "goal-waiting" : "goal-stalled");
+		this.state = { ...loop, iteration: loop.iteration + 1, lastWakeAt: env.now };
+		this.persist();
+		this.pi.sendUserMessage(message);
+		this.scheduleTick(this.state.intervalMs);
+		this.updateWidget();
+	}
+
+	private maybeStartCompaction(ctx: ExtensionContext): boolean {
+		const loop = this.state;
+		if (!loop || loop.status !== "active" || loop.compactAt === null) return false;
+		if (!this.settings.compaction.enabled || this.compacting) return false;
+		if (!ctx.isIdle() || ctx.hasPendingMessages()) return false;
+		const usage = ctx.getContextUsage();
+		if (!usage || typeof usage.tokens !== "number" || !usage.contextWindow) return false;
+		if (usage.tokens / usage.contextWindow < loop.compactAt) return false;
+		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+		this.compacting = true;
+		ctx.compact({
+			customInstructions: buildCompactionInstructions(
+				loop,
+				goal,
+				this.settings.compaction.instructions,
+			),
+			onComplete: () => {
+				this.compacting = false;
+				const currentCtx = this.sessionCtx;
+				// A pending wake held during compaction delivers at the next
+				// settled boundary; nudge in case that boundary already passed.
+				if (currentCtx && this.wakePending) this.onAgentSettled(currentCtx);
+			},
+			onError: (error) => {
+				this.compacting = false;
+				this.sessionCtx?.ui.notify(
+					`pi-loop compaction failed: ${error instanceof Error ? error.message : String(error)}`,
+					"warning",
+				);
+			},
+		});
+		return true;
+	}
+
+	// --- state transitions & presentation ---
+
+	private transition(status: "paused" | "stopped", why: string): void {
+		if (!this.state) return;
+		this.state = { ...this.state, status };
+		this.clearTimer();
+		this.wakePending = false;
+		this.pendingLoopId = undefined;
+		this.persist();
+		this.sessionCtx?.ui.notify(`Loop ${status}: ${why}.`, "info");
+		this.updateWidget();
+	}
+
+	persist(): void {
+		if (!this.state) return;
+		this.pi.appendEntry(LOOP_STATE_ENTRY_TYPE, { loop: this.state });
+	}
+
+	updateWidget(): void {
+		const ui = this.sessionCtx?.ui;
+		if (!ui) return;
+		const loop = this.state;
+		if (!loop || loop.status === "stopped") {
+			ui.setStatus(LOOP_STATUS_KEY, undefined);
+			return;
+		}
+		if (loop.status === "paused") {
+			ui.setStatus(LOOP_STATUS_KEY, "loop paused");
+			return;
+		}
+		const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+		const next = this.wakePending
+			? "next on idle"
+			: this.nextWakeAt
+				? `next ${formatClock(this.nextWakeAt)}`
+				: "next unscheduled";
+		ui.setStatus(
+			LOOP_STATUS_KEY,
+			`loop ${formatDuration(loop.intervalMs)} · ${loop.iteration}/${cap} · ${next}`,
+		);
+	}
+
+	statusLines(ctx: ExtensionContext): string[] {
+		const loop = this.state;
+		if (!loop) return ["No loop in this session. Start one with /loop <interval> [prompt]."];
+		const lines = [
+			`Status: ${loop.status}`,
+			`Interval: every ${formatDuration(loop.intervalMs)}`,
+			`Iterations: ${loop.iteration}${loop.maxIterations === null ? " (unlimited)" : ` of ${loop.maxIterations}`}`,
+			`Started: ${new Date(loop.startedAt).toLocaleString()}`,
+			`Expires: ${new Date(loop.expiresAt).toLocaleString()}`,
+			`Proactive compaction: ${loop.compactAt === null ? "off" : `at ${Math.round(loop.compactAt * 100)}% of context`}`,
+		];
+		if (loop.prompt) lines.push(`Prompt: ${loop.prompt}`);
+		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+		if (goal) lines.push(`Goal (pi-goal): ${goal.status} — ${goal.text}`);
+		if (this.nextWakeAt && loop.status === "active") {
+			lines.push(`Next wake: ${formatClock(this.nextWakeAt)}`);
+		}
+		if (this.wakePending) lines.push("A wake is pending delivery at the next idle boundary.");
+		if (this.lastDecision) {
+			const { action, reason, at } = this.lastDecision;
+			lines.push(`Last tick: ${action} (${reason}) at ${formatClock(at)}`);
+		}
+		return lines;
+	}
+
+	// --- command actions ---
+
+	startLoop(ctx: ExtensionCommandContext, start: LoopStartArguments): void {
+		this.sessionCtx = ctx;
+		const now = this.now();
+		const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+		if (!start.prompt && goal?.status !== "active") {
+			ctx.ui.notify(
+				"A prompt is required unless a pi-goal goal is active: /loop <interval> <prompt>.",
+				"error",
+			);
+			return;
+		}
+		const expiryMs = parseDuration(this.settings.maxLoopDuration) ?? 604_800_000;
+		const compactAt =
+			start.compactAt !== undefined
+				? start.compactAt
+				: this.settings.compaction.enabled
+					? this.settings.compaction.threshold
+					: null;
+		this.state = {
+			id: randomUUID().slice(0, 8),
+			status: "active",
+			...(start.prompt ? { prompt: start.prompt } : {}),
+			intervalMs: start.intervalMs,
+			maxIterations:
+				start.maxIterations !== undefined ? start.maxIterations : this.settings.maxIterations,
+			compactAt,
+			iteration: 0,
+			startedAt: now,
+			expiresAt: now + expiryMs,
+		};
+		this.wakePending = false;
+		this.pendingLoopId = undefined;
+		this.persist();
+		this.scheduleTick(start.intervalMs);
+		this.updateWidget();
+		const clampNote = start.clamped
+			? ` (requested ${formatDuration(start.requestedMs)}, clamped to the ${formatDuration(start.intervalMs)} minimum)`
+			: "";
+		const target = start.prompt ? "the loop prompt" : "the active goal";
+		ctx.ui.notify(
+			`Loop started: every ${formatDuration(start.intervalMs)}${clampNote}, first wake at ${formatClock(now + start.intervalMs)}, poking ${target}. Stop with /loop stop.`,
+			"info",
+		);
+	}
+
+	pauseLoop(ctx: ExtensionContext): void {
+		this.sessionCtx = ctx;
+		if (!this.state || this.state.status !== "active") {
+			ctx.ui.notify("No active loop to pause.", "warning");
+			return;
+		}
+		this.transition("paused", "paused by user");
+	}
+
+	resumeLoop(ctx: ExtensionContext): void {
+		this.sessionCtx = ctx;
+		const loop = this.state;
+		if (!loop || loop.status !== "paused") {
+			ctx.ui.notify("No paused loop to resume.", "warning");
+			return;
+		}
+		if (this.now() >= loop.expiresAt) {
+			this.state = { ...loop, status: "active" };
+			this.transition("stopped", "loop expired (maxLoopDuration reached)");
+			return;
+		}
+		this.state = { ...loop, status: "active" };
+		this.persist();
+		this.scheduleTick(loop.intervalMs);
+		this.updateWidget();
+		ctx.ui.notify(
+			`Loop resumed: next wake at ${formatClock(this.now() + loop.intervalMs)}.`,
+			"info",
+		);
+	}
+
+	/** Re-arm the timer after an interval edit while active. */
+	resumeAfterEdit(): void {
+		const loop = this.state;
+		if (!loop || loop.status !== "active") return;
+		this.scheduleTick(loop.intervalMs);
+		this.updateWidget();
+	}
+
+	stopLoop(ctx: ExtensionContext, why = "stopped by user"): void {
+		this.sessionCtx = ctx;
+		if (!this.state || this.state.status === "stopped") {
+			ctx.ui.notify("No loop to stop.", "warning");
+			return;
+		}
+		this.transition("stopped", why);
+	}
+}

package/src/manager.ts

@@ -0,0 +1,237 @@
+/**
+ * Bare-/loop manager and /loop settings, built on Pi's native dialog
+ * primitives (ui.select / ui.input / ui.confirm). Non-TUI modes get status
+ * notifications instead of menus.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatDuration, parseInterval } from "./interval.js";
+import type { LoopController } from "./loop.js";
+import { readGoalSnapshot } from "./state.js";
+import {
+	DEFAULT_LOOP_SETTINGS,
+	type LoopSettings,
+	normalizeLoopSettings,
+	saveLoopSettings,
+} from "./settings.js";
+import { parseDuration } from "./interval.js";
+
+export async function showLoopManager(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		notifyStatus(controller, ctx);
+		return;
+	}
+	for (;;) {
+		const loop = controller.state;
+		const options: string[] = ["Status"];
+		if (loop?.status === "active") options.push("Pause", "Edit prompt", "Edit interval", "Stop");
+		else if (loop?.status === "paused") options.push("Resume", "Edit prompt", "Edit interval", "Stop");
+		else options.push("Start a loop…");
+		options.push("Settings");
+		const choice = await ctx.ui.select(`Pi Loop${loop ? ` · ${loop.status}` : ""}`, options);
+		if (choice === undefined) return;
+		switch (choice) {
+			case "Status":
+				notifyStatus(controller, ctx);
+				break;
+			case "Pause":
+				controller.pauseLoop(ctx);
+				break;
+			case "Resume":
+				controller.resumeLoop(ctx);
+				break;
+			case "Stop":
+				controller.stopLoop(ctx);
+				break;
+			case "Start a loop…":
+				await startFromMenu(controller, ctx);
+				break;
+			case "Edit prompt":
+				await editPrompt(controller, ctx);
+				break;
+			case "Edit interval":
+				await editInterval(controller, ctx);
+				break;
+			case "Settings":
+				await showLoopSettings(controller, ctx);
+				break;
+			default:
+				return;
+		}
+	}
+}
+
+function notifyStatus(controller: LoopController, ctx: ExtensionCommandContext): void {
+	ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+}
+
+async function startFromMenu(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const intervalText = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", "5m");
+	if (intervalText === undefined) return;
+	const interval = parseInterval(intervalText.trim() || "5m");
+	if (!interval) {
+		ctx.ui.notify(`Invalid interval: ${intervalText}. Use <number><unit>, e.g. 5m.`, "error");
+		return;
+	}
+	const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+	const promptText = await ctx.ui.input(
+		goal?.status === "active"
+			? "Loop prompt (optional: empty pokes the active goal)"
+			: "Loop prompt",
+	);
+	if (promptText === undefined) return;
+	const prompt = promptText.trim();
+	controller.startLoop(ctx, {
+		kind: "start",
+		requestedMs: interval.requestedMs,
+		intervalMs: interval.effectiveMs,
+		clamped: interval.clamped,
+		...(prompt ? { prompt } : {}),
+	});
+}
+
+async function editPrompt(controller: LoopController, ctx: ExtensionCommandContext): Promise<void> {
+	const loop = controller.state;
+	if (!loop || loop.status === "stopped") return;
+	const next = await ctx.ui.input("Loop prompt", loop.prompt ?? "");
+	if (next === undefined) return;
+	const prompt = next.trim();
+	const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
+	if (!prompt && goal?.status !== "active") {
+		ctx.ui.notify("A prompt is required unless a pi-goal goal is active.", "error");
+		return;
+	}
+	if (prompt) controller.state = { ...loop, prompt };
+	else {
+		const { prompt: _dropped, ...rest } = loop;
+		controller.state = rest;
+	}
+	controller.persist();
+	ctx.ui.notify("Loop prompt updated.", "info");
+}
+
+async function editInterval(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const loop = controller.state;
+	if (!loop || loop.status === "stopped") return;
+	const next = await ctx.ui.input("Wake interval (e.g. 5m, 2h)", formatDuration(loop.intervalMs));
+	if (next === undefined) return;
+	const interval = parseInterval(next.trim());
+	if (!interval) {
+		ctx.ui.notify(`Invalid interval: ${next}. Use <number><unit>, e.g. 5m.`, "error");
+		return;
+	}
+	controller.state = { ...loop, intervalMs: interval.effectiveMs };
+	controller.persist();
+	if (loop.status === "active") {
+		// Re-arm on the new cadence from now.
+		controller.resumeAfterEdit();
+	}
+	ctx.ui.notify(
+		`Loop interval set to ${formatDuration(interval.effectiveMs)}${interval.clamped ? " (clamped to the minimum)" : ""}.`,
+		"info",
+	);
+}
+
+export async function showLoopSettings(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(`Edit pi-loop settings manually: ${controller.settingsPath}`, "info");
+		return;
+	}
+	for (;;) {
+		const s = controller.settings;
+		const items = [
+			`Max iterations: ${s.maxIterations === null ? "Unlimited" : s.maxIterations}`,
+			`Max loop duration: ${s.maxLoopDuration}`,
+			`Proactive compaction: ${s.compaction.enabled ? `On at ${Math.round(s.compaction.threshold * 100)}%` : "Off"}`,
+			`Post-compact continuation: ${s.compaction.postCompactContinuation ? "On" : "Off"}`,
+			`Inline /loop: ${s.inlineInvocation ? "On" : "Off"}`,
+		];
+		const choice = await ctx.ui.select("Pi Loop Settings", items);
+		if (choice === undefined) return;
+		const index = items.indexOf(choice);
+		const next = structuredClone(s);
+		if (index === 0) {
+			const value = await ctx.ui.input(
+				"Max iterations (positive number, or unlimited)",
+				s.maxIterations === null ? "unlimited" : `${s.maxIterations}`,
+			);
+			if (value === undefined) continue;
+			const trimmed = value.trim();
+			if (trimmed === "unlimited") next.maxIterations = null;
+			else {
+				const parsed = Number(trimmed);
+				if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+					ctx.ui.notify(`Invalid value: ${value}.`, "error");
+					continue;
+				}
+				next.maxIterations = parsed;
+			}
+		} else if (index === 1) {
+			const value = await ctx.ui.input("Max loop duration (e.g. 7d)", s.maxLoopDuration);
+			if (value === undefined) continue;
+			if (parseDuration(value.trim()) === undefined) {
+				ctx.ui.notify(`Invalid duration: ${value}. Use <number><unit>, e.g. 7d.`, "error");
+				continue;
+			}
+			next.maxLoopDuration = value.trim();
+		} else if (index === 2) {
+			if (s.compaction.enabled) next.compaction.enabled = false;
+			else {
+				const value = await ctx.ui.input(
+					"Compaction threshold (percent of context window)",
+					`${Math.round((s.compaction.threshold || DEFAULT_LOOP_SETTINGS.compaction.threshold) * 100)}%`,
+				);
+				if (value === undefined) continue;
+				const raw = value.trim().replace(/%$/, "");
+				const fraction = Number(raw) / 100;
+				if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
+					ctx.ui.notify(`Invalid threshold: ${value}. Use a percentage between 1 and 99.`, "error");
+					continue;
+				}
+				next.compaction.enabled = true;
+				next.compaction.threshold = fraction;
+			}
+		} else if (index === 3) {
+			next.compaction.postCompactContinuation = !s.compaction.postCompactContinuation;
+		} else if (index === 4) {
+			next.inlineInvocation = !s.inlineInvocation;
+		} else {
+			continue;
+		}
+		if (!applySettings(controller, ctx, next)) continue;
+	}
+}
+
+function applySettings(
+	controller: LoopController,
+	ctx: ExtensionCommandContext,
+	next: LoopSettings,
+): boolean {
+	if (!normalizeLoopSettings(next)) {
+		ctx.ui.notify("Refusing to save invalid pi-loop settings.", "error");
+		return false;
+	}
+	try {
+		saveLoopSettings(next, controller.settingsPath);
+	} catch (error) {
+		ctx.ui.notify(
+			`Could not save settings (${error instanceof Error ? error.message : String(error)}); the previous values remain active.`,
+			"error",
+		);
+		return false;
+	}
+	controller.settings = next;
+	return true;
+}

package/src/markers.ts

@@ -0,0 +1,41 @@
+/**
+ * Provenance markers for loop-injected messages, following pi-goal's marker
+ * pattern: an HTML comment the model and transcript can see but that reads as
+ * metadata, letting stale or duplicate deliveries be detected (research:
+ * Claude Code's untagged auto-fires made wakeups indistinguishable from user
+ * prompts, issue #57660).
+ */
+
+const POKE_MARKER_PREFIX = "pi-loop-poke:";
+const CONTINUATION_MARKER_PREFIX = "pi-loop-continuation:";
+
+const POKE_MARKER_PATTERN = new RegExp(
+	`<!--\\s*${escapeRegExpText(POKE_MARKER_PREFIX)}([^\\s:>]+):(\\d+)\\s*-->`,
+);
+const CONTINUATION_MARKER_PATTERN = new RegExp(
+	`<!--\\s*${escapeRegExpText(CONTINUATION_MARKER_PREFIX)}([^\\s>]+)\\s*-->`,
+);
+
+export function appendPokeMarker(prompt: string, loopId: string, iteration: number): string {
+	return `${prompt}\n\n<!-- ${POKE_MARKER_PREFIX}${loopId}:${iteration} -->`;
+}
+
+export function extractPokeMarker(
+	prompt: string,
+): { loopId: string; iteration: number } | undefined {
+	const match = POKE_MARKER_PATTERN.exec(prompt);
+	if (!match || match[1] === undefined || match[2] === undefined) return undefined;
+	return { loopId: match[1], iteration: Number(match[2]) };
+}
+
+export function appendContinuationMarker(prompt: string, loopId: string): string {
+	return `${prompt}\n\n<!-- ${CONTINUATION_MARKER_PREFIX}${loopId} -->`;
+}
+
+export function extractContinuationMarker(prompt: string): string | undefined {
+	return CONTINUATION_MARKER_PATTERN.exec(prompt)?.[1];
+}
+
+function escapeRegExpText(value: string) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}