@hank-warren/pi-loop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hank Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# pi-loop — interval wakeups for the Pi coding agent
+
+Inspired by Claude Code's `/loop`, adapted to Pi: re-run a prompt on an interval, rescue a stalled session that has an unfinished [pi-goal](https://github.com/narumiruna/pi-extensions/tree/main/packages/pi-goal) goal, and keep long loops coherent across context compaction.
+
+pi-loop is a **pacemaker, not an evaluator**: it owns *when* the session wakes; pi-goal owns *whether the work is done*. It reads pi-goal's `goal-state` and pi-plan-mode's `plan-mode-state` session entries read-only and fail-open — with neither installed it still runs plain recurring-prompt loops.
+
+## Usage
+
+```
+/loop 5m check my PR, address review comments, fix CI   # recurring prompt every 5 minutes
+/loop 30m                                               # pi-goal goal active: poke it every 30 minutes
+/loop                                                   # manager TUI (status, pause/resume, edit, settings, stop)
+/loop status | pause | resume | stop | settings
+/loop --max 20 --compact-at 60% 10m <prompt>            # per-loop overrides
+```
+
+- **Intervals** are `<number><unit>` with unit `s`/`m`/`h`/`d`, parsed by the extension (never the model), minimum 1 minute (smaller values clamp, and the effective value is echoed).
+- `/loop` also works **mid-prompt** (`get CI green — /loop 10m recheck the pipeline`): the command dispatches first and the surrounding prose follows. Backtick code is ignored; messages with images pass through. Toggle with the `inlineInvocation` setting.
+
+## What a wakeup does
+
+Each tick evaluates, in order:
+
+1. **Expired?** Loops hard-expire after `maxLoopDuration` (default 7 days) — a forgotten loop is bounded.
+2. **Plan mode active?** Skip quietly; never inject prompts into a planning conversation.
+3. **Agent busy?** Never interrupt: coalesce into a single pending wake delivered at the next fully-settled idle boundary. N missed ticks collapse into one poke.
+4. **Goal state** (when pi-goal has a goal): completion **stops** the loop; a safety pause (`paused`/`blocked`/`usage_limited`/`budget_limited`) **pauses** the loop — pi-loop never pokes past pi-goal's circuit breakers; an `active` or `goal_wait`-waiting goal in an idle session is exactly the stall this extension exists for, so it pokes toward the goal (a tick is the external wake `goal_wait` arranges).
+5. **Iteration cap** (default 25 delivered pokes, `--max`/settings, explicit `unlimited` opt-in): stop.
+6. **Poke**: the stored prompt (with a short scheduled-iteration preamble) or a goal wake message. Every loop-injected message carries a provenance marker (`<!-- pi-loop-poke:<id>:<n> -->`) so wakeups are distinguishable from user prompts and stale wakes are dropped.
+
+The footer widget shows `loop 5m · 3/25 · next 14:32`; `/loop status` shows the full card including the last tick's decision and reason.
+
+## Loop-aware compaction
+
+Long loops die by context exhaustion, not by failing. pi-loop owns the compaction path:
+
+- **Proactive compact at a threshold** (default 70% of the context window, `--compact-at` / settings): at an idle boundary, pi-loop triggers `/compact` itself with loop-specific instructions — preserve the objective and acceptance criteria verbatim, decisions and dead-ends, files modified, commands and unresolved errors, the next 1-3 actions, and carry prior summaries forward cumulatively. Pending pokes are held until the compaction completes. Pi's reserve-token auto-compaction remains as the fault handler.
+- **Post-compaction continuation**: after every compaction (whoever triggered it), a follow-up message restates the loop prompt, iteration, and — when a goal exists — the goal text plus pi-goal's accounting (iteration, automatic turns, token budget) so work resumes coherently instead of drifting. It never contains a dispatchable command.
+- Loop state itself lives in custom session entries, which compaction never touches, and survives session restarts (the timer re-arms on resume; expired loops are dropped with a notice).
+
+## Settings
+
+`~/.pi/agent/pi-loop.json` (absent file = defaults, never created implicitly; saves are atomic and preserve unknown fields), or `/loop settings`:
+
+```json
+{
+  "maxIterations": 25,
+  "maxLoopDuration": "7d",
+  "compaction": {
+    "enabled": true,
+    "threshold": 0.7,
+    "postCompactContinuation": true,
+    "instructions": null
+  },
+  "pokePreamble": null,
+  "inlineInvocation": true
+}
+```
+
+`maxIterations: null` means unlimited. `compaction.instructions` and `pokePreamble` override the built-in templates.
+
+## Install
+
+```bash
+pi install npm:@hank-warren/pi-loop
+```
+
+Works standalone; pairs best with `npm:@hank-warren/pi-goal` (or upstream `@narumitw/pi-goal`) for goal-evaluated stop criteria.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hank-warren/pi-loop",
+  "version": "0.1.0",
+  "description": "Interval wakeups for Pi: recurring prompt re-runs, stall rescue toward an active pi-goal goal, and loop-aware compaction that survives long sessions.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "loop",
+    "scheduler",
+    "automation"
+  ],
+  "author": "Hank Warren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hank-warren/pi-extensions.git",
+    "directory": "packages/pi-loop"
+  },
+  "bugs": {
+    "url": "https://github.com/hank-warren/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-loop#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/src/command.ts

@@ -0,0 +1,142 @@
+/**
+ * Deterministic /loop argument parsing. Grammar:
+ *
+ *   /loop                                    -> show (manager TUI / status)
+ *   /loop status|pause|resume|stop|settings  -> subcommand
+ *   /loop [--max N] [--compact-at X] <interval> [prompt...]
+ *
+ * Flags precede the interval; the interval is the first non-flag token;
+ * everything after it (raw, newlines preserved) is the prompt.
+ */
+
+import { parseInterval } from "./interval.js";
+
+export const LOOP_SUBCOMMANDS = ["status", "pause", "resume", "stop", "settings"] as const;
+export type LoopSubcommand = (typeof LOOP_SUBCOMMANDS)[number];
+
+export interface LoopStartArguments {
+	kind: "start";
+	requestedMs: number;
+	intervalMs: number;
+	clamped: boolean;
+	/** undefined = use settings default; null = unlimited. */
+	maxIterations?: number | null;
+	/** undefined = use settings default; null = disabled for this loop. */
+	compactAt?: number | null;
+	prompt?: string;
+}
+
+export type LoopCommand =
+	| { kind: "show" }
+	| { kind: LoopSubcommand }
+	| LoopStartArguments
+	| { kind: "error"; message: string };
+
+export function parseLoopCommand(args: string): LoopCommand {
+	const trimmed = args.trim();
+	if (!trimmed) return { kind: "show" };
+	if ((LOOP_SUBCOMMANDS as readonly string[]).includes(trimmed)) {
+		return { kind: trimmed as LoopSubcommand };
+	}
+
+	const tokens = [...args.matchAll(/\S+/g)].map((match) => ({
+		text: match[0],
+		index: match.index,
+	}));
+	let maxIterations: number | null | undefined;
+	let compactAt: number | null | undefined;
+	let position = 0;
+	while (position < tokens.length) {
+		const token = tokens[position];
+		if (token === undefined || !token.text.startsWith("--")) break;
+		const [flag, inlineValue] = splitFlag(token.text);
+		const next = tokens[position + 1];
+		const value = inlineValue ?? next?.text;
+		const consumed = inlineValue !== undefined ? 1 : 2;
+		if (flag === "--max") {
+			if (value === undefined) return { kind: "error", message: "--max needs a value (a positive number, or unlimited)." };
+			maxIterations = parseMax(value);
+			if (maxIterations === undefined) {
+				return { kind: "error", message: `Invalid --max value: ${value}. Use a positive whole number or unlimited.` };
+			}
+		} else if (flag === "--compact-at") {
+			if (value === undefined) return { kind: "error", message: "--compact-at needs a value (e.g. 60% or off)." };
+			compactAt = parseCompactAt(value);
+			if (compactAt === undefined) {
+				return { kind: "error", message: `Invalid --compact-at value: ${value}. Use a percentage between 1% and 99% (e.g. 60%), a fraction (0.6), or off.` };
+			}
+		} else {
+			return { kind: "error", message: `Unknown flag: ${flag}. Known flags: --max, --compact-at.` };
+		}
+		position += consumed;
+	}
+
+	const intervalToken = tokens[position];
+	if (intervalToken === undefined) {
+		return { kind: "error", message: "An interval is required to start a loop, e.g. /loop 5m <prompt>." };
+	}
+	const interval = parseInterval(intervalToken.text);
+	if (!interval) {
+		return {
+			kind: "error",
+			message: `Invalid interval: ${intervalToken.text}. Use <number><unit> with unit s, m, h, or d, e.g. 5m.`,
+		};
+	}
+	const promptToken = tokens[position + 1];
+	const prompt = promptToken === undefined ? undefined : args.slice(promptToken.index).trim();
+	return {
+		kind: "start",
+		requestedMs: interval.requestedMs,
+		intervalMs: interval.effectiveMs,
+		clamped: interval.clamped,
+		...(maxIterations === undefined ? {} : { maxIterations }),
+		...(compactAt === undefined ? {} : { compactAt }),
+		...(prompt ? { prompt } : {}),
+	};
+}
+
+function splitFlag(token: string): [string, string | undefined] {
+	const equals = token.indexOf("=");
+	if (equals === -1) return [token, undefined];
+	return [token.slice(0, equals), token.slice(equals + 1)];
+}
+
+function parseMax(value: string): number | null | undefined {
+	if (value === "unlimited" || value === "null") return null;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function parseCompactAt(value: string): number | null | undefined {
+	if (value === "off" || value === "none") return null;
+	let fraction: number;
+	if (value.endsWith("%")) {
+		fraction = Number(value.slice(0, -1)) / 100;
+	} else {
+		fraction = Number(value);
+	}
+	if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) return undefined;
+	return fraction;
+}
+
+export interface LoopArgumentCompletion {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+const LOOP_ARGUMENT_COMPLETIONS: readonly LoopArgumentCompletion[] = [
+	{ value: "status", label: "status", description: "Show the current loop" },
+	{ value: "pause", label: "pause", description: "Pause the loop" },
+	{ value: "resume", label: "resume", description: "Resume a paused loop" },
+	{ value: "stop", label: "stop", description: "Stop the loop" },
+	{ value: "settings", label: "settings", description: "Open pi-loop settings" },
+];
+
+export function completeLoopArguments(prefix: string): LoopArgumentCompletion[] | null {
+	const trimmed = prefix.trimStart();
+	const matches = LOOP_ARGUMENT_COMPLETIONS.filter((candidate) =>
+		candidate.value.startsWith(trimmed),
+	);
+	return matches.length > 0 ? matches : null;
+}

package/src/decide.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure tick decision. The engine gathers the environment and this function
+ * decides what a wakeup does, so the full decision matrix is unit-testable
+ * without timers or a Pi runtime.
+ *
+ * Precedence (approved plan): loop liveness → expiry → plan mode → busy →
+ * goal state → iteration cap → poke.
+ */
+
+import { GOAL_SAFETY_STATUSES, type GoalSnapshot, type LoopState } from "./state.js";
+
+export interface TickEnvironment {
+	now: number;
+	/** Agent is running, retrying, compacting, or has queued messages. */
+	busy: boolean;
+	/** A loop-owned proactive compaction is in flight; hold pokes. */
+	compacting: boolean;
+	planModeEnabled: boolean;
+	goal: GoalSnapshot | undefined;
+}
+
+export type TickDecision =
+	| { action: "none"; reason: "loop-not-active" }
+	| { action: "expire"; reason: "loop-expired" }
+	| { action: "skip"; reason: "plan-mode-active" | "agent-busy" | "compaction-in-flight" }
+	| { action: "stop"; reason: "goal-complete" | "max-iterations" }
+	| { action: "pause"; reason: "goal-safety"; cause: string }
+	| { action: "poke"; reason: "recurring-prompt" | "goal-stalled" | "goal-waiting" };
+
+export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
+	if (loop.status !== "active") return { action: "none", reason: "loop-not-active" };
+	if (env.now >= loop.expiresAt) return { action: "expire", reason: "loop-expired" };
+	if (env.planModeEnabled) return { action: "skip", reason: "plan-mode-active" };
+	if (env.compacting) return { action: "skip", reason: "compaction-in-flight" };
+	if (env.busy) return { action: "skip", reason: "agent-busy" };
+
+	const goal = env.goal;
+	if (goal) {
+		if (goal.status === "complete") return { action: "stop", reason: "goal-complete" };
+		if ((GOAL_SAFETY_STATUSES as readonly string[]).includes(goal.status)) {
+			return { action: "pause", reason: "goal-safety", cause: goal.status };
+		}
+		if (goal.status !== "active") {
+			// Unknown status from a newer pi-goal: treat like a safety state
+			// rather than poking past a guard we do not understand.
+			return { action: "pause", reason: "goal-safety", cause: goal.status };
+		}
+	}
+
+	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
+		return { action: "stop", reason: "max-iterations" };
+	}
+
+	if (goal) {
+		// An idle session with an active goal is exactly the stall/wait case:
+		// pi-goal continues on its own at every idle boundary, so idleness at
+		// tick time means its continuation was lost, or the goal is waiting on
+		// an external event — which this wakeup is.
+		return { action: "poke", reason: goal.waiting ? "goal-waiting" : "goal-stalled" };
+	}
+	return { action: "poke", reason: "recurring-prompt" };
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * pi-loop: Claude-Code-/loop-inspired pacemaker for Pi with hybrid semantics
+ * (recurring prompt re-runs plus stall rescue) and loop-aware compaction.
+ * The loop owns *when* the session wakes; @narumitw/pi-goal (or the
+ * @hank-warren/pi-goal fork) owns *whether the work is done*, read through
+ * its `goal-state` session entries only.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { completeLoopArguments, parseLoopCommand } from "./command.js";
+import { registerInlineInvocation } from "./inline-invocation.js";
+import { LoopController, type LoopControllerOptions } from "./loop.js";
+import { showLoopManager, showLoopSettings } from "./manager.js";
+
+export default function loop(pi: ExtensionAPI, options: LoopControllerOptions = {}) {
+	const controller = new LoopController(pi, options);
+
+	pi.registerCommand("loop", {
+		description:
+			"Wake the session on an interval: /loop [--max N] [--compact-at 60%] <interval> [prompt]",
+		getArgumentCompletions: (prefix: string) => completeLoopArguments(prefix),
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const command = parseLoopCommand(args);
+			switch (command.kind) {
+				case "show":
+					await showLoopManager(controller, ctx);
+					return;
+				case "status":
+					ctx.ui.notify(controller.statusLines(ctx).join("\n"), "info");
+					return;
+				case "pause":
+					controller.pauseLoop(ctx);
+					return;
+				case "resume":
+					controller.resumeLoop(ctx);
+					return;
+				case "stop":
+					controller.stopLoop(ctx);
+					return;
+				case "settings":
+					await showLoopSettings(controller, ctx);
+					return;
+				case "error":
+					ctx.ui.notify(command.message, "error");
+					return;
+				case "start": {
+					const existing = controller.state;
+					if (existing && existing.status !== "stopped") {
+						const replace =
+							ctx.mode === "tui"
+								? await ctx.ui.confirm(
+										"Replace loop?",
+										"A loop already exists in this session. Replace it?",
+									)
+								: false;
+						if (!replace) {
+							ctx.ui.notify(
+								"A loop already exists; /loop stop it first or confirm replacement in the TUI.",
+								"warning",
+							);
+							return;
+						}
+					}
+					controller.startLoop(ctx, command);
+					return;
+				}
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		controller.onSessionStart(ctx);
+	});
+	pi.on("session_shutdown", async () => {
+		controller.onSessionShutdown();
+	});
+	pi.on("agent_settled", async (_event, ctx) => {
+		controller.onAgentSettled(ctx);
+	});
+	pi.on("session_compact", async (_event, ctx) => {
+		controller.onSessionCompact(ctx);
+	});
+	registerInlineInvocation(pi, controller);
+}

package/src/inline-command.ts

@@ -0,0 +1,89 @@
+/**
+ * Inline slash-command detection.
+ *
+ * Pi dispatches extension commands only when a message *starts* with the
+ * command token; a command mentioned mid-prompt arrives as plain text. This
+ * helper finds the first inline occurrence of a command token so the caller
+ * can dispatch it and deliver the surrounding prose separately.
+ *
+ * This module is deliberately package-agnostic: every package-specific detail
+ * is a parameter so the file can be duplicated byte-for-byte into sibling
+ * packages (see DUPLICATED_SOURCES in scripts/validate.py once a second copy
+ * exists). Edit one copy, then copy it over the other.
+ */
+
+export interface InlineCommandSplit {
+	/** Text before the command token, trailing whitespace removed. */
+	prose: string;
+	/** Everything after the command token to end of message, trimmed. */
+	commandArgs: string;
+}
+
+/**
+ * Find the first inline `/<commandName>` occurrence in `text`.
+ *
+ * Detection rules:
+ * - The token must be preceded by start-of-line or whitespace and followed by
+ *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
+ *   path-like `foo/cmd` never matches.
+ * - A token at position 0 is ignored: that is Pi's native dispatch position.
+ * - Occurrences inside backtick code (inline spans and fenced blocks) are
+ *   ignored. Code regions are approximated by the CommonMark backtick-run
+ *   rule: a run of N backticks opens a region closed by the next run of
+ *   exactly N backticks.
+ *
+ * Returns undefined when no qualifying occurrence exists.
+ */
+export function extractInlineCommand(
+	text: string,
+	commandName: string,
+): InlineCommandSplit | undefined {
+	const token = `/${commandName}`;
+	const code = codeRegions(text);
+	let searchFrom = 0;
+	while (searchFrom < text.length) {
+		const index = text.indexOf(token, searchFrom);
+		if (index === -1) return undefined;
+		searchFrom = index + 1;
+		if (index === 0) continue;
+		const before = text[index - 1];
+		if (before !== undefined && !/\s/.test(before)) continue;
+		const afterToken = text[index + token.length];
+		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
+		if (insideRegion(code, index)) continue;
+		const commandArgs = text.slice(index + token.length).trim();
+		if (!commandArgs) continue;
+		return {
+			prose: text.slice(0, index).trimEnd(),
+			commandArgs,
+		};
+	}
+	return undefined;
+}
+
+type Region = readonly [start: number, end: number];
+
+function codeRegions(text: string): Region[] {
+	const regions: Region[] = [];
+	const runs: Array<{ index: number; length: number }> = [];
+	const runPattern = /`+/g;
+	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
+		runs.push({ index: match.index, length: match[0].length });
+	}
+	for (let open = 0; open < runs.length; open += 1) {
+		const opener = runs[open];
+		if (opener === undefined) continue;
+		for (let close = open + 1; close < runs.length; close += 1) {
+			const closer = runs[close];
+			if (closer === undefined || closer.length !== opener.length) continue;
+			regions.push([opener.index, closer.index + closer.length]);
+			open = close;
+			break;
+		}
+	}
+	return regions;
+}
+
+function insideRegion(regions: readonly Region[], index: number): boolean {
+	return regions.some(([start, end]) => index >= start && index < end);
+}

package/src/inline-invocation.ts

@@ -0,0 +1,39 @@
+/**
+ * Inline /loop invocation: recognize `/loop <args>` mid-prompt through Pi's
+ * input pipeline, dispatch it command-first, and deliver surrounding prose as
+ * a follow-up. Same design as the pi-goal fork's inline /goal; the detection
+ * helper (inline-command.ts) is duplicated byte-for-byte from
+ * packages/pi-goal and registered in DUPLICATED_SOURCES.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { extractInlineCommand } from "./inline-command.js";
+import type { LoopController } from "./loop.js";
+
+export const INLINE_LOOP_COMMAND = "loop";
+
+export function registerInlineInvocation(pi: ExtensionAPI, controller: LoopController) {
+	pi.on("input", (event) => {
+		// Messages sent by extensions (including our own re-dispatch below) are
+		// never rewritten; leading "/loop" is consumed by Pi's command dispatch
+		// before this event fires, so recursion is impossible either way.
+		if (event.source === "extension") return;
+		if (!controller.settings.inlineInvocation) return;
+		// A message with attached images is passed through untouched: splitting
+		// it would detach the images from the text they belong to.
+		if (event.images && event.images.length > 0) return;
+		const split = extractInlineCommand(event.text, INLINE_LOOP_COMMAND);
+		if (!split) return;
+		// While the agent streams, Pi requires an explicit delivery mode; reuse
+		// the mode the original message would have used.
+		const deliverAs = event.streamingBehavior;
+		pi.sendUserMessage(
+			`/${INLINE_LOOP_COMMAND} ${split.commandArgs}`,
+			deliverAs ? { deliverAs } : undefined,
+		);
+		if (split.prose) {
+			pi.sendUserMessage(split.prose, { deliverAs: "followUp" });
+		}
+		return { action: "handled" as const };
+	});
+}

package/src/interval.ts

@@ -0,0 +1,63 @@
+/**
+ * Deterministic duration parsing. The extension owns the grammar (research:
+ * model-parsed intervals make timing undebuggable): a positive integer plus
+ * one unit, `30s` / `5m` / `2h` / `1d`.
+ */
+
+export const MIN_INTERVAL_MS = 60_000;
+export const MAX_INTERVAL_MS = 2_147_483_647; // setTimeout's cap.
+
+const DURATION_PATTERN = /^(\d{1,9})(s|m|h|d)$/;
+
+const UNIT_MS: Record<string, number> = {
+	s: 1_000,
+	m: 60_000,
+	h: 3_600_000,
+	d: 86_400_000,
+};
+
+/** Parse a duration token to milliseconds, or undefined when malformed. */
+export function parseDuration(token: string): number | undefined {
+	const match = DURATION_PATTERN.exec(token.trim());
+	if (!match) return undefined;
+	const amount = Number(match[1]);
+	const unit = match[2] === undefined ? undefined : UNIT_MS[match[2]];
+	if (!Number.isSafeInteger(amount) || amount <= 0 || unit === undefined) return undefined;
+	const ms = amount * unit;
+	return ms > MAX_INTERVAL_MS ? undefined : ms;
+}
+
+export interface ParsedInterval {
+	requestedMs: number;
+	/** Clamped to MIN_INTERVAL_MS; the caller must echo the effective value. */
+	effectiveMs: number;
+	clamped: boolean;
+}
+
+/** Parse a loop interval token, clamping below the minimum. */
+export function parseInterval(token: string): ParsedInterval | undefined {
+	const requestedMs = parseDuration(token);
+	if (requestedMs === undefined) return undefined;
+	const effectiveMs = Math.max(MIN_INTERVAL_MS, requestedMs);
+	return { requestedMs, effectiveMs, clamped: effectiveMs !== requestedMs };
+}
+
+/** Render a millisecond duration back to the most compact token. */
+export function formatDuration(ms: number): string {
+	for (const [unit, size] of [
+		["d", UNIT_MS.d],
+		["h", UNIT_MS.h],
+		["m", UNIT_MS.m],
+	] as const) {
+		if (size !== undefined && ms >= size && ms % size === 0) return `${ms / size}${unit}`;
+	}
+	return `${Math.round(ms / 1_000)}s`;
+}
+
+/** Render a wall-clock time as HH:MM for the status widget. */
+export function formatClock(timestamp: number): string {
+	const date = new Date(timestamp);
+	const hours = `${date.getHours()}`.padStart(2, "0");
+	const minutes = `${date.getMinutes()}`.padStart(2, "0");
+	return `${hours}:${minutes}`;
+}